passbaton

# passbaton > **AI 编程代理的会话连续性。** 您的代理可以从中断的地方继续工作 — 无需再重复解释您的项目。 为 **Claude Code、OpenAI Codex CLI 和 Google Gemini CLI** 提供持久内存，共享一个本地数据库：自动上下文注入、压缩交接、语义搜索和错误→解决方案召回。零配置，零 API 成本，100% 本地。 [](https://www.npmjs.com/package/passbaton) [](https://www.npmjs.com/package/passbaton) [](https://opensource.org/licenses/MIT) **⚡ 一次安装 → 自动加载上下文 · 🧩 生存于压缩（无需重复解释） · 🔒 100% 本地，$0 API**  > **更名（v2.0.0）：** 该项目以前名为 `claude-session-continuity-mcp`。旧名称表明它仅适用于 Claude — 但它并非如此。 **Claude Code、Codex CLI 和 Gemini CLI 都是首要的，并共享一个本地内存。** 现有安装仍然有效：旧的 `claude-hook-*` 命令仍然作为别名提供。参见 [从 v1 迁移](#migrating-from-v1)。 ## 问题 每次新建一个会话 — 无论是在 Claude Code、Codex CLI 还是 Gemini CLI 中： ``` "这是一个 Next.js 15 项目，使用 App Router..." "我们决定使用 Server Actions，因为..." "上次我们正在处理身份验证系统..." "构建命令是 pnpm build..." ``` **5 分钟的上下文设置。每一次。** ## 解决方案 **全自动。** 生命周期钩子处理所有事情，无需手动调用 — 在 **Claude Code**、**OpenAI Codex CLI** 和 **Google Gemini CLI** 上，共享一个本地内存，以便上下文可以在这三个之间传递： ```bash # 会话开始 → 自动加载相关上下文 + 最近的会话历史 # 当询问时 → 自动注入相关记忆/解决方案 # 在对话过程中 → 跟踪活动文件 + 自动注入错误解决方案 # 在压缩时 → 结构化交接上下文以保持连续性 # 在退出时 → 从转录中提取提交、决定、错误修复对 ``` ``` ← 会话开始时的自动输出： # my-app - 会话恢复 📍 **状态**：实现注册表单 ## 最近的会话 ### 2026-02-28 **工作**：完成与 Google 提供商的 OAuth 集成 **提交**：feat：添加 OAuth 回调处理程序；修复：重定向 URI 配置 **决定**：使用 Server Actions 代替 API 路由 ### 2026-02-27 **工作**：建立身份验证基础 **下一步**：实现注册表单验证 ## 指令 - 🔴 始终使用 Zod 进行表单验证 - 📎 默认情况下使用 Server Components ## 关键记忆 - 🎯 决定了 App Router，使用 Server Actions - ⚠️ OAuth redirect_uri 不匹配 → 检查环境文件 ``` **零手动工作。** 上下文跟随你。 --- ## 为什么选择这个而非其他内存工具？ 大多数 Claude 内存工具依赖于 **显式工具调用**（“记住这一点”），一个 **云 API**，或一个 **后台 AI 工作程序**。这个工具故意不同： | | passbaton | 典型的云/AI 内存 MCP | |---|---|---| | **设置** | `npm i -g` → 钩子自动安装 | 手动服务器 + API 密钥 | | **触发器** | 5 个自动钩子（无需命令） | 您调用一个 `remember` 工具 | | **存储** | 100% 本地 SQLite | 云 / 外部服务 | | **API 成本** | **$0** — 本地嵌入 | 按令牌 / 订阅 | | **延迟** | < 5ms（设备上） | 网络往返 | | **隐私** | 永远不会离开您的机器 | 发送到提供商 | | **搜索** | FTS5 + 本地语义，KO/EN/JA 跨语言 | 各不相同 | 如果您想要零配置、离线、无成本的内存，那就在您工作时自动发生 — 就是这样。 ### 自动注入 vs. 显式搜索 还有一类优秀的 **本地搜索** 工具（例如 [ctx](https://github.com/ctxrs/ctx)）索引您的代理历史记录，以便您可以查询它（`search "failed migration"`）。这是互补的，而不是相同的工作： | | passbaton | 本地搜索工具（ctx 等） | |---|---|---| | **如何使用它** | **自动** — 上下文在会话开始时出现，无需命令 | 您（或代理）运行搜索查询 | | **压缩** | **PreCompact 钩子重新注入交接** → 压缩后无需重新解释上下文 | 不是它的工作（它是一个搜索索引） | | **最适合** | *在会话和压缩之间永不丢失线索*，无需手动干预 | *查找* 过去的特定决定/命令，按需 | 在您需要 **查找** 内容时使用搜索。当您希望上下文 **跟随您** 而无需询问时使用此工具。 --- ## Codex CLI 支持（v1.16.0+） 除了 Claude Code 之外，还支持 **OpenAI Codex CLI**。如果 `~/.codex` 存在， 安装程序在 `~/.codex/hooks.json` 中注册相同的钩子（SessionStart、UserPromptSubmit、PreCompact、Stop），并且钩子自动检测主机并发出正确的输出格式（Codex 的 `hookSpecificOutput.additionalContext`）。 共享相同的本地 `sessions.db`，因此上下文跨越两个代理：您在 Codex 中执行的操作在 Claude Code 中可用，反之亦然。 **范围：** 会话保存 + 上下文注入在两者上有效。Codex 文件更改跟踪（PostToolUse）尚未连接 — 会话保存已经通过转录分析涵盖了大部分内容。Codex 的 `transcript_path` 被视为不稳定的接口（它可能在启动时为 null），因此主机检测使用安装程序注入的 `--codex` 标记，而不是依赖路径。 --- ## Gemini CLI 支持（v1.17.0+） 还支持 **Google Gemini CLI**。如果 `~/.gemini` 存在，安装程序在 `~/.gemini/settings.json` 中注册钩子（SessionStart、BeforeAgent、PreCompress、SessionEnd — Gemini 的事件名称），保留您的其他设置。共享相同的本地 `sessions.db`，因此上下文跨越所有三个代理。 Gemini 的转录格式已针对真实的 `~/.gemini/tmp/.../chats/*.jsonl` 文件进行了验证 — 它使用 **两种格式**（一个扁平的 `{type, content}` 行和一个较旧的 `{"$set":{"messages":[…]}}` 差异行）；解析器处理这两种格式。像 Codex 一样，`transcript_path` 可能在启动时为 null，因此主机检测使用 `--gemini` 标记。 **诚实的范围说明：** 会话保存（SessionEnd）和上下文输出已验证工作。Gemini 的 `SessionStart` 上下文注入被记录为 **仅建议** 上游 ([gemini-cli#15413](https://github.com/google-gemini/gemini-cli/issues/15413)) — 如果您的 Gemini 构建不能在启动时渲染注入的上下文，那就是上游限制，而不是此工具。会话连续性仍然通过保存的历史记录工作。 --- ## 从 v1 迁移 如果您将此工具安装为 `claude-session-continuity-mcp`（v1.x），**没有任何问题** — v1 `claude-hook-*` 命令仍然作为别名在 v2 中提供。 要迁移到新名称： ```bash npm install -g passbaton # 安装新包 npm uninstall -g claude-session-continuity-mcp # 可选：删除旧包 ``` 安装程序会将您的钩子条目重写为 `passbaton-hook-*`，并删除旧的 `claude-hook-*` 行 — 它匹配两个名称，因此您不会最终得到重复的条目。您的现有 `sessions.db` 保持不变：**所有过去的会话、记忆和解决方案都保留。** 没有任何其他变化 — 相同的钩子，相同的数据库，相同行为。 --- ## 快速入门 > **需要 Node.js 22+。** 原生 `better-sqlite3` 依赖项仅为 Node 22、24 和 26（当前支持的版本 — Node 18 和 20 均为生命周期结束）提供预编译二进制文件。在较旧的 Node 上，它会回退到从源代码编译，这需要在没有构建工具的情况下失败。Node 22 及更高版本可以干净地安装，无需编译器。 ### 推荐：全局安装 ```bash npm install -g passbaton ``` **就是这样！** postinstall 脚本会自动： 1. 在 `~/.claude.json` 中注册 MCP 服务器 2. 在 `~/.claude/settings.json` 中安装 Claude 钩子 ### 为什么选择全局安装（`-g`）？ 此工具旨在跟踪 **所有 Claude Code 项目**，使用一个统一的数据库。 强烈建议全局安装，因为： | 原因 | 详情 | |---|---| | **单一事实来源** | 一个二进制文件服务于所有项目 — 项目之间没有版本漂移 | | **钩子是用户范围的** | `~/.claude/settings.json` 位于您的主目录中，而不是每个项目 | | **跨项目上下文** | `app-a` 和 `app-b` 的会话共享同一个数据库和搜索索引 | | **一次更新 = 刷新所有内容** | `npm install -g <latest>` 一次更新所有项目；无需在每个项目中重新安装 | | **`npm exec` 优先查找全局** | 钩子调用 `npm exec -- passbaton-hook-*`，无论当前工作目录如何，都可靠地找到全局包 | **重要：** 即使全局安装，您仍然可以 **为特定项目禁用钩子**（见下文）。 全局安装 ≠ 强制在每个项目上启用。 ### 为特定项目禁用钩子 全局安装并不意味着“在任何地方都启用”。您有三个控制层级： | 层级 | 文件 | 范围 | |---|---|---| | 1. 全局启用（默认） | `~/.claude/settings.json` | 所有项目 | | 2. 项目范围禁用 | `<project>/.claude/settings.json` | 整个团队（已提交） | | 3. 个人禁用 | `<project>/.claude/settings.local.json` | 仅限您（gitignored） | **要在特定项目中禁用钩子**，请创建具有空钩子数组的覆盖文件： ```json // <project>/.claude/settings.json（或 settings.local.json 用于个人禁用） { "hooks": { "SessionStart": [], "UserPromptSubmit": [], "PostToolUse": [], "PreCompact": [], "Stop": [] } } ``` 空数组覆盖全局设置 → 该项目的会话不再被跟踪。 ### 更新到新版本 ```bash npm install -g passbaton@latest ``` 这就是全部 — 所有项目在下一次 Claude Code 重启时都会采用新的二进制文件。 无需在每个项目中重新安装。 ### 替代：本地安装（不推荐） 如果您确实想要每个项目的本地安装（例如，为一个项目锁定版本）： ```bash cd <project> && npm install passbaton ``` 缺点：您必须在每个项目中单独安装，并且 `npm exec` 可能无法从钩子上下文中可靠地找到本地副本（依赖于 cwd）。坚持使用 `-g` 除非您有特定的原因。 ### 已安装内容 **MCP 服务器**（在 `~/.claude.json` 中）： ```json { "mcpServers": { "project-manager": { "command": "npx", "args": ["passbaton"] } } } ``` **Claude 钩子**（在 `~/.claude/settings.json` 中）： ```json { "hooks": { "SessionStart": [{ "hooks": [{ "type": "command", "command": "npm exec -- passbaton-hook-session-start" }] }], "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "npm exec -- passbaton-hook-user-prompt" }] }], "PostToolUse": [{ "matcher": "Edit", "hooks": [{ "type": "command", "command": "npm exec -- passbaton-hook-post-tool" }] }, { "matcher": "Write", "hooks": [{ "type": "command", "command": "npm exec -- passbaton-hook-post-tool" }] }], "PreCompact": [{ "hooks": [{ "type": "command", "command": "npm exec -- passbaton-hook-pre-compact" }] }], "Stop": [{ "hooks": [{ "type": "command", "command": "npm exec -- passbaton-hook-session-end" }] }] } } ``` **注意（v1.5.0+）：** 具有 5 个钩子的完整生命周期覆盖。使用 `npm exec --`，它优先查找本地 `node_modules/.bin`。 ### 已安装钩子（v1.5.0+） | 钩子 | 命令 | 功能 | |------|---------|----------| | `SessionStart` | `passbaton-hook-session-start` | 在会话开始时自动加载项目上下文 | | `UserPromptSubmit` | `passbaton-hook-user-prompt` | 自动注入相关记忆 + 过去的引用搜索 | | `PostToolUse` | `passbaton-hook-post-tool` | 跟踪活动文件（编辑、写入）+ 自动注入错误解决方案（Bash） | | `PreCompact` | `passbaton-hook-pre-compact` | 在压缩前结构化交接上下文 | | `Stop` | `passbaton-hook-session-end` | 从转录中提取提交、决定、错误修复对 | ### 手动钩子管理 ```bash # 检查钩子状态 npx passbaton-hooks status # 重新安装钩子 npx passbaton-hooks install # 删除钩子 npx passbaton-hooks uninstall ``` ### 3. 重启 Claude Code 安装完成后，重启 Claude Code 以激活钩子。 --- ## 功能 | 功能 | 描述 | |---------|-------------| | 🤖 **零手动工作** | Claude 钩子自动捕获/加载所有上下文 | | 🎯 **仅限优质记忆** | **（v1.10.0）** 仅限决策、学习、错误 — 无文件更改噪音 | | 🧠 **语义搜索** | 多语言-e5-small 嵌入（94+ 语言，384d） | | 🌍 **多语言** | 韩语/英语/日语 + 跨语言搜索（EN→KR，KR→EN） | | 🔗 **Git 集成** | 从转录中自动提取提交消息 | | 🕸️ **知识图谱** | 记忆关系（解决、原因、扩展...） | | 📊 **记忆分类** | 5 种类型：观察、决定、学习、错误、模式 | | ✅ **集成验证** | 一键执行构建/测试/ lint | | 📋 **任务管理** | 基于优先级的任务管理 | | 🔧 **自动错误→解决方案** | **（v1.12.0）** Bash 错误自动检测 → 注入过去的解决方案；会话结束时自动记录错误修复对 | | 💰 **令牌效率** | **（v1.11.0）** 从 UserPromptSubmit 中删除 loadContext（节省 24-60K 令牌/会话） | | 📑 **渐进式披露** | **（v1.11.0）** memory_search 返回索引第一，memory_get 获取完整内容 | | ⏳ **时间衰减** | **（v1.11.0）** 具有类型特定半衰期的记忆评分，以保持相关性 | | 📝 **结构化交接** | **（v1.10.0）** PreCompact 保存工作摘要、活动文件、待处理操作 | | 🚪 **智能会话结束** | **（v1.10.0）** 从转录中提取提交、决定、错误修复对 | | 🗑️ **自动噪音清理** | **（v1.10.0）** 自动删除过时的观察记忆（3d+） | | 🔍 **过去引用检测** | **（v1.8.0）** "저번에 X 怎么做的?" 自动搜索数据库 | | 📝 **用户指令提取** | **（v1.8.0）** 从提示中自动提取 "always/never" 规则 | --- ## 功能开关 — 所有功能均为可选 **（v2.1.0）** 每个功能都可以单独开启/关闭。配置存放在一个纯 JSON 文件中 (`~/.claude/passbaton.config.json`) — 与数据分开，因此在重置数据库时保持不变。没有文件 = 今日的默认值（对现有用户无影响）。 ```bash passbaton config # 打印一个分组的表，包含每个功能 + 开/关 passbaton config set patternMining on # 启用一个功能 passbaton config preset minimal # minimal | default | everything passbaton config reset # 恢复默认设置 passbaton config path # 打印活动配置文件路径 ``` 每个功能也有一个环境变量覆盖，用于一次性/CI使用：`PASSBATON_<FEATURE>=0`（例如，`PASSBATON_TRIGGERMATCHING=0`）优先于配置文件。 **默认启用（核心）** | 功能 | 键 | 它能做什么 | |---|---|---| | 会话开始注入 | `sessionStart` | 在启动时恢复之前的上下文 | | **压缩交接+** | `compactionHandover` | 在压缩前，带走您的工作状态 **以及热文件和上次构建状态** — 平台自动内存结构无法涵盖的空白 | | 会话持久化 | `sessionEnd` | 在退出时保存会话状态 | | 自动记忆浮现 | `autoInject` | 在启动时自动浮现相关的过去记忆 | | 任务跟踪 | `taskTracking` | 通过 MCP + 钩子读取/写入任务列表 | | **热点预预热** | `hotPathPrewarm` | 启动时显示您在这个项目中最常编辑的文件，按实际访问次数排名 | | **验证账本** | `verificationLedger` | 如果最近的会话使构建失败或问题未解决，则在启动时警告 | ### 跨代理（默认启用） | 功能 | 键 | 它能做什么 | |---|---|---| | 跨代理共享 | `crossAgentSync` | 跨Claude Code/Codex/Gemini共享一个本地数据库 | | 工具使用捕获 | `postToolCapture` | 观察工具使用以构建热点（低噪音） | ### 实验性（默认禁用 — 需要选择加入） | 功能 | 键 | 它能做什么 | |---|---|---| | 触发器匹配 | `triggerMatching` | 将提示关键词与自动注入解决方案（可能假阳性）匹配 | | 模式挖掘 | `patternMining` | 挖掘工作模式并建议工作流程（有偏见） | | 自动记忆存储 | `memoryAutoStore` | 从提示中自动写入观察记忆（噪音） | | 状态行 | `statusLineInject` | 在会话开始输出中追加一个passbaton状态行 | --- ### 工作原理 **SessionStart Hook** (`npx passbaton-hook-session-start`): - 自动检测项目： monorepo (`apps/project-name/`) 或单个项目 (`package.json` 根目录名称) - 从 `.claude/sessions.db` 加载上下文 - 注入：当前状态，**最近 3 个会话**，包含提交/决策/指令，待处理任务，过滤的关键记忆 - 自动清理过时记忆（3 天以上自动跟踪，14 天以上自动压缩） **UserPromptSubmit Hook** (`npx passbaton-hook-user-prompt`): - 在每次提示提交时运行 - **(v1.11.0)** 不再调用 loadContext() — 节省 24-60K tokens/会话 - 注入相关上下文（过滤：决策，学习，错误） **PostToolUse Hook** (`npx passbaton-hook-post-tool`): - 跟踪热点文件路径并更新 `active_context.recent_files` - **(v1.12.0)** 自动检测 Bash 错误 → 搜索解决方案数据库 → 注入过去的解决方案到上下文 - **不再创建观察记忆** （v1.10.0 — 消除 `[File Change]` 噪音） **PreCompact Hook** (`npx passbaton-hook-pre-compact`): - 构建结构化移交上下文：工作总结，活动文件，待处理操作，关键事实，最近错误 - **不再存储自动压缩记忆** （v1.10.0） **Stop Hook** (`npx passbaton-hook-session-end`): - 从 JSONL 转录中提取提交消息（`git commit -m` 模式） - 提取错误修复对（错误 → 3 消息内的解决方案） - **(v1.12.0)** 自动将错误→修复对记录到解决方案表以供未来重用 - 提取决策（“因为”，“而不是”，“选择”模式） - **(v1.11.0)** 单次转录解析（4 JSONL 读取 → 1） - 将结构化元数据存储在 `sessions.issues` 列的 JSON 中 ### 示例输出（会话开始） ```markdown # my-app - 会话恢复 📍 **状态**: 实现注册表单 🚧 **阻碍**: OAuth 回调 URL 问题 ## 最近会话 ### 2026-02-28 **工作**: 完成 OAuth 集成 **提交**: feat: 添加 OAuth 处理程序；fix: 重定向配置 **决策**: 使用 Server Actions 而非 API 路由 **下一步**: 实现表单验证 ## 指令 - 🔴 始终使用 Zod 进行验证 ## 待处理任务 - 🔄 [P8] 实现表单验证 - ⏳ [P5] 添加错误处理 ## 关键记忆 - 🎯 已决定使用应用路由器，使用 Server Actions - ⚠️ OAuth redirect_uri 不匹配 → 检查环境文件 ``` ### Hook 管理 ```bash # 检查状态 npx passbaton-hooks status # 重新安装 npx passbaton-hooks install # 删除 npx passbaton-hooks uninstall # 暂时禁用 export MCP_HOOKS_DISABLED=true ``` ### 过去引用检测（v1.8.0） 当您询问过去的工作时，`UserPromptSubmit` Hook 会自动搜索数据库： ``` 您： "저번에 인앱결제 어떻게 했어?" → Hook 检测到 "저번에" + 提取关键词 "인앱결제" → 搜索会话，记忆（FTS5），和解决方案 → 自动将匹配的结果注入上下文 ``` **支持的模式（韩语和英语）：** | 模式 | 示例 | |---------|---------| | 저번에/전에/이전에 ... 어떻게 | "저번에 CORS 에러 어떻게 해결했지?" | | ~했던/만들었던/해결했던 | "수정했던 로그인 로직" | | 지난 세션/작업에서 | "지난 세션에서 결제 구현" | | last time/before/previously | "How did we handle auth last time?" | | did we/did I ... before | "Did we fix the database migration before?" | | remember when/recall when | "Remember when we set up CI?" | **输出示例：** ```markdown ## 相关过去工作（从您的问题中自动检测） ### 会话 - [2/14] 카카오 로그인 앱키 수정, 인앱결제 IAP 플로우 수정 ### 记忆 - 🎯 [决策] 测试： 인앱결제 상품 등록 완료 ### 解决方案 - **IAP_BILLING_ERROR**: 通过 StoreKit 2 迁移解决 ``` ### 为什么使用 npm exec？（v1.4.3+） 以前的版本使用绝对路径或 `npx`： ```json // v1.3.x - 绝对路径（在多项目中损坏） "command": "node \"/path/to/project-a/node_modules/.../session-start.js\"" // v1.4.0-1.4.2 - npx（需要全局安装或访问 npm 注册表） "command": "npx passbaton-hook-session-start" ``` 现在我们使用 `npm exec --`： ```json "command": "npm exec -- passbaton-hook-session-start" ``` **`npm exec --` 首先查找本地 `node_modules/.bin`，然后回退到全局。** 与本地和全局安装配合使用，无需访问 npm 注册表。 --- ## 工具（v5 API）- 25 个专注的工具 ### 1. 会话生命周期（4）⭐ ```javascript // 会话开始 - 自动加载上下文 session_start({ project: "my-app", compact: true }) // 会话结束 - 自动保存上下文 session_end({ project: "my-app", summary: "Completed auth flow", modifiedFiles: ["src/auth.ts", "src/login/page.tsx"] }) // 查看会话历史 session_history({ project: "my-app", limit: 5 }) // 语义搜索过去的会话 search_sessions({ query: "auth work", project: "my-app" }) ``` ### 2. 项目管理（4） ```javascript // 获取项目状态和任务统计 project_status({ project: "my-app" }) // 初始化新项目 project_init({ project: "my-app" }) // 分析项目技术栈 project_analyze({ project: "my-app" }) // 列出所有项目 list_projects() ``` ### 3. 任务管理（4） ```javascript // 添加任务 task_add({ project: "my-app", title: "Implement signup", priority: 8 }) // 更新任务状态 task_update({ taskId: 1, status: "done" }) // 列出任务 task_list({ project: "my-app", status: "pending" }) // 从 TODO 注释中建议任务 task_suggest({ project: "my-app" }) ``` ### 4. 解决方案存档（3） ```javascript // 记录错误解决方案 solution_record({ errorSignature: "TypeError: Cannot read property 'id'", solution: "Use optional chaining: user?.id" }) // 查找类似解决方案（关键词或语义） solution_find({ query: "TypeError property", semantic: true }) // AI 驱动的解决方案建议 solution_suggest({ errorMessage: "Cannot read property 'email'" }) ``` ### 5. 验证（3） ```javascript // 运行构建 verify_build({ project: "my-app" }) // 运行测试 verify_test({ project: "my-app" }) // 运行所有（构建 + 测试 + lint） verify_all({ project: "my-app" }) ``` ### 6. 记忆系统（5） ```javascript // 存储分类记忆 memory_store({ content: "State management with Riverpod makes testing easier", type: "learning", // observation, decision, learning, error, pattern project: "my-app", tags: ["flutter", "state-management"], importance: 8, relatedTo: 23 // 连接到现有记忆 }) // 搜索记忆 — 返回索引（id, type, tags, score）以提高 token 效率 memory_search({ query: "state management test", type: "learning", semantic: true, // 使用嵌入相似性 limit: 10 }) // 通过 ID 获取完整记忆内容（v1.11.0） memory_get({ memoryId: 23 }) // 查找相关记忆（图 + 语义） memory_related({ memoryId: 23, includeGraph: true, includeSemantic: true }) // 获取记忆统计 memory_stats({ project: "my-app" }) ``` ### 7. 知识图（2） ```javascript // 用类型关系连接两个记忆 graph_connect({ sourceId: 23, targetId: 25, relation: "solves", // related_to, causes, solves, depends_on, contradicts, extends, example_of strength: 0.9 }) // 探索知识图 graph_explore({ memoryId: 23, depth: 2, relation: "all", // 或特定关系类型 direction: "both" // outgoing, incoming, both }) ``` ## 记忆类型 | 类型 | 描述 | 用例 | |------|-------------|----------| | `observation` | 代码库中发现的模式，结构 | "所有屏幕都分离在 features/ 文件夹中" | | `decision` | 架构，库选择 | "决定使用 SharedPreferences 进行缓存" | | `learning` | 新知识，最佳实践 | "Riverpod 更适合测试" | | `error` | 发生的错误和解决方案 | "Provider.read() 不会重建 → 使用 watch()" | | `pattern` | 循环的代码模式，约定 | "避免滥用 late 关键字" | ## 关系类型 | 关系 | 描述 | 示例 | |----------|-------------|---------| | `related_to` | 一般关系 | A 和 B 相关 | | `causes` | A 导致 B | 缓存决策 → 文件结构更改 | | `solves` | A 解决 B | Riverpod 学习 → 提供者错误修复 | | `depends_on` | A 依赖于 B | 文件结构 → 缓存决策 | | `contradicts` | A 与 B 冲突 | 两个设计决策冲突 | | `extends` | A 扩展 B | late 模式 → 扩展到 Riverpod 学习 | | `example_of` | A 是 B 的示例 | 特定代码是模式的示例 | --- ## 数据存储 `~/.claude/sessions.db` 处的 SQLite 数据库： | 表 | 目的 | |-------|---------| | `memories` | 分类记忆（观察，决策，学习，错误，模式） | | `memories_fts` | 全文搜索索引（FTS5） | | `memory_relations` | 知识图关系 | | `embeddings_v4` | 语义搜索向量（multilingual-e5-small，384d） | | `project_context` | 固定项目信息（技术栈，决策） | | `active_context` | 当前工作状态 | | `tasks` | 任务 backlog | | `solutions` | 错误解决方案存档 | | `sessions` | 会话历史 | --- ## 环境变量 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `WORKSPACE_ROOT` | - | 工作空间根路径（必填） | | `MCP_HOOKS_DISABLED` | `false` | 禁用 Claude Hooks | | `LOG_LEVEL` | `info` | 日志级别（debug/info/warn/error） | | `LOG_FILE` | - | 可选的文件日志路径 | --- ## 开发 ```bash # 克隆 git clone https://github.com/leesgit/passbaton.git cd passbaton # 安装 npm install # 构建 npm run build # 测试 npm test # 测试并覆盖 npm run test:coverage ``` --- ## 性能 | 指标 | 值 | |--------|-------| | 上下文加载（缓存） | **<5ms** | | 记忆搜索（FTS） | ~10ms | | 语义搜索 | ~50ms | | 构建验证 | 取决于项目 | --- ## 路线图 - [x] v2 API（15 个专注的工具） - [x] v4 API（24 个工具 - 记忆 + 图） - [x] v5 Claude Hooks（自动捕获） - [x] 具有类型关系的知识图 - [x] 记忆分类（6 种类型） - [x] 语义搜索（嵌入） - [x] 多语言模式检测（KO/EN/JA） - [x] Git 提交集成 - [x] 111 个测试（6 个测试套件） - [x] GitHub Actions CI/CD - [x] 多语言语义搜索（v1.6.0 - multilingual-e5-small） - [x] 跨语言搜索 EN↔KR（v1.6.0） - [x] 解决方案语义搜索（v1.6.0） - [x] 修复 Hook 设置文件路径（v1.6.1 - settings.json，而不是 settings.local.json） - [x] 自动迁移旧 Hook（v1.6.1） - [x] 修复 PostToolUse 匹配器格式为字符串（v1.6.3） - [x] 为新 Hook 格式修复 README 文档（v1.6.4） - [x] 空会话跳过和技术栈保存改进（v1.7.1） - [x] UserPromptSubmit Hook 中的过去引用自动检测（v1.8.0） - [x] 用户指令提取（“always/never”规则）（v1.8.0） - [x] 记忆质量大修 — 不再有 `[File Change]` 噪音（v1.10.0） - [x] PreCompact 中的结构化移交上下文（v1.10.0） - [x] 智能会话结束：从转录中提取提交/决策/错误修复（v1.10.0） - [x] 自动噪音清理（3 天以上的观察，14 天以上的自动压缩）（v1.10.0） - [x] 显示 3 个最近的会话，并带有结构化元数据（v1.10.0） - [x] Token 效率 - 从 UserPromptSubmit 中移除 loadContext，节省 24-60K tokens/会话（v1.11.0） - [x] 单次转录解析，4 JSONL 读取 → 1（v1.11.0） - [x] 具有类型特定半衰期的记忆评分的时间衰减（v1.11.0） - [x] 渐进式披露 - memory_search 返回索引，memory_get 获取完整内容（v1.11.0） - [x] 通过 Jaccard 相似性进行记忆巩固（v1.11.0） - [x] 自动错误→解决方案管道 - PostToolUse 检测 Bash 错误，注入过去的解决方案（v1.12.0） - [x] 会话结束自动记录错误修复对到解决方案表（v1.12.0） - [x] 跨项目解决方案搜索，当前项目优先（v1.12.0） - [ ] sqlite-vec 原生向量搜索（v2 - 当数据 > 1000 条记录时） - [ ] Web 仪表盘 - [ ] 云同步选项 --- ## 贡献 欢迎 PR！请： 1. 复刻仓库 2. 创建功能分支 3. 为新功能添加测试 4. 确保 `npm test` 通过 5. 提交 PR --- ## 许可证 [MIT](LICENSE) © Byeongchang Lee --- ## 致谢 - [模型上下文协议](https://modelcontextprotocol.io/) 由 Anthropic 提供 - [Xenova Transformers](https://github.com/xenova/transformers.js) 用于嵌入 --- <div align="center"> **如果这能帮助您避免重复解释您的项目，请考虑给它一个 ⭐ - 这真的有助于其他人找到它。** </div>