amb
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAMB
AMB
One Cut
One Cut
Governed project memory retrieval and writeback for any AI coding agent, in any harness, across sessions and tools.
Agent Memory Bridge (AMB) is the durable memory and signal authority. This skill is the everyday procedure for using it. Memory explains why a decision, rule, or gotcha exists. Live code, config, and tests show what is true now.
Contract baseline: AMB v0.38.4, durable schema v12, exactly 17 public MCP tools. There is no automatic learning and no 18th tool. Tool names below are the public MCP names (, , …). Clients may prefix them (). The prefix is a client label, not a different tool and not extra authority.
recallstoreagentMemoryBridge_recall为任意 harness 中的任意 AI coding agent 提供受治理的项目记忆检索与回写,跨会话和跨工具生效。
Agent Memory Bridge (AMB) 是持久记忆和信号的权威来源。本 skill 是日常使用它的操作规程。记忆解释某项决策、规则或 gotcha 为何存在。实时代码、配置和测试则表明当前真实情况。
契约基线:AMB v0.38.4,持久化 schema v12,恰好 17 个公开 MCP 工具。不存在自动学习,也没有第 18 个工具。下方工具名称是公开 MCP 名称(、 等)。客户端可能会为其添加前缀()。该前缀是客户端标签,不代表不同工具,也不提供额外权限。
recallstoreagentMemoryBridge_recallTrigger moments
触发时机
Memory helps only when the agent consults it at the right time. Waiting for the user to say "remember" or "recall" means it is almost never used. Use AMB at these moments, whatever harness you run in:
| Moment | Action | Write? |
|---|---|---|
| Start of a task in a project | One targeted | No |
| The request asks why, refers to earlier work ("last time", "we decided", "continue"), or reports a bug, error, or regression | | No |
| First file change of the session, when no recall has happened yet | | No |
| Two failed attempts at the same fix | Stop and | No |
| Before handing work to another agent | Pass the namespace and the recalled record ids in the handoff. | No |
| End of work that changed files | Consolidate: list 0-3 writeback candidates (new decision, validated gotcha, or changed fact to | Only after the user confirms |
Rules for these moments:
- Each moment costs one targeted call, not a scan. If a recall comes back empty or irrelevant, say so in one line and continue.
- The consolidate step proposes. It never stores on its own. See references/everyday_workflows.md.
- The skill describes how to use memory. The harness decides when the agent is reminded. If the host can run hooks or plugins, wire these moments there with (lifecycle_and_hooks.md). If it cannot, put the table above in the host's instruction file (for example
amb-connect).AGENTS.md - Some hosts load MCP tool schemas lazily. Load the AMB tools once at the first trigger instead of skipping memory because the tool is not loaded yet.
只有在正确时机查询记忆,记忆才能发挥作用。等待用户说出“记住”或“回忆”才使用,几乎意味着它永远不会被使用。无论使用哪种 harness,都应在以下时机调用 AMB:
| 时机 | 操作 | 是否写入? |
|---|---|---|
| 项目任务开始时 | 在已解析的 namespace 上执行一次定向 | 否 |
| 请求询问原因、涉及先前工作(“上次”“我们已经决定”“继续”),或报告 bug、错误、回归问题 | 在回答或编辑前,针对指定区域 | 否 |
| 会话中首次文件变更发生前,且尚未执行 recall | 对即将变更的文件或模块执行 | 否 |
| 同一修复尝试失败两次后 | 停止操作,并在第三次尝试前针对该症状 | 否 |
| 将工作移交给另一 agent 前 | 在交接过程中传递 namespace 和已 recall 的 record id。 | 否 |
| 更改了文件的工作结束时 | 汇总:列出 0–3 个回写候选项(新决策、已验证的 gotcha,或需要 | 仅在用户确认后 |
这些时机的规则:
- 每个时机只需一次定向调用,而非扫描。如果 recall 返回为空或不相关,用一行说明并继续。
- consolidate 步骤只提出候选项,绝不会自行存储。参见 references/everyday_workflows.md。
- 本 skill 描述如何使用记忆,harness 决定何时提醒 agent。如果宿主可以运行 hooks 或 plugins,可通过 将这些时机接入其中(lifecycle_and_hooks.md)。如果无法接入,则应将上表放入宿主的指令文件,例如
amb-connect。AGENTS.md - 某些宿主会延迟加载 MCP tool schema。应在首次触发时加载一次 AMB tools,不要因为工具尚未加载就跳过记忆。
When to use
何时使用
- Any trigger moment above.
- The user asks to remember a project decision, rule, constraint, or preference.
- The task depends on prior lessons, gotchas, or domain notes.
- A stored record is outdated, contradictory, or mis-tagged and must be corrected.
- The user wants a compact look at what a namespace already holds.
- Work continues across sessions or tools and the durable facts should travel with the project, not the chat.
- 上述任一触发时机。
- 用户要求记住某项项目决策、规则、约束或偏好。
- 任务依赖先前经验、gotcha 或领域说明。
- 已存储的记录过时、矛盾或标签错误,需要更正。
- 用户希望简要查看某个 namespace 已包含的内容。
- 工作跨会话或跨工具继续,且持久事实应随项目保存,而不是仅存在于聊天记录中。
When NOT to use
何时不要使用
- One-off questions with no project context that will not matter next session.
- Repeated recalls inside one task after the first recall for that area came back empty or irrelevant. Do not re-query the same terms.
- Mechanical syntax rules, linter errors, or directory layout conventions that can be enforced by AST tools, compilers, or linters. Harden the environment (ESLint, Biome, Ruff, type narrowing, pre-commit checks) instead of writing text to memory.
- First connection, install, , doctor, or verify. Route that to
project init.amb-connect - Tracked episode ledgers and worker handoffs, unless the task explicitly needs them. Those live in references/advanced_modes.md.
- 没有项目上下文,且下次会话也不会产生影响的一次性问题。
- 同一任务中,针对某区域首次 recall 已返回为空或不相关之后再次重复 recall。不要使用相同查询词重复请求。
- 可由 AST 工具、编译器或 linter 强制执行的机械式语法规则、linter 错误或目录布局约定。应加固环境(ESLint、Biome、Ruff、type narrowing、pre-commit checks),而不是向记忆写入文本。
- 首次连接、安装、、doctor 或 verify。应转至
project init。amb-connect - 除非任务明确需要,否则不要用于 tracked episode ledgers 和 worker handoffs。这些内容位于 references/advanced_modes.md。
Core loop
核心循环
Default to the six everyday tools: , , , , , .
recallbrowsestatsstorereviseannotate默认使用六个日常工具:、、、、、。
recallbrowsestatsstorereviseannotate1. Resolve scope
1. 解析范围
Use one governed namespace. Do not guess it from the folder name or the chat.
- Inside a git checkout that was initialized with AMB: run (or the checkout path). Use the returned
agent-memory-bridge project resolve .only whennamespaceisstatus. That value isbound.project:<slug> - ,
no_binding,ambiguous_binding, andnot_a_repositoryare not a namespace. Do not invent one. Initialization belongs torepository_unavailable.amb-connect - If the user names a scope, use that explicit namespace: ,
project:<name>, ordomain:<name>.global - Repository-free work (bots, shared practices, operating rules) does not go through . See references/scope_and_namespaces.md.
project resolve
project resolve使用一个受治理的 namespace。不要根据文件夹名称或聊天内容进行猜测。
- 在使用 AMB 初始化的 git checkout 中:运行 (或指定 checkout 路径)。仅当
agent-memory-bridge project resolve .为status时使用返回的bound。该值为namespace。project:<slug> - 、
no_binding、ambiguous_binding和not_a_repository不是 namespace。不要自行创建。初始化应由repository_unavailable处理。amb-connect - 如果用户指定了范围,使用该明确的 namespace:、
project:<name>或domain:<name>。global - 无 repository 的工作(bots、共享实践、操作规则)不使用 project resolve。参见 references/scope_and_namespaces.md。
project resolve2. Recall in context
2. 在上下文中 recall
Search before browsing the web or rereading old chat.
text
recall(
namespace=<resolved namespace>,
query="<task terms, not the whole prompt>",
kind="memory",
limit=5
)- Keep at or below 5 unless the user asks for a wider scan.
limit - Prefer a targeted query. Empty-query is for filters or signal polling, not a memory dump.
recall - Use only when you do not yet know the query. Use
browsefor a count and health check, not for content.stats - A text of durable memory can also return derived
recall. That block is rebuildable WHAT, not a stored decision.repository_knowledge
在浏览网页或重读旧聊天记录之前进行搜索。
text
recall(
namespace=<resolved namespace>,
query="<task terms, not the whole prompt>",
kind="memory",
limit=5
)- 除非用户要求更广泛地扫描,否则将 保持在 5 或以下。
limit - 优先使用定向查询。空查询 用于过滤或 signal polling,而不是导出记忆。
recall - 仅在尚不知道查询内容时使用 。使用
browse获取数量和健康状态,而不是具体内容。stats - 对持久记忆执行文本 时,也可能返回派生的
recall。该数据块是可重建的 WHAT,而不是已存储的决策。repository_knowledge
3. Check live code against memory
3. 使用记忆核对实时代码
Memory is not a substitute for the repo.
- If the record and the code agree, apply the record.
- If they disagree, the code wins for current behavior. Say so, then ask whether the memory should be revised.
- Do not "fix" code just to match a stale record, and do not silently rewrite the record to match the code.
记忆不能替代 repository。
- 如果记录与代码一致,应用该记录。
- 如果二者不一致,以代码作为当前行为的依据。说明这一情况,然后询问是否应修订记忆。
- 不要为了匹配过时记录而“修复”代码,也不要在未说明的情况下将记录改写为与代码一致。
4. Store only approved decisions
4. 仅存储已批准的决策
Write after the user confirms the fact, or after a gotcha is validated by a failing-then-fixed check.
- Apply the 3-question ingestion filter before storing:
- Can a linter catch it? Configure the linter; do not store in AMB.
- Can static types or runtime assertions enforce it? Harden types/schemas; do not store in AMB.
- Only store in AMB if it is an irreversible architectural decision, domain boundary, or external SDK gotcha.
- Explicit user intent ("remember that we pin schema v12") may be stored as a decision or constraint.
- An inferred lesson is a proposal until the user confirms it. Say what you would store; do not store it as authority.
- Use . Keep the payload compact. Templates: references/record_templates.md.
kind="memory" - Write as a bare label (
confidence:orobserved). Put the reason on a separatevalidatedorevidence:line. Extra text after the label, such assource:, is rejected asobserved (3 runs).invalid_confidence - Repeated identical calls may deduplicate. If the response is
store, enrich withduplicate_with_new_metadata. Do not store a second copy to sneak in a title or tag.annotate
Workflows: references/everyday_workflows.md.
在用户确认事实后,或某个 gotcha 通过先失败后修复的检查得到验证后写入。
- 存储前应用三问摄取过滤器:
- Linter 能捕获它吗? 配置 linter;不要存入 AMB。
- 静态类型或运行时断言能强制执行它吗? 加固类型/schema;不要存入 AMB。
- 仅在以下情况存入 AMB:不可逆的架构决策、domain boundary 或 external SDK gotcha。
- 明确的用户意图(例如“记住我们将 schema 固定为 v12”)可作为决策或约束存储。
- 推断得到的经验在用户确认前只是一项提案。说明你准备存储的内容;不要将其作为权威信息直接存储。
- 使用 。保持 payload 紧凑。模板参见 references/record_templates.md。
kind="memory" - 将 写为纯标签(
confidence:或observed)。原因应放在单独的validated或evidence:行中。标签后的额外文本(例如source:)会被拒绝并返回observed (3 runs)。invalid_confidence - 重复的相同 调用可能会被去重。如果响应为
store,使用duplicate_with_new_metadata补充信息。不要通过存储第二份副本来额外添加 title 或 tag。annotate
工作流参见 references/everyday_workflows.md。
5. Correct by superseding
5. 通过替代关系更正
When a stored fact changes, call with the predecessor id and the full replacement content. The old row stays for audit and gains a edge.
revisesupersedes- Metadata-only enrichment (title, extra tags, provenance) uses . Content stays unchanged.
annotate - is not the correction path. Use it only for the narrow cases in references/revision_and_correction.md.
forget
当已存储的事实发生变化时,使用 predecessor id 和完整的替换内容调用 。旧记录会保留用于审计,并新增 边。
revisesupersedes- 仅补充元数据(title、额外 tags、provenance)时使用 ,内容保持不变。
annotate - 不是更正路径。仅在 references/revision_and_correction.md 所述的少数场景中使用。
forget
Everyday profile
日常工具配置
| Tool | Role |
|---|---|
| Targeted search of durable memory (or signal polling when explicitly coordinating). |
| Recent items when you do not yet have a query. |
| Counts, kind breakdown, top domains, oldest/newest timestamps. |
| Create one compact memory, or one signal when coordinating. |
| New successor that supersedes an older memory. |
| Audited title, tag, or provenance enrichment without a new fact. |
Leave these for the modes that need them:
- records whether a recall result helped. It does not change the memory or the ranking.
feedback - reclassifies one existing row to
promote,learn, orgotchain place. It is a maintenance action, not the way to capture a new decision.domain-note - and
forgetare maintenance.exportdeletes.forgetcopies a namespace out for reading or interchange.export - ,
begin_run,record_run_event, andget_runare a tracked work ledger. They do not replace project memory.complete_run - ,
claim_signal, andextend_signal_leasemove coordination state. They are not durable truth.ack_signal
Full matrix: references/tool_matrix.md.
| 工具 | 作用 |
|---|---|
| 定向搜索持久记忆(明确进行协调时,也可用于 signal polling)。 |
| 在尚无查询内容时浏览近期项目。 |
| 查看数量、kind 分布、主要 domains 以及最早/最新时间戳。 |
| 创建一条紧凑记忆,或在协调时创建一条 signal。 |
| 创建替代旧记忆的新后继记录。 |
| 在不添加新事实的情况下,补充经审计的 title、tag 或 provenance。 |
以下工具保留给需要相应模式的场景:
- 记录 recall 结果是否有帮助。它不会改变记忆或排序。
feedback - 将一条现有记录原地重新分类为
promote、learn或gotcha。这是维护操作,不是记录新决策的方式。domain-note - 和
forget用于维护。export会删除记录,forget会将 namespace 复制出来以供读取或交换。export - 、
begin_run、record_run_event和get_run构成 tracked work ledger。它们不能替代项目记忆。complete_run - 、
claim_signal和extend_signal_lease用于移动协调状态。它们不代表持久事实。ack_signal
完整矩阵参见 references/tool_matrix.md。
Redlines
红线
- Never treat memory as a prompt trash can for linter errors, syntax reminders, or directory conventions. If an agent makes the same mechanical mistake twice, harden the repository environment with linter rules or types—do not write more text to memory.
- Never dump conversational transcripts, chat history, hidden reasoning, or secrets into memory.
- Never treat an unverified inferred lesson as durable authority. Confirm it with the user first.
- Never silently overwrite contradictory memory. links the successor to the predecessor. A second
reviseof a conflicting claim creates a parallel record.store - Never pass signal-only parameters as if they applied to durable memory. Do not send ,
ttl_seconds, orexpires_atonsignal_statuscalls. Omit them. The MCP boundary may null a placeholder, but the lower-level contract stays strict, and a placeholder can still hide results.kind="memory" - Never confuse a client tool allowlist with server authorization. A visible tool is not permission to write global rules, delete records, or mint a verified-success receipt. Ordinary MCP callers cannot mint verification receipts.
- 绝不将记忆当作存放 linter 错误、语法提醒或目录约定的 prompt 垃圾桶。如果 agent 两次犯下相同的机械式错误,应使用 linter 规则或类型加固 repository 环境,而不是向记忆写入更多文本。
- 绝不将对话转录、聊天历史、hidden reasoning 或 secrets 写入记忆。
- 绝不将未经验证的推断经验视为持久权威信息。必须先获得用户确认。
- 绝不静默覆盖矛盾的记忆。会将后继记录关联到前驱记录。再次
revise冲突声明会创建一条并行记录。store - 绝不把仅适用于 signal 的参数当作适用于持久记忆的参数。在 调用中不要发送
kind="memory"、ttl_seconds或expires_at,应将其省略。MCP boundary 可能会将占位值置为 null,但底层 contract 仍保持严格,占位值仍可能隐藏结果。signal_status - 绝不将客户端 tool allowlist 与服务端 authorization 混淆。工具可见并不代表有权写入全局规则、删除记录或生成已验证成功凭据。普通 MCP caller 无法生成 verification receipt。
References
参考资料
- references/tool_matrix.md — all 17 tools, inputs, outputs, and when to call them.
- references/everyday_workflows.md — session start, decisions, gotchas, inspection.
- references/record_templates.md — decision, gotcha, constraint, procedure, domain-note, handoff.
- references/revision_and_correction.md — find, revise, annotate, and the narrow cases.
forget - references/scope_and_namespaces.md — git-bound projects vs repository-free scopes.
- references/advanced_modes.md — tracked runs and coordination signals.
- references/tool_matrix.md — 全部 17 个工具、输入、输出及调用时机。
- references/everyday_workflows.md — 会话启动、决策、gotcha 与检查。
- references/record_templates.md — 决策、gotcha、约束、流程、domain-note 与 handoff 模板。
- references/revision_and_correction.md — 查找、修订、标注以及少数 场景。
forget - references/scope_and_namespaces.md — git-bound projects 与 repository-free scopes。
- references/advanced_modes.md — tracked runs 与 coordination signals。