Skip to content
Back to search

memory-mcp

Persistent memory for Claude Code — never lose context between sessions

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yuvalsuede--memory-mcp/badge.svg)](/listings/yuvalsuede--memory-mcp)

HTML

<a href="/listings/yuvalsuede--memory-mcp"><img src="/api/listings/yuvalsuede--memory-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Install globally
npm install -g claude-code-memory

# Interactive setup (API key + hooks)
memory-mcp setup

# Initialize a project
memory-mcp init ~/Projects/my-app

That's it. Start coding. Memories accumulate automatically.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 341 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # memory-mcp
  2. [![npm version](https://img.shields.io/npm/v/claude-code-memory.svg)](https://www.npmjs.com/package/claude-code-memory)
  3. [![npm downloads](https://img.shields.io/npm/dm/claude-code-memory.svg)](https://www.npmjs.com/package/claude-code-memory)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  5. [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
  6. [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](tsconfig.json)
  7. **Persistent memory + automatic git snapshots for Claude Code.** Never lose context. Never lose code.
  8. ```
  9. 🧠 45 memories | 📊 2.8K tokens | 📸 23 snapshots | ⏱️ 5m ago
  10. ```
  11. ## Why memory-mcp?
  12. | Problem | Solution |
  13. |---------|----------|
  14. | Re-explaining your project every session | Auto-captures decisions, patterns, architecture |
  15. | Context window fills up, knowledge lost | Two-tier memory: CLAUDE.md (instant) + deep search |
  16. | Broke something, can't remember what worked | Git snapshots on every save, instant rollback |
  17. | No idea what Claude "knows" about your project | Visual dashboard shows all context |
  18. | Worried about cloud storage | 100% local files, your git repo |
  19. ## What makes it different
  20. - **Git Snapshots** — Every memory save commits your entire project. Roll back anytime.
  21. - **Two-Tier Memory** — CLAUDE.md loads instantly, deep store searchable mid-conversation.
  22. - **LLM-Powered** — Haiku extracts what matters, consolidates duplicates, prunes stale info.
  23. - **Visual Dashboard** — See your context: tokens, memories by type, snapshot history.
  24. - **Zero friction** — No commands to run. It just works silently.
  25. ## Quick Start
  26. ```bash
  27. # Install globally
  28. npm install -g claude-code-memory
  29. # Interactive setup (API key + hooks)
  30. memory-mcp setup
  31. # Initialize a project
  32. memory-mcp init ~/Projects/my-app
  33. ```
  34. That's it. Start coding. Memories accumulate automatically.
  35. ## How It Works
  36. ```mermaid
  37. graph TB
  38. subgraph "Phase 1: Silent Capture"
  39. A[Claude Code Session] -->|User sends message| B[Claude responds]
  40. B -->|Hook fires: Stop/PreCompact/SessionEnd| C[extractor.js]
  41. C --> D[Read transcript from cursor]
  42. D --> E[Chunk if >6000 chars]
  43. E --> F[Send to Haiku LLM]
  44. F -->|Extract memories as JSON| G[Dedup via Jaccard similarity]
  45. G --> H[Save to .memory/state.json]
  46. H --> I[Decay confidence scores]
  47. I --> J{Consolidation needed?}
  48. J -->|>80 memories or every 10 extractions| K[Haiku merges/drops]
  49. J -->|No| L[Sync CLAUDE.md]
  50. K --> L
  51. end
  52. subgraph "Phase 2: Recovery"
  53. M[New session starts] -->|Built-in behavior| N[Claude reads CLAUDE.md]
  54. N --> O[Claude has full project context]
  55. end
  56. subgraph "Phase 3: Deep Recall"
  57. O --> P{Need specific context?}
  58. P -->|memory_search| Q[Keyword search across memories]
  59. P -->|memory_ask| R[Haiku synthesizes answer from top 30 matches]
  60. P -->|memory_related| S[Tag-based retrieval]
  61. end
  62. subgraph "Data Store"
  63. H -.-> T[(.memory/state.json<br/>Full memory store)]
  64. L -.-> U[(CLAUDE.md<br/>~150 line summary)]
  65. T -.->|MCP tools read| Q
  66. T -.->|MCP tools read| R
  67. T -.->|MCP tools read| S
  68. end
  69. style A fill:#4a9eff,color:#fff
  70. style F fill:#ff6b6b,color:#fff
  71. style K fill:#ff6b6b,color:#fff
  72. style R fill:#ff6b6b,color:#fff
  73. style T fill:#ffd93d,color:#000
  74. style U fill:#6bcb77,color:#000
  75. ```
  76. **Two-tier memory architecture:**
  77. | Layer | Purpose | Size |
  78. |-------|---------|------|
  79. | `CLAUDE.md` | Auto-read on session start. Top ~150 lines of the most important context. | Compact |
  80. | `.memory/state.json` | Full memory store. Searchable via MCP tools mid-conversation. | Unlimited |
  81. **Silent capture via hooks:**
  82. 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:
  83. - **Architecture** — how the system is structured
  84. - **Decisions** — why X was chosen over Y
  85. - **Patterns** — conventions and how things are done
  86. - **Gotchas** — non-obvious pitfalls
  87. - **Progress** — what's done, what's in flight
  88. - **Context** — business context, deadlines, preferences
  89. **Smart memory management:**
  90. - Jaccard similarity deduplication (no duplicate memories)
  91. - Confidence decay (progress fades after 7 days, context after 30)
  92. - LLM-powered consolidation (merges overlapping memories, prunes stale ones)
  93. - Line-budgeted CLAUDE.md (stays under ~150 lines, most important first)
  94. ## Updating
  95. To update an existing installation:
  96. ```bash
  97. npm install -g claude-code-memory --force
  98. ```
  99. To update hooks (e.g., after a bug fix):
  100. ```bash
  101. memory-mcp setup
  102. ```
  103. ## Requirements
  104. - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
  105. - Node.js 18+
  106. - Anthropic API key (for the Haiku-based extractor, ~$0.001 per extraction)
  107. ## CLI Commands
  108. ```
  109. memory-mcp setup Interactive first-time setup
  110. memory-mcp init [dir] Initialize memory for a project
  111. memory-mcp status [dir] Show memory status and health
  112. memory-mcp statusline [dir] Compact one-line status (great for shell prompts)
  113. memory-mcp context [dir] Show context metrics and token usage
  114. memory-mcp context --html Generate visual HTML dashboard
  115. memory-mcp search <query> Search memories by keyword
  116. memory-mcp ask <question> Ask a question, get answer from memory
  117. memory-mcp consolidate [dir] Merge duplicates, prune stale memories
  118. memory-mcp key [api-key] Set or check Anthropic API key
  119. memory-mcp snapshots [dir] List git snapshot history
  120. memory-mcp snapshot-enable Enable automatic git snapshots
  121. memory-mcp snapshot-disable Disable git snapshots
  122. memory-mcp help Show help
  123. ```
  124. ## Context Dashboard
  125. Visualize your memory usage with `memory-mcp context`:
  126. ```
  127. Context Dashboard
  128. Project: my-app
  129. Total Context
  130. 2.8K estimated tokens
  131. Tier 1 CLAUDE.md (auto-loaded)
  132. █████████████████░░░░░░░░░░░░░ 1.0K
  133. 45 lines, 44 in memory block
  134. Tier 2 .memory/state.json (searchable)
  135. ██████████████████████████████ 1.8K
  136. 29 active, 5 archived, 24 superseded
  137. Memories by Type
  138. architecture ███░░░░░░░░░░░░░░░░░ 8 memories (291 tokens)
  139. decision ██████░░░░░░░░░░░░░░ 18 memories (540 tokens)
  140. gotcha ████░░░░░░░░░░░░░░░░ 10 memories (332 tokens)
  141. progress ██████░░░░░░░░░░░░░░ 19 memories (538 tokens)
  142. Git Snapshots
  143. ● Enabled on __memory-snapshots
  144. 42 commits → origin
  145. ```
  146. Use `memory-mcp context --html` to generate an interactive browser dashboard.
  147. ## Git Snapshots
  148. Automatic project versioning tied to your working sessions. Every memory extraction commits your entire project to a hidden branch.
  149. ```bash
  150. # Enable during init (you'll be prompted)
  151. memory-mcp init ~/Projects/my-app
  152. # Or enable later
  153. memory-mcp snapshot-enable
  154. # View snapshot history
  155. memory-mcp snapshots
  156. # Compare two snapshots
  157. memory-mcp snapshot-diff abc123 def456
  158. # Restore to a previous state
  159. memory-mcp snapshot-restore abc123
  160. # Disable (preserves existing snapshots)
  161. memory-mcp snapshot-disable
  162. ```
  163. **How it works:**
  164. - Commits go to `__memory-snapshots` branch (invisible in normal workflow)
  165. - Optional push to remote (e.g., origin)
  166. - Commit messages include what memories were extracted
  167. - Full project state captured, not just memory files
  168. **Use cases:**
  169. - Roll back after breaking changes
  170. - See what your project looked like during a specific session
  171. - Track project evolution alongside context evolution
  172. ## MCP Tools (used by Claude mid-conversation)
  173. When configured as an MCP server, Claude can access these tools during a session:
  174. | Tool | Description |
  175. |------|-------------|
  176. | `memory_search` | Keyword search across all memories |
  177. | `memory_related` | Get memories by tag or area |
  178. | `memory_ask` | Ask a question, get an LLM-synthesized answer from memory |
  179. | `memory_save` | Manually save a memory |
  180. | `memory_recall` | List all memories with filters |
  181. | `memory_delete` | Remove a memory |
  182. | `memory_consolidate` | Trigger memory consolidation |
  183. | `memory_consciousness` | Generate the full consciousness document |
  184. | `memory_stats` | Show memory statistics |
  185. | `memory_init` | Set project name and description |
  186. ## What Gets Stored
  187. Memories are categorized into six types:
  188. ```
  189. architecture "Next.js 14 app router with Supabase backend, Stripe for billing"
  190. decision "Chose server components for public pages because of SEO requirements"
  191. pattern "All API routes validate input with zod and return NextResponse"
  192. gotcha "Supabase RLS policy on word_lists requires user_id OR org_id, not both"
  193. progress "Auth complete, billing webhook handling in progress"
  194. context "Client wants launch by March, focus on core features only"
  195. ```
  196. ## File Structure
  197. After initialization, your project gets:
  198. ```
  199. your-project/
  200. ├── CLAUDE.md ← auto-updated memory summary (read on session start)
  201. ├── .memory/
  202. │ ├── state.json ← full memory store
  203. │ └── cursor.json ← tracks what's been processed
  204. ├── .mcp.json ← MCP server configuration
  205. └── .claude/
  206. └── settings.json ← hook configuration
  207. ```
  208. ## CLAUDE.md Format
  209. The memory block is inserted between markers, preserving any existing CLAUDE.md content:
  210. ```markdown
  211. <!-- MEMORY:START -->
  212. # MyProject
  213. A brief description
  214. _Last updated: 2026-01-27 | 45 active memories, 62 total_
  215. ## Architecture
  216. - Next.js 14 app router with Supabase backend
  217. - Auth via NextAuth with Google and email providers
  218. ## Key Decisions
  219. - Chose server components for SEO pages
  220. - Using Supabase RLS instead of API-level auth
  221. ## Patterns & Conventions
  222. - All API routes use zod validation
  223. - Tailwind only, no CSS modules
  224. ## Gotchas & Pitfalls
  225. - RLS policy requires user_id OR org_id, not both
  226. ## Current Progress
  227. - Auth: complete
  228. - Billing: in progress
  229. ## Context
  230. - Launch target: March
  231. _For deeper context, use memory_search, memory_related, or memory_ask tools._
  232. <!-- MEMORY:END -->
  233. ```
  234. ## Global vs Per-Project Install
  235. **Global** (recommended): hooks work for all projects automatically.
  236. ```bash
  237. memory-mcp setup # select "global" when prompted
  238. ```
  239. **Per-project**: hooks and MCP configured per project.
  240. ```bash
  241. memory-mcp init /path/to/project
  242. ```
  243. ## Configuration
  244. API key is resolved in order:
  245. 1. `ANTHROPIC_API_KEY` environment variable
  246. 2. `~/.memory-mcp/config.json`
  247. 3. `~/.config/anthropic/api_key`
  248. 4. `~/.anthropic/api_key`
  249. ## Cost
  250. The extractor uses Claude Haiku for memory extraction and consolidation. Typical cost:
  251. - ~$0.001 per extraction (after each Claude response)
  252. - ~$0.005 per consolidation (every ~10 extractions)
  253. - A full day of coding: ~$0.05–0.10
  254. ## License
  255. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.