engram-cc

Engram Context Continuum

通用 AI 会话记忆底层。 一次安装，适用于每个 AI 编码助手。跨会话、文件夹重命名和工具切换，持久保留上下文。

在神经科学中，记忆痕迹是记忆在大脑中留下的物理印记。EngramCC 为 AI 实现了同样的功能——一个本地记忆底层，持久保存 AI 助手学到的内容、做出的决定和完成的工作，让下一次会话能从上一次结束的地方准确接续。

---

问题

每次 AI 编码会话都从零开始。助手重新读取昨天读过的文件，重新学习已经掌握的约定，再次询问你已经回答过的问题。上下文压缩会在工作中途悄然抹去会话内容。切换工具，所有记忆便荡然无存。

EngramCC 从基础设施层面解决这个问题——不是通过更费力地编写提示词，而是构建一个运行在任何 AI 助手底层的持久记忆层。

---

快速安装

npx engram-cc

在希望由 ECC 管理的项目根目录中运行，或传入 --project-dir <path>。

设置 CLI 会检测你的硬件，准备项目本地的 .engram-cc/ 工作区，询问共享模型目录，并在 .engram-cc/assistant-configs/ 下生成助手 hook/MCP 配置片段。不会修改用户主目录中的配置。

标准 MCP 安装命令

对于会从 npm 自行安装 MCP 服务的助手，EngramCC 的标准命令是：

npx --yes --package=@morous-dev/engram-cc -- engramcc-mcp

等效的 npm exec 形式：

npm exec --yes --package=@morous-dev/engram-cc -- engramcc-mcp

助手不应猜测 npx @morous-dev/engram-cc mcp。请使用上面的显式软件包/二进制形式。

对于项目本地 ECC 设置，.engram-cc/assistant-configs/ 下生成的配置片段会特意使用 node <project-local build/mcp/server.js>。上面的 npx --package ... 形式适用于不先运行项目本地设置、直接从 npm 安装 EngramCC 的助手。

---

支持的助手

助手	Hook 支持	MCP 支持
Claude Code	完整生命周期 hook	recall / search / recent / graph_query
Gemini CLI	完整生命周期 hook	recall / search / recent / graph_query
VS Code Copilot	—	recall / search / recent / graph_query
Codex CLI	原生 hook（session_start、pre_tool_use、stop）+ 与转录记录精确对应的 user_prompt_submit / post_tool_use + 合成的 pre_compact	recall / search / recent / graph_query
Kilo CLI	仅支持通过包装器辅助；未经验证的原生 hook	recall / search / recent / graph_query
OpenCode	完整生命周期 hook	recall / search / recent / graph_query
Cursor	—	recall / search / recent / graph_query

在 Windows 上，生成的 hook 配置片段会调用 src/hooks/hook-runner.mjs，以注入助手和项目环境变量，避免脆弱的 cmd /C 引号处理。

Codex 专项说明：精确提示词/工具桥接会读取 Codex 在 CODEX_HOME / ~/.codex/sessions/ 下的会话 JSONL，但 ECC 仍只会将其状态写入项目本地的 .engram-cc/ 目录。由于 Codex 不提供真正的提示词提交注入 hook，启动上下文还包含一项 Codex 回合策略：当较早的上下文可能已被压缩时，引导助手在用户回合中使用 EngramCC MCP 记忆。

Kilo 专项说明：目前已验证的支持包括 MCP，以及用于会话开始/结束连续性的 ekilo 包装器流程。Kilo 已提出原生生命周期 hook 的功能请求，因此 ECC 尚未宣称与 Kilo 的原生 hook 完全兼容。

---

工作原理

EngramCC 作为会话中间件运行——生命周期 hook 会捕获会话期间发生的事情，本地 SLM 会在会话结束时离线合成记忆，而 MCP 服务会向任何已连接的助手提供预先整理的上下文。

┌─────────────────────────────────────────────────────────────────┐
│                    Your AI Coding Session                        │
│                                                                   │
│  UserPromptSubmit → PostToolUse → PreCompact → Stop              │
│         │               │              │          │               │
│         └───────────────┴──────────────┴──────────┘              │
│                                 │                                 │
│                         SQLite event DB                           │
│                                 │                                 │
│                     ┌───────────┴───────────┐                    │
│                     │   Local SLM Archivist  │                    │
│                     │  (no API calls, 100%   │                    │
│                     │   offline synthesis)   │                    │
│                     └───────────┬───────────┘                    │
│                                 │                                 │
│              ┌──────────────────┼──────────────────┐             │
│              │                  │                  │             │
│         YAML handoff     Knowledge graph     Vector store        │
│         (hot resume)      (BFS traversal)   (semantic search)    │
│              │                  │                  │             │
│              └──────────────────┴──────────────────┘             │
│                                 │                                 │
│                         MCP server                                │
│                    (recall / search / recent                      │
│                       / graph_query)                              │
└─────────────────────────────────────────────────────────────────┘
         ↑                                         ↓
   SessionStart hook                       Next session
   injects context                         picks up here

会话生命周期

钩子	触发时机	功能
UserPromptSubmit	用户发送消息时	捕获意图和决策信号
PostToolUse	任意工具执行完成时	捕获文件操作、错误和工具结果
PreCompact	上下文接近上限时	在清除前对会话状态拍摄快照
SessionStart	会话开启时	注入热交接内容，或冷启动摘要 + MCP 指针
Stop	会话关闭时	SLM 综合处理 → 交接 YAML + 图谱 + 向量存储

分层上下文注入

EngramCC 会精准注入上下文，而非盲目注入：

• 热恢复（距上次会话不到 30 分钟）：注入完整交接 XML — 包含完整工作上下文、决策、修改的文件和错误
• 冷启动：一句话概述 + 指向 MCP recall 工具的指针 — 不会在过时上下文上浪费任何 token

记忆架构

层级	存储方式	内容	生命周期
工作记忆	YAML	偏好、约定、持久决策	跨会话
情景记忆	SQLite + FTS5	所有会话事件，支持全文搜索	按项目
语义记忆	SQLite 图谱	文件／决策知识图谱，支持 BFS 遍历	按项目
程序记忆	sqlite-vec	按嵌入向量索引的高价值事件	按项目

---

本地 SLM 流水线

EngramCC 优先使用本地模型来综合会话记忆 — 在压缩、交接和检索支持方面，不会调用外部 API。

设置 CLI 会检测你的硬件，并选择最佳可用层级：

层级	模型	所需 RAM	功能
1	基于规则	0	始终运行的启发式提取
2	MiniLM-L6-v2 ONNX	~400 MB	通过 @huggingface/transformers 生成嵌入
3	Llama 3.2 3B Q5_K_M	~4 GB	主要的本地综合处理层级
3b	Qwen3.5 4B Q4_K_M	~3.5 GB	备用综合处理层级，多语言／编码能力出色
3c	Gemma 3 4B QAT Q4_0	~3 GB	备用综合处理层级，结构化推理能力出色
4	Ollama / LM Studio / Groq	用户提供	外部 HTTP 提供方

模型存储在 engramcc 设置期间选定的共享目录中，并保存在 <projectDir>/.engram-cc/config.json 中。系统会自动逐级回退：如果没有可用的第 3 层模型，则运行第 2 层；如果第 2 层不可用，则运行第 1 层。核心记忆捕获不会因此受阻。

---

稳定的项目身份

EngramCC 通过存储在 .ecc-id 中的稳定 UUID跟踪项目，而不是通过文件夹路径。这意味着：

• 重命名项目文件夹 → 历史记录不变
• 将项目移至其他驱动器 → 历史记录不变
• 从 git 重新克隆 → 历史记录不变（回退到 git 根提交哈希）

解析顺序：.ecc-id 文件 → git 根提交哈希 → 新的 UUIDv4（仅写入一次，不会重新生成）。

---

数据位置

<projectDir>/.engram-cc/
├── sessions/
│   └── <uuid>.db               ← SQLite DB per project (all memory tiers)
├── assistant-configs/          ← Local hook/MCP snippets per assistant
├── config.json                 ← Project config, including shared models path
├── handoff.yaml                ← Session handoff (hot resume data)
└── working.yaml                ← Cross-session working memory

<chosenModelsRoot>/Engram Context Continuum/models/
└── <model>.gguf                ← Shared GGUF models reused across projects

所有数据都存储在本地。核心操作不进行网络调用。无需凭据、令牌或 API 密钥。

---

MCP 工具

通过 MCP 连接后，任何助手都可以直接查询 EngramCC：

工具	用途
recall	完整会话上下文：交接内容 + 工作记忆
search	对所有会话事件进行 FTS5 全文搜索
recent	最近的 N 条事件，可按类别筛选
graph_query	对知识图谱进行 BFS 遍历

---

配置

在 plugin-config.yaml 中覆盖压缩层级或外部提供方：

# Force a specific compression tier (default: auto)
compression:
  tier: "tier3b"

  # Tier 4 only
  external:
    provider: "ollama"
    model: "phi4-mini"
    base_url: "http://localhost:11434"

---

基准测试

以下数据已于 March 14, 2026 在当前仓库状态下完成验证，验证时已修复延续压缩问题。它们反映的是实际运行结果，而非历史最佳成绩。

已验证的基准测试运行

命令	测量内容	当前结果
npm run build	TypeScript 编译完整性	✅ PASS
node benchmark/test-session-db.mjs	会话数据库、归档、恢复链、延续传递回归测试	✅ 53/53
npm run test:quality	S1/S2/S3 端到端交接质量	✅ 20/20
node benchmark/test-hook-portability.mjs	跨助手钩子环境与启动可移植性	✅ 14/14
node benchmark/test-codex-adapter.mjs	Codex 转录同步 + 触发器 + 停止回归测试	✅ 29/29
npm run test:brutal:quick	真实数据提取校准（WildChat + SWE-bench）	✅ PASS
npm run test:lifecycle:quick	100 次循环真实数据生命周期 / 归档保留观察	✅ PASS
node benchmark/test-adversarial.mjs --model llama3.2-3b	对抗性 SLM 输入 A1–A11	✅ 11/11
node benchmark/test-adversarial.mjs --model qwen	对抗性 SLM 输入 A1–A11	✅ 11/11
node benchmark/test-adversarial.mjs --model gemma3-4b	对抗性 SLM 输入 A1–A11	✅ 11/11
node benchmark/test-tier-comparison.mjs	跨层级压缩保留（4→20 次循环）	✅ tier3、tier3b、tier3c 均为 38/38
node benchmark/test-scale.mjs	提示词长度稳定性	✅ Llama 16/16 · Qwen 15/16
node benchmark/test-compaction-marathon.mjs	多轮压缩记忆保留	✅ 53/53
node benchmark/test-diffmode.mjs	语法约束的 JSON 输出	✅ Llama 3.2 3B + Qwen3.5 4B 均通过

这些结果的含义

交接质量

npm run test:quality 测试从会话事件到向下一会话注入上下文的完整流程。

场景	断言	结果
S1 — 初始会话	6/6	✅
S2 — 热恢复	5/5	✅
S3 — 马拉松 / 冷启动	9/9	✅

总计：20/20

真实数据检索 / 保留

npm run test:brutal:quick 和 npm run test:lifecycle:quick 使用公开的外部数据集：

• WildChat-1M 编码对话
• SWE-bench GitHub 问题陈述

当前已验证的观察结果：

• 提取强度校准：PASS
• 对抗性提取器陷阱：15/15
• 链式阶段 extract → store → search → snapshot：PASS
• 生命周期检查点：第 25 / 50 / 75 / 100 次循环时，FTS5 召回率分别为 100% / 80% / 80% / 100%
• 第 100 次循环按来源统计的召回率：WildChat 5/7 (71%)、SWE-bench 13/13 (100%)

生命周期运行中遗漏的两项是低信号词（nothing、creator），并非归档损坏。

SLM 对抗鲁棒性

对抗测试套件是代码库中难度最高的准确率基准测试：涵盖代码墙、堆栈跟踪、多语言会话、反复变化的错误、领域术语、隐藏的当前任务以及多轮压缩链。

当前已验证的分数：

模型	分数
Llama 3.2 3B Q5_K_M	11/11
Qwen3.5 4B Q4_K_M	11/11
Gemma 3 4B QAT Q4_0	11/11

这很重要，因为 A11 曾经是真正的短板。在压缩链中加入确定性延续传递状态后，现在已通过测试。

SLM 规模稳定性

node benchmark/test-scale.mjs 探测提示词从 128 词增长到 985 词时的表现。

模型	结果
Llama 3.2 3B	16/16
Qwen3.5 4B	15/16

当前注意事项：

• Qwen 4B 在 S4（985 词）的无幻觉检查中有 一 项未通过。

跨层级压缩保留

node benchmark/test-tier-comparison.mjs 在全部三个生产级 GGUF 层级上运行相同的 4→20 次循环压缩压力测试。

层级	结果
tier3 — Llama 3.2 3B	38/38
tier3b — Qwen3.5 4B	38/38
tier3c — Gemma 3 4B	38/38

更新此 README 时，相较于原始快照，已验证的令牌节省比例为：

• tier3：24–26%
• tier3b：16–23%
• tier3c：20–28%

多轮压缩马拉松

node benchmark/test-compaction-marathon.mjs 模拟跨越 4、8、12、16 和 20 轮压缩的长时间运行会话。

当前已验证结果：

• 53/53 项断言通过
• 所有锚点事实在 20 轮压缩后均得以保留

重要注意事项

• 在某些运行中，tier3 仍会偶尔从语法约束的 diff 模式回退到散文模式。上述已验证套件中的正确性测试均通过，但这种回退仍然存在。
• Qwen 4B 整体表现强劲，但当前规模测试的成绩是 15/16，并非满分。
• 旧的 A11 失败已不再是当前情况，不应再将其作为现存弱点提及。
• benchmark/test-160k-real.mjs 在 carry-forward 补丁之后尚未重新运行，因此这里有意省略了旧数据，不将其纳入主要结论。

总体结论

在 CLI 内存底层架构最重要的方面，ECC 现在表现强劲：

• 真实数据的提取与保留
• 端到端交接质量
• 链式压缩连续性
• 跨层级 SLM 稳健性

检索层仍是长期安全网。SLM 层现在已经足以在多轮压缩中延续会话状态，不再出现旧版 A11 的崩溃问题。

---

开发

npm run build       # Compile TypeScript → build/
npm run typecheck   # Type check without emit
npm run clean       # Remove build/
npm run setup       # Build + run setup CLI

运行时要求：

• Node.js >= 18（所有钩子、MCP 服务、安装 CLI）

贡献者须知：

• 添加或更改助手适配器前，请先阅读 ADAPTER-AUTHORING.md。其中定义了允许修改的部分、功能规则、存储规则和当前的可移植性边界。

---

平台支持

EngramCC 可在 Windows、macOS 和 Linux（x64 和 ARM64）上运行。

依赖项	类型	平台覆盖范围
better-sqlite3	原生 C++ 插件	为所有主流平台和 Node 版本提供预编译二进制文件
node-llama-cpp (Tier 3)	原生插件	13 种预编译变体：Windows/macOS/Linux × x64/ARM64 × CPU/CUDA/Vulkan/Metal
sqlite-vec (Vector store)	原生插件	为 Windows x64、macOS x64/ARM64、Linux x64/ARM64 提供预编译版本
@huggingface/transformers (Tier 2)	纯 JS + WASM	通用 — 不含原生代码
所有其他依赖项	纯 JS	通用

故障排除：better-sqlite3 构建失败

better-sqlite3 是唯一需要原生编译的硬依赖项。它为常见的平台和 Node 版本组合提供预编译二进制文件。如果预编译版本与你的环境不匹配，npm 会回退到从源代码编译，这需要：

Windows：

npm install --global windows-build-tools
# or install Visual Studio Build Tools with "Desktop development with C++"

macOS：

xcode-select --install

Linux（Debian/Ubuntu）：

sudo apt install build-essential python3

Linux（Fedora/RHEL）：

sudo dnf groupinstall "Development Tools"

如果 npm install 因 gyp ERR! 或 node-pre-gyp 错误而失败，安装上述构建工具并重新运行 npm install 即可解决问题。

故障排除：本地 SLM 层级不可用

本地合成层级需要在项目配置的共享模型目录中放置 GGUF 模型。如果没有受支持的 Tier 3 模型，EngramCC 会回退到 Tier 2（嵌入）或 Tier 1（基于规则）。

示例：

engramcc --tier=tier3 --project-dir <project> --models-dir <shared-models-dir>
engramcc --tier=tier3b --project-dir <project> --models-dir <shared-models-dir>
engramcc --tier=tier3c --project-dir <project> --models-dir <shared-models-dir>

大致运行时要求：

• tier3 Llama 3.2 3B：约 4 GB RAM
• tier3b Qwen3.5 4B：约 3.5 GB RAM
• tier3c Gemma 3 4B：约 3 GB RAM

故障排除：向量存储未启用

向量存储使用 sqlite-vec，它是可选依赖项。如果加载失败，EngramCC 仍可正常运行，只是无法使用向量搜索——其他所有内存层级（情景记忆、语义记忆、工作记忆）均不受影响。请运行以下命令进行验证：

node -e "require('sqlite-vec')" 2>&1 || echo "sqlite-vec not available — vector search disabled"

---

项目结构

src/
├── hooks/          ← Lifecycle hook entry points (.mjs + .ts)
├── adapters/       ← Per-assistant registration (Claude Code, Gemini CLI, etc.)
├── session/        ← SQLite event capture, schema, FTS5
├── memory/         ← Working YAML, knowledge graph, vector store
├── handoff/        ← Session handoff writer, reader, dedup
├── compression/    ← SLM pipeline: tier selection, ONNX, node-llama-cpp
├── mcp/            ← MCP stdio server
├── tokenization/   ← Token budget auditor
├── project-id.ts   ← Stable project UUID resolution
└── cli/
    ├── setup.ts    ← Install CLI: hardware detection, adapter registration
    └── download-model.ts ← GGUF model downloader

---

许可证

开源： AGPL-3.0 — 可免费使用、修改和分发，但衍生作品也必须以 AGPL-3.0 开源。

商业用途： 对于需要在闭源产品或托管服务中使用 EngramCC，且不受 AGPL 义务约束的团队，可提供专有许可证。详情请参阅 COMMERCIAL-LICENSE.md。