内容
# 本地优先的 Claude Code 内存
适用于 [Claude Code](https://claude.com/claude-code) 的**私有内存**：助手自动保存重要的对话事实，在每次会话开始时调用它们，并能够根据这些事实进行语义搜索，同时**本地进行嵌入**（Ollama），不会向外发送任何多余信息。
三个核心组件：
1. **自动记忆** - 一个 markdown 文件夹，每个文件代表一个事实，附带索引 `MEMORY.md`。
2. **停止钩子** - 在会话结束前，模型会决定将哪些内容保存到记忆中。
3. **语义搜索** - 本地进行（Ollama + `nomic-embed-text`），作为 MCP 工具 `semantic_search` 对助手可用。无需外部向量数据库，只需一个 Python 脚本和一个薄 MCP 包装。
所有内容均适用于 **macOS**（对于 Linux，路径有所不同；无需 Keychain）。
---
## 内存结构
内存是一个 markdown 文件夹（默认为 `~/claude-memory/`）。规则：
- **一个文件 = 一个事实**，文件名是短的 `kebab-case` 标识符。
- 每个文件都有 **frontmatter**，包含 `name`、`description` 和 `metadata.type`。
- 索引 **`MEMORY.md`** 包含指向每个事实的链接；Claude Code 会在会话开始时将其加载到上下文中。
- Claude Code 通过 `settings.json` 中的 `autoMemoryDirectory` 设置了解记忆文件夹。
事实类型 (`metadata.type`)：
| 类型 | 存储内容 |
|-------------|-----------------------------------------------------------------------|
| `user` | 用户信息：角色、专业知识、偏好 |
| `feedback` | 助手的工作方式：规则、调整；总是包括“原因” |
| `project` | 当前任务/目标/限制，不从代码和 git 历史中导出 |
| `reference` | 外部资源链接（URL、仪表板、文档） |
记忆文件示例：
```markdown
---
name: prefers-typescript-strict
description: 用户始终希望在新项目中启用 TypeScript 的 strict 模式
metadata:
type: feedback
---
在新建项目时，始终在 tsconfig 中启用 `strict: true`。
**原因：** 在编译阶段捕获类型错误，用户坚持这样做。
**应用方式：** 初始化任何 TS 项目时，无需提醒即可启用 strict 模式。
```
`MEMORY.md` 中的一行：`- [标题](文件名.md) - 短链接`
---
## 安装
### 0. 依赖项
```bash
brew install jq # 用于钩子
brew install ollama # 或 https://ollama.com
ollama serve & # 在 127.0.0.1:11434 上启动
ollama pull nomic-embed-text
mkdir -p ~/claude-memory
printf '# Memory index\n' > ~/claude-memory/MEMORY.md
```
### 1. 自动保存停止钩子
复制 [`hooks/memory-save-on-stop.sh`](hooks/memory-save-on-stop.sh):
```bash
mkdir -p ~/.claude/hooks
cp hooks/memory-save-on-stop.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/memory-save-on-stop.sh
```
在 `~/.claude/settings.json` 中添加（与现有键合并，将 `$USER` 替换为您的用户名 - `echo $HOME` 将显示完整路径）：
```json
{
"autoMemoryDirectory": "/Users/<you>/claude-memory",
"hooks": {
"Stop": [
{ "hooks": [ { "type": "command",
"command": "/Users/<you>/.claude/hooks/memory-save-on-stop.sh",
"timeout": 30 } ] }
]
}
}
```
路径必须是绝对路径。重启 Claude Code。
### 2. 语义搜索
```bash
mkdir -p ~/semsearch
cp semsearch/semsearch.py semsearch/mcp_server.py ~/semsearch/
python3 ~/semsearch/semsearch.py reindex
python3 ~/semsearch/semsearch.py search "用户代码偏好"
```
### 3. Claude Code 中的 MCP 服务器
在 `~/.claude.json` 中的 `mcpServers` 部分添加（不要完全覆盖文件）：
```json
{
"mcpServers": {
"semsearch": {
"type": "stdio",
"command": "python3",
"args": ["/Users/<you>/semsearch/mcp_server.py"]
}
}
}
```
重启 Claude Code - 工具 `semantic_search` 就会出现。
---
## 使用
- **自动累积：** 在会话结束时，助手会将新事实累积到 `~/claude-memory`。
- **在开始时回忆：** `MEMORY.md` 被加载到新会话的上下文中。
- **按语义搜索：** 当有大量事实时，助手会调用 `semantic_search`。
- **定期** 运行 `python3 ~/semsearch/semsearch.py reindex` 以使搜索看到新事实（索引不会自动更新 - 如果需要，可以绑定到 cron 或 `SessionStart` 钩子）。
## 私有性
钩子和内存是本地文件。嵌入由本地 Ollama 计算，索引存储在磁盘上。
只有与 Claude Code 正常工作时才会向外发送信息。
## 可扩展性
引擎按来源构建（`semsearch.py` 中的 `ingest_memory`）。如果要索引其他内容（笔记、文档、工单）- 添加返回相同格式记录的 `ingest_*` 函数，并在 `reindex` 中启用它。
## 许可证
MIT - 见 [LICENSE](LICENSE)。
