内容
# 记忆服务器
一个 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器，为 Claude 提供持久的长期记忆，适用于单个项目范围内的会话。它存储会话摘要和结构化洞察在本地 SQLite 数据库中，以便 Claude 在每次新对话开始时能够回忆过去的决策、模式和错误。
## 概述
### 动机
Claude Code 在会话之间没有记忆。每次对话都从头开始——没有对上周做出的架构决策、调试过程中花费两个小时的问题或上一个功能中有效的模式的回忆。你最终会重复解释上下文、重新讨论已确定的决策，并看到 Claude 重复已经犯过的错误。
常见的解决方法是 `CLAUDE.md`：一个文件，开发者在其中记录架构、约定和指南，并在每个会话中加载。这个方法适用于稳定、高级别的上下文——但不适合在构建过程中积累的知识。学习内容很难在当时写成干净的 Markdown，文件会无限制地增长，文件中的所有内容都会在每个会话中加载，无论是否相关。 一个包含 500 行的 `CLAUDE.md` 文件，涵盖身份验证、数据库模式、前端约定和部署问题等所有内容，即使你只是在修复 CSS 错误时，也会出现在上下文中。
这个项目采用不同的方法：洞察在发生时被捕获并存储在结构化、可搜索的数据库中。在每个会话开始时，Claude 调用 `query_insights`，并带有与当前任务相关的过滤器——只提取实际适用的决策、模式和错误。其余的则不出现在上下文中。
### 益处
- **会话间的连续性** —— Claude 在不需要你重新解释的情况下回忆过去的决策、模式和错误
- **即时捕获** —— 洞察在发生时保存，而不是在会话结束时从逐渐消失的记录中重建
- **结构化回忆** —— 洞察被分类和标记，因此 `query_insights` 只提供相关的信息，而不是全部倾倒
- **零云依赖** —— 记忆存储在项目内的本地 SQLite 文件中；没有任何内容离开你的机器
- **低摩擦** —— 钩子自动捕获和回忆；配置完成后无需手动步骤
### 项目范围
该服务器故意限定为 **一次一个项目**。`PROJECT_PATH` 环境变量将数据库固定到特定目录，因此不同代码库的洞察永远不会混淆。
它 **不**：
- 在机器或团队成员之间同步内存
- 默认存储对话记录（通过 `write_session` 选择加入）
- 替换项目 wiki 或 ADR 流程 —— 它捕获 Claude 学到的东西，而不是人类做出的决定
- 提供跨项目搜索或全局内存层（每个项目使用单独的 MCP 服务器实例）
## 架构
> 来源：[architecture.excalidraw](architecture.excalidraw) —— 在 [Excalidraw](https://excalidraw.com) 中打开进行编辑。
## 工作原理
### 编写洞察
洞察的编写有两种方式：
- **会话结束** —— 会话停止钩子调用 `write_session` 以保存会话元数据（模型、持续时间、令牌计数）、叙述摘要和结果，以及从会话中提取的任何结构化洞察。
- **会话期间内联** —— Claude 在决策、模式、错误或学习发生时立即调用 `add_insight`，而不是等到会话结束。如果会话记录尚不存在，`add_insight` 会自动创建它。
每次洞察写入也会使用 `Xenova/all-MiniLM-L6-v2` 模型（384 维，在本地通过 `@huggingface/transformers` 运行）生成 **语义嵌入**。嵌入编码了洞察标题和正文的含义，并与文本一起存储在 `sqlite-vec` 虚拟表中（`insight_vec_v2`）。模型权重（~23 MB）会在首次使用时从 Hugging Face 下载，并在 `~/.cache/huggingface/` 中永久缓存。
### 查询洞察
在下一个会话开始时，Claude 调用 `query_insights` 以在开始工作之前提供相关的过去上下文。
当提供 `搜索` 术语时，`query_insights` 首先为查询生成嵌入，然后使用向量余弦距离在 `insight_vec_v2` 上运行 K-最近邻（KNN）查找。这会返回语义相关的洞察，即使确切的措辞不同 —— 例如，搜索 *"身份验证流程"* 可以显示一个洞察，标题为 *"在路由处理程序之前添加 JWT 验证门*"。其他过滤器（`type`、`tag`、`project_path`）应用于 KNN 结果之上以进一步缩小范围。
如果嵌入模型不可用或向量表为空，`query_insights` 会自动 fallback 到 SQL `LIKE` 子字符串匹配。可以为添加向量搜索之前编写的现有洞察使用 `reindex_insights` 进行回填。
## 工具
| 工具 | 描述 |
|------|-------------|
| `write_session` | 持久化一个带有摘要和洞察的已完成会话。从停止钩子调用。 |
| `add_insight` | 向会话中添加单个洞察（如果需要，自动创建会话）。在会话期间使用增量写入。 |
| `remove_insight` | 通过精确 ID 和/或精确标题删除洞察。至少提供一个；如果两者都提供，则两者必须匹配。 |
| `query_insights` | 按类型、标签、项目或语义自由文本搜索洞察。在会话开始时调用以回忆过去的上下文。 |
| `get_recent_sessions` | 列出带有摘要和洞察数量的最近会话。 |
| `get_session_detail` | 获取会话的完整详细信息，包括所有洞察和可选的记录。 |
| `reindex_insights` | 为添加向量搜索之前编写的洞察回填语义嵌入。 |
| `review_duplicates` | 扫描所有存储的洞察以查找重复项或近似重复项。当嵌入可用时使用向量相似性，否则使用标题词重叠（Jaccard）。返回带有 ID 的分组集群；将结果输送到 `remove_insight` 进行清理。 |
### 洞察类型
- `decision` —— 做出的架构或设计选择
- `pattern` —— 有效的重复方法
- `mistake` —— 犯过的错误以及如何避免它们
- `blocker` —— 遇到的障碍以及如何解决它们
- `learning` —— 会话期间获得的新知识
## 安装
### 先决条件
- Node.js 20+
- Claude Code CLI
### 市场安装（推荐）
如果此插件已发布到您添加的 Claude Code 市场：
```bash
/plugin marketplace add <marketplace-name-or-url>
/plugin install project-memory@<marketplace-name>
```
插件的 `SessionStart` 钩子会在 `dist/` 缺失或过时时自动构建 MCP 服务器（`npm ci && npm run build`）。如果 `npm` 不在 `PATH` 中，则会在上下文中出现一个响亮的错误——请从 https://nodejs.org 安装 Node.js >=20 并重启。
首次自动构建完成后，**请重启 Claude Code**，让 MCP 服务器加载新构建的 `dist/`。
### 传统安装（基于脚本，无市场）
构建服务器并通过 `~/.claude/settings.json` 连接所有钩子——无需手动 JSON 编辑。
```bash
git clone https://github.com/sukenshah/claude-code-project-memory.git
cd claude-code-project-memory
bash hooks/install.sh
```
重启 Claude Code 以激活。要卸载：
```bash
bash hooks/uninstall.sh
```
Windows:
```powershell
.\hooks\install.ps1
.\hooks\uninstall.ps1 # 卸载
.\hooks\reinstall.ps1 # 更新（见下文）
```
### 更新到最新版本
拉取新更改后，请重新安装插件以重建服务器并重新注册所有钩子：
```bash
git pull
bash hooks/reinstall.sh
```
Windows:
```powershell
git pull
.\hooks\reinstall.ps1
```
这会删除现有的 MCP 注册和钩子，重新构建服务器并重新注册所有内容。**您的项目内存数据库不受影响** —— 所有存储的洞察和会话历史都保留。
在重新安装后，请重启 Claude Code 以激活更新的插件。
### 首次运行：为现有项目填充内存
安装后，在 Claude Code 中运行此提示，从项目的根目录开始。它会扫描代码库并使用 project-memory MCP 工具为内存数据库填充洞察。
```
扫描此代码库并使用 project-memory MCP 工具填充项目内存中的洞察。
对于以下每个类别，提取具体、具体的洞察——不是 README 的摘要：
- **模式** （类型：pattern）：代码库中一致使用的重复成语、约定和方法。示例：如何处理错误、如何构建测试、命名约定、如何加载配置。
- **决策** （类型：decision）：代码中可见的架构或设计选择。示例：框架/库的选择、数据库模式设计、API 形状、文件组织原理。
- **学习** （类型：learning）：新贡献者需要了解的代码库中的非显式内容。示例：陷阱、约束、为什么没有使用看似更简单的解决方案。
步骤：
1. 探索仓库结构：入口点、关键目录、主要源文件、配置文件、测试。
2. 阅读足够的代码以提取真正的洞察——不是表面观察。
3. 对于每个洞察，使用 `add_insight` 调用，并带有特定的标题、详细的正文和相关的标签。
4. 目标是 10-20 个高信号洞察。跳过仅凭文件名即可推导的明显内容。
不要调用 `write_session` —— 仅限洞察。
```
这需要 2-5 分钟，具体取决于项目大小。完成后，未来的会话将以已经加载的相关上下文开始。
### 从手动配置迁移
如果您以前手动配置了此服务器，请在运行 `install.sh` 之前删除旧条目，以避免重复的 MCP 服务器和双重注入的钩子指令。
**1. 从 `~/.claude/settings.json`（或 `.mcp.json`）中删除旧的 MCP 服务器条目**：该键可能类似于 `"project-memory-mcp"` 或 `"project-memory"`：
```json
"mcpServers": {
"project-memory-mcp": { ... } ← 删除此条目
}
```
**2. 从 `~/.claude/settings.json`（或 `.claude/settings.json`）中删除旧的钩子条目**：删除包含 `printf`、`jq` 或 `project-memory-mcp` 的 `SessionStart`、`Stop` 和 `PreCompact` 块：
```json
"hooks": {
"SessionStart": [ { "matcher": "startup", "hooks": [ { "command": "jq -n ..." } ] } ], ← 删除
"Stop": [ { "matcher": "", "hooks": [ { "command": "printf 'SESSION END..." } ] } ], ← 删除
"PreCompact": [ { "matcher": "", "hooks": [ { "command": "printf 'PRE-COMPACT..." } ] } ] ← 删除
}
```
然后运行 `bash hooks/install.sh`。
### 手动设置
<details>
<summary>手动配置（高级）</summary>
1. 克隆并构建：
```bash
git clone https://github.com/sukenshah/claude-code-project-memory.git
cd claude-code-project-memory
npm run build
```
2. 在 `~/.claude.json` 中注册 MCP 服务器：
```json
{
"mcpServers": {
"project-memory": {
"command": "node",
"args": ["/absolute/path/to/claude-code-project-memory/dist/index.js"]
}
}
}
```
3. 将钩子添加到 `~/.claude/settings.json`：
```json
{
"hooks": {
"SessionStart": [
{
"matcher": "startup",
"hooks": [
{
"type": "command",
"command": "node \"/absolute/path/to/claude-code-project-memory/hooks/session-start.js\"",
"timeout": 10
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "node \"/absolute/path/to/claude-code-project-memory/hooks/user-prompt.js\"",
"timeout": 10
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "node \"/absolute/path/to/claude-code-project-memory/hooks/stop.js\"",
"timeout": 10
}
]
}
],
"PostCompact": [
{
"hooks": [
{
"type": "command",
"command": "node \"/absolute/path/to/claude-code-project-memory/hooks/post-compact.js\"",
"timeout": 10
}
]
}
]
}
}
```
</details>
## 数据库
SQLite 数据库存储在：
```
<PROJECT_PATH>/.claude/project-memory/insights.db
```
`PROJECT_PATH` 默认值为 `process.cwd()`，但可以通过 `PROJECT_PATH` 环境变量覆盖。数据库目录在首次运行自动创建。
## 开发
```bash
npm run dev # 使用 tsx 运行（无构建步骤）
npm run build # 将 TypeScript 编译为 dist/
npm start # 运行编译后的输出
```
## 许可证
MIT —— 见 [LICENSE](LICENSE)。
