rhanka/engram-memory (エングラムメモリ)

MCPを通じたエングラムメモリ

根拠: @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) を含めないでください。 ホストが呼び出しごとにこれらをバインドします。すべての入力スキーマは閉じています (additionalProperties: false): 余分なフィールドは INVALID_SCHEMA になります。オプションフィールドは省略し、null を送信しないでください。
• テナントとワークスペースの分離: 各呼び出しはホストが選択した1つの正確なスコープにバインドされます。引数にはスコープセレクタは含まれません。権限は {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 は効果がありません。
• メンテナンスはエージェントの能力ではありません: admin, bootstrap, rotate, revoke, backup, restore, migrate, projection invalidation, supersede, dispute, rewind, expire, history、candidate inspection は6つのツールの範囲外です。メンテナンス権限 (['read','maintain']) はホストのみで、エージェントパスには決して到達しません。
• 各ツールは独立して検出および許可されます。 メモリを有効にしても6つすべてが許可されるわけではありません。ツールがないということは、その機能がないことを意味します。メモリツールがまったくない場合は、メモリが無効になっていることを意味します（デフォルトで無効。ホストとテナントがオプトインする必要があります）。別のルートを探さないでください。
• プロトコルエラーはメモリの回答ではありません: -32603 Trusted invocation context unavailable (信頼できるホストコンテキスト、目的、プリンシパル、テナント、ソースの不一致、確認参照の欠落または信頼できない) および -32602 Unknown tool。停止し、ホストオペレーターに報告し、引数を変更して再試行しないでください。

1. メモリを使用するタイミングと使用しないタイミング

永続的で再利用可能な知識に使用します。後続のセッションや別のエージェントによって再発見する価値があるもの：根拠のある決定、引用可能なソースを持つシステムに関する検証済み事実、規約、よくある落とし穴とその修正、引き継ぎ情報。

使用しないもの: スクラッチ状態や進行中の状態、チャットのトランスクリプト、生のツール出力、タスクローカルなメモ、推測、または§4のもの。検索と取得は accepted_current レコードのみを開示します。保留中、却下、撤回、紛争中、履歴、期限切れ、信頼無効、トゥームストーン状態のレコードは決して返されません。

2. 6つのツール

すべての結果はエンベロープです。成功: {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 (読み取り専用): ランキングなしで既知の現在のレコードを1つ読み取ります。

• 入力: 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、キャプチャ時刻より厳密に後、ホストの上限内)}、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 は、同じ冪等性IDを持つ同一コンテンツのリプレイです。
• 典型的なエラー: INVALID_SCHEMA (キャプチャ時刻より後の expires_at を含む); UNAUTHORIZED (キャプチャ権限がない、retain がホストポリシーで許可されていない、expires_at がホストの上限を超えている、ホストの同意なしの調整ファミリ); 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 アドミッションセマンティクスは 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	閉じたスキーマ（境界、NFC、相互参照、ダイジェスト形式 sha256: + 64小文字16進数）に対して引数を修正します。
UNAUTHORIZED, AUTHORIZATION_EXPIRED, AUTHORIZATION_REVOKED	停止します。権限が不足しています。ホストに報告します。別のIDで再試行しないでください。
NOT_FOUND	ターゲットが利用できないものとして扱います。調査しないでください。
DIGEST_CONFLICT	キーが異なるコンテンツまたはターゲットですでに使用されています。理由を調べてください。新しい操作にのみ新しいキーを使用してください。
ILLEGAL_TRANSITION, ALREADY_TERMINAL	ライフサイクル状態がそれを禁止しています。検索または取得で再確認してください。ループしないでください。
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. キャプチャの前に検索。 キャプチャの duplicate_exact は、同じキーと同一コンテンツの再試行のみをカバーします。セマンティック重複チェックではありません。同等の現在のレコードが存在する場合は、再度キャプチャする代わりにその record_id を引用してください。
2. キャプチャは管理されたドラフトを作成します。 候補は保留中で暗号化されています。検索も読み取りもできず、candidate_id は record_id ではありません。
3. アドミッションは要求され、決して想定されません。 決定を提供することはできません。正確な結果を報告してください。忘れられたコンテンツ: 新しいキャプチャでも committed_pending が返されます。request_admission では、有効なペイロードダイジェストが同じスコープ内のトゥームストーン化されたレコードと一致する場合、それ以外は受け入れる決定が pending_adjudication として保留されます。通常のポリシー拒否は rejected を返します。元のキャプチャキーを同じコンテンツで再利用することは、キャプチャのリプレイ (duplicate_exact) であり、新しい裁定ではありません。返された結果を報告します。忘れられたコンテンツを変更したり、この保護を回避するために言い換えたりしないでください。
4. 来歴. すべてのコンポーネントは少なくとも1つの引用を引用します。content_digest は引用されたコンテンツの sha256: ダイジェストです（正確な正規化は unverified）。引用、証拠、理由は、ホストの検証者がチェックするまでアサーションのままです。信頼クラスはホストによって割り当てられ、決してあなたによって割り当てられることはありません。あなたのアクターIDは、ホストにバインドされたプリンシパル、agent_id、セッションです。text に書かれた名前には権限はありません。
5. 冪等性. 変更呼び出しには、16〜256 UTF-8バイトのNFC idempotency_key が必要です（少なくとも16 ASCII文字を使用。公開されたJSON Schemaの minLength はランタイムチェックよりも緩いです）。論理操作ごとに1つのキーを、あなたのプリンシパルにスコープして使用します。呼び出し前に記録して、再試行がそれを再利用できるようにします。同じキーと同じコンテンツ: リプレイ (duplicate_exact または replayed: true)。同じキーで異なるコンテンツ、ターゲット、またはツール: DIGEST_CONFLICT。ストアは各コミットIDを内部インテントハッシュにバインドします。あなたはそれを決して送信せず、不一致は DIGEST_CONFLICT として現れます。再試行は最初のキャプチャで解決された保持を再利用します。
6. 保持. 指示がない限り retention を省略します。デフォルトの派生物ルールは make-ineligible です。retain はホストの明示的な許可が必要です。ホストの上限を超える expires_at は UNAUTHORIZED で拒否されます。ソースには所有者が承認した保持値は存在しません。保持はオープンな所有者レベルのポイントです。

4. 決して保存してはいけないもの

• 秘密、資格情報、トークン、APIまたは署名キー、パスワード、接続文字列、.env 値、セッションクッキー、およびホスト自身のバインディング crede

…

[翻訳のため省略]