Claude Code Memory System: Building Persistent Project Intelligence

One of the most frustrating aspects of AI assistants is session amnesia—every conversation starts fresh. Claude Code solves this with the Memory MCP, a knowledge graph system that persists across sessions.

This guide covers everything you need to know about building persistent project intelligence.

The Problem: Session Amnesia

Traditional AI workflows suffer from context loss:

Session 1: "We decided to use Redis for caching because..."
Session 2: "Why are we using Redis?"
Session 3: "Should we switch to Memcached?"
Session 4: [Repeats same discussion]

Every session, you re-explain decisions. Every session, context is lost. This is institutional memory failure.

The Solution: Memory MCP

The Memory MCP creates a persistent knowledge graph that stores:

• Entities - Named concepts with observations
• Relations - Connections between entities
• Observations - Facts about entities

┌─────────────────────────────────────────────────────────────┐
│                   Knowledge Graph                            │
│                                                             │
│  ┌────────────────┐         ┌────────────────┐             │
│  │ authentication │◄──uses──│ redis_cache    │             │
│  │                │         │                │             │
│  │ Observations:  │         │ Observations:  │             │
│  │ - Uses JWT     │         │ - Selected for │             │
│  │ - Tokens valid │         │   speed        │             │
│  │   for 24h      │         │ - v7.2         │             │
│  └────────────────┘         └────────────────┘             │
│          │                          │                       │
│          │                          │                       │
│          └──────────┬───────────────┘                       │
│                     │                                       │
│                     ▼                                       │
│            ┌────────────────┐                               │
│            │ user_session   │                               │
│            │                │                               │
│            │ Observations:  │                               │
│            │ - 30 min TTL   │                               │
│            │ - Refresh      │                               │
│            │   strategy     │                               │
│            └────────────────┘                               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Setting Up Memory MCP

Step 1: Add Memory MCP to Project

Use the official CLI to add the Memory MCP:

# Add with project isolation (CRITICAL!)
claude mcp add --scope project memory \
  -e MEMORY_FILE_PATH=./.claude/memory.json \
  -- npx -y @modelcontextprotocol/server-memory

Important: The MEMORY_FILE_PATH environment variable isolates memory per project. Without it, all projects share the same memory file.

Step 2: Verify Installation

# Check MCP status
claude mcp list

# Should show:
# memory (project) - @modelcontextprotocol/server-memory

Step 3: Initialize Memory

On first use, create initial context:

User: "Save initial project context to memory"

Claude:
→ Creates entities for: project, tech_stack, key_decisions
→ Establishes relations between entities
→ Stores initial observations

Memory Operations

Creating Entities

Entities are named concepts with a type and observations:

{
  "name": "authentication_system",
  "entityType": "component",
  "observations": [
    "Uses JWT tokens for stateless auth",
    "Tokens expire after 24 hours",
    "Refresh tokens rotate on each use",
    "Implemented in auth/ directory"
  ]
}

Creating Relations

Relations connect entities with named relationships:

{
  "from": "authentication_system",
  "to": "redis_cache",
  "relationType": "uses"
}

Adding Observations

Add new facts to existing entities:

{
  "entityName": "authentication_system",
  "contents": [
    "Added MFA support on 2026-01-10",
    "MFA uses TOTP algorithm"
  ]
}

Memory Commands

Save Knowledge

/memory-save

Or in natural language:

"Save this decision to memory: We chose PostgreSQL over MySQL because..."

Claude will:

1. Identify entities to create/update
2. Extract observations
3. Establish relations
4. Store to knowledge graph

Search Knowledge

/memory-search

Or in natural language:

"What do we know about our caching strategy?"

Claude will:

1. Search the knowledge graph
2. Find relevant entities
3. Return observations and relations

List All Knowledge

/memory-list

Shows all stored entities and their observations.

Audit Memory

/memory-audit

Identifies:

• Stale information
• Duplicate entities
• Missing relations
• Cleanup recommendations

What to Store in Memory

Architecture Decisions

Entity: database_choice
Type: decision
Observations:
- "Selected PostgreSQL for JSONB support"
- "Considered MySQL but needed JSON queries"
- "Decision date: 2026-01-05"
- "Decision maker: Tech lead"

Design Patterns

Entity: error_handling_pattern
Type: pattern
Observations:
- "Use Result type for all async operations"
- "Never throw in domain layer"
- "Log errors at boundary only"
- "Pattern documented in ARCHITECTURE.md"

Bug Fixes

Entity: auth_timeout_bug
Type: bug_fix
Observations:
- "Issue: Users logged out after 5 minutes"
- "Root cause: Token refresh race condition"
- "Solution: Implemented mutex around refresh"
- "PR: #234, Merged: 2026-01-08"

Team Conventions

Entity: code_review_process
Type: process
Observations:
- "All PRs require 2 reviews"
- "Security-sensitive code needs security-auditor"
- "Use conventional commits"
- "Squash merge only"

External Dependencies

Entity: stripe_integration
Type: integration
Observations:
- "API version: 2024-11-20"
- "Webhook endpoint: /api/webhooks/stripe"
- "Using Stripe Checkout for payments"
- "Test mode API key in STRIPE_SECRET_KEY"

Memory Patterns

Pattern 1: Session Start Load

Start each session by loading relevant context:

"What do we know about the feature I'm working on?"

Claude searches memory and provides context.

Pattern 2: Decision Recording

After making decisions, record them:

"Save this decision to memory: We're using Redis for
session caching because it provides sub-millisecond
latency and we need 10K+ concurrent sessions."

Pattern 3: Bug Context

When fixing bugs, save the context:

"Save this bug fix to memory: The login timeout was
caused by token refresh race condition. Fixed by
adding mutex. Relevant files: auth/refresh.ts"

Pattern 4: Periodic Review

Regularly audit and clean memory:

/memory-audit

Then:

"Clean up outdated observations about the old auth system"

Integration with Workflows

Director Mode Integration

Memory enables true Director Mode by providing persistent context:

"Implement user profile editing based on our existing
patterns and decisions."

Claude:
→ Searches memory for: patterns, conventions, decisions
→ Finds: error handling pattern, API conventions
→ Implements following established patterns

Multi-Session Projects

For complex projects spanning multiple days:

Day 1: "We're building a payment system. Save the architecture."
Day 2: "Continue payment work. What did we decide yesterday?"
Day 3: "Finish payment integration. What's left?"

Memory provides continuity across sessions.

Team Knowledge Sharing

Memory becomes shared team knowledge:

// .claude/memory.json (committed to repo)
{
  "entities": [...],
  "relations": [...]
}

New team members inherit institutional knowledge.

Advanced Memory Techniques

Hierarchical Knowledge

Organize knowledge in hierarchies:

project
├── architecture
│   ├── frontend
│   │   └── React patterns, state management
│   ├── backend
│   │   └── API conventions, auth patterns
│   └── database
│       └── Schema decisions, indexing strategies
└── decisions
    ├── technical
    └── product

Temporal Context

Include timing in observations:

Observations:
- "[2026-01-05] Initial choice: MySQL"
- "[2026-01-08] Migrated to PostgreSQL for JSONB"
- "[2026-01-10] Added read replica for analytics"

Confidence Levels

Mark observation confidence:

Observations:
- "[CONFIRMED] Uses JWT for auth"
- "[ASSUMPTION] Token TTL is 24 hours (verify)"
- "[OUTDATED] Previous used session cookies"

Cross-Reference Patterns

Link related knowledge:

Entity: auth_bug_001
Observations:
- "Related to: token_refresh_mechanism"
- "See also: session_management"
- "Fixed in: PR #234"

Memory Architecture

File Structure

.claude/
├── memory.json        # Knowledge graph storage
├── settings.json      # MCP configuration
└── skills/            # Custom skills

Memory JSON Format

{
  "entities": [
    {
      "name": "entity_name",
      "entityType": "component|decision|pattern|...",
      "observations": ["observation 1", "observation 2"]
    }
  ],
  "relations": [
    {
      "from": "entity_a",
      "to": "entity_b",
      "relationType": "uses|depends_on|implements|..."
    }
  ]
}

Storage Strategy

Option 1: Project Local (Recommended)

MEMORY_FILE_PATH=./.claude/memory.json

• Committed with code
• Team-shared knowledge
• Project-specific

Option 2: User Global

MEMORY_FILE_PATH=~/.claude/memory.json

• Personal knowledge
• Cross-project patterns
• User preferences

Option 3: Hybrid

Project: .claude/memory.json (architecture, decisions)
User: ~/.claude/memory.json (personal patterns)

Memory Maintenance

Regular Cleanup

/memory-audit

Identifies:

• Entities not accessed in 30+ days
• Duplicate or conflicting observations
• Orphaned relations
• Suggested consolidations

Migration Strategy

When refactoring:

"Update memory: We migrated from Express to Fastify.
Mark all Express-related observations as outdated."

Archiving

For completed projects:

"Archive all memory related to v1 authentication
with note: 'Replaced by v2 OAuth implementation'"

Memory vs Other Persistence

Feature	Memory MCP	CLAUDE.md	Git History
Structured	Yes (graph)	No (text)	No
Queryable	Yes	No	Partial
Temporal	Yes	Manual	Yes
Team-shared	Yes	Yes	Yes
Context cost	Low (on-demand)	High (always loaded)	N/A

When to Use Memory vs CLAUDE.md

Use Memory for:

• Decisions and rationale
• Bug fixes and resolutions
• Evolving patterns
• Session-to-session context

Use CLAUDE.md for:

• Static policies
• Tool configurations
• Project structure
• Workflow definitions

Troubleshooting

Memory Not Persisting

1. Check MEMORY_FILE_PATH is set
2. Verify file write permissions
3. Check MCP is running: claude mcp list

Search Not Finding Results

1. Check entity names (case-sensitive)
2. Verify observations contain search terms
3. Use broader search terms

Duplicate Entities

1. Run /memory-audit
2. Merge duplicates: “Merge entity A and B”
3. Update relations to point to merged entity

Best Practices

1. Save Immediately

When making decisions, save right away:

"Save this decision to memory now before we forget the context."

2. Be Specific

Good observation:

"Selected PostgreSQL for JSONB support needed for user preferences storage"

Avoid:

"Using PostgreSQL"

3. Include Context

Add the “why” not just the “what”:

"Chose Redis over Memcached because we need data structures (lists, sets) for session management"

4. Update Regularly

When things change:

"Update memory: We increased token TTL from 24h to 7 days per user feedback"

5. Audit Monthly

Schedule regular maintenance:

/memory-audit

Getting Started

Today:

1. Add Memory MCP to your project
2. Save one architecture decision
3. Try /memory-search

This week:

1. Build initial knowledge graph
2. Save all major decisions
3. Integrate with daily workflow

This month:

1. Complete knowledge graph coverage
2. Establish team conventions
3. Regular audit schedule

---

Memory transforms Claude Code from a stateless tool to a knowledgeable partner. Build your knowledge graph, and every session starts with full context.

Sources: Claude Code Documentation, Memory MCP