内容
# 会话回忆
本地、自主代理的**语义回忆，适用于 Claude Code 和 Codex 会话历史记录**。两个主机共用一个索引，因此任一代理都可以恢复由另一个代理创建的上下文。它为代理提供了五种工具（通过 MCP），以便其恢复过去的工作，而不是让您重新解释：
- `recall_search(query)` — 通过**含义**（而非子字符串）查找过去的讨论。
- `expand_around(session_id, uuid)` — 进入原始对话回合（工具调用、输出、思考）的光标。
- `step(session_id, uuid, direction)` — 移动到相邻的对话回合（廉价的光标步进）。
- `grep(pattern)` — 按需对**所有**索引的记录进行子字符串扫描，包括内部工具输出和思考过程，这些过程从未成为搜索块。
- `recent_sessions()` — 最新会话优先（当前会话、新鲜程度）。
按需（无 v1 主动自动注入）。本地、开源。
`recall_search`、`grep` 和 `recent_sessions` 还接受可选的 `scope_cwd` — 将当前工作目录传递给作用域结果以限定在当前仓库（工作树折叠到仓库根目录）；省略它以进行跨项目回忆。排名靠前的结果会附带人类可读的 `when_human` 时间戳以及原始纪元。每个 MCP 工具都接受可选的 `source`（`claude` 或 `codex`）；省略它以使用统一历史记录。结果包括源信息，如 `source=claude` 或 `source=codex`。这三个发现工具还接受 `on_date` 以限定一天或包含 `start_date` / `end_date`（`YYYY-MM-DD`）以及可选的 IANA `timezone`，以便代理可以将检索限定在实际的本地日历日期，而不是依赖语义查询影响排名。如果省略 `timezone`，会话回忆将使用运行 MCP 服务器的计算机的时区。
**状态：** v1，已构建并在真实历史记录上验证。主要设计原理在 [docs/decisions/](docs/decisions/) 中。
## 工作原理
来自 `~/.codex/sessions` 和 `~/.codex/archived_sessions` 的 Claude Code 记录和 Codex 会话共享相同的索引。
仅嵌入对话“表面” — 用户提示和助手文本回复。工具调用、结果、推理和其他跟踪数据不嵌入，但可通过 `expand_around`（和 `step`）或 `grep` 按需访问。原始 Codex 记录文件保留在本地；仅提取的对话表面被发送到配置的嵌入提供程序。
嵌入：Voyage `voyage-4-large`（维度 1024）→ SQLite（`sqlite-vec` KNN + FTS5，bm25 排名）→ Voyage `rerank-2.5` → top-k。索引是增量（按文件元数据，包括 Codex inode + 大小）的，对于实时记录非常廉价：它们是追加写入的，因此未更改的块通过内容哈希匹配并重用其向量 — 只有新回合才会命中嵌入 API。移动 Codex 发布到存档也会重用其现有向量。每个文件都在其自己的事务中索引；失败的文件将被记录并在下一次运行重试，永远不会中止其余文件。Claude 侧链（`<session>/subagents/`）和 Codex 生成的子代理会话被故意跳过 — 它们是内部工具，不是主要用户/代理对话。
嵌入是可插拔的（Voyage 是默认的）；重新排序器是可选的，并且系统在没有它时可以降级为 KNN + FTS。使用嵌入提供程序/模型切换时，会检测到（嵌入指纹是每个文件的索引签名的组成部分）并触发干净的重新嵌入，而不是静默混合向量空间。
## 安装/运行
对于与捆绑的 Claude Code/Codex 插件的正常使用，请在您的用户 `PATH` 上安装两个 CLI 入口点（清单还会检查 `~/.local/bin`）：
```bash
pipx install --editable .
export VOYAGE_API_KEY=... # 您的 Voyage 密钥
session-recall index # 两个来源（与 --source all 相同）
session-recall index --source claude # 仅 ~/.claude/projects
session-recall index --source codex # 活动 + 存档 Codex 会话
session-recall search "query" # 统一语义搜索
session-recall search "query" --source codex
session-recall recent --source claude # 最新 Claude 会话
session-recall recent --date 2026-07-14 # 使用此计算机的时区
session-recall search "deployment work" --start-date 2026-07-14 \
--end-date 2026-07-14 --timezone Asia/Yekaterinburg
session-recall grep "exact" --source codex --limit 100 # 原始扫描，无需 API
session-recall prune # 删除已删除记录的行
```
对于仓库开发或手动 MCP 注册，树内虚拟环境也适用：
```bash
python -m venv .venv && .venv/bin/pip install -e .
.venv/bin/session-recall index
```
`index --source` 接受 `all`、`claude` 或 `codex`，默认为 `all`。`search`、`recent`、`grep` 和 `prune` 接受可选的 `--source claude|codex`；省略它以适用于两者。`search`、`recent` 和 `grep` 接受 `--date` 以限定一天或 `--start-date`、`--end-date` 和 `--timezone` 以限定范围；范围日期是包含的，可以省略任一边界。时区默认为计算机的本地时区，可以使用 IANA 名称覆盖。原始 `grep` 默认最多返回 100 个匹配项；使用 `--limit` 调整上限。
### 连接到 Claude Code 或 Codex（MCP）
仓库包括 Claude Code 和 Codex 插件清单，适用于同一个 MCP 服务器和回忆技能。要手动在 Claude Code 中注册服务器：
```bash
claude mcp add session-recall --scope user -- \
/absolute/path/.venv/bin/python -m session_recall.server
```
服务器从环境中读取 `VOYAGE_API_KEY`。对于 Codex，`.codex-plugin/plugin.json` 清单已准备好放置在本地仓库或个人市场中；请遵循 [本地插件安装指南](https://learn.chatgpt.com/docs/build-plugins#install-a-local-plugin-manually)。在 Claude Code 中，通过 `claude mcp list` → `✔ Connected` 验证。启用插件后启动新的会话/任务，以便加载 MCP 工具和技能。
## 保持索引新鲜
索引是增量的（跳过已索引的文件），因此保持新鲜非常廉价。插件捆绑的 `SessionStart` 钩子与两个主机兼容，并在后台运行 `session-recall index`；默认 `--source all` 刷新两个历史记录。Codex 需要一次性审查/信任新安装或更改的钩子，方法是通过 `/hooks`。对于手动 Claude Code 钩子，请在 `~/.claude/settings.json` 中：
```json
"hooks": {
"SessionStart": [
{ "hooks": [ {
"type": "command",
"command": "sr=/abs/path/.venv/bin/session-recall; pgrep -f \"$sr index\" >/dev/null 2>&1 || (VOYAGE_API_KEY=... \"$sr\" index >/tmp/sr-index.log 2>&1 &)"
} ] }
]
}
```
`pgrep` 守护进程防止重叠运行；`( … & )` 分离进程，以便会话启动时不会等待。保持主机级钩子同步：shell 已经将索引器置于后台，而 Codex 忽略 Claude 的 `async` 扩展程序。`launchd`/cron 定时器是另一个选项。（本地在一台机器上足够；服务器端索引仅在多台机器上才有意义 — 代价是隐私和网络。）
## 隐私 — 硬不变性
这是公共仓库。**只有代码被放入其中。**
- 数据、索引、原始记录、嵌入 → `~/.local/share/session-recall/`，**在仓库树之外**。它们物理上无法提交。
- API 密钥 → 仅限环境（`VOYAGE_API_KEY`）；`.gitignore` 阻止 `.env`。
- 测试 → 合成夹具，仅限真实会话的切片。
- Claude Code 记录和活动及存档 Codex 记录在本地读取。仅用户/助手表面文本被嵌入；工具/推理跟踪数据保留在嵌入之外，仅通过显式原始扩展或 grep 访问。
- 块文本 **发送到您配置的嵌入/重新排序提供程序（默认为 Voyage）** — 选择您信任的提供程序来处理您的记录，或将 OpenAI 兼容的提供程序指向本地端点。
