Engrim：面向AI CLI的本地优先SQLite记忆引擎

跨模型、跨 Agent 的情景记忆存储。

一个本地优先、以项目为作用域的 SQLite 记忆引擎，允许开发者在同一项目上自由切换模型和环境（Google Antigravity、Claude Code、Cursor MCP、Windsurf），而不丢失架构决策、用户约束或项目状态。

1. 核心价值主张

"为什么每次对话都要为 20 万个被遗忘的噪音 token 买单？模型是可消耗的工具；你的项目决策不是。"

随着上下文窗口扩展到 100 万 + token，开发者面临注意力稀释问题：推理质量下降，每次对话轮次的成本翻倍，清空上下文会导致完全失忆。

engrim 用 4,000 个精心筛选的情景工作记忆 token 取代注意力稀释：

AI 记忆的瑞士：将项目智能与任何单一 AI 供应商或专有云隔离。你可以自由切换——在 Antigravity 中使用 Gemini 3.8，在 Claude Code 中使用 Claude 3.7 Sonnet，在 Codex CLI 中继续项目——你的 Agent 会从上一个 Agent 停下的地方无缝接续。

自动驾驶的保存按钮：将决策、约束和状态在工作过程中外化。已连接的 AI Agent（Antigravity、Claude Code、Cursor、Codex、Codex CLI）可以在做出架构决策时通过 MCP 工具自动写入记忆，你也可以手动保存（engrim add）。自由清空 Agent 会话（/clear），观察上下文完整重建。

智能热上下文加载：结合 SQLite FTS5（bm25 关键词搜索）与静态向量嵌入（model2vec），构建零延迟的混合互惠排序融合引擎。

2. 实证证明（105 个会话案例研究）

在 50,000 行算法交易系统上连续测试 105 个会话。186 个单元测试零回退，跨模型切换零上下文失忆。

在运行真实资金的活跃算法交易代码库上进行生产测试：

历时数天的架构、参数调优和调试工作，超过 153,000 个 token，被压缩到不足 1,000 token 的活跃记忆包中（不足上下文窗口的 1%）。

这意味着每次会话重启时，重新加载上下文的成本减少了 99% 以上。

在相同代码仓库上无缝切换 Google Antigravity CLI、Claude Code 和 Cursor MCP，零模型漂移、零架构回退。

graph TD
    subgraph Agents ["Supported Agent Environments"]
        AGY["Google Antigravity<br/>(PreInvocation & Stop Hooks)"]
        CLAUDE["Claude Code<br/>(SessionStart & Stop Hooks)"]
        CURSOR["Cursor / Windsurf<br/>(Model Context Protocol stdio)"]
        CODEX["Codex CLI<br/>(Hooks & MCP)"]
    end

    subgraph CoreEngine ["engrim Core Engine (v1.3.0)"]
        ADAPTERS["Adapters & Hooks<br/>(agy, claude, mcp)"]
        PROVENANCE["Agent Provenance Engine<br/>(origin_agent tracking)"]
        ROUTER["Hybrid Retrieval & Minder<br/>(bm25 lexical + vector cosine)"]
    end

    subgraph Storage ["Local-First SQLite Store (~/.engrim/memory.db)"]
        MEMORIES[("Curated Memories<br/>(decisions, facts, feedback)")]
        FTS5["FTS5 Full-Text Search<br/>(porter stemmer, triggers)"]
        VEC["Vector Embeddings<br/>(model2vec static embeddings)"]
        LOG["Flight Recorder Log<br/>(turns + action lines)"]
    end

    AGY <-->|"hook / CLI"| ADAPTERS
    CLAUDE <-->|"hook / CLI"| ADAPTERS
    CURSOR <-->|"JSON-RPC (stdio)"| ADAPTERS
    CODEX <-->|"hook / MCP"| ADAPTERS
    ADAPTERS --> PROVENANCE
    PROVENANCE --> ROUTER
    ROUTER --> MEMORIES
    MEMORIES --- FTS5
    MEMORIES --- VEC
    ADAPTERS --> LOG

4. 多 Agent 快速上手

pip install engrim

自动检测（推荐）

运行不带参数的 engrim setup，它会自动检测机器上已安装的环境并全部配置：

engrim setup

如果存在 ~/.gemini → 接入 Antigravity 生命周期钩子、skill 和 MCP 服务器。

如果存在 ~/.claude → 接入 Claude Code SessionStart、Stop、状态栏和 CLAUDE.md。

如果存在 ~/.cursor → 生成并合并 Cursor MCP 配置。

如果存在 ~/.codex → 接入 Codex CLI 钩子和 MCP 服务器。

显式平台配置

engrim setup --agy

配置 ~/.gemini/config/hooks.json，在 PreInvocation 时执行 engrim hook --agent agy --event boot，在 Stop 时执行 engrim hook --agent agy --event stop。

将标准 Antigravity skill 部署到 ~/.gemini/config/skills/engrim/SKILL.md。

在 ~/.gemini/antigravity-cli/mcp_config.json 和 ~/.gemini/config/mcp_config.json 注册 MCP 服务器。

engrim setup --claude

在 ~/.claude/settings.json 接入 SessionStart、SessionEnd、Stop 和 UserPromptSubmit 钩子。

在 Claude Code 状态栏配置实时环境状态显示。

向 ~/.claude/CLAUDE.md 追加记忆使用说明。

engrim setup --cursor

向 ~/.cursor/mcp.json 添加 engrim，运行 engrim serve --mcp。

engrim setup --codex

在 ~/.codex/hooks.json 接入 SessionStart、SessionEnd、Stop 和 UserPromptSubmit 钩子。

在 ~/.codex/config.toml 注册 MCP 服务器。

将 engrim 添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "engrim": {
      "command": "engrim",
      "args": ["serve", "--mcp"]
    }
  }
}

engrim setup --all

一条命令配置所有支持的环境。

（对任意 setup 命令使用 --dry-run 可以检查变更而不修改磁盘。）

5. Agent 出处追踪

当多个 Agent 协作同一代码库时，出处至关重要。engrim 记录每条记忆条目的来源，用 origin_agent 字段标识：

允许值：antigravity、claude-code、cursor、cli 或 user。

根据活跃的钩子、MCP 客户端或 CLI 会话自动填充。

在 engrim context 和 engrim list 中微妙呈现：

🧠 engrim · memory restored for this project — you don't have to re-explain · /workspace
  18 of 54 curated records loaded (~3850 chars) · the rest one `recall` away

[DECISION]
- #961 [DECISION] (via Antigravity): Inverted stop loss matrix for high volatility  (risk, execution)
- #942 [DECISION] (via Claude Code): Switched primary database from MongoDB to PostgreSQL  (db, schema)
- #910 [DECISION] (via Cursor): Standardized on Pydantic v2 schemas across API boundaries  (api, types)

现有数据库在首次访问时通过 ALTER TABLE memories ADD COLUMN origin_agent TEXT 非破坏性迁移。

6. 加固的 Model Context Protocol (MCP) 服务器

启动零依赖、JSON-RPC 2.0 stdio MCP 服务器：

engrim serve --mcp
# or: engrim mcp

stdout 严格保留给 JSON-RPC 消息，所有诊断日志重定向到 stderr。

暴露的核心 MCP 工具：

8. Continue-As-Clear 工作流

边工作边捕获：每当做出重大决策或架构规则时，需要保存到记忆。AI Agent 通常会通过 engrim_add 工具自动完成这一步，但你也可以手动干预（自己运行 engrim add）。

使用 resume-pointer：在结束会话或清空前，添加一条标记为 resume-pointer 的记录，描述即时的下一个任务。最新的指针会在下次会话引导包顶部以 [▶ RESUME HERE] 固定。

用 engrim review 验证：检查所有近期决策是否已捕获。

自由清空（/clear）：会话窗口被清空；engrim 在下一次提示或调用时自动重新注入活跃记忆包。

9. Engrim 与其他方案对比

目前有多种其他记忆解决方案和编程助手（如 gbrain、OpenCode、Codex 和 Pi）。以下是 engrim 的差异所在：

vs gbrain：gbrain 是一个优秀的供应商无关的记忆工具，而 engrim 的差异化在于使用轻量级本地优先的 SQLite 架构。一切都快速且可离线使用，无需复杂配置或云依赖。

vs OpenCode & Codex：其他方案可能内置了 SQLite 或记忆组件，但 engrim 是专门设计的情景记忆引擎，跨多个不同 Agent（Antigravity、Claude Code、Cursor、Codex、Codex CLI）追踪决策出处。它作为统一后端，供所有工具共享。

vs Pi：Pi 作为个人 AI 伴侣具有长期记忆。engrim 专为编程项目与软件架构定制——以编码 Agent 可通过混合搜索（FTS5 + 向量）高效查询的格式捕获决策、状态和约束。

10. 安全与隐私

100% 本地 & 离线：所有记忆记录和日志保存在本地 SQLite 文件（~/.engrim/memory.db）。无遥测、无云同步、无追踪。

模型存储：使用 model2vec 本地静态嵌入（约 30ms 加载时间，无需 GPU，CPU 运行）。可切换为纯词法模式（ENGRIM_EMBED=off）实现零额外依赖。

POSIX 文件权限：数据库以受限的仅所有者权限（0600）创建。

Git 保护：*.db 默认加入 .gitignore；你的记忆永不意外提交到版本控制。

MIT © 2026 Tim Gordon.