rhanka/engram-memory

透過 MCP 使用 Engram 記憶

事實來源：@sentropic/engram 0.22.0 候選版（fb223377），提供者 sentropic.engram.memory，連接器 engram-memory，合約 1.0.0。任何標記為 unverified 的內容，均未得到本文末尾所列來源的證實。

0. 主機擁有的項目（請優先閱讀）

• 絕對不在參數中傳遞： tenant、workspace、scope、principal、agent_id、session、credential、auditId、deadline、cancellation、confirmation（elicitationRef）。主機會在每次呼叫時繫結這些項目。每個輸入 schema 都是封閉的（additionalProperties: false）：任何額外欄位都會導致 INVALID_SCHEMA 錯誤。請省略選用欄位；絕不傳送 null。
• 租戶與工作區隔離： 每次呼叫都繫結於主機選擇的一個確切範圍；參數不攜帶任何範圍選擇器。授權範圍是基於 {tenantId, workspaceId} 的，外部範圍會被拒絕。你永遠無法看到其他租戶的記憶：未知的目標與你範圍外的目標都會回傳 NOT_FOUND。
• purpose_ref（用於 search、get、capture）必須等於主機繫結的用途；不符會導致協議拒絕。主機如何告知代理其 purpose_ref 的方式是 unverified：如果你沒有取得，請詢問主機操作者。
• 突變呼叫（capture、request_admission、withdraw、forget）會通過主機的突變防護（冪等性保留與操作摘要）。withdraw 與 forget 始終需要主機的確認防護（繫結於能力、目標與操作摘要的人類核准，TTL 最多 300 秒，執行時間在 30 秒內）。當主機選擇將確認標記為必要時，capture 與 request_admission 也需要確認。你不能代表自己確認：模型撰寫的 confirmed: true 不具任何效果。
• 維護絕非代理的能力： 管理、啟動、輪替、撤銷、備份、還原、遷移、投影失效、取代、爭議、回滾、過期、歷史或候選項檢查，皆不在六種工具之內。維護授權（['read','maintain']）僅限主機使用，絕不會到達代理路徑。
• 每種工具皆獨立被發現與授權； 啟用記憶功能並不代表授予全部六種工具。缺少某個工具表示你缺乏該能力；完全沒有記憶工具表示記憶功能對你而言已停用（預設停用；主機與租戶必須選擇啟用）。請勿尋找其他途徑。
• 協議錯誤並非記憶的答案： -32603 Trusted invocation context unavailable（缺少或不受信任的主機上下文、用途、主體、租戶或來源不符、缺少確認參考）和 -32602 Unknown tool。請停止操作，向主機操作者報告，不要修改參數後重試。

1. 何時使用記憶，何時不使用

用於持久、可重複使用的知識，值得在之後的會話中或由其他代理再次找到：包含理由的決策、有可引用來源的系統驗證事實、慣例、常見問題及其解決方案、交接事項。

請勿用於：草稿或進行中的狀態、聊天記錄、原始工具輸出、任務層級的備註、推測，或 §4 中的任何內容。Search 與 get 僅揭露 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（必要的語意通道中斷；沒有靜默降級；重試或要求詞彙搜尋）、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 為安全整數；其單位為 unverified）、citations（1 至 256 個 {citation_id, source_ref, locator {scheme, value}, content_digest, observed_at? (Instant)}）。選用：retention {derivative_rule: "retain" | "make-ineligible", expires_at? (Instant, 嚴格在 capture 時間之後，在主機上限之內)}、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 不在 capture 時間之後）、UNAUTHORIZED（無 capture 權限、主機政策不允許 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。內建引擎在接受時會發出此值；已發布的 schema 允許在其他狀態下出現選用的 record_id。請解讀 outcome.status 與 replayed，而非僅依賴欄位存在與否；duplicate_exact 的接納語義為 unverified。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	根據封閉的 schema（界限、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。 Capture 的 duplicate_exact 僅涵蓋使用相同金鑰與相同內容的重試；它不是語義上的重複檢查。如果存在等效的當前記錄，請引用其 record_id 而非再次 capture。
2. Capture 建立一個受管制的草稿。 該候選項處於待辦狀態且已加密；它不可搜尋或讀取，且 candidate_id 不是 record_id。
3. 接納是被請求的，而非假設的。 你無法提供決定。請報告確切的結果。已遺忘的內容： 新的 capture 仍會回傳 committed_pending。在 request_admission 時，如果有效 payload 摘要與相同範圍內一個已刪除的記錄相符，則原本會接受的决定會維持為 pending_adjudication；普通的政策拒絕仍會回傳 rejected。使用相同的原始 capture 金鑰與相同內容是 capture 重播（duplicate_exact），而非新的裁定。請報告回傳的結果；絕不修改或改寫已遺忘的內容以繞過此保護。
4. 來源。 每個元件至少引用一條引文；content_digest 是所引用內容的 sha256: 摘要（確切的標準化方式為 unverified）。引文、證據與理由在主機驗證器檢查之前仍屬主張；信任類別由主機指定，絕非由你指定。你的行為者身份是主機繫結的主體、agent_id 與會話；寫在 text 中的名稱不具任何權威性。
5. 冪等性。 突變呼叫需要一個長度為 16 至 256 個 UTF-8 位元組的 NFC idempotency_key（至少使用 16 個 ASCII 字元；已發布的 JSON Schema minLength 比執行時期檢查寬鬆）。每個邏輯操作使用一個金鑰，範圍限定於你的主體。在呼叫前記錄它，以便重試時能重複使用。相同的金鑰與內容：重播（duplicate_exact 或 replayed: true）。相同的金鑰但不同的內容、目標或工具：DIGEST_CONFLICT。儲存層會將每個提交身份繫結到一個內部意圖雜湊；你永遠不會傳送它，不符會表現為 DIGEST_CONFLICT。重試會重複使用首次 capture 時解析的保留規則。
6. 保留。 除非收到指示，否則省略 retention。預設的衍生規則為 make-ineligible；retain 需要明確的主機許可；超出主機上限的 expires_at 會被拒絕並回傳 UNAUTHORIZED。在來源中不存在任何經擁有者核准的保留值：保留是一個開放的擁有者層級點。

4. 絕對不儲存的內容

• 機密、憑證、令牌、API 或簽章金鑰、密碼、連線字串、.env 值、會話 cookie 以及主機自身的繫結憑證