Claude Code 与 Codex 来回切换时，怎样让“上次的决定”不丢：CogniKernel 的本地项目记忆实践
AI 编程进入多会话、多工具协作后，最容易反复消耗上下文的并不是“代码在哪”，而是“为什么当时这样决定”。例如，一个会话已经确认限流器必须用 Redis、某条迁移方案试过但应放弃、某个目录不能直接改；下一次换到另一个 Agent，往往又要重新读文件、翻提交记录，甚至再走一遍已经排除的死路。
CogniKernel 是一个面向 Claude Code 与 Codex 的本地项目记忆工具。它把值得保留的决策、约束和已放弃方案写入按项目路径组织的 SQLite 存储，再在下一次会话启动或按需查询时组装为紧凑上下文。项目采用 Apache-2.0 许可证，作者为 Kanishk Singh；它不是把整段聊天记录塞进向量库，也不是额外调用大模型做摘要。
这篇文章关注一个实际边界：如何把跨会话记忆做成可恢复的工程状态，而非另一个不透明的提示词黑盒。
它保存的不是“聊天记录”，而是有类型的项目事实
CogniKernel 的基本单位是带类型的事件。README 列出的核心类型包括：已经作出的 DECISION、硬/软约束 CONSTRAINT_HARD 与 CONSTRAINT_SOFT，以及 APPROACH_ABANDONED_DO_NOT_RETRY。最后一类尤其重要：它让“这个方案已经试过、不该重试”成为可检索事实，而非散落在旧会话里的口头提醒。
写入流程可概括为：清洗输入、分类和显著性判断、合并更新、持久化。工具为事实生成 decision key；新的同类事实如果代表决策变更，可按 latest-wins 规则取代旧版本。底层存储是 SQLite，README 明确提到 WAL、FTS5、事件溯源记录以及原子迁移。这样的组合意味着记忆可以被检查、清除和重放，而不会只能依赖某家模型的隐藏摘要。
检索也不是纯向量召回。默认以 FTS5 BM25 的词法检索为主；安装可选依赖后，才把稠密检索与词法结果通过 Reciprocal Rank Fusion 融合。对“不要做 X”这类约束，项目还保留了受类型限制的检索池，避免普通主题相关内容把禁止项挤出结果。这是与“把所有历史切块嵌入”不同的取舍：对代码约束和具体配置名，精确词法命中通常是有价值的。
先跑通最小闭环，再决定是否下载本地模型
官方 README 给出的安装与初始化命令如下。建议先在测试仓库试运行，确认它会写入哪些本地配置和 MCP 设置，再用于长期项目：
pip install "cognikernel[embedding]" cd /path/to/project cognikernel init . cognikernel install-heads cognikernel doctor .
init . 用于登记项目并安装 Claude Code、Codex 所需的集成配置；install-heads 下载两个微调的本地编码器权重；doctor . 则检查接线状态。完整模型路径使用两个 ONNX 编码器：一个判断句子是否值得保留及其类型，另一个判断新事实是否覆盖已有事实。README 标注单个模型约 130 MB，install-heads 的一次性下载约 270 MB，并提供 SHA-256 校验。
这里不要误解“无 LLM”——它指记忆提取过程本身不再额外向生成式模型发送会话文本，不是说 Claude Code 或 Codex 不需要模型。好处是没有为记忆层新增 API key、按会话 token 成本或云端文本外发；代价是分类能力取决于本地模型和规则，而不是开放式摘要的表达力。
如果暂时不执行 install-heads，工具仍可工作，但会退化到确定性的词法路径。README 将其定义为 fail-open：本地模型或记忆服务出错时，hook 记录 WARNING 后返回，编码会话继续而不是被记忆插件阻断。对生产项目，这是合理的优先级——辅助记忆不该成为编辑、构建和提交的单点故障。
Claude Code 自动捕获，Codex 需要同步：边界要说清
CogniKernel 在 Claude Code 中利用四个 hook 表面：会话启动时注入项目状态、提交提示时做相关记忆召回、工具调用前展示约束、会话结束时捕获决策。其中，写入/编辑前的提醒属于 just-in-time guardrail：它试图在即将触碰禁区时提示先前约束，而不是在几页上下文之后才让人发现偏离。
Codex 的集成方式不同。README 说明 Codex 没有等价的 Stop hook，因此它的历史捕获采用 pull 模式：扫描 ~/.codex/sessions 中与项目当前工作目录关联的记录，再通过同一提取管线写入存储。需要手动同步时可以执行：
cognikernel codex-sync /path/to/project cognikernel show /path/to/project cognikernel doctor --strict /path/to/project
这也解释了跨工具协作的真实能力边界：两个工具可共用同一逻辑项目的 SQLite 记忆，Codex 侧可通过 MCP 的 recall、find_related、skeleton、get_session_state 读取；但 Claude Code 那种逐提示、逐工具调用的即时提醒，并不会自动等价地出现在 Codex 中。把这层差异写进团队约定，比假定“装了就全自动同步”可靠得多。
把它当成项目状态层，而非自动真相机
这类工具最适合三种场景：长期维护的代码库；同一目录在 Claude Code 与 Codex 之间轮换；以及有明确架构约束、迁移禁区或历史失败方案的任务。它能降低重新发现上下文的成本，却不能替代代码审查、测试或文档。
让记忆有边界：哪些内容该进，哪些内容不该进
把记忆层接入编码会话，并不意味着应当把所有对话都视为项目知识。对团队而言，首先要区分三类信息：稳定的架构决定、在一段时间内有效的工程约束，以及仅属于当前排错过程的临时猜测。前两类适合被捕获或通过 MCP 查询；第三类若未经验证就长期保留，反而会把一次偶然的错误诊断变成后续 Agent 的错误前提。
一个简单做法是把可复核的依据写在决策附近：关联的 issue、测试名称、配置文件路径或代码模块。CogniKernel 的事件记录包含 evidence 与 provenance 的设计方向，但开发者仍应把“为什么这样做”的证据保留在仓库可审查的位置。记忆负责在正确时机找回上下文，版本控制、测试和设计文档仍负责定义事实。
也要提前确定清理策略。项目阶段切换、架构重写或分支长期分叉后，旧约束可能不再适用。此时可以先用 cognikernel show 检查现有内容，再按项目需要使用 README 提供的 reset 能力清理存储。不要为了追求“完整历史”让过期决定持续注入上下文；对于 Agent 来说，过期但措辞坚定的规则往往比缺失规则更危险。
用一次真实任务验收，而不是只看安装成功
启用后的第一周，可选一个跨两三次会话才能完成的小改动做验收：第一次会话明确记录一个目录边界、一个技术选择和一个被否决方案；第二次改用另一种 Agent 或在新窗口继续；最后检查它是否能够召回正确约束，并确认记忆不可用时编码流程仍能继续。doctor --strict 适合放在这类验收中观察健康状态，但不应把它替代为业务测试。
还应关注注入内容的长度与相关性。跨会话记忆的收益来自减少重新定位，而不是把更多历史塞进当前上下文。如果注入块经常包含无关旧任务，优先修正决策的粒度和项目边界；如果同一约束不断被误触发，则需要检查原始表述是否过于宽泛。把这些观察写入团队的使用约定，才能让本地记忆从个人插件演化成可协作的工程能力。
建议实践时建立两条规则。第一，进入记忆的约束应尽可能具体，例如“支付迁移必须保持双写两周”，而不是“注意兼容性”；前者能在检索和编辑前提醒中被准确判断。第二，决策变更后应明确记录新的理由，让 latest-wins 合并有可用依据；不要期待工具从模糊对话里永远猜对组织意图。
README 中还给出过多项目会话对比：相对于无记忆或平铺笔记，文件读取次数在所列项目中更少，部分场景的 token 消耗也更低。它同时承认小型、实现密集的任务可能没有明显收益。因此更稳妥的评估方法是先在一个持续数周的仓库启用，观察 doctor 状态、写入内容和实际减少的重复定位工作，再决定是否把它纳入团队默认配置。
CogniKernel 的价值不在于“记住一切”，而在于让已经确认的决策、硬约束与失败路径具备本地、可检索、可更新的生命周期。对频繁切换 AI 编程工具的开发者而言，这比在每个新会话开头重复贴一段项目背景更接近可维护的工程实践。