cognikernel

CogniKernel **持久、结构化的项目记忆，适用于 Claude Code 和 Codex。** CogniKernel 通过其钩子表面监视编码会话，提取值得保留的 *决策、约束和放弃的方法*，将它们合并到事件源存储中，并在下次工作时将其注入为一个紧凑的上下文块，以便代理停止重新决定您。存储按键是项目路径，因此在一个工具中创建可以传递到另一个工具。 它**不是**矢量数据库包装器。它是一个事件源日志，记录 *类型化的* 记忆，具有词汇优先检索、写入时合并和一个可靠性脊柱，旨在永远不会破坏您的会话。 **并且循环中没有 LLM。** 大多数记忆工具通过将您的转录发送到生成模型来“总结重要的内容”——另一个 API 密钥、每个会话的令牌成本、增加的延迟，以及您的会话内容离开机器。CogniKernel 将提取视为 *分类，而不是生成*：一个确定性的清理 → 分类 → 合并管道，带有两个小型微调编码器模型（~130 MB ONNX，在 CPU 上运行），用于评分显著性和检测新决策何时取代旧决策。无需 API 调用，无需计费，机器上离开。涉及的唯一 LLM 是您已经运行的编码代理——CogniKernel 使其记住。 > **命名：** CogniKernel 是项目；`memlora`（包 `memlora-edge`）是它附带的 Python 模块和 CLI — 代码在此名称下开发。 一个项目，两个名称：`memlora init`、`memlora doctor`等。 --- ## 记忆循环 CogniKernel 所做的一切都是一个**观察 → 提取 → 合并 → 存储 → 装配 → 注入左侧栏捕获；右侧栏回忆；下面的脊柱使两者保持一致。 +========================= CODE 会话 =========================+ | 工作 - 代理推理的上下文窗口 | +--------------+-----------------------------------------+ | 停止钩子捕获转录 | 注入块 ^ +--------------+---------------+ +---------------+--------------+ |] 提取管道 | [6] 压缩 + 注入 | 清 分类 -> | | 权限加权预算， | |显著性（ON-> | 降级以适应（保留每个 | | 决策键 + 合同 约束）-> 块 | ---------------+ +--------------+ |队 | 排名 + 适应 v ^ +--------------+---------------+ +---------------+--------------+ | [2] 工作线程 + 合并 | |] 检索 | 声明 -> 增量合并 -> | | FTS5 BM25 + 密集 -> RRF | | 取代（最新胜出）-> | | 禁止搜索（K1） | | 项目 （幂等） | | 骨架图（PageRank） | +--------------+---------------+ +--------------+ | 持久（原子） 忆 v +--------------+-----------------------------------------+--------------+ | [3] 事件源存储 * SQLite（WAL） | | 类型事件 | 证据 | 来源 | FTS5 | 嵌入 | 账本 | ------+ | [4] 可靠性脊柱 原子迁移 | 幂等重放 | | | doctor --strict | 故障开放 | 导入检查 | CI 门控 | ----------------------------------------------------------------------+ ``` --- ## 四个钩子表面ogniKernel 附加到会话的四个点上。每个都是故障开放的——如果内存不可用或出错子记录在 `WARNING`，干净地返回，会话继续。 | 表面钩子 | 权限 | 它能做什么 | |---|---|---|---| | **会话块 `SessionStart` | 咨询 | 注入规范的决策/约束/骨架块 | | **CK-1 回忆** | `UserPromptSubmit` | 咨询 | 表面提示相关记忆，双重证据门控，通过渲染账本去重 | | **读取/编辑门控** | `PreToolUse` | **硬 / JIT** | 读取效率门控；**即时禁止表面** 在写入/编辑（K2）上 | | **捕获** | `Stop` | 副作用 | 提取化决策 - 您永远不会手动编写记忆到 CLAUDE.md | --- ## 记忆的内容 记忆是 **类型化，而不是自由文本块。类型驱动排名、渲染和取代： - `DECISION` — 做出的选择（“使用 Redis 作为速率限制器”） - `CONSTRAINT_HARD `CONSTRAINT_SOFT` — 规则，按义务力分级 - `APPROACH_ABANDONED_DO_NOT_RETRY` — 一个死胡同，保存在 **墓地** 中，以免代理重试 - 约定，配置事实，模式决策（规范角色键） 一个 **决策键** 让后续的重述 *取代* 早期重述（最新胜出），因此存储自我合并而不是积累矛盾。可选的交叉编码器在安装编码器后端时添加语义取代。 --- ## 检索 词汇优先，具有密集信号融合 - 纯矢量： - **混合核心** — FTS5 BM25 ∪ 可选 → 互惠 - **禁止搜索 一个类型受限的，因此“不要做 X”的规则不会被主题相似的内容淹没 - **骨架** — 一个 AST 符号图，按 PageRank 排名；`find_related` 联合 **语义（嵌入）邻居** 和 **导入图相邻** 事件，以显示更改影响的内容（语义轴需要 `embedding` 额外） - **读取时的金色记录合并** — 最新胜出协调，因此回忆返回一个连贯的答案，而不是一堆修订 --- ## 它为您节省了什么 在三个组中基准测试 - CogniKernel 与平面精选笔记与无记忆 - 具有四个多会话项目的真实代理会话： - **文件读取：普遍胜利。** CogniKernel 组的文件读取次数最少 - 通常 **2–4× 少**（23 vs 63，16 vs 47/53，40 vs 89/83），在最佳情况下 **3 次读取 vs 29**，因为注入块 + AST 骨架承载了整个存储库的形状。文件读取次数越少，工具往返次数越少，上下文窗口中留下的实际工作空间越大 - 会话在压缩之前 *变长*，而不仅仅是更便宜。 - **令牌：最多 ~20% 更便宜** 在记忆重要的地方。按价格计算的令牌成本（缓存写入 1.25×，缓存读取 0.1×，输出 5×）在具有演化决策和跨文件依赖关系的项目上 **降低 18–23%** - 而在代码本身重读成本较低的小型实施密集型项目上大致相当。我们发布诚实的数字，而不是原始令牌数字（原始总和看起来更好 ~30–40%，但% 的任何会话都是折扣缓存读取）。 - **回忆而不是重新。** 记忆发挥作用的地方是状态太大、演化太快或生命周期太长，无法廉价地重新推导：代理一开始就知道约束和死胡同，而不是花费会话的前四分之一重新发现它们。 --- ## 可靠性 - 脊柱 系统设计为 *可读降级*，而非静默： - **原子迁移** — 每个编号的迁移都应用其主体 + 版本号提升在一个事务中；安全地在脚本中间 - **幂等重放** — 重放工作线程作业不会重复计算或漂移衰证据来源保护） 故障开放钩子**每个表面都吸收故障 *并记录 WARNING*；沉默从不被视为成功 - **`memlorastrict`** — 每个子系统的健康状况（模式，FTS5，嵌入，符号，工作线程队列降级时退出状态非零 - **架构 — `import-linter` 分层合约，由元测试保护以防止输入错误 - **CI 提升门控** — 在每个 PR lint + 完整套包括 `tests/reliability/` 故障注入）；CONTRIBUTING.md`](CONTRIBUTING.md) --- 跨平台（Codex） 存储是平台中立的 - 每个逻辑项目一个 SQLite 数据库，因此 Claude Code 和 Codex 在同一目录中工作时共享一个内存。项目解析是 **别名感知** 的：`C:\repo` 和 `/mnt/c/repo` 解析为同一个存储，因此内存会随着 checkout 在 Windows、WSL 和本地挂载之间移动；对于真正不同的 checkout 路径，`.memlora/config.toml` 中的可选 `project_identity` 键将它们固定到一个共享存储中。Codex 通过注册的 MCP 服务器（`get_session_state` / `recall`）读取内存；捕获方向是 **基于拉取** 的，因为 Codex 没有 `Stop` 钩子的等价物： - **`memlora codex-sync <project>`** 扫描 `~/.codex/sessions` 以查找记录的 `cwd` 映射到项目的更新，并通过 *相同的* 提取管道捕获增量（更新→转录适配器是唯一的 Codex 特定代码；增量/去重/幂等性是共享且不变的）。 - **在时自动** — Claude 的 SessionStart 在构建块待处理 Code，MCP 服务器的器在每个循环中拉取新的更新，因此实时 Claude 会话在不等待下一个会话的情况下获取 Code的决策； 在 Codex 端，`init` 编写一个 `AGENTS.md` 指令 + 一个 `ck-sync` 技能，以便 Codex 在会话开始时拉取。 - **`init` 准备两者** — `.mcp.json`（Claude）和 `.codex/config.toml`（带有服务器的 `cwd` + 项目环境固定）+ `AGENTS.md`（Codex），幂不会覆盖现有设置 **`memlora doctor`** 报告一个 `code 健康状况行（会话目录 + 更新计数，或“” - Codex的，因此其不存在）。 在 Code做出的决策在下一个 Claude 会话块中生效亦然。操作点表面（CK-1，Use 门控）仅适用于 Claude — Codex提示/工具的钩 因此在 Codex循环降级为 + MCP 回忆。 --- ## 接口 **M**（会话注入；这些用于性的使用）： ` · `find_related `skeleton` · `get_session_state` ：** - `memlora init <project>` — 注册项目并安装会话钩子 - `memlora doctor [--strict] <project>` — 子系统健康报告 - `meml <project 为此项目捕获 Codex CLI 会话 - `memlora install-head — 安装训练的编码器工件（显著性和器 ONNX 体）：从 [`heads-v1` 发布版](https:///Kanishk/cognikernel/releasesheads-v1) 下载并校验 sha256，或 `models/` 复制 - `mem show <project>`memlora reset <project>` — 检查 / 清除存储的记忆 --- ## 快速入门 ```sh uv sync # 核心（仅词汇） uv sync --extra embedding # + 密集检索（fastembed + numpy） uv run memlora init . # 注册此项目 + 安装钩子 uv runora doctor . # 子系统健康 uv runora install-heads 可选：训练的编码器头（~270 MB 下载）； # 没有它们，提取/回落到 旧的/词汇 一切仍然有效 ``` 然后在项目中启动一个 Claude Code 会话 - 内存块会自动出现在会话开始时，并在会话结束时捕获决策。 --- ## 项目布局 ``` src/memlora/ integration/ 钩子，CLI，MCP 服务器/工作线程编排 extraction/理 -> 分类显著性 -> 管道 delta 增量合并 + 取代（最新胜可选交叉编码器） retrieval/ 混合 BM25 + 密集 -> RRF storage/源 SQLite，FTS5，迁移，渲染 embedding/ 可选密集向量（） symbols/ AST 骨架 + 图 compression/ 权限加权降 injection/ 块模板组装 model.py 事件的领域基本tests/ unit/ 每个子系统 reliability/ 重放 · 工作线程竞争 · 损坏输入注入 ``` --- ## 状态 **v18**（包括 Codex 跨平台捕获）。架构合约：3 个保留 / 0 个破坏。CI 门控：Ubuntu（3.11/12）和 Windows + 完整套有关每个更改的定义，请参见 `CONTRIBUTING.md`。