Attestari Atlas

Plate I

The whole map

Attestari is one engine behind six entry points. Every write becomes an event on an append-only log, every read comes from a projection folded out of that log, and the proofs hang off the same log.

Three ideas carry the whole design

• The log is the database. Six immutable event types are the source of truth. The knowledge graph, the vectors and the keyword index are projections that can be dropped and rebuilt (plate III).
• Every guarantee lives in shared code. All three storage tiers extend the chain with the same audit.next_entry() and manage keys through the same KeyManager, so the audit chain and the shred cannot drift between in-memory, SQLite and Postgres (plate VIII).
• Ports keep the core dependency-free. Extractor, Embedder, EventStore and ProjectionBackend are Python Protocols. The defaults use only the standard library; Claude, sentence-transformers and Postgres plug in behind the same shapes (plate XIV).

Plate II

The write path

One add() call records the raw message as an episode, extracts triples, skips what is already known, closes the old value of a single-valued predicate, and asserts the rest. Every append also extends the audit chain, and seals personal data when a KEK is set.

The rules add() applies

The two extractors

Plate III

The event log

Six frozen dataclasses are the whole database. The projection is a pure fold over them, and folding the log in pieces gives the same result as folding it whole, so a reader folds only what is new. A tombstone drops the subject's lineage from the fold.

The six events

Every write carries a Scope: subject_id (the data subject, and the unit of deletion), agent_id, session_id and org_id. Only the subject id is used to filter reads today.

A real log, as stored

Four add() calls (three for alice, one for ravi) and one forget("alice"), run against the in-memory store with a KEK on 0.0.8. The plaintext column is what the subject's data key would reveal; for alice that key was destroyed at seq 16, so those values are struck through.

After the forget: chain ok=True, deep verify ok=True, 10 entries skipped as sanctioned erasures, head 58d281fa599a8ad5…. Alice's recall returns None; ravi still returns Chennai.

Plate IV

Two kinds of time

Each fact carries a valid-time window, when it was true in the world, and a system time, when Attestari recorded it. Corrections close windows instead of deleting rows, so a search can replay any date.

A query with as_of answers "what was true on that day". It does not answer "what did the system believe on that day": the system-time columns are stored, but no query reads them yet. The 15 Jan 2026 preset shows a day where the two answers differ.

Plate V

The read path

search() filters first and scores second. Only facts valid at the requested instant, for the requested subject, become candidates. Each is scored on two channels, and the weights depend on whether the embedder carries real meaning.

A worked example, from a real run

query   "where does the user live"     tokens: doe · live · the · user · where
fact    "alice lives_in Berlin"        tokens: alice · berlin · in · live

keyword   1 shared (live) ÷ 5 query tokens   = 0.200
semantic  cosine of the two hash vectors          = 0.224
score     0.4 × 0.224 + 0.6 × 0.200            = 0.209   (hash-embedder weights)

top 5 for alice:
   0.209  lives_in  Berlin
   0.000  name_is   Alice
   0.000  works_at  Globex
   0.000  uses      Python
   0.000  uses      Rust

The cheap stemmer drops a trailing s from tokens longer than three letters, which is why lives matches live and does becomes doe. The four facts that scored zero still came back, because there is no score floor.

The same ranking on two engines

The other read calls

How a read stays current

Each backend keeps its last projection in a ProjectionCache, with the log position it reflects: an audit entry's seq and hash (0.0.8). A read first asks the store for the events appended since that position. The store checks the position against the audit chain, whose hash commits to every entry before it, and returns only the new events, decrypted; the cache folds them into a new projection. If the position is no longer on the chain, after a rolled-back write or a truncate, the cache folds the log again from the start.

• Each process reads the whole log once, on its first read. After that, a read with nothing new costs one indexed query, and at 30k events a SQLite search() takes 0.5 ms where 0.0.7 took 334 ms.
• A projection never changes once returned, so a result you hold stays as it was, and threads read without a lock.
• A forget reaches every process at its next read, before it answers anything. Until then an idle worker still holds the subject's decrypted facts in memory (plate XV).
• A change made directly in the database, such as a key deleted without forget() or a row edited in place, reaches a process that already holds those events only after a restart. The deep audit reports both.

Plate VI

The audit chain

Every append adds an entry whose hash covers the previous entry and a digest of the event. The chain-only check catches reordering, insertion and deletion. The deep check also re-derives each event's digest and catches silent edits. Both accept a sanctioned crypto-shred and flag a rogue key deletion.

What each digest commits to

From 0.0.7, when a KEK is set and the event has a subject, content_hash and object_hash are keyed commitments: a k1: HMAC under a key derived from the subject's DEK. Shredding the DEK destroys that key, so a retained hash can't confirm a guessed value. Deep verification re-derives them with the keys of the subjects that are still live. Without a KEK both stay plain sha256, and entries written by 0.0.6 or earlier keep theirs.

entry_hash = sha256(prev_hash + payload_hash), and the first prev hash is 64 zeros. Timestamps are committed as epoch microseconds so a Postgres round-trip re-derives byte for byte. Deep verification walks entries against readable events and skips an entry only when its ref is in erased_refs(): the subject's key is gone and a tombstone exists. The default check needs no event content at all, which is what lets it vouch for a shredded log.

A full rewrite of the whole chain is internally consistent. Detecting that requires recording the head hash somewhere the operator cannot rewrite; Attestari prints it, publishing it is a manual step today.

Plate VII

Crypto-shred and forget

Each subject's payloads and fact objects are sealed with that subject's own data key, and one root key wraps every data key. forget() deletes the wrapped data key, so every copy of that ciphertext, in backups and replicas included, goes dark at once, while the audit chain and a signed certificate remain.

Issued by the run on plate III. verify_certificate(cert, kek) returned True; the same certificate with 40 extra deletions claimed returned False. The dry run before it reported the same 3 episodes, 7 facts and manifest, with signature=None and dry_run=True. The signing key is HMAC(KEK, "attestari/certificate-signing/v1"), domain-separated from content encryption. It is symmetric: whoever holds the KEK can issue and verify.

What survives a forget

Two stores sit outside the shred and need their own backup policy: the keyring table, because a backup taken before the forget still holds the wrapped key, and the edge and entity projections, because retrieval needs plaintext. Plate VIII shows which tables go where.

Plate VIII

Storage tiers

Three EventStore adapters share one set of guarantees. They differ in durability, concurrency, how reads happen and whether certificates are kept. All three call the same audit.next_entry() and KeyManager, so the chain and the shred behave identically.

How an append stays atomic

• SQLite: the event row, its audit row and a freshly minted data key commit in one BEGIN IMMEDIATE transaction, so a crash cannot leave the chain out of step with the log. Each event row's seq equals its audit entry's seq. From 0.0.8 the data key is read from the keyring inside that transaction on every write, so a key from a rolled-back write is never reused.
• In memory: from 0.0.8 a lock orders appends, key changes and reads across threads, and a block of appends rolls back together if it raises.
• Postgres: one transaction per append takes an advisory lock, reads the last entry hash, inserts the event row with event_seq and the audit row. From 0.0.7 the event is sealed inside that transaction (ciphertext plus keyed hashes), and a lock keeps threads that share one connection from mixing their transactions. events() merges episode and fact_event back into one order by event_seq.
• Postgres projections: from 0.0.8 a write updates only the edge and entity rows its events touched, in the same transaction as the events, so the tables and the log commit together and a rolled-back write leaves them as they were. projection_state records the audit entry the tables reflect. A missing row, or one whose hash isn't on the chain, means a full rebuild() (one transaction, TRUNCATE and re-insert), as does attaching to tables a restore left empty. Events from a writer that doesn't update the tables, such as a 0.0.7 worker during an upgrade, are caught up on the next write.

Plate IX

Surfaces

Six ways in, each carrying a different slice of the facade. The matrix shows which operations each surface exposes today.

REST API

uvicorn attestari.server:app. Durable by default: Postgres when ATTESTARI_DATABASE_URL is set, otherwise the local SQLite file. It ships without authentication; put your own in front.

MCP server

attestari-mcp over stdio, or uvx --from "attestari[server]" attestari-mcp straight from PyPI. Listed in the MCP Registry as io.github.attestari/attestari.

Configuration

Plate X

Governing Mem0 and Zep

wrap() leaves retrieval with the store you already run. It records every write in Attestari's chain before passing it on, passes searches straight through, and turns the downstream delete into evidence by reading the subject back.

from attestari import Memory
from attestari.wrap import wrap

governed = wrap(mem0_client, ledger=Memory.postgres())   # adapter inferred from the client's module
governed.add("I live in Berlin.", subject_id="u1")        # ledger first, then Mem0
governed.search("where do I live", subject_id="u1")       # straight to Mem0
receipt = governed.forget("u1")
receipt.complete, receipt.downstream_verified, receipt.downstream_error, receipt.certificate

Reading a receipt

None means nobody checked, which is reported as such and never as a pass. An unrecognised non-empty read-back counts as data still present, because guessing "probably empty" is the dangerous direction for a deletion check.

Adapters

Calls made through attribute passthrough on the wrapped client are not recorded; only add, search and forget are governed. Attestari cannot shred data inside someone else's service, because it does not hold their keys. A wrapped deployment proves that the deletion was requested, that the downstream delete was called and what it returned, that Attestari's own copy is unrecoverable, and that none of that was altered afterwards.

Plate XI

Using it as a memory layer

Every integration runs the same loop: add the user's words after they speak, search before the model answers, put facts and their ids into the prompt, and forget on request.

Five ways to wire it

from attestari import Memory

mem = Memory.local()          # Memory.postgres() for a shared service

def remember(user_id, text, msg_id):
    mem.add(text, subject_id=user_id, source_ref=f"chat:{msg_id}")

def recall(user_id, query, min_score):   # tune min_score on your own data
    hits = mem.search(query, subject_id=user_id, limit=5)
    return [f"{h.edge.predicate} {h.edge.object} [fact {h.edge.fact_id[:8]}]"
            for h in hits if h.score >= min_score]

{
  "mcpServers": {
    "attestari": {
      "command": "attestari-mcp",
      "env": {
        "ATTESTARI_KEK": "<base64 key from your secret store>",
        "ANTHROPIC_API_KEY": "<for Claude extraction>"
      }
    }
  }
}

from attestari_langchain import AttestariRetriever, AttestariChatMessageHistory

retriever = AttestariRetriever(mem=mem, subject_id="u_8f3a", k=5)
# Documents carry fact_id, valid_from, source_episode_id, confidence, score

history = lambda sid: AttestariChatMessageHistory(mem, subject_id=sid)
# learns from human turns; .messages = live facts; .clear() = forget()

import { AttestariClient } from "@attestari/client";

const mem = new AttestariClient("http://memory.internal:8000");
await mem.add("I moved to Berlin.", { subjectId: "u_8f3a", sourceRef: "chat:991" });
const hits = await mem.search("where does the user live", { subjectId: "u_8f3a" });
const preview = await mem.forget("u_8f3a", "dsar-4411", true);   // dry run
const cert = await mem.forget("u_8f3a", "dsar-4411");

governed = wrap(mem0_client, ledger=Memory.postgres())

# or, for a non-Python stack, put the server in front:
#   ATTESTARI_WRAP_UPSTREAM=https://memory.internal uvicorn attestari.server:app
#   POST /v1/wrap/add · /v1/wrap/search · /v1/wrap/forget/{id}

Choosing a starting point

Rules that keep it honest in production

• Use an opaque, pseudonymous subject_id. It stays in plaintext after a shred.
• Pass source_ref (message id, document id) on every add; it is the receipt that get_provenance returns. Keep personal data out of it for the same reason.
• Backdate with valid_from when a message reports a past change ("I moved in March").
• Threshold search() scores instead of trusting answer(); it returns the top object even for an unrelated question.
• Declare multi-valued predicates your extractor produces, with PredicateRegistry.declare, or Claude's free-form predicates will supersede each other.
• Give a person who comes back after an erasure a new subject_id. From 0.0.8, add() refuses an erased one with ForgottenSubjectError, a 409 over REST.
• Preview every erasure with dry_run, pass the preview's manifest_hash as expected_manifest so the erasure covers exactly what you reviewed (0.0.7), and keep the certificate the real call returns.

Plate XII

Where it fits

Attestari earns its place where a system has to remember people and also prove what it knew and what it erased. Where neither proof matters, a plain memory layer is simpler.

Poor fits today

• Chasing retrieval leaderboards. The internal LOCOMO evidence-recall proxy is 0.711 with MiniLM embeddings and 0.661 with the hash embedder; the project does not compete on that axis.
• Multi-hop graph reasoning. Retrieval has a semantic and a keyword channel and no graph traversal.
• Very high write rates on one log. Writes take turns under one log-wide lock, about 12 ms each at 30k events (plate XV).
• Erasing every mention of a person across other people's memories. forget() removes one subject's scope.
• Policies that require physical overwriting of media. Crypto-shred destroys keys, not bytes.
• Query-time tenant isolation by org or agent. Only subject_id filters reads.

Plate XIII

Running it for compliance

Operating Attestari is mostly key policy, backup policy and a scheduled check. The evidence bundle is regenerated from the live ledger by anyone with read access, which is what makes it evidence.

Production checklist

The evidence bundle, from the plate III run

attestari evidence --deep --out ./evidence writes evidence.json and a readable EVIDENCE.md with the commands to reproduce every claim. This is the JSON for the in-memory run; certificates is null because that tier does not persist them, which the bundle reports rather than implying an empty history.

{
  "attestari_version": "0.0.8",
  "generated_at": "2026-10-09T17:59:19.149596+00:00",
  "store": "InMemoryEventStore",
  "verification": {
    "mode": "deep",
    "ok": true,
    "entries": 16,
    "head": "58d281fa599a8ad5\u2026",
    "broken_at": null
  },
  "erasures": [
    {
      "subject_id": "alice",
      "requested_by": "dpo@example.com",
      "recorded_at": "2026-10-09T17:59:19.149252+00:00",
      "erased": true,
      "live_facts": 0
    }
  ],
  "certificates": null,
  "ok": true
}

Where the regulations come in

The auditor pack in the repository (auditor/) carries the DPO one-pager and both mappings. None of it is legal advice, and the position on cryptographic erasure is favourable but unsettled.

Plate XIV

Implementation index

Where each piece lives, how big it is, and how the project measures itself.

Tests and CI gates

522 tests collected in 0.0.8; 520 pass with a local Postgres, and 2 skip unless mem0 or zep is installed. 300 of them compare the incremental fold with the 0.0.7 fold on random logs, and every projection the cache returns in any test is also checked against a full fold. CI runs a pgvector service and gates every push on: the zero-dependency spike, the full pytest suite on all tiers, the LangChain tests, the built-in eval (6 of 6), a Postgres p95 latency gate under 200 ms at 50 subjects and 200 queries, and the audit-and-forget demo.

Measured numbers

Plate XV

Sharp edges

What the code does that a deployer should know before relying on it. Surveyed against 0.0.6 on 4 October 2026 and revised for 0.0.7 and 0.0.8 on 9 October 2026: eleven items are still open, seven of them stated in the docs; five were fixed in 0.0.8 and five in 0.0.7.

Still open in 0.0.8

Fixed in 0.0.8

Fixed in 0.0.7