amb

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AMB

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 (
recall
,
store
, …). Clients may prefix them (
agentMemoryBridge_recall
). The prefix is a client label, not a different tool and not extra authority.
为任意 harness 中的任意 AI coding agent 提供受治理的项目记忆检索与回写,跨会话和跨工具生效。
Agent Memory Bridge (AMB) 是持久记忆和信号的权威来源。本 skill 是日常使用它的操作规程。记忆解释某项决策、规则或 gotcha 为何存在。实时代码、配置和测试则表明当前真实情况。
契约基线:AMB v0.38.4,持久化 schema v12,恰好 17 个公开 MCP 工具。不存在自动学习,也没有第 18 个工具。下方工具名称是公开 MCP 名称(
recall
、
store
等)。客户端可能会为其添加前缀(
agentMemoryBridge_recall
)。该前缀是客户端标签,不代表不同工具,也不提供额外权限。

Trigger 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:
MomentActionWrite?
Start of a task in a projectOne targeted
recall
on the resolved namespace.
No
The request asks why, refers to earlier work ("last time", "we decided", "continue"), or reports a bug, error, or regression
recall
gotchas and decisions for the named area before answering or editing.
No
First file change of the session, when no recall has happened yet
recall
on the files or module about to change.
No
Two failed attempts at the same fixStop and
recall
gotchas for the symptom before a third attempt.
No
Before handing work to another agentPass the namespace and the recalled record ids in the handoff.No
End of work that changed filesConsolidate: list 0-3 writeback candidates (new decision, validated gotcha, or changed fact to
revise
).
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
    amb-connect
    (lifecycle_and_hooks.md). If it cannot, put the table above in the host's instruction file (for example
    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 上执行一次定向
recall
。
否
请求询问原因、涉及先前工作(“上次”“我们已经决定”“继续”),或报告 bug、错误、回归问题在回答或编辑前,针对指定区域
recall
gotcha 和决策。
否
会话中首次文件变更发生前,且尚未执行 recall对即将变更的文件或模块执行
recall
。
否
同一修复尝试失败两次后停止操作,并在第三次尝试前针对该症状
recall
gotcha。
否
将工作移交给另一 agent 前在交接过程中传递 namespace 和已 recall 的 record id。否
更改了文件的工作结束时汇总:列出 0–3 个回写候选项(新决策、已验证的 gotcha,或需要
revise
的变更事实)。
仅在用户确认后
这些时机的规则:
  • 每个时机只需一次定向调用,而非扫描。如果 recall 返回为空或不相关,用一行说明并继续。
  • consolidate 步骤只提出候选项,绝不会自行存储。参见 references/everyday_workflows.md。
  • 本 skill 描述如何使用记忆,harness 决定何时提醒 agent。如果宿主可以运行 hooks 或 plugins,可通过
    amb-connect
    将这些时机接入其中(lifecycle_and_hooks.md)。如果无法接入,则应将上表放入宿主的指令文件,例如
    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,
    project init
    , doctor, or verify. Route that to
    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),而不是向记忆写入文本。
  • 首次连接、安装、
    project init
    、doctor 或 verify。应转至
    amb-connect
    。
  • 除非任务明确需要,否则不要用于 tracked episode ledgers 和 worker handoffs。这些内容位于 references/advanced_modes.md。

Core loop

核心循环

Default to the six everyday tools:
recall
,
browse
,
stats
,
store
,
revise
,
annotate
.
默认使用六个日常工具:
recall
、
browse
、
stats
、
store
、
revise
、
annotate
。

1. 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
    agent-memory-bridge project resolve .
    (or the checkout path). Use the returned
    namespace
    only when
    status
    is
    bound
    . That value is
    project:<slug>
    .
  • no_binding
    ,
    ambiguous_binding
    ,
    not_a_repository
    , and
    repository_unavailable
    are not a namespace. Do not invent one. Initialization belongs to
    amb-connect
    .
  • If the user names a scope, use that explicit namespace:
    project:<name>
    ,
    domain:<name>
    , or
    global
    .
  • Repository-free work (bots, shared practices, operating rules) does not go through
    project resolve
    . See references/scope_and_namespaces.md.
project resolve
is read-only. It does not create a binding, and caller tags, workspace labels, or prompt text cannot select identity.
使用一个受治理的 namespace。不要根据文件夹名称或聊天内容进行猜测。
  • 在使用 AMB 初始化的 git checkout 中:运行
    agent-memory-bridge project resolve .
    (或指定 checkout 路径)。仅当
    status
    为
    bound
    时使用返回的
    namespace
    。该值为
    project:<slug>
    。
  • no_binding
    、
    ambiguous_binding
    、
    not_a_repository
    和
    repository_unavailable
    不是 namespace。不要自行创建。初始化应由
    amb-connect
    处理。
  • 如果用户指定了范围,使用该明确的 namespace:
    project:<name>
    、
    domain:<name>
    或
    global
    。
  • 无 repository 的工作(bots、共享实践、操作规则)不使用 project resolve。参见 references/scope_and_namespaces.md。
project resolve
是只读操作。它不会创建 binding,caller tags、workspace labels 或 prompt text 均不能用于选择身份。

2. 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
    limit
    at or below 5 unless the user asks for a wider scan.
  • Prefer a targeted query. Empty-query
    recall
    is for filters or signal polling, not a memory dump.
  • Use
    browse
    only when you do not yet know the query. Use
    stats
    for a count and health check, not for content.
  • A text
    recall
    of durable memory can also return derived
    repository_knowledge
    . That block is rebuildable WHAT, not a stored decision.
在浏览网页或重读旧聊天记录之前进行搜索。
text
recall(
  namespace=<resolved namespace>,
  query="<task terms, not the whole prompt>",
  kind="memory",
  limit=5
)
  • 除非用户要求更广泛地扫描,否则将
    limit
    保持在 5 或以下。
  • 优先使用定向查询。空查询
    recall
    用于过滤或 signal polling,而不是导出记忆。
  • 仅在尚不知道查询内容时使用
    browse
    。使用
    stats
    获取数量和健康状态,而不是具体内容。
  • 对持久记忆执行文本
    recall
    时,也可能返回派生的
    repository_knowledge
    。该数据块是可重建的 WHAT,而不是已存储的决策。

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:
    1. Can a linter catch it? Configure the linter; do not store in AMB.
    2. Can static types or runtime assertions enforce it? Harden types/schemas; do not store in AMB.
    3. 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
    kind="memory"
    . Keep the payload compact. Templates: references/record_templates.md.
  • Write
    confidence:
    as a bare label (
    observed
    or
    validated
    ). Put the reason on a separate
    evidence:
    or
    source:
    line. Extra text after the label, such as
    observed (3 runs)
    , is rejected as
    invalid_confidence
    .
  • Repeated identical
    store
    calls may deduplicate. If the response is
    duplicate_with_new_metadata
    , enrich with
    annotate
    . Do not store a second copy to sneak in a title or tag.
Workflows: references/everyday_workflows.md.
在用户确认事实后,或某个 gotcha 通过先失败后修复的检查得到验证后写入。
  • 存储前应用三问摄取过滤器:
    1. Linter 能捕获它吗? 配置 linter;不要存入 AMB。
    2. 静态类型或运行时断言能强制执行它吗? 加固类型/schema;不要存入 AMB。
    3. 仅在以下情况存入 AMB:不可逆的架构决策、domain boundary 或 external SDK gotcha。
  • 明确的用户意图(例如“记住我们将 schema 固定为 v12”)可作为决策或约束存储。
  • 推断得到的经验在用户确认前只是一项提案。说明你准备存储的内容;不要将其作为权威信息直接存储。
  • 使用
    kind="memory"
    。保持 payload 紧凑。模板参见 references/record_templates.md。
  • 将
    confidence:
    写为纯标签(
    observed
    或
    validated
    )。原因应放在单独的
    evidence:
    或
    source:
    行中。标签后的额外文本(例如
    observed (3 runs)
    )会被拒绝并返回
    invalid_confidence
    。
  • 重复的相同
    store
    调用可能会被去重。如果响应为
    duplicate_with_new_metadata
    ,使用
    annotate
    补充信息。不要通过存储第二份副本来额外添加 title 或 tag。
工作流参见 references/everyday_workflows.md。

5. Correct by superseding

5. 通过替代关系更正

When a stored fact changes, call
revise
with the predecessor id and the full replacement content. The old row stays for audit and gains a
supersedes
edge.
  • Metadata-only enrichment (title, extra tags, provenance) uses
    annotate
    . Content stays unchanged.
  • forget
    is not the correction path. Use it only for the narrow cases in references/revision_and_correction.md.
当已存储的事实发生变化时,使用 predecessor id 和完整的替换内容调用
revise
。旧记录会保留用于审计,并新增
supersedes
边。
  • 仅补充元数据(title、额外 tags、provenance)时使用
    annotate
    ,内容保持不变。
  • forget
    不是更正路径。仅在 references/revision_and_correction.md 所述的少数场景中使用。

Everyday profile

日常工具配置

ToolRole
recall
Targeted search of durable memory (or signal polling when explicitly coordinating).
browse
Recent items when you do not yet have a query.
stats
Counts, kind breakdown, top domains, oldest/newest timestamps.
store
Create one compact memory, or one signal when coordinating.
revise
New successor that supersedes an older memory.
annotate
Audited title, tag, or provenance enrichment without a new fact.
Leave these for the modes that need them:
  • feedback
    records whether a recall result helped. It does not change the memory or the ranking.
  • promote
    reclassifies one existing row to
    learn
    ,
    gotcha
    , or
    domain-note
    in place. It is a maintenance action, not the way to capture a new decision.
  • forget
    and
    export
    are maintenance.
    forget
    deletes.
    export
    copies a namespace out for reading or interchange.
  • begin_run
    ,
    record_run_event
    ,
    get_run
    , and
    complete_run
    are a tracked work ledger. They do not replace project memory.
  • claim_signal
    ,
    extend_signal_lease
    , and
    ack_signal
    move coordination state. They are not durable truth.
Full matrix: references/tool_matrix.md.
工具作用
recall
定向搜索持久记忆(明确进行协调时,也可用于 signal polling)。
browse
在尚无查询内容时浏览近期项目。
stats
查看数量、kind 分布、主要 domains 以及最早/最新时间戳。
store
创建一条紧凑记忆,或在协调时创建一条 signal。
revise
创建替代旧记忆的新后继记录。
annotate
在不添加新事实的情况下,补充经审计的 title、tag 或 provenance。
以下工具保留给需要相应模式的场景:
  • feedback
    记录 recall 结果是否有帮助。它不会改变记忆或排序。
  • promote
    将一条现有记录原地重新分类为
    learn
    、
    gotcha
    或
    domain-note
    。这是维护操作,不是记录新决策的方式。
  • forget
    和
    export
    用于维护。
    forget
    会删除记录,
    export
    会将 namespace 复制出来以供读取或交换。
  • begin_run
    、
    record_run_event
    、
    get_run
    和
    complete_run
    构成 tracked work ledger。它们不能替代项目记忆。
  • 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.
    revise
    links the successor to the predecessor. A second
    store
    of a conflicting claim creates a parallel record.
  • Never pass signal-only parameters as if they applied to durable memory. Do not send
    ttl_seconds
    ,
    expires_at
    , or
    signal_status
    on
    kind="memory"
    calls. Omit them. The MCP boundary may null a placeholder, but the lower-level contract stays strict, and a placeholder can still hide results.
  • 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
    或
    signal_status
    ,应将其省略。MCP boundary 可能会将占位值置为 null,但底层 contract 仍保持严格,占位值仍可能隐藏结果。
  • 绝不将客户端 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
    forget
    cases.
  • 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。