inspeximus

# inspeximus — the agent memory that takes it back

<img alt="A dark archive hall of suspended glass record panels receding into haze. One panel is struck through by a line of amber light, which arcs forward to a later panel. A sealed paper receipt rests on the floor beneath it." src="https://raw.githubusercontent.com/DanceNitra/inspeximus/main/docs/assets/hero.jpg">

**Your agent's most expensive failure is not forgetting. It is confidently remembering the old
answer.**

Long-term memory for AI agents in one zero-dependency Python file (`inspeximus/core.py` runs on
its own), plus an opt-in MCP server for any client and a one-line config install for Claude Code,
Cursor, Windsurf, Codex and Cline.

Correcting a fact is not the hard part, and this field already does it. Graphiti invalidates facts
and leads with it; cognee ships `forget` as one of its four operations. When we measured mem0 and
Graphiti, both kept the corrected value, which is the right thing to do. What neither has is a
channel to undo that correction on command, from an instruction that names no value. Here a fact
that was wrong, or true on Monday and outdated by Friday, gets corrected once, and you can still put
it back afterwards.

The benchmarks ask which of two conflicting facts wins. The question after that one is whether you
can take the correction back, and whether you can show what changed.

The name is from medieval charters. A king, bishop, abbot or town council opened with *inspeximus*,
"we have inspected", reciting an older document in full to record that they had examined it, usually
confirming it, and sealing the result so a later reader could check. It attested that the copy
faithfully matched the original, not that the original was true. Same guarantee here, and
`provenance()` says so in a `limits` field rather than leaving you to find out.

[![PyPI](https://img.shields.io/pypi/v/inspeximus?color=2563eb&label=pypi)](https://pypi.org/project/inspeximus/)
[![Downloads](https://img.shields.io/pypi/dm/inspeximus?color=2563eb)](https://pypistats.org/packages/inspeximus)
[![CI](https://github.com/DanceNitra/inspeximus/actions/workflows/ci.yml/badge.svg)](https://github.com/DanceNitra/inspeximus/actions/workflows/ci.yml)
[![Claims audit](https://github.com/DanceNitra/inspeximus/actions/workflows/audit.yml/badge.svg)](https://github.com/DanceNitra/inspeximus/actions/workflows/audit.yml)
[![Python](https://img.shields.io/pypi/pyversions/inspeximus)](https://pypi.org/project/inspeximus/)
[![Zero dependencies](https://img.shields.io/badge/dependencies-0-2563eb)](https://pypi.org/project/inspeximus/)
[![Tests](https://img.shields.io/badge/tests-2600%2B-2563eb)](#how-this-is-tested)
[![License](https://img.shields.io/pypi/l/inspeximus)](LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21708778.svg)](https://doi.org/10.5281/zenodo.21708778)

```bash
pip install inspeximus
```

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/correction-dark.svg">
  <img alt="After you correct a fact, how often does the old value come back? inspeximus 0%, Graphiti 0.x 13.3%, mem0 2.0.11 46.7%, and inspeximus with its guard disabled 100% — n=30 per system, each on its own native configuration." src="docs/assets/correction-light.svg">
</picture>

---

## The 30 seconds that matter

Every memory library can store and retrieve. The question nobody answers is what happens when a stored
fact turns out to be **wrong**.

```python
from inspeximus import Inspeximus

m = Inspeximus("memory.json")

m.remember("The staging database is db-3.internal", key="staging-db")
m.remember("The staging database is db-7.internal", key="staging-db")   # a correction

m.recall("which staging database")[0]["text"]
# 'The staging database is db-7.internal'          <- the correction wins, every time

m.revert("staging-db")                              # and it is reversible
m.recall("which staging database")[0]["text"]
# 'The staging database is db-3.internal'
```

No embedding drift, no "the LLM usually picks the newer one". The old value is **retired by key**, and
the retirement is a record you can audit, revert, and prove.

**Say the old value again and it still does not come back.** That is the part a recency rule cannot
do, and it is where most stores differ from this one: writing `db-3` a third time, under the same
key, leaves `db-7` current. Going back is a decision you make on purpose, with
`remember(..., reaffirm=True)` — the guard cannot un-supersede on its own.

**The limit, because it is keyed:** a statement written with *no* key is a new fact, not a
correction, and it is outside the guard. If your pipeline re-ingests a stale document without keys,
that text competes on its own merits. Both behaviours are measured in
[`probes/does_a_restatement_take_the_key_back.py`](probes/does_a_restatement_take_the_key_back.py),
which runs offline in a second.

---

## When someone asks you to prove it

Turn receipts on and every write joins a hash chain. The values alone cannot tell you whether
somebody edited the file behind the library's back. The chain can.

```python
from inspeximus import Inspeximus

m = Inspeximus("memory.json", receipts=True)
m.remember("The staging database is db-3.internal", key="staging-db")
m.remember("The staging database is db-7.internal", key="staging-db")

m.verify_writes()[0]        # nothing has been touched yet
# True

# now somebody edits the store directly, turning db-7 into db-9
from inspeximus import sqlite_store
items = sqlite_store.load("memory.json")
before = sqlite_store.snapshot(items)
edited = next(r for r in items if "db-7" in r["text"])
edited["text"] = edited["text"].replace("db-7", "db-9")
sqlite_store.save("memory.json", items, before)

Inspeximus("memory.json", receipts=True).verify_writes()[1][0].split(": ", 1)[1]
# 'its TEXT or KEY no longer matches its write receipt (edited after write)'
```

### Where the store is written

You do not pick a storage format. A new store is written as rows, and an existing JSON store is
converted the first time this version opens it: the conversion re-reads what it wrote and refuses
unless the record count and the id order both survive, and it leaves the original beside the store as
`memory.json.pre-rows.bak`. Encrypted stores stay a single encrypted blob, because at-rest encryption
covers the whole file.

Rows are there because every write used to rewrite the whole file, and because two writers could not
share one.

One persisted write, both formats, three independent trials of thirty writes each
(`probes/one_write_two_formats_across_store_sizes.py`):

| records in the store | whole file | one row | |
|---|---|---|---|
| 1,000 | 0.0075 s | 0.0071 s | rows about 1.1x faster |
| 10,000 | 0.0818 s | 0.0422 s | rows about 1.9x faster |
| 30,000 | 0.2334 s | 0.1292 s | rows about 1.8x faster |

The gap is a function of file size: rewriting a file gets more expensive as the file grows and
writing one row does not, so the gain arrives with the records. Take the smallest row as the least
reliable one. At a thousand records the two are close enough that separate runs of this probe have
come out both ways, and in the run behind this table one of the three trials still did, which is why
the probe reports every trial rather than an average and says so when the direction is not stable. The table above is generated from the receipt the probe writes
(`tools/sync_store_format_table.py`), so it is what one run measured rather than what we remember.

With twelve processes writing at once, the JSON store landed 56 of 96 records in its worst trial and never landed all of them, while the row store landed every record in 4 of 4 trials at both widths tested.
See `probes/twelve_writers_and_the_one_that_stopped_writing.py`. Both probes re-measure the
whole-file baseline on the machine they run on rather than quoting ours, so a slower machine reports
a smaller gap instead of a false one.

Two things to know before you upgrade:

- **A store written by this version cannot be read by 2.26.1 or earlier.** Those versions decode the
  file as UTF-8 and raise `UnicodeDecodeError`. To go back, rename `memory.json.pre-rows.bak` over
  the store and pin the older release.
- **The rollback copy is deleted by the first erasure.** `forget`, `forget_subject` and `forget_pii`
  remove it, because a copy this library made without being asked is not somewhere personal data gets
  to survive a deletion request. `erasure_certificate()` reports what happened to that file by name,
  so the end of your rollback window is recorded rather than silent. To keep the copy, set
  `INSPEXIMUS_KEEP_CONVERSION_BACKUP=1`: the certificate then declares the backup as data the erasure
  did not reach, which is the trade you are making.

`INSPEXIMUS_STORE_FORMAT=json` keeps the old format, for a store that other tooling reads directly.

`provenance(key=...)` answers the rest in one call: every value the key has held and the policy that
retired each one, where the current value came from including taint inherited through summaries,
whether the record still matches what its receipt committed to, and a `limits` field naming what none
of it proves. Erasure works the same way. `forget_subject()` hard-deletes every memory attributable
to a person, including the summaries that inherited it through lineage, and leaves a signed
content-free tombstone, so a later reader can tell a deliberate erasure from tampering.
`erasure_certificate()` makes that checkable by a third party with no private key and no reason to
trust us.

`inspeximus compliance` prints the same evidence labelled by article, with its own scope attached:
the agent-memory slice only, not the whole system, and not a certification.

### Proving when, and whether the clock belonged to anyone

Every clock in the system belongs to the operator being audited, so `timestamp.py` gets an RFC 3161
token from a third party instead. Under eIDAS Article 41 a QUALIFIED timestamp carri