{
  "markdown": "# memory-mcp\n\n[![npm version](https://img.shields.io/npm/v/claude-code-memory.svg)](https://www.npmjs.com/package/claude-code-memory)\n[![npm downloads](https://img.shields.io/npm/dm/claude-code-memory.svg)](https://www.npmjs.com/package/claude-code-memory)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](tsconfig.json)\n\n**Persistent memory + automatic git snapshots for Claude Code.** Never lose context. Never lose code.\n\n```\n🧠 45 memories | 📊 2.8K tokens | 📸 23 snapshots | ⏱️ 5m ago\n```\n\n## Why memory-mcp?\n\n| Problem | Solution |\n|---------|----------|\n| Re-explaining your project every session | Auto-captures decisions, patterns, architecture |\n| Context window fills up, knowledge lost | Two-tier memory: CLAUDE.md (instant) + deep search |\n| Broke something, can't remember what worked | Git snapshots on every save, instant rollback |\n| No idea what Claude \"knows\" about your project | Visual dashboard shows all context |\n| Worried about cloud storage | 100% local files, your git repo |\n\n## What makes it different\n\n- **Git Snapshots** — Every memory save commits your entire project. Roll back anytime.\n- **Two-Tier Memory** — CLAUDE.md loads instantly, deep store searchable mid-conversation.\n- **LLM-Powered** — Haiku extracts what matters, consolidates duplicates, prunes stale info.\n- **Visual Dashboard** — See your context: tokens, memories by type, snapshot history.\n- **Zero friction** — No commands to run. It just works silently.\n\n## Quick Start\n\n```bash\n# Install globally\nnpm install -g claude-code-memory\n\n# Interactive setup (API key + hooks)\nmemory-mcp setup\n\n# Initialize a project\nmemory-mcp init ~/Projects/my-app\n```\n\nThat's it. Start coding. Memories accumulate automatically.\n\n## How It Works\n\n```mermaid\ngraph TB\n    subgraph \"Phase 1: Silent Capture\"\n        A[Claude Code Session] -->|User sends message| B[Claude responds]\n        B -->|Hook fires: Stop/PreCompact/SessionEnd| C[extractor.js]\n        C --> D[Read transcript from cursor]\n        D --> E[Chunk if >6000 chars]\n        E --> F[Send to Haiku LLM]\n        F -->|Extract memories as JSON| G[Dedup via Jaccard similarity]\n        G --> H[Save to .memory/state.json]\n        H --> I[Decay confidence scores]\n        I --> J{Consolidation needed?}\n        J -->|>80 memories or every 10 extractions| K[Haiku merges/drops]\n        J -->|No| L[Sync CLAUDE.md]\n        K --> L\n    end\n\n    subgraph \"Phase 2: Recovery\"\n        M[New session starts] -->|Built-in behavior| N[Claude reads CLAUDE.md]\n        N --> O[Claude has full project context]\n    end\n\n    subgraph \"Phase 3: Deep Recall\"\n        O --> P{Need specific context?}\n        P -->|memory_search| Q[Keyword search across memories]\n        P -->|memory_ask| R[Haiku synthesizes answer from top 30 matches]\n        P -->|memory_related| S[Tag-based retrieval]\n    end\n\n    subgraph \"Data Store\"\n        H -.-> T[(.memory/state.json<br/>Full memory store)]\n        L -.-> U[(CLAUDE.md<br/>~150 line summary)]\n        T -.->|MCP tools read| Q\n        T -.->|MCP tools read| R\n        T -.->|MCP tools read| S\n    end\n\n    style A fill:#4a9eff,color:#fff\n    style F fill:#ff6b6b,color:#fff\n    style K fill:#ff6b6b,color:#fff\n    style R fill:#ff6b6b,color:#fff\n    style T fill:#ffd93d,color:#000\n    style U fill:#6bcb77,color:#000\n```\n\n**Two-tier memory architecture:**\n\n| Layer | Purpose | Size |\n|-------|---------|------|\n| `CLAUDE.md` | Auto-read on session start. Top ~150 lines of the most important context. | Compact |\n| `.memory/state.json` | Full memory store. Searchable via MCP tools mid-conversation. | Unlimited |\n\n**Silent capture via hooks:**\n\nClaude 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:\n\n- **Architecture** — how the system is structured\n- **Decisions** — why X was chosen over Y\n- **Patterns** — conventions and how things are done\n- **Gotchas** — non-obvious pitfalls\n- **Progress** — what's done, what's in flight\n- **Context** — business context, deadlines, preferences\n\n**Smart memory management:**\n\n- Jaccard similarity deduplication (no duplicate memories)\n- Confidence decay (progress fades after 7 days, context after 30)\n- LLM-powered consolidation (merges overlapping memories, prunes stale ones)\n- Line-budgeted CLAUDE.md (stays under ~150 lines, most important first)\n\n## Updating\n\nTo update an existing installation:\n\n```bash\nnpm install -g claude-code-memory --force\n```\n\nTo update hooks (e.g., after a bug fix):\n\n```bash\nmemory-mcp setup\n```\n\n## Requirements\n\n- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)\n- Node.js 18+\n- Anthropic API key (for the Haiku-based extractor, ~$0.001 per extraction)\n\n## CLI Commands\n\n```\nmemory-mcp setup              Interactive first-time setup\nmemory-mcp init [dir]          Initialize memory for a project\nmemory-mcp status [dir]        Show memory status and health\nmemory-mcp statusline [dir]    Compact one-line status (great for shell prompts)\nmemory-mcp context [dir]       Show context metrics and token usage\nmemory-mcp context --html      Generate visual HTML dashboard\nmemory-mcp search <query>      Search memories by keyword\nmemory-mcp ask <question>      Ask a question, get answer from memory\nmemory-mcp consolidate [dir]   Merge duplicates, prune stale memories\nmemory-mcp key [api-key]       Set or check Anthropic API key\nmemory-mcp snapshots [dir]     List git snapshot history\nmemory-mcp snapshot-enable     Enable automatic git snapshots\nmemory-mcp snapshot-disable    Disable git snapshots\nmemory-mcp help                Show help\n```\n\n## Context Dashboard\n\nVisualize your memory usage with `memory-mcp context`:\n\n```\nContext Dashboard\n\n  Project: my-app\n\n  Total Context\n  2.8K estimated tokens\n\n  Tier 1 CLAUDE.md (auto-loaded)\n  █████████████████░░░░░░░░░░░░░ 1.0K\n  45 lines, 44 in memory block\n\n  Tier 2 .memory/state.json (searchable)\n  ██████████████████████████████ 1.8K\n  29 active, 5 archived, 24 superseded\n\n  Memories by Type\n  architecture ███░░░░░░░░░░░░░░░░░   8 memories (291 tokens)\n  decision     ██████░░░░░░░░░░░░░░  18 memories (540 tokens)\n  gotcha       ████░░░░░░░░░░░░░░░░  10 memories (332 tokens)\n  progress     ██████░░░░░░░░░░░░░░  19 memories (538 tokens)\n\n  Git Snapshots\n  ● Enabled on __memory-snapshots\n  42 commits → origin\n```\n\nUse `memory-mcp context --html` to generate an interactive browser dashboard.\n\n## Git Snapshots\n\nAutomatic project versioning tied to your working sessions. Every memory extraction commits your entire project to a hidden branch.\n\n```bash\n# Enable during init (you'll be prompted)\nmemory-mcp init ~/Projects/my-app\n\n# Or enable later\nmemory-mcp snapshot-enable\n\n# View snapshot history\nmemory-mcp snapshots\n\n# Compare two snapshots\nmemory-mcp snapshot-diff abc123 def456\n\n# Restore to a previous state\nmemory-mcp snapshot-restore abc123\n\n# Disable (preserves existing snapshots)\nmemory-mcp snapshot-disable\n```\n\n**How it works:**\n- Commits go to `__memory-snapshots` branch (invisible in normal workflow)\n- Optional push to remote (e.g., origin)\n- Commit messages include what memories were extracted\n- Full project state captured, not just memory files\n\n**Use cases:**\n- Roll back after breaking changes\n- See what your project looked like during a specific session\n- Track project evolution alongside context evolution\n\n## MCP Tools (used by Claude mid-conversation)\n\nWhen configured as an MCP server, Claude can access these tools during a session:\n\n| Tool | Description |\n|------|-------------|\n| `memory_search` | Keyword search across all memories |\n| `memory_related` | Get memories by tag or area |\n| `memory_ask` | Ask a question, get an LLM-synthesized answer from memory |\n| `memory_save` | Manually save a memory |\n| `memory_recall` | List all memories with filters |\n| `memory_delete` | Remove a memory |\n| `memory_consolidate` | Trigger memory consolidation |\n| `memory_consciousness` | Generate the full consciousness document |\n| `memory_stats` | Show memory statistics |\n| `memory_init` | Set project name and description |\n\n## What Gets Stored\n\nMemories are categorized into six types:\n\n```\narchitecture   \"Next.js 14 app router with Supabase backend, Stripe for billing\"\ndecision       \"Chose server components for public pages because of SEO requirements\"\npattern        \"All API routes validate input with zod and return NextResponse\"\ngotcha         \"Supabase RLS policy on word_lists requires user_id OR org_id, not both\"\nprogress       \"Auth complete, billing webhook handling in progress\"\ncontext        \"Client wants launch by March, focus on core features only\"\n```\n\n## File Structure\n\nAfter initialization, your project gets:\n\n```\nyour-project/\n├── CLAUDE.md              ← auto-updated memory summary (read on session start)\n├── .memory/\n│   ├── state.json         ← full memory store\n│   └── cursor.json        ← tracks what's been processed\n├── .mcp.json              ← MCP server configuration\n└── .claude/\n    └── settings.json      ← hook configuration\n```\n\n## CLAUDE.md Format\n\nThe memory block is inserted between markers, preserving any existing CLAUDE.md content:\n\n```markdown\n<!-- MEMORY:START -->\n# MyProject\nA brief description\n\n_Last updated: 2026-01-27 | 45 active memories, 62 total_\n\n## Architecture\n- Next.js 14 app router with Supabase backend\n- Auth via NextAuth with Google and email providers\n\n## Key Decisions\n- Chose server components for SEO pages\n- Using Supabase RLS instead of API-level auth\n\n## Patterns & Conventions\n- All API routes use zod validation\n- Tailwind only, no CSS modules\n\n## Gotchas & Pitfalls\n- RLS policy requires user_id OR org_id, not both\n\n## Current Progress\n- Auth: complete\n- Billing: in progress\n\n## Context\n- Launch target: March\n\n_For deeper context, use memory_search, memory_related, or memory_ask tools._\n<!-- MEMORY:END -->\n```\n\n## Global vs Per-Project Install\n\n**Global** (recommended): hooks work for all projects automatically.\n\n```bash\nmemory-mcp setup  # select \"global\" when prompted\n```\n\n**Per-project**: hooks and MCP configured per project.\n\n```bash\nmemory-mcp init /path/to/project\n```\n\n## Configuration\n\nAPI key is resolved in order:\n1. `ANTHROPIC_API_KEY` environment variable\n2. `~/.memory-mcp/config.json`\n3. `~/.config/anthropic/api_key`\n4. `~/.anthropic/api_key`\n\n## Cost\n\nThe extractor uses Claude Haiku for memory extraction and consolidation. Typical cost:\n\n- ~$0.001 per extraction (after each Claude response)\n- ~$0.005 per consolidation (every ~10 extractions)\n- A full day of coding: ~$0.05–0.10\n\n## License\n\nMIT\n",
  "bytes": 10785,
  "sha": "f19be6abdeac12272abf7b62ae13cd53167910b5dab3e6927a7b613c2c6dcc9c",
  "repo_slug": "yuvalsuede/memory-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_yuvalsuede_memory_mcp_cf2e5708/readme"
}