AI编码代理项目记忆系统

印迹

AI编码代理的项目内存。

Engram是一个本地优先存储系统，为AI代理提供跨会话的持久上下文。它将结构化事件（决策、发现、警告、突变、结果）存储在轻量级SQLite数据库中，并生成简报，让代理了解项目状态。

我建立这个是因为我一直在失去背景。每次会话都从零开始——不记得尝试了什么，失败了什么，决定了什么，或者要避免什么。Engram解决了这个问题。在工作时发布事件，下一个代理（或你的下一个会话）会得到一个简报，而不是盲目开始。

为什么存在

AI编码代理在实际项目中有四个问题：

1. 失忆 --每节课开始时对之前的工作没有记忆
2. 隔离 --不知道其他代理人做了什么或正在做什么
3. 没有学习 --过去决策的结果已经丧失；错误重复
4. 失明 --无法知道自上次会议以来发生了什么变化

这些不是理论上的。如果你曾经重新调查过一个已经修复的错误，做出了一个与昨天的错误相矛盾的决定，或者修改了另一个代理正在处理的文件——这就是Engram所阻止的。

该项目最初名为“AgentBus”（一种代理间消息总线），但在咨询了三种人工智能模型（GPT-4o、Gemini 2.5 Flash、Claude Sonnet）后，我们一致认为“总线”框架是错误的。这不是中间件。这是一 带有简报界面的项目内存日志简报是产品，其他一切都是为了它。

代理商：如何使用Engram

如果Engram是在您的环境中配置的，无论是通过Claude Code插件（一步安装，请参阅下面的安装）还是手动配置为MCP服务器/CLI，您都有16个可用工具。

如果存在Claude Code挂钩（随插件一起提供，或通过手动安装 engram hooks install)，文件突变和bash命令结果会自动捕获——您很少需要发布 mutation 或 outcome 手工事件。

briefing --以此开始每个会话

engram briefing

返回最近项目活动的结构化摘要：活动警告、最近的决策、文件更改、发现和结果。这是最重要的一个电话。先运行它。

post_event --记录你所学到的并做出决定

engram post_event(event_type="decision", content="Using bcrypt over argon2 — existing infra uses bcrypt", scope=["src/auth/hash.py"])
engram post_event(event_type="warning", content="Don't modify user_sessions — migration pending", priority="critical")
engram post_event(event_type="outcome", content="JWT fix worked", related_ids=["evt-abc123"])

事件类型以及何时使用它们：

使用 related_ids 链接事件（例如将结果链接到它验证的决策）。链接的事件通过以下方式显示在查询中 related_to.

指导方针：

• 发布有理由的决定，而不仅仅是“我做了X”—— 为什么 最重要的
• 警告具有很高的价值：它们可以防止未来的代理人犯已知的错误
• 保持内容不超过2000个字符。简明扼要。您正在为具有有限上下文窗口的其他代理编写。
• 包括 scope （文件路径）当事件与特定文件相关时，这将启用范围查询和过时检测

query --搜索项目历史记录

engram query(text="authentication")
engram query(event_type="warning", scope="src/auth")
engram query(since="24h", event_type="mutation")
engram query(related_to="evt-abc123")

全文搜索加结构化过滤器。过滤器与AND逻辑相结合。当你需要简报提供之外的特定背景时，可以使用这个。

区域标签

每个事件都可以携带一个可选 area --概念组件标签 (billing, email-change)独立于文件 scope.它使一个 跨会话跨多个文件的功能，可在一个查询中调用：

engram post -t decision -c "cooldown on resend" -s src/lib/rate-limit.ts -A email-change
engram query --area email-change

自动填充 area 无需手动设置，添加 .engram/areas.json:

{
  "rules": [
    { "prefix": "src/http/routes/me/", "area": "account" },
    { "prefix": "src/billing/", "area": "billing" }
  ]
}

最长的匹配前缀获胜。该文件是可选的；没有它， area 就是你明确传递的任何内容（或空）。

resolve_event / supersede_event / reopen_event --保持状态活跃

engram resolve_event(event_id="evt-abc123", reason="Fixed in PR #42")
engram supersede_event(event_id="evt-abc123", superseded_by="evt-def456")
engram reopen_event(event_id="evt-abc123")

事件不仅仅是追加。当警告被处理时， resolve_event 这样它就不会像活的那样浮出水面了。当一个决定被替换时，发布新的决定，然后 supersede_event 新身份证的旧身份证。 reopen_event 如果已解决的问题再次出现。保持状态最新是让简报只显示实时状态，而不是添加过时但看起来实时的条目。

status --检查系统状态

engram status

返回事件计数、上次活动时间戳和数据库大小。可用于检查Engram是否已填充。

session_start / session_end --宣布你正在做什么

engram session_start(focus="Implementing auth middleware", scope=["src/auth/"])
engram session_end(session_id="ses-abc123")

会话让其他代理（以及您的未来会话）知道正在处理什么。事件会自动标记为您的活动会话。简报会自动聚焦到会话的范围。每个代理只有一个会话——启动一个新的会话会结束前一个会话。

什么是好活动

好： decision: Using FTS5 instead of embeddings for search — covers 95% of queries at <10k events with zero dependencies

坏： decision: Changed search

好： warning: Do NOT modify the user_sessions table — migration to new schema is pending in PR #47, any changes will be overwritten

坏： warning: be careful with sessions

内容应该是独立的。未来的代理人阅读它时不会有你当前的背景。

为人类：设置和安装

先决条件

• Python 3.12+
• 项目目录（最好是git存储库——Engram在init上挖掘git历史）

将船只分为两种形式。选择一个与您的环境相匹配的：

• 选项1:克劳德代码插件 --单安装包，自动连接MCP服务器、钩子和斜线命令技能。推荐给Claude Code用户。
• 选项2:Python包 --从源代码安装（见下文），仅CLI或配置为其他客户端的MCP服务器（Cline、Cursor、Continue、自定义LLM应用程序）。用于无头自动化或任何非Claude Code的环境。（还没有在PyPI上—— engram name中有一个无关的占位符包；不要 pip install engram.)

两条路径在下面共享相同的Python包；插件正在打包+顶部布线。您可以在每个项目之间切换。

选项1:克劳德代码插件（推荐）

安装Python包 engram 和 engram-mcp 在路径上：

# Once Engram ships on PyPI:
pip install engram[mcp]

# Until then, from a repo checkout:
git clone https://github.com/coinstax/engram
cd engram
pip install -e ".[mcp]"

在Claude Code中加载插件（开发模式，直到发布市场列表）：

cd /path/to/your/project
claude --plugin-dir /path/to/engram/plugin

插件连接了什么：

• mcp__engram__* 每个会话中的MCP工具
• PostTool使用钩子捕获写入/编辑突变和bash结果
• 自动初始化的SessionStart钩子 .engram/ 首次启动时，从git历史中提取种子，并发布简报（无手册 engram init 需要）
• Slash命令-当前 /engram:briefing；v1.7.0中有更多内容(/engram:post-decision, /engram:query, /engram:checkpoint-save, /engram:checkpoint-restore)

该插件不会修改您的 CLAUDE.md --面向代理的指导是通过MCP服务器的内置提供的 instructions 字段和插件的SKILL.md文件。看 插件/README.md 有关从CLI安装的挂钩迁移的详细信息（运行 engram hooks uninstall 首先避免重复事件捕获）。

添加 .engram/ 对你 .gitignore --数据库是机器本地的。

选项2:Python包（用于其他MCP客户端或无头使用）

# From source
git clone https://github.com/coinstax/engram
cd engram
pip install -e ".[mcp]"

# Or just the CLI (no MCP server)
pip install -e .

咨询需要额外的SDK。 多模型咨询功能(engram consult, start_consultation)取决于提供商的SDK，这些SDK是可选的，因此基础安装和MCP服务器保持精简。用 consult 额外（或 all MCP+共同咨询）：

pip install -e ".[consult]"   # openai, google-genai, httpx, python-dotenv
pip install -e ".[all]"       # mcp + consult

然后在环境或项目中为要使用的提供程序设置API密钥 .env。您只需要实际咨询的提供商的密钥：

# example .env in your project root
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
XAI_API_KEY=xai-...

跑 engram consult models 查看检测到哪些密钥（它加载 .env).如果没有安装SDK，咨询将失败，并显示一条消息告诉您安装 engram[consult].

在项目中初始化：

cd /path/to/your/project
engram init

这做了四件事：

1. 创造 .engram/events.db （WAL模式+FTS5的SQLite数据库）
2. 挖掘你的git历史记录来为事件存储添加种子（解决冷启动问题）
3. 写a CLAUDE.md 带有代理指令（或附加到现有指令中）
4. 建议跑步 engram hooks install 用于被动观察

添加 .engram/ 对你 .gitignore --数据库是每台机器的本地数据库。

启用被动观察（Claude Code挂钩，手动安装）：

engram hooks install

将钩子写入 .claude/settings.json 自动：

• 当Claude Code使用写入或编辑工具时记录文件突变
• 记录bash命令结果（跳过像这样的琐碎命令 ls, cat, pwd)
• 在每节课开始时进行项目简报

安装了钩子后，代理可以自动获取上下文，而无需手动发布。检查状态或删除 engram hooks show / engram hooks uninstall（如果你使用的是选项1，跳过这个——插件已经附带了这些钩子。）

配置为MCP服务器（适用于插件以外的客户端）：

添加到代理的MCP配置中：

{
  "mcpServers": {
    "engram": {
      "command": "/path/to/your/venv/bin/engram-mcp",
      "env": {
        "ENGRAM_PROJECT_DIR": "/path/to/your/project"
      }
    }
  }
}

MCP服务器公开了17个工具： post_event, query, resolve_event, supersede_event, reopen_event, briefing, status, session_start, session_end, list_sessions, save_checkpoint, list_models, start_consultation, start_consultation_file, consult_say, consult_show, consult_done.

安全模式（无外部LLM访问的内存）：

若要为代理提供项目内存，但无法调用外部LLM提供程序或从环境中读取API密钥，请在安全模式下运行服务器。这就去掉了六种咨询工具(list_models, start_consultation, start_consultation_file, consult_say, consult_show, consult_done)，留下11个确定性本地项目内存工具。两种等效方式：

• 使用 engram-mcp-safe 控制台脚本而不是 engram-mcp，或
• 集 ENGRAM_SAFE_MODE=1 在服务器的环境中。

{
  "mcpServers": {
    "engram": {
      "command": "/path/to/your/venv/bin/engram-mcp-safe",
      "env": {
        "ENGRAM_PROJECT_DIR": "/path/to/your/project"
      }
    }
  }
}

status 报告 "external_llm_tools": false 当安全模式处于活动状态时。对于非Claude集成， engram init --no-claude-md 在不创建或修改的情况下播种项目 CLAUDE.md.

代理指令（如果您的框架没有自动加载 CLAUDE.md):

engram init 将此块写入项目的 CLAUDE.md。如果您的代理框架从其他文件读取指令，请将其复制到那里：

## Project Memory (Engram)
This project uses Engram for persistent memory across agent sessions.

### Every session
- **Start of every session**: Call `engram briefing` to understand project context
- Use `briefing --focus src/path` for scope-aware context on a specific area

### Recording events
- After important decisions: `post_event` with type "decision" and your rationale
- To leave warnings for future agents: `post_event` with type "warning"
- After discovering something about the codebase: `post_event` with type "discovery"
- Set `priority` to "critical" or "high" for urgent warnings that all agents must see
- Include `scope` (file paths) so events appear in focused briefings

### Event lifecycle
- When an issue is fixed: resolve the event with `engram resolve <id> --reason "..."`
- When a decision is replaced: supersede it with `engram supersede <id> --by <new-id>`
- If a resolved issue resurfaces: reopen with `engram reopen <id>`

### Searching
- To search past context: `engram query` with search terms
- Filter by type, scope, time range, or related event IDs

### Sessions (focus tracking)
- Use `session_start` with `focus` and `scope` to declare what you're working on
- Events are auto-tagged with your session; briefings auto-scope to your session's focus
- One session per agent — starting a new one ends the previous

### Consultations (design validation)
- Call `list_models` (or `engram consult models`) to see available model keys and which API keys are set
- Use `start_consultation` to get feedback from external AI models (`gpt`, `claude-opus`, `gemini-pro`, `grok`, etc.)
- Continue with `consult_say`, review with `consult_show`, close with `consult_done`
- Extend or override the model set per project in `.engram/models.json`

### Context checkpoints
- After writing a context file: `save_checkpoint` to record it and enrich with Engram events
- Use `briefing` with `full=True` to restore: combines checkpoint context + recent activity

CLI使用情况

Engram还可以作为非MCP代理或手动使用的独立CLI：

# Post events
engram post -t decision -c "Using Redis for session cache — latency requirements" -s src/cache.py
engram post -t warning -c "Don't touch migration files — pending deploy" -s db/migrations --priority critical
engram post -t outcome -c "Cache fix worked" -r evt-abc123  # link to related event

# Query
engram query "authentication"
engram query -t warning --since 7d
engram query -t mutation -s src/api --since 24h
engram query --related-to evt-abc123

# Briefing
engram briefing
engram briefing --since 24h -s src/auth
engram briefing --focus src/auth            # scope-aware: highlights auth-related events
engram briefing --resolved-window 24        # show events resolved in last 24h

# Lifecycle management
engram resolve evt-abc123 --reason "Fixed in PR #42"
engram supersede evt-abc123 --by evt-def456
engram reopen evt-abc123

# Sessions
engram session start --focus "Implementing auth" --scope src/auth
engram session ls                # list active sessions
engram session show ses-abc123   # show session details
engram session end               # end current session

# Context checkpoints
engram checkpoint .claude/context/session.md      # record + enrich with Engram data
engram checkpoint context.md --no-enrich          # record without enrichment
engram briefing --full                            # restore: checkpoint + recent activity

# Garbage collection
engram gc --dry-run          # preview what would be archived
engram gc --max-age 90       # archive mutations/outcomes older than 90 days

# Status
engram status

建筑学

src/engram/
  models.py      — Event, Session, Checkpoint, QueryFilter, BriefingResult dataclasses
  store.py       — EventStore: SQLite + WAL + FTS5, schema migration (v1→v5), session + checkpoint CRUD
  query.py       — QueryEngine: relative time parsing, structured + FTS queries
  bootstrap.py   — GitBootstrapper: mines git log + README/CLAUDE.md into seed events
  briefing.py    — BriefingGenerator: 4-section briefings, focus ranking, dedup, staleness
  formatting.py  — Compact/JSON formatters for events and sessions, relative timestamps
  context.py     — ContextAssembler: auto-context for consultation system prompts
  hooks.py       — Claude Code hooks: rich mutation/outcome capture, structural extraction, session auto-registration
  gc.py          — GarbageCollector: archives old events, preserves warnings/decisions
  checkpoint.py  — CheckpointEngine: context save/restore integration, file enrichment
  cli.py         — Click CLI: init, post, query, briefing, checkpoint, session, resolve, supersede, reopen, gc, hooks
  providers.py   — Multi-model provider dispatch (OpenAI, Google, Anthropic, xAI)
  consult.py     — Multi-turn consultation engine with persistent conversations
  mcp_server.py  — FastMCP server: 17 tools (events, sessions, checkpoints, briefing, consultations)

储存： .engram/events.db --SQLite具有WAL模式用于并发访问，FTS5虚拟表具有自动索引触发器。模式v6，在连接时自动从任何先前版本迁移。

事件架构： 13个字段： id, timestamp, event_type, agent_id, content, scope, area, related_ids, status, priority, resolved_reason, superseded_by, session_id核心7字段始终被填充； area 是可选的（显式设置或从中推断 .engram/areas.json)生命周期字段默认为合理值； session_id 自动链接到活动会话。

设计决策：

• 仅FTS5，无嵌入——覆盖<10000个事件的95%查询，无额外依赖关系
• 5种事件类型（低于原始规范中的9种）——发现、决策、警告、突变、结果
• 内容上限为2000个字符——防止代理转储整个文件
• init上的Git引导——冷启动问题被确定为首要的采用障碍
• 零配置，本地优先——仅SQLite，没有云，没有用于核心功能的服务器
• 单运行时依赖关系（点击）——MCP支持是可选的
• 被动优先——钩子自动捕捉活动；手动张贴仅适用于高信号事件
• 丰富的突变捕获——编辑差异和编写结构提取可以生成信息丰富的摘要，而不仅仅是文件路径
• 警告和决策永远不会被垃圾回收——它们代表了永久的项目知识
• 双通道分发（v1.7+）-- pip install engram 对于CLI/MCP二进制文件，用于布线的Claude Code插件。技能和MCP工具共存：用户调用工作流的技能，用于编程/自主使用的MCP。

设计过程

Engram是通过与三个AI模型进行结构化协商而设计的，每个模型都有不同的审查视角：

• OpenAI GPT-4o：被审查为将使用该系统的人工智能代理。标记了手动发布合规性问题，并推动了最小必填字段。
• 谷歌双子座2.5 Flash：重点审查大型背景法学硕士。倡导语义搜索（推迟到v2）和分层摘要。最强大的声音，实现令牌高效输出。
• 克劳德·十四行诗4.6：以评论家的身份自我评价。确定冷启动问题是致命的，认为FTS5足以满足v1，并提出了“Engram”这个名字

所有三次协商的综合结果见下文 docs/CONSULTATION_SYNTHESIS.mdv1.1路线图也经历了同样的过程——参见 docs/V1_1_SPEC.md.

路线图

v1.0 --事件存储、CLI、MCP服务器、git引导、简报、FTS5搜索

v1.1 --通过Claude Code挂钩、事件链接、Claude.md自动写入、具有去重/过时检测的智能简报、垃圾收集进行被动观察

v1.2 --带外部模型的多轮人工智能咨询系统（GPT-4o、Gemini Flash、Claude Sonnet）、持久对话存储、CLI+MCP工具

v1.3 --事件生命周期（解决/取代/重新打开）、事件优先级（关键/高/正常/低）、范围感知简报 --focus，4节简报结构，自动咨询上下文，思维模式支持

v1.4 --会话意图(engram session start/end/ls/show)、事件会话链接、活动会话的自动范围简报、过时会话清理、钩子自动注册、查阅文件功能

v1.5 --上下文保存/恢复集成(engram checkpoint, engram briefing --full)，用Engram事件丰富文件， save_checkpoint MCP工具

v1.6 --更丰富的突变捕获：编辑工具差异('old' -> 'new' 或统一diff）、编写工具结构提取（.py、.js、.ts、.rs、.go的类/定义名称）、行数、创建/编写区别

v1.6.1 --维护：一致 agent_id on hook捕获事件，atomic settings.json写道， engram hooks uninstall / show 命令， mcp<2.0 上引脚，相对时间戳测试夹具

v1.8.0 （当前版本，2026-07-07）——针对当前前沿旗舰更新的咨询模型(gpt-5.5, claude-opus-4-8, claude-sonnet-5, gemini-3.1-pro-preview, gemini-3.5-flash, grok-4.3)使用版本无关的密钥。模型集现在可以通过以下方式为每个项目扩展 .engram/models.json，以及 engram consult models /the list_models MCP工具使可用密钥可被发现。修复了潜在的400：Anthropic提供商现在使用适应性思维({"type": "adaptive"})而不是删除 budget_tokens目前的克劳德模型拒绝了这一点。

v1.7.0 （2026-07-06）——克劳德代码插件打包。Ships Engram作为单安装插件包(plugin/ 目录），自动连接MCP服务器、钩子和斜线命令技能。未初始化项目中的首次启动会自动创建 .engram/ 从git历史记录中提取种子，而无需修改用户的跟踪记录 CLAUDE.md （代理指导依赖于MCP服务器 instructions 字段和插件SKILL.md文件）。Python CLI在无头/自动化使用方面保持一流。目前船舶 /engram:briefing; /engram:post-decision, /engram:query, /engram:checkpoint-save, /engram:checkpoint-restore 接下来着陆。同样在这个循环中：事件生命周期工具(resolve/supersede/reopen)现在通过MCP公开，而不仅仅是CLI，事件获得了可选的 area 标签（模式v6），用于按独立于文件的概念对工作进行分组 scope。参见 插件/README.md 和 docs/ROADMAP.md 为了范围。

v1.7之后的下一个 --分层总结、冲突检测、结果跟踪

看 docs/ROADMAP.md 对于包含15个计划功能的完整优先路线图。

许可证

麻省理工学院——见 许可证.