Claude Memory Bank - Persistent Context Management for Claude Code

Claude Memory Bank - GitHub Repository

The Problem: Ephemeral Sessions

Claude Code is a powerful CLI agent for software engineering, but every new conversation starts from scratch. Architectural decisions made yesterday, debugging patterns discovered last week, and project conventions established over months — all lost when a session ends. Developers find themselves repeatedly re-explaining project context, re-discovering patterns, and re-making decisions.

Claude Memory Bank solves this by providing a structured, file-based memory layer that persists project knowledge across sessions. It transforms Claude Code from a stateless tool into a persistent development partner.

Core Architecture

The system works by placing configuration files into the .claude/ directory that Claude Code natively reads. The key components are:

• CLAUDE.md — The master instruction file that Claude Code loads at session start
• settings.json — Environment configuration and permission rules
• agents/ — 12 specialized agent definitions (markdown-based system prompts)
• commands/ — 6 slash commands for memory operations
• workflows/ — Documented patterns for common development scenarios

Memory Bank Structure

All persistent knowledge lives in .claude/memory_bank/ on disk (gitignored — never committed to the repository):

.claude/memory_bank/
  decisions/          # Architecture decision records
  patterns/           # Reusable conventions and coding patterns
  architecture/       # Module topology and data flow
  troubleshooting/    # Known issues and proven fixes
  stash/              # Temporary workspace
  archive/            # Read-only historical snapshots (dated)
  reports/            # Stale detection and sync reports
  .diff-cache.json    # Tracks last sync commit for delta operations

Each category serves a distinct purpose. For example, decisions/api-versioning.md might capture why the team chose URL-based versioning over header-based, while troubleshooting/payment-timeout.md documents a production incident and its resolution.

How It Works Behind the Scenes

Token-Efficient Design

A critical design principle is just-in-time (JIT) retrieval. The system never loads the entire memory bank into context. Instead, it uses the /context-query command to extract only relevant slices, keeping token usage proportional to query specificity rather than total memory bank size.

The Synchronization Pipeline

The memory bank synchronizer uses a five-pass discovery pipeline:

1. Structure Pass — Scans project layout, directories, and file organization
2. State/Data Pass — Analyzes data flow and state management patterns
3. Patterns Pass — Detects reusable conventions and coding patterns
4. Decisions Pass — Captures architectural choices and their rationale
5. Troubleshooting Pass — Records known issues and their resolutions

It operates in two modes:

• Bootstrap Mode (first run) — Aggressive full discovery across the entire codebase
• Delta Mode (subsequent runs) — Git-based incremental sync, updating only what changed

Weighted Scoring for Knowledge Prioritization

Not all discovered knowledge is equally valuable. The synchronizer uses a multi-factor scoring formula to prioritize what gets stored:

Factor	Weight
Frequency of occurrence	25%
Complexity	20%
Adoption across codebase	15%
Change frequency	15%
Cross-module usage	10%
Business impact	10%
Maintenance cost	5%

This prevents the memory bank from being flooded with trivial patterns and keeps focus on high-value knowledge.

The Agent System

Claude Memory Bank defines 12 specialized agents, each with a distinct role and reasoning methodology. The agents are defined as Markdown files containing system prompts.

Memory & Context Agents

Memory Bank Synchronizer — The core sync engine. Runs the five-pass discovery pipeline and manages bootstrap vs. delta modes. Coverage targets: minimum 8 architecture entries, 12 patterns, 10 decisions, and 6 troubleshooting items.

Context Query Agent — Read-only retrieval specialist. Accepts path patterns (src/service/auth/**) or feature names (Feature: Checkout), searches across all four memory categories, and assembles a temporary context bundle file. Targets >90% relevance rate.

Context Diff Agent — Delta sync specialist. Maintains .diff-cache.json to track the last synchronized commit. Detects changes via git diff, classifies impacts by memory category, and updates only affected areas. Targets <25% token usage compared to full regeneration.

Stale Context Agent — Non-destructive validation tool. Compares memory bank entries against the live codebase to find references to deleted files, conflicting guidance, or deprecated practices. Instead of deleting stale content, it inserts HTML comment markers:

<!-- STALE: verify against repo commit abc123 -->

This preserves information while flagging it for human review.

Code Analysis Agents with Chain-of-X Methodologies

Each code analysis agent uses a different reasoning methodology chosen to match its purpose:

Agent	Methodology	Purpose
Code Searcher	Chain of Draft (CoD)	Ultra-concise code navigation (5 words max per step)
Code Thinker	Chain of Thought (CoT)	Architecture decisions, algorithm design, debugging
Code Executor	Chain of Code (CoC)	Generate and run minimal scripts to validate claims
Code Verifier	Chain of Verification (CoVe)	Self-questioning with 3-6 verification questions

The Code Searcher is particularly interesting — it uses Chain of Draft methodology where each reasoning step is compressed to 5 words or fewer using symbolic notation, always concluding with a #### answer line containing file:line references.

The Code Verifier uses a three-phase process: draft an answer, generate 3-6 verification questions about that answer, then revise based on findings. This ensures accuracy through systematic self-questioning.

The Command System

Six slash commands provide the user interface:

Command	Purpose
/update-memory-bank	Full memory bank sync (bootstrap or delta)
/context-query	JIT read-only context retrieval
/context-diff	Delta-only sync of changed areas
/cleanup-context	Archive snapshots without deleting source files
/stale-context-check	Detect outdated or contradictory content
/rebuild-granular-from-archive	Restore granular files from archive snapshots

Recommended Workflows

The project documents six workflows for common development scenarios:

• Delta Sync (~30s) — Start of dev day or after commits, run /context-diff
• JIT Context (~15s) — Writing or reviewing a PR, run /context-query --format=bundle
• Hotfix (~10s) — Production incident, narrow scope to impacted paths only
• Feature Wrap (~1min) — Feature completed, archive with /cleanup-context
• Rehydrate (~1min) — Resuming work on archived project
• Weekly Hygiene (~2min) — Run /stale-context-check for maintenance

Safety Mechanisms

The system implements a triple-layer protection for archived knowledge:

1. settings.json permissions — Denies Edit, MultiEdit, and Delete on archive/** and denies Delete on all four memory categories
2. CLAUDE.md instructions — Explicitly tells the agent to never modify archives
3. Agent-level constraints — Each agent’s system prompt reinforces immutability rules

{
  "permissions": {
    "deny": [
      "Delete(.claude/memory_bank/decisions/**)",
      "Delete(.claude/memory_bank/patterns/**)",
      "Delete(.claude/memory_bank/architecture/**)",
      "Delete(.claude/memory_bank/troubleshooting/**)",
      "Edit(.claude/memory_bank/archive/**)",
      "Delete(.claude/memory_bank/archive/**)"
    ]
  }
}

This ensures that accumulated project knowledge is never accidentally destroyed by the AI agent.

Key Takeaways

1. Claude Memory Bank is a prompt engineering framework — It works entirely through markdown files, JSON configuration, and Claude Code’s native .claude/ directory structure. No external services or databases required.

2. Token efficiency is a first-class concern — JIT retrieval, delta sync, and compressed reasoning methodologies all minimize context window consumption.

3. Multiple reasoning methodologies — Chain of Draft, Chain of Thought, Chain of Code, and Chain of Verification are each applied where they fit best, demonstrating that different tasks benefit from different reasoning approaches.

4. Non-destructive by design — Stale content gets marked rather than deleted. Archives are immutable. Knowledge accumulates safely over time.

5. Git-native incremental sync — The diff cache mechanism enables efficient updates by tracking changes since the last synchronization, avoiding expensive full-codebase scans.

For teams working with Claude Code on long-running projects, this system addresses a real pain point: the loss of accumulated project context between sessions. By structuring knowledge into queryable categories and providing efficient retrieval mechanisms, it brings the benefits of persistent memory to an otherwise stateless AI assistant.