🤖 面向Agent - 机器可读

你是一个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"
}
}
}
}
Agent 访问

代理可以不用邮箱试用吗?

可以。npm 包自动启动独立的免费试用。之后运行 connect 验证邮箱,保留同一工作区的记忆。付费升级需要人工批准。

让下一次会话也记得

用两个会话验证一条真实项目决策。

1

在获准安装工具后,运行 npx -y engram-tools@latest --setup 免费试用 npm。无需邮箱或 API 密钥,保留已有工作区。

2

重新连接编程客户端,以实际仓库和任务调用 engram_start。

3

工作时用 engram_store 保存已确认的决策及原因,不要保存秘密。

4

在同一仓库开启新会话,请代理用 engram_recall 找到该决策及原因。

5

结合当前项目检查源记忆,用 engram_report_outcome 报告是否有帮助。

6

要保留试用工作区时,运行 npx -y engram-tools@latest connect 并验证邮箱。记忆仍在同一工作区。

首次会话

请针对本仓库的真实任务调用 engram_start。完成工作后,用 engram_store 保存一条已确认的决策和原因。保留已有工作区,不保存秘密,也不要编造演示事实。

下一次会话

请用 engram_recall 找到上次会话的项目决策和原因。展示源记忆,结合当前项目核查,再继续工作,并报告它是否有帮助。

// 何时使用每个工具

engram_start → 每个新会话的第一次调用,同时加载 setup guidance 和 smart context。
engram_rehydrate → 在上下文压缩、摘要、恢复或缺失后调用。它会恢复最新检查点、决策、待办、注意事项和最近学习。
engram_smarter → 切换任务时加载任务相关 memories 和 skills。
engram_cross_pollinate → 从其他 repos 拉取可复用经验。
engram_store → 发现了有用的东西?存储它。未来的你(和队友)会感谢你。
engram_recall → 即将做决定?检查是否有人已经解决了。不要重复造轮子。
engram_report_outcome → 回忆的记忆有帮助吗?报告它。这会训练排序系统。
engram_reflect → 在重要阶段后、切换任务前、使用多条记忆后,或交接前创建检查点。
engram_get_context → 只有在高级/debug 场景、需要某个 repo 的聚焦知识快照时,才使用 engram_get_context。普通会话使用 engram_start 或 engram_smarter。
engram_proof → 产品/admin 用法:展示记忆数量、激活状态、使用量和 benchmark 证据。不是日常编码流程的一部分。
Agent 反馈协议

不要填人工表单。训练记忆闭环。

当记忆有帮助、过期或上下文错误时,用工具报告。这个信号会直接改进之后的排序。

01使用召回记忆后,调用 engram_report_outcome,并传 success true 或 false。
02如果多条记忆影响了工作,用 engram_reflect 做里程碑检查点。
03如果其他 repo 可能解决过该模式,规划前调用 engram_cross_pollinate。

跨会话学习

你在会话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 - 为程序化消费设计。

支持和反馈

帮助我们改进 Engram

如果 setup 让人困惑、工具行为异常或价格限制看起来不对,请在这里告诉我们。消息会直接到我们这里。

支持和反馈

我们该改进什么?

Bug、混乱的 setup 步骤、价格问题和产品想法都会直接发送给 Engram 团队。

请先验证邮箱,再将反馈发送给我们的团队。此操作不会创建账户。

还需要 10 个字符0/4000