你是一个AI Agent。
这是你的记忆API。
Engram通过17个MCP工具为你提供持久记忆。存储你所学到的,回忆你团队知道的,报告哪些方法有效。
# 1. 免费试用,无需邮箱或 API 密钥 npx -y engram-tools@latest --setup # 2. 重启 Claude、Codex、Cursor、Gemini、Antigravity、Windsurf 或 VS Code # 3. 把这些作为 agent 指令粘贴,不是 shell 命令 用 project、repo、role、market、stack 和 task 调用 engram_start。 选择方案前,调用 engram_recall 或 engram_cross_pollinate。 如果上下文被压缩、恢复或缺失,继续前先调用 engram_rehydrate。重要阶段后或交接前,用 engram_reflect 创建检查点。
为你的工具设置
// ~/.claude/mcp.json{"mcpServers": {"engram": {"command": "npx","args": ["-y", "engram-tools@latest", "mcp"],"env": {"ENGRAM_API_URL": "https://api.engram.tools"}}}}
让下一次会话也记得
用两个会话验证一条真实项目决策。
在获准安装工具后,运行 npx -y engram-tools@latest --setup 免费试用 npm。无需邮箱或 API 密钥,保留已有工作区。
重新连接编程客户端,以实际仓库和任务调用 engram_start。
工作时用 engram_store 保存已确认的决策及原因,不要保存秘密。
在同一仓库开启新会话,请代理用 engram_recall 找到该决策及原因。
结合当前项目检查源记忆,用 engram_report_outcome 报告是否有帮助。
要保留试用工作区时,运行 npx -y engram-tools@latest connect 并验证邮箱。记忆仍在同一工作区。
首次会话
请针对本仓库的真实任务调用 engram_start。完成工作后,用 engram_store 保存一条已确认的决策和原因。保留已有工作区,不保存秘密,也不要编造演示事实。
下一次会话
请用 engram_recall 找到上次会话的项目决策和原因。展示源记忆,结合当前项目核查,再继续工作,并报告它是否有帮助。
// 何时使用每个工具
不要填人工表单。训练记忆闭环。
当记忆有帮助、过期或上下文错误时,用工具报告。这个信号会直接改进之后的排序。
跨会话学习
你在会话1中修复了一个棘手的Bug。会话2,相同的Bug模式出现在另一个文件中。你立即回忆起修复方法。
团队知识传递
前端的Cursor Agent发现API期望snake_case。后端的Claude Code Agent无需任何人告知就学会了。
规范执行
写代码前,你回忆项目规范。"用Zod做验证,不用Joi。"你自动遵循团队标准。
记忆、时效与反馈
本指南说明工具的实际行为。参数表直接来自 MCP schema。响应示例是已去除敏感信息的 HTTP 片段。MCP 通过 text/format 返回 JSON、Markdown 或简短确认;解析前请检查 format。
根据目的选择工具
开始仓库工作
engram_start工作区说明和相关记忆
回答一个具体问题
engram_recall针对该问题排序的记忆
上下文仍在,但需要切换任务
engram_smarter新任务的背景摘要
上下文丢失后继续工作
engram_rehydrate安全恢复会话日志,必要时利用当前记忆
记录阶段性进展
engram_reflect保存检查点;会话保持开启
npm 客户端可以在没有邮箱或 API 密钥的情况下创建独立的免费试用。远程 OAuth 连接需要邮箱验证。切勿编造凭据。repo 是已授权工作区内的记忆过滤条件,不会授予另一个工作区的访问权限。
开始仓库工作用 engram_start,查询具体问题用 engram_recall,切换任务用 engram_smarter,上下文压缩或工作中断后用 engram_rehydrate。Smarter 为新任务检索长期记忆,不会重建旧日志。两者都可能记录会话事件。Rehydrate 可以读取已关闭或同事的历史,但不能重新打开或写入这些会话。engram_reflect 保持会话开启;engram_close_session 才是明确结束会话的操作。
focused 默认返回 start=8、recall=5、smarter=5、cross_pollinate=5 条记忆。deep 默认分别为 16、12、12、12。显式 limit 会在工具允许的上限内覆盖默认数量。除非显式指定 include_skills=true 或 false,否则系统会按任务关键词选择相关操作指南。
Rehydrate 使用独立的日志详细度:depth=brief 最多 12 个事件和 2 份摘要,standard 为 30 和 4,full 为 60 和 8。不接受 limit,也不接受检索深度 focused/deep。
如果 recall 返回 count=0,应说明没有找到匹配记忆。检查 repo 和查询,必要时改写问题或使用 depth=deep。增加结果数量不会让无关信息变得相关。只有在其他仓库可能有可迁移经验时才使用 cross_pollinate。get_context 用于主动按类别检查记忆,并非每次空结果后的自动下一步。
将规则与会变化的事实分开
每条记忆最好只包含一个可独立维护的事实。权限规则与部署状态应有不同 ID。单条内容使用 type、content 和可选 claim;多条内容使用 claims,包含 1–32 个独立单元,每个都有 type、content、claim。不要混用两种格式。旧的未分类记忆仍为 legacy_unassessed;添加元数据不代表一条笔记一定只含一个事实。
type 是 CONVENTION、SOLUTION 等检索类别;claim.kind 区分 rule、decision、state、lesson、reference。仅 state 有 stage,可取 proposed、implemented、tested、deployed。State 必须提供带时区的 ISO 时间 observed_at,不能比服务器时间超前超过一分钟。可使用 UTC 或明确的时区偏移,请同步客户端时钟。tested/deployed 还需 evidence。证据由代理提供,Engram 不会独立核实。可选 review_after 不得早于 observed_at;它表示复查时间,不会自动使记忆过期,也不是撤销规则的授权。
kind=rule 标签不会赋予代理人的权限,也不能覆盖当前指令。只有验证过替换关系后,才使用 supersedes_memory_ids 和 change_reason。拆分旧笔记时,split_from 包含 memory_id 和 content_sha256,默认只预览。只有提供 dry_run=false 和实际返回的 split:<id>:<plan_hash> 确认值后才应用。历史部分仍然是历史,不要把旧笔记的成功票继承给无关的新事实。
示例:将占位符替换为实际返回的值。
{
"claims": [
{
"type": "CONVENTION",
"content": "Deployment requires explicit owner approval.",
"claim": {
"kind": "rule"
}
},
{
"type": "SOLUTION",
"content": "The OAuth callback fix passed the isolated test suite.",
"claim": {
"kind": "state",
"stage": "tested",
"observed_at": "2026-11-15T09:00:00Z",
"evidence": "Commit abc1234; isolated OAuth regression receipt"
}
}
]
}审查混合旧笔记,同时保留有效规则
如果笔记同时包含有效审批规则和过时发布状态,不要为了隐藏状态而撤回整条笔记。先逐一核查独立事实。在拟定 claims 中保留有效规则,仅将过时部分标为历史。只有创建者或工作区的人类所有者能拆分;源记录必须私有、有效,且尚未声明为独立 claim。
预览时同时发送 claims 和 split_from。content_sha256 必须基于保存的原文计算,不能使用缩略显示或改写文本。预览不会写入记忆。应用前检查返回的 claims、active_claims、historical_claims。下例是 MCP SDK 伪代码:source 表示真实源记忆,claims 是审查后的单元列表,只有过时部分使用 historical:true。
再次提交未改变的源记录和计划,并设置 dry_run=false,原样使用预览返回的 confirmation。不要自行构造确认值。源记录或计划改变后,需要重新预览。原笔记作为历史保留,新单元有各自 ID,且不继承旧票数。预览只校验写入方案的结构,不证明你的事实判断正确。
示例:将占位符替换为实际返回的值。
const plan = {
split_from: {
memory_id: source.id,
content_sha256: sha256(source.content) // SHA-256 hex of exact text
},
claims // reviewed independent units; obsolete pieces use historical: true
};
const result = await client.callTool({ name: "engram_store", arguments: plan });
if (result.isError) throw new Error("Split preview failed");
if (result.structuredContent?.format !== "json") throw new Error("Expected JSON preview");
const preview = JSON.parse(result.structuredContent.text);
// Review preview.claims, active_claims and historical_claims before applying.
await client.callTool({
name: "engram_store",
arguments: { ...plan, dry_run: false, confirmation: preview.confirmation }
});有用不等于已核实或仍然有效
success=true 表示记忆帮助完成了任务,并不证明它现在属实、已在生产环境运行,或旧混合笔记中的每句话都正确。trust=validated 和 confidence 是对已报告有用性的兼容性标签,不是独立验证。请查看 claim.stage、observed_at、evidence、last_outdated_report_at,并用当前代码和运行证据核查关键事实。
初始相关性可为 relevant、irrelevant、uncertain。实际使用效果可为 helpful、unhelpful、not_used、not_evaluated。只有 helpful/unhelpful 会产生结果票并影响 confidence。结果可以同时是 irrelevant 和 not_used,而不产生使用失败票。没有反馈就保持未评价状态。相关性说明与实际使用证据分别保存。
通过 engram_reflect.feedback 或 POST /api/v1/feedback 提交 useful/noisy/stale/missing_context/too_long,是在评价 Engram 产品本身。它与单条记忆的使用结果独立,不会修改该记忆的 confidence。
准确关联查询,并安全处理重试
retrieval_id 标识已记录的一次结果列表展示,session_id 标识会话日志。将每个 retrieval_id 与对应列表一同保留,尤其是同一记忆出现在多个并行查询时。retrieval_id 为 null 表示该响应无法精确归因。只要回执、记忆和调用者仍满足访问条件,旧查询或已关闭会话也可接收显式反馈;不要重开源日志。
单次实际使用通过 engram_report_outcome 传入 memory_id、success、retrieval_id。批量使用 outcomes,最多 20 个唯一的查询/记忆组合。也可将相同条目作为 pending_feedback 附在下一次 start、recall、smarter、store、reflect、cross_pollinate、get_context、skill、report_outcome 调用中。需要 outcome:write,但不额外消耗调用配额。无法评价的条目应省略,不能编造结论。
重试精确反馈时,发送相同的 retrieval_id、memory_id 和实际使用字段。Engram 会在响应中返回 duplicate=true,不增加票数。duplicate 不是输入,也不存在 retry 开关。相同重试不报 409;只有修改已记录的使用票才返回 409。旧格式缺少 retrieval_id 时,会选取过去 24 小时内同一认证成员和工作区中,包含该记忆的最新展示。session_id 可把范围限制到指定日志。旧格式重试可能增加票数,这种推断不能当成精确关联。真正的新使用应有新的检索展示。
反馈批次先于主操作提交。即使主操作失败,也应查看 feedback_receipt,因为反馈可能已成功保存。远程 MCP 和 npm 客户端都会在错误中保留回执。已提交反馈后的错误不会自动重试,但主操作本身仍可能不具幂等性。reflect.used_memories 中,最多 20 个精确反馈条目必须各带 retrieval_id,作为一个原子批次提交;旧格式放到另一次 reflect 中。后续学习或检查点可能失败,feedback_receipt 会说明已接受的结果。
示例:将占位符替换为实际返回的值。
{
"repo": "example",
"query": "Which deployment rule applies?",
"pending_feedback": [
{
"retrieval_id": "<id from the previous result list>",
"memory_id": "<memory in that list>",
"relevance": "irrelevant",
"usefulness": "not_used"
}
]
}推荐:精确关联检索的使用结果(engram_reflect 参数)
{
"store": false,
"summary": "Applied the recalled approval rule.",
"used_memories": [
{
"retrieval_id": "<id from that result list>",
"memory_id": "<memory in that list>",
"success": true,
"detail": "Checked owner approval before releasing."
}
]
}仅用于兼容:单独提交旧格式反馈(engram_reflect 参数)
{
"store": false,
"summary": "Reported a use without a retained query receipt.",
"used_memories": [
{
"memory_id": "<accessible memory id>",
"success": true,
"detail": "This use has inferred attribution, not an exact query link."
}
]
}撤回、永久删除与安全恢复
engram_retract_memory 可逆地撤回私有知识,创建者或人类工作区所有者可以操作。engram_restore_memory 要求撤回记录仍被保留,并检查配额和已确认的替换关系。再次保存相同文本或调用 rehydrate 都不会静默恢复它。已永久删除的记录无法恢复。
OAuth token 即使属于 OWNER 成员,也不能预览或执行永久删除。两种操作都需要单独使用人类工作区所有者的 API 凭据。不要获取或替换为所有者密钥来绕过 OAuth 限制。engram_delete_memory 默认预览影响;执行必须设置 dry_run=false 和 confirmation=delete:<exact memory_id>。它会删除在线记忆、已知关联副本及受影响日志的自由文本。已传给客户端的上下文、独立记录、无关联改写、服务商和备份不在此次定向删除范围内。
会话列表会隐藏与已撤回、过期或已删除知识关联的任务文本。如果无法安全重建日志,请使用安全的当前记忆,或用 engram_start(new_session=true) 创建干净日志,不要绕过隐藏机制。恢复仍保留的源记录,可能重新开放其安全保留的历史。
API参考
所有17个MCP工具的完整文档。
engram_start开始仓库工作。 用于有实质工作的会话开头;恢复丢失上下文请用 rehydrate。 返回工作区说明、会话 ID 和相关记忆。
{"agent_tool": "codex","project": "English.cash","repo": "english.cash","role": "full-stack product engineer","market": "English learning","task": "fix guest practice so it uses the same API path as paid practice","stack": ["Next.js", "TypeScript", "PostgreSQL", "LLM router"]}
engram_rehydrate上下文丢失后恢复工作。 在压缩、摘要替代历史或中断后,继续工作前调用。 返回安全可读的检查点、决策和待办,不会重开关闭的历史。
{"agent_tool": "codex","project": "Engram","repo": "engram","task": "continue mobile Safari chat fix after context compaction","reason": "chat was compacted and only a short summary remains","depth": "standard"}
engram_smarter切换任务时重新聚焦。 在同一有效会话中使用,不恢复丢失日志。 返回新任务的相关记忆和指南。
{"context": "Next.js 16 mobile Safari chat widget overflows when keyboard opens","repo": "engram","file": "web/src/components/ChatWidget.tsx","include_skills": true}
engram_cross_pollinate借鉴其他仓库的经验。 其他项目可能已解决类似问题时使用。 返回来源及适用性说明,目标仓库不作为搜索来源。
{"target_repo": "skillbridge-monorepo","context": "Add team invite flow with owner/admin permissions and email delivery","source_repos": ["engram", "evimibul"],"include_public": true,"limit": 5}
engram_store保存可独立维护的知识。 确认长期经验后使用;不要把规则和暂时状态混存。 返回单条 ID 或 claims 的各自 ID;旧笔记拆分默认预览。
{"type": "SOLUTION","content": "Mobile Safari chat panels should not autofocus inputs. Size the fixed panel from visualViewport, use 16px input text, and assert bounds after typing.","tags": ["ios", "safari", "mobile", "chat-widget"],"repo": "engram","agent_tool": "codex","context": {"file": "web/src/components/ChatWidget.tsx","platform": "ios-safari"}}
engram_recall决策前搜索具体答案。 针对一个问题、历史决策或错误。 返回排序记忆及可用的 retrieval_id;无匹配时应明确说明。
{"query": "Stripe checkout succeeded but workspace plan still free after webhook","repo": "engram","type": "SOLUTION","limit": 3}
engram_report_outcome报告记忆是否有用。 实际使用后用 retrieval_id 关联;无关不等于使用失败。 精确重复不加票,改票返回 409;旧格式从 24 小时内推断,重复可能加票。
{"retrieval_id": "retrieval_id_from_that_recall","memory_id": "cmqstripeplan123","success": true,"detail": "The recalled webhook transaction pattern fixed the dashboard plan mismatch in production."}
engram_reflect记录阶段检查点。 重要阶段、使用多条记忆后或交接前调用,不按固定计时调用。 返回经验、结果和检查点;store=false 不禁止所有写入,会话保持开启。
{"repo": "engram","task": "Fix mobile Safari chat overflow and close behavior","summary": "Chat panel now sizes from visualViewport, avoids mobile autofocus, uses 16px input text, and close restores the launcher.","used_memories": [{"memory_id": "cmqioschat123","success": true,"detail": "The iOS visualViewport gotcha pointed to the correct fix."}],"learnings": [{"type": "SOLUTION","content": "For mobile fixed panels, compute bounds from visualViewport and verify after focusing an input; CSS dvh alone may not catch layout viewport offset.","tags": ["mobile", "safari", "visualViewport"]}]}
engram_get_context按类别检查仓库记忆。 用于主动审查或调试,不必跟随每次空搜索。 返回相关类别;仓库无匹配时范围可能扩大。
{"repo": "engram","task": "Polish localized documentation without breaking rendered pages"}
engram_skill加载分步操作指南。 适合可重复流程,不用于查单个项目事实。 返回指南步骤或名称;未知名称 count=0,不安装或运行任何东西。
{"skill": "security-audit"}
engram_proof查看工作区使用证据。 用于产品或管理审查,不是日常编码必需步骤。 返回记忆、调用、激活和基准证据。
engram_proof()
engram_setup查看连接和工作区说明。 了解设置时使用;日常开始用 start。 显示工作区、工具和下一步建议。
{"agent_tool": "claude-code"}
engram_list_sessions找到准确的会话日志。 多个会话匹配时使用;workspace 可发现团队共享元数据。 返回分页元数据和 next_cursor;隐藏关联撤回知识的任务文本。
{ "repo": "engram", "scope": "mine", "limit": 20 }
engram_close_session结束指定会话。 完成或交接时可选,需要会话所有权和 session:write。 检查点和关闭原子完成;重复返回同一回执。保留记忆和只读历史。
{ "session_id": "example-session", "summary": "Tests passed; deployment awaits approval." }
engram_retract_memory可逆撤回私有知识。 创建者或人类所有者可凭 memory:write 撤回失效建议。 保留内容,隐藏检索、依赖模式及关联日志;重复无新影响。
{ "memory_id": "example-memory", "reason": "This advice needs revalidation." }
engram_restore_memory核查后重新启用撤回记忆。 限创建者或人类所有者,检查配额和替换关系。 保留原 ID 和内容;已有效记录不变,已删记录不可恢复。Store 不代替恢复。
{ "memory_id": "example-memory" }
engram_delete_memory检查并执行永久删除。 包括预览都需要人类 OWNER API 凭据,OAuth 不可用;执行需准确 confirmation。 删除在线记录、已知派生项和受影响日志文本,保留最小回执。独立记录、无关联改写、客户端历史、备份和服务商不在范围内。
{ "memory_id": "example-memory", "dry_run": true }
记忆类型
CONVENTION编码标准和团队规则
"Always use Prisma migrations"
PATTERN重复出现的方法和模板
"API routes use cached() wrapper"
GOTCHA会出错或令人意外的事
"Neon requires SSL in production"
SOLUTION有效的修复
"Fix: add pooler to connection string"
ARCHITECTURE系统设计决策
"Search uses Haversine + bbox"
DEPENDENCY库信息和版本
"Prisma 7 needs adapter pattern"
// 机器可读端点
GET https://engram.tools/api/v1/capabilities返回包含支持的工具、记忆类型、速率限制和定价的JSON - 为程序化消费设计。