claude-os/docs/MEMORY_MCP_GUIDE.md

Memory MCP: Persistent Context Across Sessions

Created: 2025-10-24 Status: Ready for production use Location: ~/.claude/mcp-servers/memory/

---

What Is Memory MCP?

Memory MCP is a persistent memory system for Claude Code that maintains context across sessions without requiring knowledge base searches.

Instead of:

You: "Search the KB for Block 122"
→ I search through embeddings
→ Results shown

You get:

You: "What did we work on yesterday?"
→ I recall from memory automatically
→ Show you complete context

Why This Matters

The Problem We Solved

Issue: Context loss between sessions

• Knowledge base requires explicit searches
• Embedding lookup adds latency (40-50 seconds)
• No automatic recall of recent work
• User must actively ask "search for..."

Solution: Memory MCP

• Instant recall (no latency)
• Automatic context reference
• Zero setup required
• Works even when embedding service is down

Quick Start

Say "Remember" in Any Session

You: "Remember: Block 122 is a 43KB appointment form with 4-step wizard"
→ Automatically saved

I Recall Automatically in Future Sessions

You: "What did we work on yesterday?"
→ I search memory and respond:
"Based on our memory, yesterday we worked on:
- Block 122 analysis (43KB, 1,150 lines)
- Created deprecation strategy
- ..."

How It Works

Architecture

Your Request
    ↓
    "Remember: [information]"
    ↓
Memory Skill (~/.claude/skills/memory/SKILL.md)
    ↓
MCP Server (server.py)
    ├─ Parse request
    ├─ Add/Search/Update memory
    ↓
JSON File (memories.json)
    ├─ Store with: ID, title, content, tags, timestamp
    ↓
Next Session
    ├─ I search memory when relevant
    ├─ Recall context automatically
    ↓
Perfect Context Continuity

Storage Format

{
  "memories": [
    {
      "id": 0,
      "title": "Block 122 Analysis",
      "content": "43KB appointment form with 4-step wizard...",
      "tags": ["Block122", "Architecture", "Complexity"],
      "created_at": "2025-10-24T19:43:05",
      "updated_at": "2025-10-24T19:43:05"
    }
  ]
}

Storage Location: ~/.claude/mcp-servers/memory/data/memories.json

Commands

Save (Most Common)

Remember: [your information]
Save to memory: [information]
Store this: [information]
Memory: [information]

Recall

What did we work on [time]?
Show me my memories about [topic]
Remind me: [topic]
What do we know about [topic]?

List

Show all my memories
List my recent memories (last 24 hours)
What memories do I have?

Update

Update memory: [title] with [new info]

Delete

Forget: [memory title]
Delete: [memory]

Current Memories

Three initial memories were seeded from today's session:

1. Block System Deep Dive

Title: Block System Deep Dive - Session 10/24/25
Tags: BlockDeprecation, Block122, Architecture, Research, PISTN, Rails
Content: Block 122 analysis (43KB), deprecation strategy, documents created

2. Memory MCP System

Title: Memory MCP System - Created 10/24/25
Tags: MemoryMCP, System, Infrastructure, Claude, Features
Content: Why Memory MCP exists, advantages over KB, how it works

3. Claude OS TIER 1 Extraction

Title: Claude OS TIER 1 Extraction Complete
Tags: CodeForge, PISTN, KnowledgeBase, AutoIndexing, MCP
Content: 130 documents indexed, git hook auto-updating, 495 chunks

Try asking: "What memories do I have?" to see them!

Memory MCP vs Knowledge Base

Both are valuable for different purposes:

Feature	Memory MCP	Knowledge Base
Recall Speed	⚡ Instant	🐢 40-50 seconds
Requires Search	❌ No - automatic	✅ Yes - explicit
Use Case	Recent project context	Searchable knowledge archive
Search Speed	O(n) - very fast	Embedding lookup - slower
Setup	0 steps (works immediately)	Manual indexing required
Works Offline	✅ Yes	❌ Needs Ollama
Format	JSON (human readable)	Vectors (not readable)
Best For	Context across sessions	Finding relevant code patterns

Together they're perfect:

• Memory MCP = What we're working on this week (recent context)
• Knowledge Base = How the entire codebase works (searchable knowledge)

Examples from Today's Session

What We Remembered

Memory 1: Block 122 Research

Title: Block System Deep Dive - Session 10/24/25

What was stored:
✓ Block 122 is 43KB, 1,150 lines
✓ 4-step wizard form with complex JavaScript
✓ 12+ conditional renders based on account settings
✓ Phone verification, vehicle lookup, service selection
✓ Complexity: 8.5/10 - enterprise-grade form

Documentation created:
✓ BLOCKS_DEPRECATION_STRATEGY.md (4-phase migration plan)
✓ BLOCK_CASE_STUDY_TUFFY_APPOINTMENT_FORM.md (detailed with code examples)
✓ BLOCK_SYSTEM_RESEARCH_FINDINGS.md (key findings summary)

Memory 2: System Infrastructure

Title: Memory MCP System - Created 10/24/25

System components:
✓ server.py - MCP server with JSON storage
✓ Memory Skill - Invoked by "Remember:" commands
✓ CLI wrapper - Manual memory saving from terminal
✓ Full-text search on titles, content, tags
✓ Instant recall without embedding delays

Memory 3: Knowledge Extraction

Title: Claude OS TIER 1 Extraction Complete

PISTN Claude OS indexing:
✓ 82 service classes indexed
✓ 286 models indexed
✓ 138 migrations indexed
✓ 130 total documents, 495 chunks
✓ Git hook for auto-indexing on commits
✓ Live knowledge that stays current

Future Session Example

Tomorrow, You Could Say:

You: "What did we accomplish yesterday?"

→ I search memory automatically
→ "Based on our memory from yesterday:

1. **Block System Research**
   - Analyzed Block 122 (43KB appointment form)
   - Created 4-phase deprecation strategy
   - Built detailed case study with Rails examples

2. **Memory MCP System**
   - Created persistent memory system
   - No search required - instant context recall
   - Works across all sessions

3. **Claude OS Updates**
   - Tier 1 PISTN extraction: 130 docs, 495 chunks
   - Git hook auto-updates on commits

What would you like to continue with?"

Installation & Setup

Already Done ✅

All files are already created at:

~/.claude/mcp-servers/memory/
├── server.py              # MCP server
├── save_memory.sh         # CLI wrapper
├── README.md              # Full documentation
├── SETUP.md               # Quick start
└── data/
    └── memories.json      # Actual memories

Using It (No Setup Required!)

Just start saying "Remember:" in any Claude Code session. That's it!

Advanced Features

Direct CLI Usage

# Add a memory directly
python3 ~/.claude/mcp-servers/memory/server.py << 'EOF'
{
  "action": "add",
  "params": {
    "title": "My Memory",
    "content": "Details here...",
    "tags": ["tag1", "tag2"]
  }
}
EOF

# View all memories
python3 ~/.claude/mcp-servers/memory/server.py << 'EOF'
{"action": "all", "params": {}}
EOF

# Search memories
python3 ~/.claude/mcp-servers/memory/server.py << 'EOF'
{"action": "search", "params": {"query": "Block"}}
EOF

Backup & Restore

# Backup memories
cp ~/.claude/mcp-servers/memory/data/memories.json ~/memories_backup.json

# View raw JSON
cat ~/.claude/mcp-servers/memory/data/memories.json | python3 -m json.tool

# Clear all memories (if needed)
rm ~/.claude/mcp-servers/memory/data/memories.json

Best Practices

1. Be Specific: "Remember: Block 122 is 43KB" beats "Remember blocks"
2. Add Tags: Help future searching ("Block122", "Migration", "Analysis")
3. Update Often: Keep memories current as you learn more
4. Summarize: Summarize key points rather than dumping huge amounts of text
5. Use Tags Wisely: Tags are searchable - pick descriptive ones

What's Next

Potential Enhancements

• Hierarchical tags (#Architecture/Block)
• Memory versioning (track changes)
• Export to Markdown
• Cloud sync across devices
• Memory importance levels (star/pin favorites)
• Related memories auto-linking
• Statistics dashboard

How You Can Extend

The Memory MCP is open and extendable:

1. Add new memory types: Structured data, links, etc.
2. Integrate with other tools: Export to Obsidian, Roam, etc.
3. Add webhooks: Auto-save from external sources
4. Create visualizations: Memory graph, timeline view

Troubleshooting

Memory not saving?

ls -la ~/.claude/mcp-servers/memory/data/

Can't recall a memory?

# List all memories
echo '{"action":"all","params":{}}' | python3 ~/.claude/mcp-servers/memory/server.py

Server not responding?

# Test the server
echo '{"action":"all","params":{}}' | python3 ~/.claude/mcp-servers/memory/server.py

The Vision

Memory MCP is part of a complete knowledge system for PISTN development:

Claude OS KB          ← Searchable codebase knowledge
    +
Memory MCP             ← Recent project context
    +
Git Hooks              ← Auto-indexing on commits
    +
Skills & MCPs          ← Automation & tools
    =
Perfect Context       → You write code that matches your patterns

Together, these systems make me a true expert developer on your codebase, without you having to repeat context or search for information.

---

Quick Reference

Want to...	Say...
Save info	"Remember: ..."
Recall yesterday	"What did we work on yesterday?"
Search memory	"Show me memories about [topic]"
List all	"Show all my memories"
Update	"Update memory: [title] with [info]"
Delete	"Forget: [title]"
View raw data	cat ~/.claude/mcp-servers/memory/data/memories.json

---

You're all set! Start using Memory MCP by simply saying "Remember:" followed by anything you want me to store. In future sessions, I'll automatically reference this context when relevant.