Claude Persistent Memory

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

______________________________________________________________________

特性

混合搜索 --BM25全文（FTS5）+向量语义相似度（sqlite-vec），组合排名（0.7向量+0.3BM25）

4通道检索 --拉动（MCP工具按需）+推动（通过用户提示、工具前、工具后的钩子自动注入）

LLM结构 --记忆自动结构化为 /// 通过Azure OpenAI实现XML格式

多项目隔离 --单个共享嵌入服务器按以下方式路由请求 dataDir每个项目都有自己的数据库，没有交叉污染。

自动聚类 --相似的记忆被分组，成熟的集群被合并成高置信度的巩固记忆

信心评分 --记忆通过验证反馈和使用模式获得/失去信心

本地优先 --所有数据都存储在SQLite本地。你的记忆永远不会离开你的机器。

快速开始

安装

# 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

安装后脚本会自动执行：

1. 生成 .claude-memory.config.js （项目配置）
2. 配置 .mcp.json （MCP服务器注册）
3. 配置 .claude/settings.json （5个生命周期挂钩）
4. 下载并验证嵌入模型（bge-m3，~2GB）
5. 通过launchd/systemd注册后台服务
6. 更新 .gitignore

在项目目录中打开Claude Code——内存已准备就绪。

备注：在安装过程中下载并验证嵌入模型（~2GB）。如果下载中断或模型损坏，安装将失败。只需重新运行 npm install 重试。

稍后配置

如果在安装过程中跳过Azure凭据：

npx claude-persistent-memory

从源代码安装

Click to expand

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

然后手动配置 .mcp.json 和 .claude/settings.json --看 配置.

建筑

┌─────────────────────────────────────────────────────────────┐
│                     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                       │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

多项目支持

嵌入服务器在所有项目中共享。每个请求都包含一个 dataDir 路由到正确项目数据库的参数：

• 嵌入模型 --加载一次，在所有项目中共享（~2GB RAM）
• 数据库连接 --合计每 dataDir，首次访问时创建（~5ms）
• 无交叉污染 --在项目A中搜索永远不会返回项目B的记忆

MCP工具

钩子

内存类型

内存生命周期

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

卸载

npx claude-persistent-memory-uninstall

或手动：删除 memory 从 .mcp.json，从中卸下内存挂钩 .claude/settings.json那么 npm uninstall @alex900530/claude-persistent-memoryThe .claude-memory/ 数据目录被保留——如果不再需要，请手动删除。

配置

中的所有设置 config.default.js （通过以下方式覆盖 .claude-memory.config.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
  },
};

项目结构

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

需求

• Node.js>=18
• macOS或Linux
• ~2GB RAM用于嵌入模型（bge-m3）
• ~2GB磁盘用于模型缓存(~/.cache/huggingface/transformers-js/)
• Azure OpenAI API访问（用于LLM结构化）

备注

• LLM提供者：目前仅支持Azure OpenAI。修改 services/llm-server.js 对于其他供应商。
• 港口：嵌入和LLM服务器默认为TCP 23811/23812。如果冲突，请更改配置。
• 多项目：所有项目共享一个嵌入服务器进程。模型加载一次；数据库由以下方式汇集 dataDir.
• 数据: .claude-memory/ 目录（包含 memory.db 以及日志）是自动创建的，并且每个项目都会自动忽略。

贡献

欢迎投稿！请阅读 贡献指南 在提交PR之前。

许可证

麻省理工学院