Engrim 1.3.0：适用于多模型 AI CLI 的本地优先 SQLite 内存引擎

TL;DR

Engrim 1.3.0 为 AI 编码助手（Google Antigravity、Claude Code、Cursor、Windsurf）提供了一个基于 SQLite 的本地优先情景记忆层，支持无缝切换模型并保持上下文持久化，同时确保所有数据离线且私密。

核心价值主张

Engrim 用一个存储在 SQLite 中的 4 KB 精选工作内存 替代了日益严重的“注意力稀释”问题——即大 token 窗口变得嘈杂且昂贵。主要优势包括：

供应商无关的连续性 – 在项目中途从 Gemini 3.8 切换到 Claude 3.7 Sonnet 再到 GPT-4o，仍能保留决策、约束和架构，无需重新解释。
显式的保存按钮语义 – 开发者可以清除代理会话（/clear），而 Engrim 会自动重新加载精选的记忆包。
混合检索 – 结合 FTS5 BM25 词法搜索与静态 model2vec 嵌入，在零延迟的倒数排名融合引擎中实现高效检索。

“为什么每轮都要为 20 万 token 的遗忘噪声付费？模型是可丢弃的工具；你的项目决策却不是。” – Engrim README

实证证据（105 会话案例研究）

在 5 万行算法交易代码库上的生产测试显示：

153,000 个 token 的工作被压缩为 < 1,000 个 token 的活跃内存（约 99% 减少）。
在 Antigravity、Claude Code 和 Cursor 之间切换后，186 个单元测试 无任何回归。
代理在项目中途切换时未出现上下文遗忘现象。

作者指出，测试涉及连续会话，但 Hacker News 上的讨论提出了关于基准可比性以及非正常退出处理的疑问。

架构概览

代理（Antigravity、Claude Code、Cursor/Windsurf） → 适配器与钩子 →
   证明溯源引擎（origin_agent 跟踪） →
   混合检索（bm25 + 向量） →
   SQLite 存储（~/.engrim/memory.db）

Memories 表 – 存储精选记录（决策、事实、反馈）。
FTS5 – 带 Porter 词干化和触发器的全文搜索。
向量列 – 静态 model2vec 嵌入用于语义召回。
飞行记录器日志 – 原始逐轮对话记录，用于审计和审查。

多代理环境快速入门

pip install engrim
engrim setup            # 自动检测 Antigravity、Claude、Cursor、Windsurf
# 或显式按代理设置
engrim setup --agy      # Antigravity 钩子
engrim setup --claude   # Claude Code 钩子
engrim setup --cursor   # Cursor MCP 注册
engrim setup --all      # 配置所有支持的代理

使用 --dry-run 可预览文件更改而无需写入。

证明溯源追踪

每个记忆条目都记录 origin_agent 字段（antigravity、claude-code、cursor、cli、user）。engrim list 的示例输出：

[DECISION]
- #961 (via Antigravity): 高波动性下反转止损矩阵
- #942 (via Claude Code): 将主数据库从 MongoDB 切换为 PostgreSQL
- #910 (via Cursor): 统一使用 Pydantic v2 模式

现有数据库会通过 ALTER TABLE 自动迁移，添加溯源列。

模型上下文协议（MCP）服务器

运行一个无依赖的 JSON-RPC 2.0 标准输入输出服务器：

engrim serve --mcp   # 或简写为 `engrim mcp`

服务器将 stdout 保留用于 JSON-RPC 消息，并将诊断信息发送至 stderr。

核心 MCP 方法

方法	签名	目的
`engrim_recall`	`(query: str, project: str = "auto", k: int = 5, type: str = None)`	混合关键词 + 语义搜索。
`engrim_add`	`(type: str, summary: str, detail: str = None, tags: list[str] = [])`	持久化一条记忆记录。
`engrim_context`	`(project: str = "auto", budget: int = 4000)`	返回一个预算限制的记忆包，用于会话启动。
`engrim_review`	`(project: str = "auto")`	在清除前扫描日志，查找未捕获的决策。

CLI 参考（精选命令）

命令	示例	描述
`engrim add`	`engrim add -t decision -s "..."`	插入一条记忆记录（类型：decision、fact、feedback、state、user、reference）。
`engrim recall`	`engrim recall -q "database"`	为当前项目执行混合排序召回。
`engrim context`	`engrim context -b 4000`	检索优先级排序、字符预算受限的启动包。
`engrim hook`	`engrim hook --agent agy --event boot`	为 Antigravity 或 Claude Code 执行生命周期钩子。
`engrim serve`	`engrim serve --mcp`	启动 MCP 服务器以集成代理。
`engrim review`	`engrim review`	在清除前验证所有近期决策是否已被捕获。
`engrim list`	`engrim list -k 20`	显示当前项目的最近记忆。

“继续即清空”工作流

捕获 – 每当做出决策或规则时，使用 engrim add（或 MCP 的 engrim_add）。
标记恢复指针 – 添加一条标记为 resume-pointer 的记录，描述下一个立即任务；最新指针将在下次启动时显示为 [▶ RESUME HERE]。
审查 – 运行 engrim review，确保没有重要决策遗漏。
清空 – 在代理中发出 /clear；Engrim 会在下一条提示中自动注入精选的记忆包。

安全与隐私保证

100% 本地且离线 – 所有数据存储在 ~/.engrim/memory.db；无遥测或云同步。
文件权限 – SQLite 文件以 0600（仅所有者）权限创建。
Git 安全 – *.db 默认被 git 忽略，防止意外提交。
可选嵌入 – 设置 ENGRIM_EMBED=off 可仅使用词法搜索，无需 model2vec 包。

社区反馈（Hacker News 精选）

@thih9: “不带参数运行 engrim setup……它自带卸载脚本吗？” – 用户要求提供清理工具；当前仓库未提供。

@aidiveyt: “停止钩子也可以阻塞本轮：返回退出码 2 并附带消息，会话会持续工作直到检查通过。” – 表明钩子失败会被正确传播，保持会话稳定性。

@corv: “我正在使用 gbrain 作为供应商无关的记忆，但实际使用中才意识到 SQLite 的轻量级优势，所以这很有趣！” – 强调了 SQLite 相较于其他记忆后端的极小资源占用优势。

@dsemakin: “实践中是什么触发了记忆的写入？需要我主动记得调用 engrim add 吗？” – 明确记忆创建是显式的；开发者必须调用 engrim add（或 MCP 的 engrim_add）来记录事实。

@flippant: “我一直在使用另一个记忆插件……决策摘要看起来非常酷——尽管代理/模型信息可能对我没用，因为我从不让代理自主提交代码。” – 对现有工具的积极评价，指出溯源元数据对某些工作流可能是可选的。

@esafak: “能否扩展一下 105 会话案例研究？……目前尚无生命周期管理或冲突解决机制，且模型自行决定何时使用它。” – 呼吁更严格的基准测试和冲突处理机制的说明。

@quietraster: “当两个代理写入同一个 SQLite 存储时，你是如何处理冲突的？” – 当前设计依赖 SQLite 的事务保证；并发写入会被序列化，但尚未实现更高级别的冲突解决机制。

局限性与开放问题

基准测试 – 发布的案例研究缺乏与竞争性记忆插件（如 ctx.rs）的直接对比；独立基准测试有助于量化 99% token 减少的声明。
冲突解决 – 虽然 SQLite 防止了数据损坏，但仓库尚未提供解决多个代理分歧编辑的策略。
卸载支持 – 无内置脚本用于移除钩子或删除记忆数据库；用户需手动清理。
跨设备同步 – 该工具有意设计为本地优先；在多台机器间同步 SQLite 文件需外部解决方案（如 rsync、云挂载驱动器）。