rhanka/engram-memory

通过 MCP 使用 Engram 记忆

真实来源：@sentropic/engram 0.22.0 候选版本 (fb223377)，提供者 sentropic.engram.memory，连接器 engram-memory，合约 1.0.0。任何标记为 未验证 的内容并非由文末列出的来源所确立。

0. 主机拥有的职责（请先阅读）

• 切勿在参数中传递： tenant、workspace、scope、principal、agent_id、session、credential、auditId、deadline、cancellation、confirmation (elicitationRef)。主机会在每次调用中绑定这些值。每个输入模式都是封闭的 (additionalProperties: false)：额外的字段会导致 INVALID_SCHEMA。省略可选字段；切勿发送 null。
• 租户和工作空间隔离： 每次调用都绑定到主机选择的一个确切作用域；参数不携带作用域选择器。授权范围限定在每个 {tenantId, workspaceId} 上，并且拒绝外部作用域。你永远不会看到其他租户的记忆：未知的目标和你作用域之外的目标都会返回 NOT_FOUND。
• purpose_ref（用于 search、get、capture）必须等于你的主机绑定的目的；不匹配会导致协议拒绝。主机如何告知代理其 purpose_ref 是 未验证 的：如果你不知道，请问主机操作员。
• 变更调用（capture、request_admission、withdraw、forget）会通过主机变更防护（幂等性预留和操作摘要）。withdraw 和 forget 始终需要主机确认防护（绑定到能力、目标和操作摘要的人工审批，TTL 最多 300 秒，30 秒内执行）。当主机选择将确认标记为必需时，capture 和 request_admission 也需要确认。你不能自行确认：模型编写的 confirmed: true 无效。
• 维护绝不是代理的能力： 管理、引导、轮换、撤销、备份、恢复、迁移、投影失效、取代、争议、回退、过期、历史或候选检查均不在六种工具之内。维护授权 (['read','maintain']) 仅限主机，绝不会到达代理路径。
• 每个工具是独立发现和授权的； 启用记忆并不授予全部六个工具。缺少某个工具意味着你缺乏该能力；完全没有记忆工具意味着记忆对你禁用（默认禁用；主机和租户必须选择加入）。不要寻找其他途径。
• 协议错误不是记忆回答： -32603 受信任的调用上下文不可用（缺少或不受信任的主机上下文、目的、主体、租户或来源不匹配、缺少确认引用）和 -32602 未知工具。停止，向主机操作员报告，不要使用更改后的参数重试。

1. 何时使用记忆，何时不使用

将其用于持久、可复用的知识，这些知识值得在以后的会话中或由其他代理再次找到：带有理由的决策、关于系统的经过验证且有可引用来源的事实、约定、反复出现的陷阱及其修复方法、交接事实。

不要将其用于：草稿或进行中的状态、聊天记录、原始工具输出、任务本地笔记、推测或 §4 中的任何内容。搜索和获取仅披露 accepted_current 记录；待处理、已拒绝、已撤回、有争议、历史、已过期、信任无效和已删除的记录永远不会返回。

2. 六种工具

每个结果都是一个信封。成功：{ok: true, output: {schema_version: 1, value}, auditId, redactionClass: "high"}。失败：{ok: false, auditId, redactionClass: "high", error: {code, message, retriable}}。它通过 structuredContent 传递，并带有相同的 JSON 文本副本；isError 等于 !ok。消息是常量化的安全字符串：根据 code 和 retriable 操作，切勿根据消息操作。

通用编码。 不透明引用（purpose_ref、component_id、primary_component_id、citation_id、source_ref、evidence_ref、reason_ref）是 1 到 512 个 UTF-8 字节的 NFC 字符串。完全按照返回的样子复制 candidate_id、record_id 和 page_cursor。时间点（observed_at、expires_at）的格式为 YYYY-MM-DDTHH:mm:ss.sssZ（规范 UTC，毫秒精度）。序列化的参数对象最多为 1,048,576 个 UTF-8 字节。

engram_memory_search（只读）：使用引用和排名收据查找当前记忆。

• 输入：query（1 到 8,192 个 UTF-8 字节）、purpose_ref。可选：limit（1 到 50，默认 10）、max_packet_bytes（4,096 到 1,048,576，默认 65,536）、capability_policy {minimum_channels: "lexical" | "lexical_and_semantic", network: "forbid" | "allow"}（默认 lexical / forbid；allow 不授予任何权限）、page_cursor（之前的 next_page_cursor，相同的查询和参数）。
• 输出：{records[], rank_receipt, next_page_cursor?, response_digest}；每个记录包是 {record, redacted_fields, redaction_receipt_digest, score, rank}。record 被编辑；record.record_id 始终存在。
• 典型错误：STALE_PAGE（启动不带 page_cursor 的新搜索）、RANKING_UNAVAILABLE（所需的语义通道不可用；无静默回退；重试或请求 lexical）、PROJECTION_OVERSIZED / RESULT_TOO_LARGE（降低 limit 或调整 max_packet_bytes）。空的 records 列表表示无匹配：基础设施故障永远不会作为空成功返回。

engram_memory_get（只读）：读取一条已知的当前记录，无需排名。

• 输入：record_id（模式 ^mem_[a-z2-7]+$）、purpose_ref。可选：max_packet_bytes。
• 输出：{record, redacted_fields, redaction_receipt_digest, read_receipt, packet_digest}；read_receipt 包含 record_id、record_digest、valid_as_of、system_as_of、validated_through_cursor、authorization_receipt_digest、revalidation_receipt_digest、checked_at、receipt_digest。
• 典型错误：NOT_FOUND（未知、超出你的作用域或当前不符合条件；设计上无法区分；不要探测变体）、PROJECTION_OVERSIZED。

engram_memory_capture（追加）：将带引用的材料作为加密的待处理候选提交。

• 输入：idempotency_key、payload、evidence。
  • payload：schema_version: 2、purpose_ref、valid_time {t, t_end?}（安全整数，t_end >= t；使用纪元毫秒：已发布的当前读取路径将它们与 Date.parse 时间点进行比较，因此其他单位可能使有界记录永远不会成为当前记录）、components（1 到 64 个 {component_id, kind: "context" | "decision" | "evidence", text (1 到 65,536 字节), citation_ids (1 到 256, 不重复)}）、primary_component_id、primary_event {at, type_ref, citation_id}（at 是安全整数；其单位 未验证）、citations（1 到 256 个 {citation_id, source_ref, locator {scheme, value}, content_digest, observed_at? (Instant)}）。可选：retention {derivative_rule: "retain" | "make-ineligible", expires_at? (Instant, 严格在捕获时间之后, 在主机上限内)}、reconciliation {family_refs}（已排序、唯一，最多 64 个）。
  • 交叉引用：citation_id 值是唯一的；component_id 值是唯一的；每个组件引用都在 citations 中解析；primary_component_id 在 components 中解析；primary_event.citation_id 在 citations 中且在主要组件中。
  • evidence：{evidence_ref, evidence_digest, citation_ids (1 到 256, 不重复), attestation?}；citation_ids 必须在 payload.citations 中解析；attestation 最多 4,096 字节。
• 输出：{status: "committed_pending" | "duplicate_exact", candidate_id, record_digest?, cursor, transaction_receipt_digest}。duplicate_exact 是使用相同内容和相同幂等标识的重放。
• 典型错误：INVALID_SCHEMA（包括 expires_at 不在捕获时间之后）、UNAUTHORIZED（无捕获权限、主机策略不允许 retain、expires_at 超出主机上限、主机未同意的 reconciliation family）、DIGEST_CONFLICT、MUTATION_OUTCOME_UNKNOWN、POLICY_UNAVAILABLE。

engram_memory_request_admission（状态转换）：要求主机的收录策略对待处理候选做出决定。

• 输入：candidate_id、idempotency_key。
• 输出：{outcome: {status: "accepted" | "rejected" | "pending_adjudication" | "duplicate_exact", candidate_id, record_id?, cursor, decision_receipt_digest, transaction_receipt_digest}, replayed}。accepted 需要 record_id。内置引擎在收录时发出它；已发布的模式允许在其他状态上使用可选的 record_id。解释 outcome.status 和 replayed，而不仅仅是字段存在；duplicate_exact 收录语义仍然 未验证。rejected 和 pending_adjudication 是成功的领域结果，不是错误。
• 典型错误：NOT_FOUND、POLICY_STALE（可重试）、DIGEST_CONFLICT、MUTATION_OUTCOME_UNKNOWN。

engram_memory_withdraw（状态转换，需要确认防护）：终止待处理候选。

• 输入：candidate_id、idempotency_key、reason_ref（不透明引用，1 到 512 字节）。
• 输出：{receipt: {event_id, operation: "withdraw", from_state: "pending", to_state: "withdrawn", cursor, event_digest, authorization_receipt_digest, transaction_receipt_digest}, replayed, key_destruction: "pending" | "complete"}。
• 典型错误：gate_failed（无有效主机确认）、NOT_FOUND、DIGEST_CONFLICT、MUTATION_OUTCOME_UNKNOWN。

engram_memory_forget（状态转换，需要确认防护）：使已收录的记录最终不符合条件。

• 输入：record_id、idempotency_key、reason_ref。
• 输出：{receipt: {..., operation: "tombstone", from_state: 其中之一 accepted_current | accepted_disputed | historical | expired | trust_invalid, to_state: "tombstoned"}, replayed, projection_invalidation: "pending" | "complete", coverage_receipt_digest?}。
• 典型错误：与 withdraw 相同。

错误码及其处理方法。 如果 retriable 为 true，则退避并重试；对于变更，使用相同的 idempotency_key 和相同的参数重试。如果为 false，则不更改参数重试。

编码	操作
INVALID_SCHEMA, INVALID_DIGEST	根据封闭模式修复参数（边界、NFC、交叉引用、摘要格式 sha256: + 64 位小写十六进制）。
UNAUTHORIZED, AUTHORIZATION_EXPIRED, AUTHORIZATION_REVOKED	停止。你缺少授权。向主机报告；切勿以其他身份重试。
NOT_FOUND	将目标视为对你不可用。不要探测。
DIGEST_CONFLICT	该密钥已与不同的内容或目标一起使用。找出原因；仅对真正的新操作使用新密钥。
ILLEGAL_TRANSITION, ALREADY_TERMINAL	生命周期状态禁止该操作。使用 search 或 get 重新检查；不要循环。
MUTATION_OUTCOME_UNKNOWN	可能已提交。使用相同的密钥和参数重试，直到有明确结果。切勿假设没有发生任何事情。
gate_failed	确认或策略防护未满足。通过主机询问人类。
STALE_PAGE	启动不带 page_cursor 的新搜索。
RESULT_TOO_LARGE, PROJECTION_OVERSIZED	在边界内降低 limit 或调整 max_packet_bytes。
RATE_LIMITED, DEADLINE_EXCEEDED, CANCELLED, STORE_UNAVAILABLE, FENCE_LOST, CURSOR_GAP, POLICY_UNAVAILABLE, POLICY_STALE, PROJECTION_STALE, RANKING_UNAVAILABLE	可重试：退避，重试（对于变更加相同密钥）。如果持续存在则报告。
CAPABILITY_UNAVAILABLE, JOURNAL_CORRUPT, BLOB_MISSING, REGISTRY_VERSION_UNAVAILABLE, BACKUP_INVALID, RESTORE_REFUSED, MIGRATION_LEDGER_INVALID	操作故障。停止并向主机操作员报告。

3. 规范

1. 先搜索后捕获。 Capture 的 duplicate_exact 仅涵盖使用相同内容和相同密钥的重试；它不是语义重复检查。如果存在等效的当前记录，请引用其 record_id 而不是再次捕获。
2. 捕获创建受管控的草稿。 候选处于待处理和加密状态；不可搜索或读取，并且 candidate_id 不是 record_id。
3. 收录是请求的，而非假定的。 你不能提供决定。报告确切结果。已遗忘的内容： 新的捕获仍然返回 committed_pending。在 request_admission 上，如果有效载荷摘要与同一作用域中的已删除记录匹配，则原本接受的决策将保持为 pending_adjudication；普通的策略拒绝仍然返回 rejected。使用原始捕获密钥和相同内容的重放是捕获重放 (duplicate_exact)，而不是新的裁决。报告返回的结果；切勿更改或改写已遗忘的内容以绕过此保护。
4. 来源追溯。 每个组件引用至少一个引用；content_digest 是所引用内容的 sha256: 摘要（精确规范化 未验证）。引用、证据和理由在主机验证者检查之前仍为断言；信任类别由主机分配，而不是由你分配。你的参与者身份是主机绑定的主体、agent_id 和会话；在 text 中编写的名称不附带任何权限。
5. 幂等性。 变更调用需要一个 NFC 格式的 idempotency_key，长度为 16 到 256 个 UTF-8 字节（至少使用 16 个 ASCII 字符；已发布的 JSON Schema minLength 比运行时检查更宽松）。每个逻辑操作一个密钥，限于你的主体。在调用前记录它，以便重试时重用。相同的密钥和相同的内容：重放（duplicate_exact 或 replayed: true）。相同的密钥和不同的内容、目标或工具：DIGEST_CONFLICT。存储将每个提交标识绑定到内部意图哈希；你永远不会发送它，不匹配会表现为 DIGEST_CONFLICT。重试重用首次捕获时解析的保留策略。
6. 保留策略。 除非有指示，否则省略 retention。默认衍生规则是 make-ineligible；retain 需要显式的主机允许；超过主机上限的 expires_at 将被拒绝并返回 UNAUTHORIZED。来源中不存在经所有者批准的保留值：保留是一个开放的所有者级别要点。

4. 切勿存储的内容

• 秘密、凭据、令牌、API 或签名密钥、密码、连接字符串、.env 值、会话 cookie 以及主机自己的绑定凭