Claude Engram

为 AI 编程助手提供持久化记忆和会话智能。挂载到 Claude Code 的生命周期中以自动跟踪错误、决策和上下文——然后挖掘您的完整会话历史，以呈现模式、预测您所需的内容，并搜索您讨论过的所有内容。

零手动操作。适用于任何兼容 MCP 的客户端。

功能特点

自动化（钩子——零调用）：

• 跟踪每一次编辑、错误、测试结果和会话事件

• 从您的提示中自动捕获决策（“让我们使用 X”，“切换到 Y”）

• 在每次文件编辑前注入 3 条最相关的记忆

• 当您即将重复过去的错误时发出警告

• 检测编辑循环（同一文件在没有进展的情况下被编辑 3 次以上）

• 在上下文压缩中存活——压缩前设置检查点，压缩后重新注入

• 在每次会话后在后台挖掘您的会话历史

会话挖掘（自动，后台）：

• 在每次会话后解析 Claude Code 的完整对话日志 (JSONL)——包括子代理对话（Explore、Plan、code-reviewer 等）

• 使用结构分析 + AllMiniLM 语义评分（容错）提取决策、错误、方法和用户更正

• 构建跨所有过去对话的可搜索索引（超过 2 万个带有子代理的块）

• 检测反复出现的困难、错误模式和文件编辑相关性

• 在编辑前预测您需要的文件和上下文

• 使用本地 LLM 反思模式，以综合根本原因和架构见解

• 首次安装时，追溯挖掘您的整个会话历史

按需使用（MCP 工具）：

• memory — 存储、搜索、归档和管理记忆

• session_mine — 搜索过去对话、查找决策、重放文件历史、检测模式

• work — 记录带有推理的决策和错误

• 此外：范围保护、上下文检查点、约定跟踪、影响分析

Related MCP server: Doclea MCP

工作原理

Claude Code
 |
 +-- Hooks (remind.py) <- Intercepts every tool call
 | SessionStart / Edit / Bash / Error / Compact / Stop
 |
 +-- Session Mining (mining/) <- Background intelligence
 | JSONL parser -> Extractors -> Search index -> Pattern detection
 |
 +-- MCP Server (server.py) <- Tools for manual operations
 | memory, session_mine, work, scope, context, ...
 |
 +-- Scorer Server (scorer_server.py) <- Persistent AllMiniLM process
 TCP localhost, ~90MB RAM, batch embeddings

钩子在每次工具调用时触发（每个预算 1-2 秒）。繁重的处理在会话结束后在后台子进程中进行。评分服务器保留在内存中，以实现快速的语义评分。

基准测试

集成基准测试

这些测试产品实际执行的功能。

复现: python tests/bench_integration.py, bench_session_mining.py, bench_obsidian_vault.py

检索基准测试

仅检索 (recall@k) — 是否在顶部结果中找到了正确的记忆。

复现: python tests/bench_longmemeval.py, bench_locomo.py, bench_convomem.py

兼容性

安装

git clone https://github.com/20alexl/claude-engram.git
cd claude-engram
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows

pip install -e . # Core
pip install -e ".[semantic]" # + AllMiniLM for vector search and semantic scoring

python install.py # Configure hooks, MCP server, and /engram skill

项目配置

python install.py --setup /path/to/your/project

或者将 .mcp.json 复制到您的项目根目录。

注意： 本仓库中的 CLAUDE.md 是 engram 特定的文档——engram 的工作并不需要它。钩子会自动触发，/engram 技能提供按需快速参考。如果您已经为项目准备了 CLAUDE.md，请保持原样，不要覆盖它。如果您希望在项目规则旁边使用 engram 文档，请将其重命名为 CLAUDE-ENGRAM.md（或类似名称），以免覆盖现有文件——Claude 在相关时会看到它。

更新

cd claude-engram
git pull
pip install -e ".[semantic]" # Reinstall if dependencies changed
python install.py # Re-run to update hooks and /engram skill

钩子和 MCP 工具会立即获取代码更改（可编辑安装）。在 Claude Code (/mcp) 中重新连接 MCP 服务器以重新加载服务器进程。

项目中途采用

已经在项目中深入工作了？正常安装即可。在第一次会话中，engram 会自动检测您现有的 Claude Code 会话历史并在后台进行挖掘——从所有过去的对话中提取决策、错误和模式。无需手动操作。

核心功能

记忆系统

• 混合搜索 — 关键词 + AllMiniLM 向量 + 重排序。无需 ChromaDB。

• 评分注入 — 在每次编辑前，根据文件匹配、标签、时效性和重要性注入前 3 条记忆。

• 分层存储 — 热数据（快速）+ 归档（冷数据，可搜索，可恢复）。规则和错误永远不会归档。

• 多项目 — 记忆按子项目划分范围。工作区规则向下级联。

会话挖掘

• 结构提取 — 分析对话流程（确认、重定向、错误->修复序列、方法变更）而不是模板匹配。

• 工具内容索引 — bash 命令 + 输出、编辑差异和错误追踪信息可与对话文本一起搜索。

• 批量嵌入 — 通过批量 TCP 协议比单独调用快 22 倍。

• 跨会话搜索 — 索引了 4.4 万多个对话块，支持语义 + 关键词 + 混合搜索。

• 模式检测 — 跨会话的反复困难、错误模式、编辑相关性。

• 预测性上下文 — 在编辑前，呈现相关文件和历史中可能的错误。

• 跨项目学习 — 聚合您所有项目的模式。

• 追溯引导 — 首次安装时挖掘所有现有的会话历史。

• 评分器自动启动 — AllMiniLM 服务器在未运行时按需启动。不会静默降级。

生命周期

• 自动捕获决策 — 结构模式（确认、重定向、明确选择）+ 语义评分作为奖励。

• 自动跟踪错误 — 来自任何失败的工具。仅记录项目文件中的错误（过滤瞬态噪声）。在重复编辑前发出警告。

• 压缩存活 — 使用会话决策/错误设置检查点，压缩后重新注入。

• 编辑循环检测 — 当同一文件在没有进展的情况下被编辑 3 次以上时进行标记。

配置

重新索引

如果搜索质量较差，或者您想在更新后重建索引：

python scripts/reindex.py "E:\workspace" --force # rebuild search index
python scripts/reindex.py "E:\workspace" --force --extract # also re-extract decisions/mistakes

或者通过 MCP: session_mine(operation="reindex", mode="bootstrap")

文档

图书馆手册 — 设计理念、内部结构、完整使用指南、API 参考、注意事项和更新日志。

/engram — 带有快速工具参考的斜杠命令（由 install.py 安装）。

许可证

MIT

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• audit_batchC
• claude_engram_statusB
• code_pattern_checkC
• code_quality_checkC
• contextA
• conventionB
• deps_mapC
• file_summarizeC