mcp-engram 0.8.2

AI Agent Continuity Engine — task-centric memory, session handoff with validation, error-aware recall, Ebbinghaus decay, hybrid retrieval (BM25+vector+graph), quality scoring. Local-first, zero cloud dependency.

Engram

**AI Agent Continuity ** — Agent 可替换，任务不中断、跨实例持续推进，而不是每次从零开始。

按需召回上下文，不靠无限堆 token。
数据始终保留在本机。

---

项目背景

AI Agent 的每次会话都是一座孤岛：

• 换个 Agent？ 从头来。
• 上下文窗口满了？ 丢掉历史，继续猜。
• 昨天踩过的坑？ 不知道，再踩一遍。
• 一个任务跨了三次会话？ 没人知道整体进度。

根本原因：Agent 没有可持续的执行上下文，也没有以"任务"为中心的记忆组织。

Engram 是一个本地运行的 MCP Server，为 AI Agent 提供持久化的任务记忆和会话连续性。它解决的不是"记住聊天记录"，而是让任务状态、执行经验、失败教训在 Agent 切换和会话中断后不丢失。

Agent 可替换，任务不中断。 按需召回上下文，不靠无限堆 token。 数据始终保留在本机。

---

安装

环境要求

• Python 3.11+
• 约 500MB 磁盘空间（嵌入模型缓存）

通过 pip 安装

pip install mcp-engram
engram-setup          # 下载嵌入模型（all-mpnet-base-v2）、初始化 DuckDB 数据库

从源码安装

git clone https://github.com/hugfeature/engram.git
cd engram
pip install -e ".[dev]"
pytest tests/ -v       # 运行测试验证安装

配置 MCP 客户端

在 Claude Code / Cursor 等 MCP 客户端中添加：

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "env": { "HF_ENDPOINT": "https://hf-mirror.com" }
    }
  }
}

国内用户建议设置 HF_ENDPOINT 使用镜像加速模型下载。

---

使用方法

核心工作流：跨 Agent 接力

Agent A                             Agent B
  │                                   │
  ├─ create_task(任务名, 目标)          │
  ├─ recall_memory(关键词)              │
  │    └─ handoff 自动置顶              │
  │    └─ 附带 related_failures         │
  │    └─ 附带 quality_score            │
  ├─ ... 执行任务 ...                  │
  ├─ track_failure(错误, task_id)       │
  ├─ track_progress(进度, task_id)      │
  ├─ session_handoff(交接, task_id) ───▶ recall_memory(关键词)
  │                                   ├─ 读取 handoff + next_steps 验证
  │                                   ├─ get_task(task_id) 查看全景
  │                                   ├─ ... 接着做 ...
  │                                   ├─ update_task(task_id, status)
  │                                   └─ session_handoff(交接, task_id) ──▶ ...

核心循环：create_task → recall → execute → track → handoff → repeat

推荐写入 CLAUDE.md 的 Agent 指令

## Memory Rules

- 接到多步任务：`create_task(name, goal)` — 创建跟踪任务
- 每次任务开始：`recall_memory(query=任务关键词)` — 自动置顶 handoff，附带 failure 上下文
- 全新知识：`store_memory(content, importance)`
- 补充已有：`update_memory(memory_id, merged_content)`
- 推翻已有：`update_memory(memory_id, new_content)`
- 阶段性进展：`track_progress(feature, status, completion, task_id=X)`
- 遇到错误：`track_failure(error, component, root_cause, task_id=X)`
- 任务结束：`session_handoff(summary, completed, in_progress, blocked, next_steps, task_id=X)`
- 查看任务全景：`get_task(task_id)` — 包含所有关联记忆

会话生命周期

Engram 自动跟踪会话状态，无需调用方显式传递 session_id：

1. 心跳注册 — 每次 recall_memory / store_memory 调用时，服务端自动注册会话心跳
2. 中断检测 — 下次 recall 时自动检测上一次会话是否异常中断，返回 interrupted_sessions 提醒
3. 优雅关闭 — 进程退出时通过 atexit hook 自动标记会话结束
4. 主动交接 — 会话结束前调用 session_handoff 记录执行上下文（推荐）

MCP 工具一览

Engram 提供 12 个 MCP 工具：

分类	工具	用途
核心	recall_memory	混合检索记忆，支持 memory_type 过滤、handoff 自动置顶、附带 failure 上下文和质量评分
	store_memory	存储新记忆，自动去重 / 合并 / 矛盾消解
	update_memory	按 ID 更新已有记忆
	session_handoff	结构化会话交接 + next_steps 执行验证（支持 task_id 关联）
任务	create_task	创建跟踪任务（name / goal），返回 task_id
	update_task	更新任务状态 / 目标 / metadata
	get_task	获取任务详情 + 关联的全部 handoff / failure / progress 记忆
工程	track_failure	结构化失败记录（支持 task_id 关联，按 component 可追溯）
	track_progress	功能进度快照（支持 task_id 关联）
	session_outcome	标记会话成功/失败，多次失败记忆额外降权
维护	consolidate_memory	手动触发记忆整合（相似记忆聚类合并）
	memory_stats	记忆统计 + 工程指标概览

重要性参考

值	场景
0.9–1.0	核心身份、永久事实
0.7–0.8	架构决策、强偏好
0.5	普通项目事实
0.2–0.3	临时会话上下文

---

文档

记忆机制

艾宾浩斯遗忘曲线

每条记忆有一个 strength 值，随时间按指数衰减：

effective_λ = base_λ × (1 - importance × 0.8)
strength = importance × e^(-λ × days) × (1 + recall_count × 0.2)

类别	λ	半衰期	适用
strategy	0.10	~38 天	被验证有效的方法论
fact	0.16	~24 天	用户偏好、技术选型
assumption	0.20	~19 天	推断的上下文
failure	0.35	~11 天	踩过的坑、临时 workaround

策略记最久，失败记最短——环境会变，昨天的坑明天可能已经填上了。

智能去重与矛盾消解

相似度 ≥ 0.85 → REINFORCE   增加回忆次数
相似度 0.65~0.84 → 检测矛盾
  ├── 语义矛盾 → REPLACE    覆盖
  └── 语义兼容 → MERGE      合并
相似度 < 0.65 → NEW         新记忆

混合检索

score = 0.3 × BM25 + 0.7 × (语义相似度 × 衰减强度) + 图谱加成

• BM25：精确关键词匹配（DuckDB FTS）
• 向量检索：语义相似度（HNSW 索引加速）
• 图谱扩展：从命中记忆出发 BFS（深度 ≤ 3），发现关联知识

Recall 增强

每次 recall_memory 自动附带三个维度的增强信息：

增强	说明
Handoff Validation	检测 handoff 的 next_steps 是否被后续 session 执行，返回每步的执行状态
Related Failures	非 failure 类记忆如果涉及特定 component，自动附带该 component 的历史 failure 上下文
Quality Score	动态计算 importance × recall频率 × session outcome 综合质量分

quality_score = clamp(importance × (1 + recall_bonus) × outcome_factor, 0, 1)
  - recall_bonus = min(recall_count × 0.1, 0.5)
  - outcome_factor = (success - failure × 0.5) 调整

新 Agent 接手时不仅知道"记住了什么"，还知道"哪些做了哪些没做"、"这块踩过什么坑"、"哪条记忆更可靠"。

自动维护

每 12 小时自动执行：

• 整合：相似度 ≥ 0.70 的记忆簇合并
• 剪枝：strength < 0.05 且无链式保护的记忆删除
• FTS 重建：保持全文索引新鲜

---

项目特性

与其他 Memory 系统的区别

维度	普通 Memory	Engram
核心抽象	记忆条目	Task + 记忆，以任务为中心组织
核心动作	存文本 → 检索文本	存状态 → 驱动下一步执行
跨会话	仅检索历史	结构化交接 + next_steps 执行验证
工程上下文	无	失败归因 + 进度追踪 + session outcome
召回质量	原样返回	quality_score + error-aware + handoff 置顶
数据增长	无限膨胀	自动去重 / 衰减 / 剪枝
会话连续性	无	自动心跳 + 中断检测 + atexit 兜底
部署	云端 API	本地优先，零依赖

---

兼容环境

平台	状态
macOS (Apple Silicon / Intel)	✅ 完全支持
Linux (x86_64 / ARM64)	✅ 完全支持
Windows (WSL2)	✅ 支持
Windows (原生)	⚠️ 未充分测试

MCP 客户端	接入方式
Claude Code	stdio / HTTP
Cursor	stdio
其他 MCP 兼容客户端	stdio / HTTP

---

Benchmark

基于 LoCoMo（Snap Research 长期对话记忆基准）评测：

System	Overall F1	LLM	部署方式
MemMachine	0.8487	GPT-4o-mini	云端
Memobase	0.7578	GPT-4o-mini	云端
Zep	0.7514	GPT-4o-mini	云端
Mem0	0.6688	GPT-4o-mini	云端
Engram	0.4383	DeepSeek-V3.2	本地

本地部署零云端依赖，四轮优化累计 F1 +50.3%，Hit@5 +26.2pp。

详细分类得分

Category	Count	F1	Hit@5
Single-Hop	114	0.5121	76.3%
Temporal	63	0.4501	95.2%
Multi-Hop	43	0.3181	60.5%
Open-Domain	13	0.1324	61.5%
Overall	233	0.4383	77.7%

---

架构

┌──────────────────────────────────────────────┐
│              MCP Client                      │
│      (Claude Code / Cursor / ...)            │
└──────────────────┬───────────────────────────┘
                   │ stdio / HTTP
┌──────────────────▼───────────────────────────┐
│  server.py (stdio) · http_server.py (REST)   │
│  shared.py (session auto-inject · dispatch)  │
│      12 MCP Tools  ·  APScheduler            │
├──────────────────────────────────────────────┤
│  handlers.py — 业务逻辑                       │
│  ┌─ Task ───────────────────────────────┐    │
│  │  create / update / get_task          │    │
│  │  handoff validation · quality score  │    │
│  └──────────────────────────────────────┘    │
│  ┌─ 写入 ──────────┐  ┌─ 读取 ──────────┐   │
│  │  resolve.py     │  │  retrieve.py    │   │
│  │  去重/矛盾消解   │  │  混合检索+评分   │   │
│  └─────────────────┘  └─────────────────┘   │
│  ┌─ 维护 ──────────┐  ┌─ 衰减 ──────────┐   │
│  │  consolidator   │  │  decay.py       │   │
│  │  聚类合并+剪枝   │  │  遗忘曲线+质量分  │   │
│  └─────────────────┘  └─────────────────┘   │
├──────────────────────────────────────────────┤
│  embedding.py (LRU向量编码)  │  graph.py (语义图谱) │
│                              │  batch_mode · user隔离│
├──────────────────────────────────────────────┤
│              db.py — DuckDB                  │
│  memories · tasks · session_lifecycle        │
│  向量HNSW  ·  BM25 FTS  ·  CRUD             │
└──────────────────────────────────────────────┘

数据目录 ~/.engram/：

文件	说明
memories.duckdb	向量数据库 — memories + tasks + session_lifecycle（单文件，零运维）
graph.json	语义图谱（支持 batch_mode、多用户隔离）
model_cache/	嵌入模型缓存

---

环境变量

完整配置项

变量	默认值	说明
HF_ENDPOINT	https://hf-mirror.com	HuggingFace 镜像
ENGRAM_MODEL	all-mpnet-base-v2	嵌入模型
ENGRAM_MODEL_TIMEOUT	30	模型加载超时（秒）
ENGRAM_PRUNE_THRESHOLD	0.05	剪枝强度阈值
ENGRAM_DEDUP_THRESHOLD	0.65	去重相似度下限
ENGRAM_REINFORCE_THRESHOLD	0.85	强化相似度阈值
ENGRAM_SIM_HIGH	0.50	检索高阈值
ENGRAM_SIM_LOW	0.20	检索低阈值
ENGRAM_REINFORCE_SIM	0.75	检索时强化阈值
ENGRAM_W_BM25	0.30	BM25 权重
ENGRAM_W_VECTOR	0.70	向量权重
ENGRAM_GRAPH_DEPTH	3	图谱 BFS 深度
ENGRAM_EDGE_THRESHOLD	0.40	图谱建边阈值
ENGRAM_MAX_EDGES	5	每条记忆最大边数
ENGRAM_CONSOLIDATE_THRESHOLD	0.70	整合聚类阈值

---

Roadmap

• Error-aware Memory — 按 component 附带历史 failure 上下文 ✅
• Handoff Validation — next_steps 执行状态检测 ✅
• Task Context — Task 一等实体，跨会话任务全景视图 ✅
• Memory Quality Score — 基于 importance + recall + outcome 动态评分 ✅
• Session Lifecycle — 自动心跳、中断检测、atexit 兜底 ✅
• Eval Pipeline — 自动化质量回归测试
• Multi-Agent Coordination — 多 Agent 并行任务分配与同步
• Coding Agent 深度集成 — IDE 原生 Task 面板

---

参与贡献

欢迎通过以下方式参与：

1. 提交 Issue — 报告 Bug 或提出功能建议
2. 提交 PR — Fork → 新建分支 → 提交 PR

git clone https://github.com/hugfeature/engram.git
cd engram
pip install -e ".[dev]"
pytest tests/ -v       # 确保测试通过

项目负责人

• @hugfeature

License

MIT

---

AI 不缺能力，缺的是"记住并持续执行"的能力。 Engram 让 Agent 的任务——不论换了几个 Agent、跨了几次会话——都可以不中断地往前走。