memorythreads

MemoryThreads [](https.com/v3velev/actions/workflows/ci.yml) **持久、可搜索的对话记忆，适用于 Claude Code 和 Codex。** MemoryThreads 是一个本地 MCP 服务器，能够自动捕获 Claude Code 和 OpenAI Codex 中的每个对话回合，并将其存储在一个 SQLite 数据库中，使得历史记录可以从任何未来的会话中立即搜索 - 混合 BM25（FTS5）+ 向量（sqlite-vec）召回，具有跨平台线程连续性。在 Claude Code 中开始工作，在 Codex 中继续工作，任一方都可以回忆起完整的共享历史。 无需云端，无需账户 - 所有内容都存储在您机器~/.claude/memory-server中。 --- ## 安装（一条命令） **前提条件：** Node.js 18.18+，以及一个 OpenAI API 密钥（仅用于本地嵌入）。 ```bash git clone https://github.com/v3velev/memorythreads ~/.claude/memory-server cd ~/.claude/memory-server && ./install.sh ``` 安装程序会提示您输入 OpenAI 密钥（或从环境变量中读取 `OPENAI_API_KEY`），然后执行以下操作： - 安装 npm 依赖项并写入 `.env` 文件 - 注册 **Claude Code**（`claude mcp add`）和 **Codex**（`codex/config.toml`）memory` MCP 服务器 - 在 `~/.claude/settings.json` 和 `~/.codex/hooks.json` 中安装捕获/召回 **钩子** - 安装 `/mt-*` **斜杠命令** - 在您的 `~/.claude/CLAUDE.md`（~/.codex/.md`）中添加 **Memory**，以便使用召回功能 - 启动 **后台工作进程**（为 launchd），该进程解析并嵌入转录文本安装程序是幂等的 - 可以安全地重新运行。，请重启 Claude Code /。 ### 使用您的 AI 您也可以将存储库交给您自己的 Claude Code，让它自己安装。粘贴以下内容： 从 https://github.comvelev/memorythreads 安装 MemoryThreads 内存服务器 - 将其到 `~/.claude/memory-server`，运行 `./install，并在询问时提供我的 OpenAI API 密钥。然后 MCP 服务器和钩子加载。 ### 将添加至您的 CLAUDE.md程序会插入此在 `<!-- memorythreads:start` 标记之间，因此重新运行不会重复）： ```markdown记忆（MemoryThreads 对话回合自动保存到中，并在所有过去的会话（Claude Code 和 Codex可搜索。 - 在猜测或询问用户关于不术语、文件、项目或过去的决定之前，请先调用_context(query, include_threads=true)`。 - `search_docs(query)` 搜索已摄入的参考文档。 - 使用 `/mt-save 将当前会话保存为；使用 `mt launch出和恢复书签。 ``` 完整的手动步骤和 Linux 说明SETUP.md](SETUP.md)。 --- ## 为什么 LLM 编程会话是无状态的 - 关闭终端，上下文就会MemoryThreads 解决了这个问题： - **无需重新解释recall_context("上周的身份验证错误")` 拉取实际的前几回合。 - **跨工具。** Claude Code 和写入并读取同一个内存，因此切换工具不会丢失线程。 - **自动。** 钩子在每个会话中捕获回合；您无需管理它。 - **快速 + 私有。** 本地 SQLite，FTS5 + sqlite-vec。您的对话永远不会离开您的机器。 --- ## 工作原理 ``` Claude Code ─┐ ┌─ recall_context / search_docs ├─ 钩子 ─► 作业队列 ─► ─► SQLite ◄─┤ (MCP 工具) Codex┘ （捕获 （解析 + 嵌入）─ mt launch （恢复） ``` 1. **捕获。** 会话钩子（Stop、PreCompact、UserPromptSubmit）会话的转录文本等待摄入。launchd 文件监视器（`incremental-sync.js`）还连续 Claude Code 回合。 2. **解析 + 嵌入 `worker.js` 解析转录文本（双格式：Claude Code JSONL 和 Codex rollout JSONL via `transcript-parser.js`），存储回合 + 线程，并将每个回合（OpenAI `text-embedding-3-small`，1536 维）嵌入 sqlite-vec 表中。 3. **召回。** MCP 服务器（`server.js`）公开 `recall_context`，它在回合/线程上运行混合 BM25 + 余弦搜索，并将匹配结果返回给模型。 4. **连续性。** `canonical_thread_id` 将 Claude Code 流和 Codex 流链接到一个逻辑 MemoryThread，因此在两个工具之间继续工作无需共享原生会话文件。 --- ## MCP 工具 | 工具 | 用途 | |---|---| | `recall_context(query, resolution=0, include_threads)` | 混合 BM25 + 向量搜索。`resolution` 0 = 原始回合（默认），1 = 完整线程，2 = 线程密钥交换。 | | `search_docs(query)` | FTS5 搜索已摄入的参考文档| `ingest_doc(source, tags?, title?)` | 添加参考文档（URL、llms.txt 或本地文件）。 | | `list_docs` / `delete_doc` | 管理已摄入的文档。 | | `save_thread(name, ...)` | 将当前会话保存为命名 MemoryThread。 | | `list_threads` / `activate_thread` / `delete_thread` | 管理和恢复书签。 | ### 斜杠命令和 CLI - `/mt-save <name>`，`/mt-list`，`/mt-delete <name>`，`/mt-doc-ingest <source>` - `mt launch` - 交互式选择器，恢复已保存的线程（`mt launch tmux` 进入 tmux 会话） - `mt browse` - TUI，浏览/筛选所有线程 - `mt status` - 数据库状态，工作进程状态，最近活动 - `mt doctor` - 完整健康检查（工作进程，作业积压，嵌入，钩子 + MCP 接线）。如果内存似乎已过期，请运行此命令 - 它会显示静默故障。会话启动钩子也会在摄入积压卡住时自动警告。 --- ## 数据模型 一个 SQLite 数据库（`data/memory.db`）。核心表：`threads`，`turns`，`turns_fts`（FTS5），`turn_embeddings`（sqlite-vec），以及 `saved_threads`，`active_memory_threads`，`docs`，`tool_，`summaries`，`recovery_buffer` 和 `jobs` 队列。完整的 DDL 请参见 [.md](SCHEMA.md回直接在对话回合上进行 - 没有提取的知识层。 --- ## 设置 请参见 [SETUP.md](SETUP.md) 以获取完整指南。简而言之： 1. `npm install` 2 `.env`（gitignored）中添加 `OPENAI_API_KEY=...`。 3. 注册 MCP 服务器：`clcp add --scope user memory node ~/.claude/memory-server`（以及 Codex 的 `~/.codex/config.toml` 中的 `[mcp_servers.memory]` 块）。 4.子块添加到 `~/.claude/settings.json` 和 `~/.codex/hooks.json`。 5. 通过 launchd 监视器启动工作进程。 ## 钩子 | 事件 | 脚本 | 角色 | |---|---|---| | `SessionStart` | `session-start-cold.sh` / `session-start-compact.sh` | 状态行；压缩恢复 | | `UserPromptSubmit` | `user-prompt-submit.cjs` | 注入相关先前回合 + 活动线程上下文 | | `` | `pre-compact.sh` | 在压缩前回合快照到 `recovery_buffer` | | `Stop` | `stop.cjs` | 将会话转录文本排队等待摄入 | 相同的钩子脚本适用于 Claude`settings.json`）和 Codex（`hooks.json`）。 --- ## 技术栈 Node.js（ES 模块）· better-sqlite3 · sqlite-vec · OpenAI 嵌入modelcontextprotocol/sdk SQLite FTS5。 隐私 所有数据均为本地`.env`（您的 API 密钥）和 `data/`（数据库）被 gitignored，永远不会被提交。