memory-mcp
Integrates with Git to automatically snapshot the entire project on every memory save, with capabilities for rollback and diff comparison.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@memory-mcp what did we decide about authentication?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
memory-mcp
Persistent memory + automatic git snapshots for Claude Code. Never lose context. Never lose code.
š§ 45 memories | š 2.8K tokens | šø 23 snapshots | ā±ļø 5m agoWhy memory-mcp?
Problem | Solution |
Re-explaining your project every session | Auto-captures decisions, patterns, architecture |
Context window fills up, knowledge lost | Two-tier memory: CLAUDE.md (instant) + deep search |
Broke something, can't remember what worked | Git snapshots on every save, instant rollback |
No idea what Claude "knows" about your project | Visual dashboard shows all context |
Worried about cloud storage | 100% local files, your git repo |
Related MCP server: Axme-code
What makes it different
Git Snapshots ā Every memory save commits your entire project. Roll back anytime.
Two-Tier Memory ā CLAUDE.md loads instantly, deep store searchable mid-conversation.
LLM-Powered ā Haiku extracts what matters, consolidates duplicates, prunes stale info.
Visual Dashboard ā See your context: tokens, memories by type, snapshot history.
Zero friction ā No commands to run. It just works silently.
Quick Start
# Install globally
npm install -g claude-code-memory
# Interactive setup (API key + hooks)
memory-mcp setup
# Initialize a project
memory-mcp init ~/Projects/my-appThat's it. Start coding. Memories accumulate automatically.
How It Works
graph TB
subgraph "Phase 1: Silent Capture"
A[Claude Code Session] -->|User sends message| B[Claude responds]
B -->|Hook fires: Stop/PreCompact/SessionEnd| C[extractor.js]
C --> D[Read transcript from cursor]
D --> E[Chunk if >6000 chars]
E --> F[Send to Haiku LLM]
F -->|Extract memories as JSON| G[Dedup via Jaccard similarity]
G --> H[Save to .memory/state.json]
H --> I[Decay confidence scores]
I --> J{Consolidation needed?}
J -->|>80 memories or every 10 extractions| K[Haiku merges/drops]
J -->|No| L[Sync CLAUDE.md]
K --> L
end
subgraph "Phase 2: Recovery"
M[New session starts] -->|Built-in behavior| N[Claude reads CLAUDE.md]
N --> O[Claude has full project context]
end
subgraph "Phase 3: Deep Recall"
O --> P{Need specific context?}
P -->|memory_search| Q[Keyword search across memories]
P -->|memory_ask| R[Haiku synthesizes answer from top 30 matches]
P -->|memory_related| S[Tag-based retrieval]
end
subgraph "Data Store"
H -.-> T[(.memory/state.json<br/>Full memory store)]
L -.-> U[(CLAUDE.md<br/>~150 line summary)]
T -.->|MCP tools read| Q
T -.->|MCP tools read| R
T -.->|MCP tools read| S
end
style A fill:#4a9eff,color:#fff
style F fill:#ff6b6b,color:#fff
style K fill:#ff6b6b,color:#fff
style R fill:#ff6b6b,color:#fff
style T fill:#ffd93d,color:#000
style U fill:#6bcb77,color:#000Two-tier memory architecture:
Layer | Purpose | Size |
| Auto-read on session start. Top ~150 lines of the most important context. | Compact |
| Full memory store. Searchable via MCP tools mid-conversation. | Unlimited |
Silent capture via hooks:
Claude Code hooks fire after every response (Stop), before context compaction (PreCompact), and at session end (SessionEnd). A fast LLM (Haiku) reads the transcript and extracts:
Architecture ā how the system is structured
Decisions ā why X was chosen over Y
Patterns ā conventions and how things are done
Gotchas ā non-obvious pitfalls
Progress ā what's done, what's in flight
Context ā business context, deadlines, preferences
Smart memory management:
Jaccard similarity deduplication (no duplicate memories)
Confidence decay (progress fades after 7 days, context after 30)
LLM-powered consolidation (merges overlapping memories, prunes stale ones)
Line-budgeted CLAUDE.md (stays under ~150 lines, most important first)
Updating
To update an existing installation:
npm install -g claude-code-memory --forceTo update hooks (e.g., after a bug fix):
memory-mcp setupRequirements
Node.js 18+
Anthropic API key (for the Haiku-based extractor, ~$0.001 per extraction)
CLI Commands
memory-mcp setup Interactive first-time setup
memory-mcp init [dir] Initialize memory for a project
memory-mcp status [dir] Show memory status and health
memory-mcp statusline [dir] Compact one-line status (great for shell prompts)
memory-mcp context [dir] Show context metrics and token usage
memory-mcp context --html Generate visual HTML dashboard
memory-mcp search <query> Search memories by keyword
memory-mcp ask <question> Ask a question, get answer from memory
memory-mcp consolidate [dir] Merge duplicates, prune stale memories
memory-mcp key [api-key] Set or check Anthropic API key
memory-mcp snapshots [dir] List git snapshot history
memory-mcp snapshot-enable Enable automatic git snapshots
memory-mcp snapshot-disable Disable git snapshots
memory-mcp help Show helpContext Dashboard
Visualize your memory usage with memory-mcp context:
Context Dashboard
Project: my-app
Total Context
2.8K estimated tokens
Tier 1 CLAUDE.md (auto-loaded)
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāā 1.0K
45 lines, 44 in memory block
Tier 2 .memory/state.json (searchable)
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāā 1.8K
29 active, 5 archived, 24 superseded
Memories by Type
architecture āāāāāāāāāāāāāāāāāāāā 8 memories (291 tokens)
decision āāāāāāāāāāāāāāāāāāāā 18 memories (540 tokens)
gotcha āāāāāāāāāāāāāāāāāāāā 10 memories (332 tokens)
progress āāāāāāāāāāāāāāāāāāāā 19 memories (538 tokens)
Git Snapshots
ā Enabled on __memory-snapshots
42 commits ā originUse memory-mcp context --html to generate an interactive browser dashboard.
Git Snapshots
Automatic project versioning tied to your working sessions. Every memory extraction commits your entire project to a hidden branch.
# Enable during init (you'll be prompted)
memory-mcp init ~/Projects/my-app
# Or enable later
memory-mcp snapshot-enable
# View snapshot history
memory-mcp snapshots
# Compare two snapshots
memory-mcp snapshot-diff abc123 def456
# Restore to a previous state
memory-mcp snapshot-restore abc123
# Disable (preserves existing snapshots)
memory-mcp snapshot-disableHow it works:
Commits go to
__memory-snapshotsbranch (invisible in normal workflow)Optional push to remote (e.g., origin)
Commit messages include what memories were extracted
Full project state captured, not just memory files
Use cases:
Roll back after breaking changes
See what your project looked like during a specific session
Track project evolution alongside context evolution
MCP Tools (used by Claude mid-conversation)
When configured as an MCP server, Claude can access these tools during a session:
Tool | Description |
| Keyword search across all memories |
| Get memories by tag or area |
| Ask a question, get an LLM-synthesized answer from memory |
| Manually save a memory |
| List all memories with filters |
| Remove a memory |
| Trigger memory consolidation |
| Generate the full consciousness document |
| Show memory statistics |
| Set project name and description |
What Gets Stored
Memories are categorized into six types:
architecture "Next.js 14 app router with Supabase backend, Stripe for billing"
decision "Chose server components for public pages because of SEO requirements"
pattern "All API routes validate input with zod and return NextResponse"
gotcha "Supabase RLS policy on word_lists requires user_id OR org_id, not both"
progress "Auth complete, billing webhook handling in progress"
context "Client wants launch by March, focus on core features only"File Structure
After initialization, your project gets:
your-project/
āāā CLAUDE.md ā auto-updated memory summary (read on session start)
āāā .memory/
ā āāā state.json ā full memory store
ā āāā cursor.json ā tracks what's been processed
āāā .mcp.json ā MCP server configuration
āāā .claude/
āāā settings.json ā hook configurationCLAUDE.md Format
The memory block is inserted between markers, preserving any existing CLAUDE.md content:
<!-- MEMORY:START -->
# MyProject
A brief description
_Last updated: 2026-01-27 | 45 active memories, 62 total_
## Architecture
- Next.js 14 app router with Supabase backend
- Auth via NextAuth with Google and email providers
## Key Decisions
- Chose server components for SEO pages
- Using Supabase RLS instead of API-level auth
## Patterns & Conventions
- All API routes use zod validation
- Tailwind only, no CSS modules
## Gotchas & Pitfalls
- RLS policy requires user_id OR org_id, not both
## Current Progress
- Auth: complete
- Billing: in progress
## Context
- Launch target: March
_For deeper context, use memory_search, memory_related, or memory_ask tools._
<!-- MEMORY:END -->Global vs Per-Project Install
Global (recommended): hooks work for all projects automatically.
memory-mcp setup # select "global" when promptedPer-project: hooks and MCP configured per project.
memory-mcp init /path/to/projectConfiguration
API key is resolved in order:
ANTHROPIC_API_KEYenvironment variable~/.memory-mcp/config.json~/.config/anthropic/api_key~/.anthropic/api_key
Cost
The extractor uses Claude Haiku for memory extraction and consolidation. Typical cost:
~$0.001 per extraction (after each Claude response)
~$0.005 per consolidation (every ~10 extractions)
A full day of coding: ~$0.05ā0.10
License
MIT
Available Tools
10 toolsmemory_askA
Ask a question and get an answer synthesized from project memories. Like RAG over your project knowledge.
Inputs: question (required).
memory_consciousnessA
Generate the full consciousness document. This is what gets written to CLAUDE.md.
Inputs: no named parameters.
memory_consolidateA
Manually trigger memory consolidation. Merges duplicates, removes outdated memories, keeps memory sharp.
Inputs: no named parameters.
memory_deleteB
Delete a specific memory by ID.
Inputs: id (required).
memory_initA
Initialize project memory with name and description.
Inputs: name (required), description (required).
memory_recallA
Recall all active memories, optionally filtered by type or tags.
Inputs: tags, type.
memory_saveA
Save a memory about this project. Records decisions, patterns, architecture, gotchas, progress, or context for future sessions.
Inputs: type (required), content (required), tags, supersedes.
memory_searchB
Search memories by keyword. Returns ranked results matching the query across content and tags.
Inputs: query (required), limit.
memory_statsA
Show memory statistics: counts by type, active/archived/superseded, last consolidation.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 10 tools
Most tools have distinct purposes, but the retrieval tools (recall, search, related, ask) overlap conceptually. However, each has a clear differentiator: recall lists all, search ranks by keyword, related explores by tag, ask synthesizes an answer. No two tools are truly indistinguishable.
All tools share the 'memory_' prefix, but suffixes mix verbs (save, delete, search) with nouns (related, consciousness, stats). This inconsistency is noticeable but the command pattern is still readable.
10 tools is well within the ideal range for a focused domain. Each tool addresses a distinct aspect of memory management without bloat.
The core memory lifecycle (init, save, recall, delete, consolidate) is covered, plus useful extras (search, ask, related, stats). Missing an explicit update tool, but delete+re-save works around it.
Maintenance
Related MCP Connectors
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
Persistent, governed institutional memory for Claude Code ā specs, decisions, learnings.
Shared work memory for Claude Code, Codex, Cursor and chat, scoped to each repository.
Related MCP Servers
- AlicenseBqualityDmaintenanceA persistent memory layer for Claude Code that maintains project information, technology stack, tasks, decisions, and session history between coding sessions, eliminating the need to re-explain project context.9MIT
- AlicenseNot gradedqualityCmaintenancePersistent project memory + architectural decisions + pre-execution safety hooks for Claude Code. Local-only storage, multi-repo workspace, automatic knowledge extraction via background auditor.6 npm14MIT
- AlicenseNot gradedqualityDmaintenancePersistent memory for Claude Code ā a self-evolving knowledge layer that survives across sessions, grows from every conversation, and surfaces relevant context automatically.14MIT
- AlicenseNot gradedqualityDmaintenanceProvides persistent memory for Claude Code, automatically extracting and surfacing relevant context from past sessions to avoid re-explaining issues and decisions.MIT