Module memory_provenance 

Phase 18.2: Memory entry provenance.

Structural security gap #3 in docs/protocols/STRUCTURAL-SECURITY-FIXES.md points out that agent memory writes (vector DBs, conversation history, scratchpads) normally happen outside Chio’s guard pipeline, which lets a compromised or confused agent plant cross-session prompt-injection payloads with no attribution. Phase 18.1 governs the writes at the guard layer; Phase 18.2 is the evidence side of that story: every governed write appends an entry to an append-only, hash-chained provenance log that ties the write to the capability and receipt that authorized it. On read, the kernel looks up the latest provenance entry for the (store, key) pair and attaches it to the receipt as memory_provenance evidence.

Keys are pairs (store, key); the empty key string is the canonical “whole-collection” marker emitted by MemoryRead when a read does not target a specific document id. Reads whose key has no chain entry are marked ProvenanceVerification::Unverified so the caller can distinguish “never governed” from “tampered chain”.

Fail-closed semantics:

• Append returns MemoryProvenanceError on any store failure; the kernel wiring treats that as a fatal error on the memory-write path (the write has already been signed as allowed, but the provenance chain must not silently drop entries).
• Verification returns ProvenanceVerification::Unverified rather than an error when the chain is intact but no entry exists, and returns it with a tampered: true reason when the stored hash disagrees with what canonical-JSON + SHA-256 would produce.

The trait is intentionally synchronous and mirrors the pattern used by crate::approval::ApprovalStore, crate::execution_nonce::ExecutionNonceStore, and the other kernel stores: in-memory reference impl lives here, SQLite impl lives in chio-store-sqlite.

Structs

InMemoryMemoryProvenanceStore

Thread-safe in-memory MemoryProvenanceStore. Useful for tests and for ephemeral deployments; production deployments should use the SQLite-backed store in chio-store-sqlite.

MemoryProvenanceAppend

Input accepted by MemoryProvenanceStore::append.

MemoryProvenanceEntry

Entry committed to the append-only provenance chain.

Enums

MemoryActionKind

Classification of a memory-shaped tool call extracted from a ToolCallRequest. Empty key values mean “whole collection”.

MemoryProvenanceError

Errors returned by MemoryProvenanceStore implementations.

ProvenanceVerification

Result of looking up provenance for a (store, key) pair.

UnverifiedReason

Why a memory read could not be verified against the provenance chain.

Constants

MEMORY_PROVENANCE_ENTRY_SCHEMA

Schema tag used in canonical-JSON hashing. Bumping this invalidates existing chains.

MEMORY_PROVENANCE_GENESIS_PREV_HASH

Sentinel prev_hash used for the first entry in a chain. Kept as a fixed 64-character hex string of zeros so canonical-JSON hashing is deterministic and the chain has no special-case branch.

Traits

MemoryProvenanceStore

Contract for the append-only, hash-chained memory provenance log.

Functions

classify_memory_action

Inspect tool_name + arguments and return a memory action if the call matches one of the well-known memory-write / memory-read tool name conventions. Returns None for everything else so non-memory tool calls bypass the provenance hook entirely.

next_entry_id

Mint a new entry id. UUIDv7 so ids sort monotonically by issuance time, matching [crate::receipt_support::next_receipt_id].

recompute_entry_hash

Compute the canonical hash that binds every field of an entry into the chain.