Attestor

The memory layer for agent teams. Self-hosted, deterministic retrieval, zero LLM in the critical path.

pip install attestor

| | |
|---|---|
| Version | 4.0.0a1 (alpha; greenfield rebuild — no v3 migration path) |
| PyPI | attestor |
| Import | attestor |
| Live site | <https://attestor.dev/> |
| Repo | <https://github.com/bolnet/attestor> |
| License | MIT |

---

What it is

Attestor is a memory store for agent teams that need a shared, tenant-isolated memory with bi-temporal replay, deterministic retrieval, and an auditable supersession chain. It runs as a Python library, a Starlette REST service, or an MCP server — same API in all three.

It is built around three claims, each grounded in code:

1. Bi-temporal — replay any past state. Every memory has both event time (valid_from / valid_until) and transaction time (t_created / t_expired). Nothing is deleted; everything is queryable forever (attestor/temporal/manager.py:43-73, core.py:888-890).
2. Semantic-first retrieval, no LLM in the hot path. A six-step deterministic pipeline. Same query → same ranking. Unit-testable (attestor/retrieval/orchestrator.py:1-14).
3. Conversation ingest with auditable conflict resolution. Two-pass speaker-locked extraction, then a four-decision (ADD / UPDATE / INVALIDATE / NOOP) resolver per fact. Every supersession carries an evidence_episode_id (attestor/extraction/conflict_resolver.py:98).

Designed for

- Multi-agent products where many LLMs write to the same memory store
- Regulated chat systems that need point-in-time reconstruction (compliance, audit, FOIA-style queries)
- Self-hosted deployments — your VPC, your Postgres, your Neo4j

Not designed for

- A general-purpose vector database
- A RAG framework with built-in chunking, reranking, and orchestration
- An LLM agent runtime — Attestor is the memory backend; the agent loop is yours

---

Quick start

1. Install

pip install attestor                 # or: pipx install attestor

2. Bring up local Postgres + Neo4j

attestor setup local                                       # writes attestor/infra/local/docker-compose.yml
docker compose -f attestor/infra/local/docker-compose.yml up -d

Postgres 16 ships with pgvector (document + vector roles). Neo4j 5 ships with GDS (graph role: PageRank, BFS, Leiden).

3. Pull the default embedder

ollama pull bge-m3                   # 1024-D, 8K context, local-first default

The provider chain in attestor/store/embeddings.py checks http://localhost:11434 first; cloud providers are fallbacks. Override via ATTESTOR_EMBEDDING_PROVIDER / ATTESTOR_EMBEDDING_MODEL.

4. Verify (mandatory)

attestor doctor

All four checks must be green for the default install: Document Store, Vector Store, Graph Store, Retrieval Pipeline. Graph (Neo4j) is required — the 6-step retrieval pipeline narrows on graph neighborhoods and the conversation ingest path writes typed edges (uses, authored-by, supersedes). The only hard dependency that cannot be down is the document store (Postgres); transient vector-probe failures are surfaced in the response trace rather than swallowed (retrieval/orchestrator.py — vector_error field).

5. Use it

from attestor import AgentMemory, AgentContext, AgentRole
mem = AgentMemory()                  # picks up env / ~/.attestor.toml automatically
ctx = AgentContext(

    agent_id="researcher-1",

    role=AgentRole.RESEARCHER,

    namespace="acme-prod",

)
mem.add(

    content="Alice is the engineering manager",

    entity="alice",

    category="role",

    context=ctx,

)
results = mem.recall(query="who runs engineering?", context=ctx)

for r in results:

    print(r.score, r.memory.content)

> SOLO mode (zero-config). In v4, AgentMemory().add('foo') auto-provisions a singleton local user, an Inbox project (metadata.is_inbox=true), and a daily session — so the snippet above works on a fresh database without configuring identity (core.py:179-209). For multi-tenant production use, pass an explicit AgentContext with a real namespace.

6. Run a smoke benchmark (optional)

Verify your install end-to-end against a tiny LongMemEval slice. Defaults match the canonical benchmark stack: openai/gpt-5.2 answerer, dual judges (openai/gpt-5.2 + anthropic/claude-sonnet-4.6), openai/gpt-5.2 distiller, OpenAI text-embedding-3-large truncated to 1024-D.

export OPENAI_API_KEY=...
.venv/bin/python scripts/lme_smoke_local.py --n 2

Every model and parameter is overridable via env var or CLI flag. See --help for the full table.

---

Architecture

Bi-temporal — replay any past state

Every memory carries two time axes:

| Axis | Columns | Meaning |
|------|---------|---------|
| Event time | valid_from, valid_until | When the fact is true in the world |
| Transaction time | t_created, t_expired | When the row landed in the store |

Plus a superseded_by chain. Old facts are never deleted — they remain queryable forever (attestor/temporal/manager.py:30-66).

```python