# Claude Persistent Memory > Give Claude Code persistent memory across sessions. Hybrid BM25 + vector semantic search, auto-structuring via LLM, and 4-channel retrieval (MCP + hooks). Your AI assistant finally remembers. - **Type:** MCP server - **Install:** `agentstack add mcp-mimi180306-claude-persistent-memory` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [MIMI180306](https://agentstack.voostack.com/s/mimi180306) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [MIMI180306](https://github.com/MIMI180306) - **Source:** https://github.com/MIMI180306/claude-persistent-memory - **Website:** https://mimi180306.github.io/claude-persistent-memory/index.html ## Install ```sh agentstack add mcp-mimi180306-claude-persistent-memory ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Claude Persistent Memory Give Claude Code long-term memory that persists across sessions. Hybrid BM25 + vector semantic search · LLM-driven structuring · Multi-project isolation = 18"> English | 中文 Features • Quick Start • Architecture • MCP Tools • Configuration • Contributing --- ## Features **Hybrid Search** — BM25 full-text (FTS5) + vector semantic similarity (sqlite-vec), combined ranking (0.7 vector + 0.3 BM25) **4-Channel Retrieval** — Pull (MCP tools on demand) + Push (auto-inject via hooks on user prompt, pre-tool, post-tool) **LLM Structuring** — Memories auto-structured into `///` XML format via Azure OpenAI **Multi-Project Isolation** — Single shared embedding server routes requests by `dataDir`. Each project has its own database, no cross-contamination. **Automatic Clustering** — Similar memories grouped, mature clusters merged into high-confidence consolidated memories **Confidence Scoring** — Memories gain/lose confidence through validation feedback and usage patterns **Local-First** — All data stored locally in SQLite. Your memories never leave your machine. ## Quick Start ### Install ```bash # Set Azure OpenAI credentials (required for LLM structuring) export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com" export AZURE_OPENAI_KEY="your-api-key" # Install in any project npm install @alex900530/claude-persistent-memory ``` The postinstall script automatically: 1. Generates `.claude-memory.config.js` (project config) 2. Configures `.mcp.json` (MCP server registration) 3. Configures `.claude/settings.json` (5 lifecycle hooks) 4. Downloads and verifies the embedding model (bge-m3, ~2GB) 5. Registers background services via launchd/systemd 6. Updates `.gitignore` Open Claude Code in the project directory — memory is ready. > **Note**: The embedding model (~2GB) is downloaded and verified during install. If the download is interrupted or the model is corrupt, install will fail. Simply re-run `npm install` to retry. ### Configure later If you skipped Azure credentials during install: ```bash npx claude-persistent-memory ``` ### Install from source Click to expand ```bash git clone https://github.com/MIMI180306/claude-persistent-memory.git cd claude-persistent-memory npm install cp config.default.js config.js # Edit config.js with your Azure credentials # Start services npm run embedding-server # Terminal 1 npm run llm-server # Terminal 2 ``` Then manually configure `.mcp.json` and `.claude/settings.json` — see [Configuration](#configuration). ## Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Claude Code Session │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Pull Channel (on demand) Push Channels (auto) │ │ ┌───────────────────┐ ┌──────────────────────────────┐ │ │ │ MCP Server │ │ UserPromptSubmit Hook │ │ │ │ memory_search │ │ PreToolUse Hook │ │ │ │ memory_save │ │ PostToolUse Hook │ │ │ │ memory_validate │ │ PreCompact Hook (analysis) │ │ │ │ memory_stats │ │ SessionEnd Hook (clustering) │ │ │ └────────┬──────────┘ └──────────────┬───────────────┘ │ │ │ │ │ │ └──────────┬───────────────────┘ │ │ │ dataDir routing │ │ ▼ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ Shared Embedding Server (TCP :23811) │ │ │ │ bge-m3 model (shared across projects) │ │ │ │ Database pool (per-project by dataDir) │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────┼──────────────┐ │ │ ▼ ▼ ▼ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │Project A│ │Project B│ │Project C│ │ │ │memory.db│ │memory.db│ │memory.db│ │ │ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ LLM Server (TCP :23812) │ │ │ │ Azure OpenAI GPT-4.1 │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### Multi-Project Support The embedding server is shared across all projects. Each request carries a `dataDir` parameter that routes to the correct project's database: - **Embedding model** — loaded once, shared across all projects (~2GB RAM) - **Database connections** — pooled per `dataDir`, created on first access (~5ms) - **No cross-contamination** — searching in Project A never returns Project B's memories ## MCP Tools | Tool | Description | |------|-------------| | `memory_search` | Hybrid BM25 + vector search. Params: `query`, `limit?`, `type?`, `domain?` | | `memory_save` | Save a new memory. Params: `content`, `type?`, `domain?`, `confidence?` | | `memory_validate` | Feedback loop — helpful (+0.1) or unhelpful (-0.05). Params: `memory_id`, `is_valid` | | `memory_stats` | System stats: total memories, type/domain distribution, cluster status | ## Hooks | Hook | Event | Timeout | What it does | |------|-------|---------|-------------| | `user-prompt-hook.js` | UserPromptSubmit | 1500ms | Embeds user query, searches, injects top memories via stdout | | `pre-tool-memory-hook.js` | PreToolUse | 300ms | Embeds tool context, searches, injects via `additionalContext` | | `post-tool-memory-hook.js` | PostToolUse | 300ms | Embeds tool context + result, searches, injects via `additionalContext` | | `pre-compact-hook.js` | PreCompact | async | Spawns LLM analysis of full transcript, extracts memories | | `session-end-hook.js` | SessionEnd | async | Incremental transcript analysis + clustering + mature cluster merging | ## Memory Types | Type | Use case | |------|----------| | `fact` | Stable facts about the codebase | | `decision` | Architectural decisions and rationale | | `bug` | Bug fixes and root causes | | `pattern` | Recurring code patterns | | `context` | Session-specific context | | `preference` | User workflow preferences | | `skill` | Promoted from mature clusters | ## Memory Lifecycle ``` Save → memory_save or auto-extract from transcript Structure → LLM converts to /// XML Embed → bge-m3 generates 1024-dim vector Dedupe → Jaccard similarity >= 0.95 → update existing Search → 0.7 * vectorSimilarity + 0.3 * normalizedBM25 Validate → memory_validate adjusts confidence ± Cluster → similar memories auto-grouped Merge → mature clusters consolidated into single memory ``` ## Uninstall ```bash npx claude-persistent-memory-uninstall ``` Or manually: remove `memory` from `.mcp.json`, remove memory hooks from `.claude/settings.json`, then `npm uninstall @alex900530/claude-persistent-memory`. The `.claude-memory/` data directory is preserved — delete manually if no longer needed. ## Configuration All settings in `config.default.js` (override via `.claude-memory.config.js`): ```js module.exports = { embeddingPort: 23811, // TCP port for embedding server llmPort: 23812, // TCP port for LLM server dataDir: './data', // memory.db location (per-project) azure: { endpoint: process.env.AZURE_OPENAI_ENDPOINT, apiKey: process.env.AZURE_OPENAI_KEY, deployment: 'gpt-4-1', }, embedding: { model: 'Xenova/bge-m3', // 1024 dimensions, 8192 token context dimensions: 1024, }, search: { maxResults: 3, // top-K results per query minSimilarity: 0.6, // vector similarity threshold }, cluster: { similarityThreshold: 0.70, // min similarity to join a cluster maturityCount: 5, // memories needed for mature cluster }, }; ``` ## Project Structure ``` claude-persistent-memory/ ├── bin/ │ ├── setup.js # postinstall + interactive setup │ └── uninstall.js # cleanup script ├── hooks/ │ ├── user-prompt-hook.js # UserPromptSubmit → memory injection │ ├── pre-tool-memory-hook.js # PreToolUse → memory injection │ ├── post-tool-memory-hook.js # PostToolUse → memory injection │ ├── pre-compact-hook.js # PreCompact → transcript analysis │ └── session-end-hook.js # SessionEnd → clustering + merging ├── lib/ │ ├── memory-db.js # SQLite + FTS5 + sqlite-vec + connection pool │ ├── embedding-client.js # TCP client for embedding server │ ├── llm-client.js # TCP client for LLM server │ ├── compact-analyzer.js # Transcript → memory extraction │ └── utils.js ├── services/ │ ├── embedding-server.js # Shared embedding service (bge-m3) │ ├── llm-server.js # LLM proxy (Azure OpenAI) │ └── memory-mcp-server.js # MCP server (stdio, per-project) ├── config.default.js └── package.json ``` ## Requirements - Node.js >= 18 - macOS or Linux - ~2GB RAM for embedding model (bge-m3) - ~2GB disk for model cache (`~/.cache/huggingface/transformers-js/`) - Azure OpenAI API access (for LLM structuring) ## Notes - **LLM provider**: Currently supports Azure OpenAI only. Modify `services/llm-server.js` for other providers. - **Ports**: Embedding and LLM servers default to TCP 23811 / 23812. Change in config if conflicting. - **Multi-project**: All projects share one embedding server process. The model is loaded once; databases are pooled by `dataDir`. - **Data**: `.claude-memory/` directory (containing `memory.db` and logs) is auto-created and gitignored per project. ## Contributing Contributions welcome! Please read the [Contributing Guide](CONTRIBUTING.md) before submitting a PR. ## License [MIT](LICENSE) ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [MIMI180306](https://github.com/MIMI180306) - **Source:** [MIMI180306/claude-persistent-memory](https://github.com/MIMI180306/claude-persistent-memory) - **License:** MIT - **Homepage:** https://mimi180306.github.io/claude-persistent-memory/index.html Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-mimi180306-claude-persistent-memory - Seller: https://agentstack.voostack.com/s/mimi180306 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.