auditable-memory-records

# Auditable Memory Records **Memory records you can check, not just trust — provenance and epistemic status for AI agents.** An agent tells you something it learned three months ago. You have no way to ask where it learned it. Most agent memory systems store *what* was remembered. Almost none store how strongly it is believed, what evidence supports it, or where exactly it came from — so a stored memory can only be trusted, never checked. Auditable Memory Records (**AMR**) specifies a small set of fields that make a memory record checkable: - **`auditable_memory`** — the conformance declaration. Required, and the reason adoption is findable. - **`epistemic`** — is this observed, derived, unresolved, or merely asserted? - **`backed_by` / `contradicts`** — declared, typed links to supporting and conflicting records - **`sources` / `claims`** — quote-level citations binding an individual claim to the exact source words that justify it, with a verifiable hash ```yaml auditable_memory: "0.1" epistemic: inference claims: - text: "insulin list prices outpaced general medical inflation" source_id: sources/kff-report-2026.md span: quote: "list prices for insulin products rose 11% between 2024 and 2026" quote_hash: "sha256:029a3c30f5e0939075dea1e1e64c18a3b108f2e724c2f0a4b85d1bd7d267e48a" contradicts: [research/pharma-pricing-brief-2025] ``` → **[Read the specification](SPEC.md)** · version 0.1.0 (draft) · CC BY 4.0 **These are not new ideas.** Nanopublications, micropublications, PROV-O, TEI and W3C Web Annotation covered most of this ground years ago, some of it far more expressively. AMR's contribution is packaging and audience — a lightweight, non-RDF format aimed at LLM agent-memory implementers. [SPEC §10](SPEC.md) says exactly what is borrowed. --- ## Conformance in one table | Level | Name | What it requires | |---|---|---| | **1** | Marked | Emit `auditable_memory`, preserve `epistemic` from a closed four-value vocabulary, and never treat absence as `fact`. | | **2** | Linked | Declared `backed_by` / `contradicts`, queryable as relations, never auto-resolved. | | **3** | Cited | Claims bind to source spans with verifiable hashes, and a third party can check them without trusting you. | **Level 1 should take an afternoon** — one declaration, one preserved field, one rule about absence, and no storage-layer changes. It is deliberately cheap, but **not satisfiable by doing nothing**: an implementation that emits no `auditable_memory` field conforms at no level. That declaration is also what makes adoption countable; without it, a record implementing this perfectly is indistinguishable from one that merely looks similar. ## Running the conformance suite `conformance/` holds the test vectors, as data rather than code, so any implementation in any language can run them: | File | Covers | |---|---| | `normalize.yaml` | Quote normalization (SPEC §4) — punctuation folding, whitespace collapse, idempotence | | `level1-marked.yaml` | The closed vocabulary and the absent-is-not-fact rule | | `level2-linked.yaml` | Ref hygiene, traversal rejection, non-resolving `contradicts` | | `level3-cited.yaml` | The four verification outcomes, hash prefixing, `claim_id` derivation | Each case carries `input`, `expect`, and `why`. Cases marked *THE LOAD-BEARING CASE* in their `why` are the ones that distinguish real conformance from field-copying — if you implement nothing else from this suite, implement those. Every hash in `level3-cited.yaml` is a real `sha256` of the normalized quote and can be recomputed independently: ```python hashlib.sha256(normalize(quote).encode()).hexdigest() ``` ## Status This is a **0.1 draft published to find implementers**, not a finished standard. The fields are extracted from a working implementation rather than designed on paper — which usefully constrains the design, but also means it currently reflects one system's experience. The most useful feedback, in order: 1. **Attempt Level 1 in your system** and report what was awkward. 2. **Argue with the closed vocabulary.** Four values is a bet. If a fifth is load-bearing for you, that matters more before the vocabulary hardens than after. 3. **Break the conformance suite.** Cases it misses are the most valuable contribution available. ## Relationship to Palinode [Palinode](https://github.com/phasespace-labs/palinode) is the reference implementation. It is not a dependency: adopting this specification does not require adopting Palinode, and adoption by other systems is the explicit goal rather than a side effect. Writing this specification found a real bug in the reference implementation: quote hashes were emitted as bare MD5 digests, which record no algorithm and therefore cannot be migrated. That is now fixed (SPEC §4), and it is the clearest argument available for extracting a specification from working code — the field had been chosen incidentally, and nothing had ever forced it to be justified. ## Licence Specification text: **CC BY 4.0**. Conformance fixtures: **MIT**. Both chosen so you can copy them into your own docs and test suites without asking.