Attestor

1. Install

pip install attestor                 # or: pipx install attestor

Or pull the container (introspection-grade image, single layer over python:3.12-slim, currently linux/amd64):

docker pull ghcr.io/bolnet/attestor:latest      # recommended — anonymous pull, mirrored to all registries below

Same image is mirrored to:

(An internal Azure ACR mirror exists at memwright.azurecr.io/attestor but is private — Azure customers should use az acr import from one of the public registries above.)

The image's default entrypoint is attestor mcp (MCP server over stdio). For full production use, point the container at an external Postgres + Neo4j via env vars (or compose them with attestor/infra/local/docker-compose.yml); override the entrypoint to run attestor doctor, attestor api, etc.

Install for Claude Code

The one command. pipx install attestor then attestor quickstart — zero questions, one default profile. It brings up the local backends, uses a local Ollama bge-m3 embedder (no cloud key), wires the MCP server (./.mcp.json) + lifecycle hooks, runs attestor doctor, and prints every step. Reverse it any time with attestor teardown.

pipx install attestor && attestor quickstart    # install (zero questions)
attestor teardown                                # uninstall (--purge also wipes data volumes)

Prerequisites: Docker running + Ollama serving bge-m3 (ollama pull bge-m3). quickstart's preflight scans for these and reports what's missing — it never prompts.

Driving it from inside Claude Code (plugin). Install the plugin once, then run the command it provides:

/plugin marketplace add bolnet/attestor     # one-time
/plugin install attestor                     # then ENABLE it in the /plugin → Installed menu
/attestor:install-attestor                   # runs `attestor quickstart` for you

Plugin commands are namespaced: the command is /attestor:install-attestor (and /attestor:uninstall-attestor), not a bare /install-attestor. A freshly-installed plugin can be disabled — enable it in the /plugin → Installed menu and /reload-plugins, or the command won't resolve.

Memory is isolated per project automatically — each working directory (git root, else cwd) is its own hard-isolated tenant, so projects never share memory. No namespace to configure.

The local backends come up as three Docker containers (the bundled attestor/infra/local/docker-compose.yml, which quickstart runs):

Every container, volume, and the compose network/project is named attestor_…, so docker ps -a \| grep attestor (and docker volume ls \| grep attestor) lists everything Attestor owns.

Cloud / managed backends (Neon · RDS · Cloud SQL, Pinecone Cloud, Neo4j AuraDB) and alternative embedders (Pinecone Inference llama-text-embed-v2, Voyage voyage-4, OpenAI text-embedding-3) are configured in ~/.attestor/attestor.yaml — see docs/INSTALL.md.

---

Install as a Skill (2026 agent SDKs)

Attestor ships with a canonical SKILL.md at skills/attestor-memory/SKILL.md. Both Anthropic (skills-2025-10-02) and OpenAI's Responses API converged on this format — a markdown file with YAML frontmatter — for distributing reusable agent expertise. The wheel ships the SKILL.md, so every 2026-grade harness can auto-discover it after a single pip install attestor.

The skill teaches the agent the six core primitives (recall, add, timeline, current_facts, forget, audit) plus the v4 enterprise surface (bi-temporal as_of replay, RBAC roles, namespace isolation, provenance signing, GDPR export / purge). Every code example references methods that actually exist on attestor.AgentMemory, and a CI test (tests/test_skill_md.py) keeps the SKILL.md from drifting from the live API.

To pin the contract in your own host:

```bash pip install attestor python -c "import attestor, importlib.resources as r; print(r.files('attestor'))" # confirm wheel installed

Quick start

Cost & runtime guide

Approximate, at reasoning_effort=high for answerer + judge, parallel=2, OpenRouter pricing:

To cut costs, edit configs/attestor.yaml's models.reasoning_effort.{answerer,judge} from high → medium or low.

one slice — capped at N samples (smoke)

scripts/bench/lme_run.sh knowledge-update 10

All 6 slices, capped at 10 samples each (smoke)

scripts/bench/lme_all.sh 10

4. Run a smoke benchmark (optional)

Verify your install end-to-end against a tiny LongMemEval slice. Defaults come from configs/attestor.yaml: Pinecone Inference llama-text-embed-v2 (1024-D) embedder + Pinecone vector store, openai/gpt-5.5 answerer, dual judges (openai/gpt-5.5 + anthropic/claude-sonnet-4-6), parallel=2.

set -a && source .env && set +a   # OPENROUTER_API_KEY, PINECONE_API_KEY, NEO4J_PASSWORD
.venv/bin/python scripts/lme_smoke_local.py --n 2 --yes

Every model and parameter comes from YAML — see § Benchmarking below for the full bench harness.

---

Configuration cheat sheet — `configs/bench.yaml`

bench:
  lme:
    variant: s                    # s | m | oracle
    cache_dir: ~/.cache/attestor/lme
    output_dir: docs/bench
    sample_limit: null            # null = full dataset; int = truncate
    category: null                # null = all 7; or single slice name
    categories: [...]             # iteration order for lme_all.sh
    variants_to_run: [...]        # for full size matrix

  knowledge_updates:
    fixtures_path: evals/knowledge_updates/fixtures.json
    n_cases: 50
    target_score: 0.92
    categories: [numeric, categorical, ...]

  report:
    headline_slice: abstention
    trend_csv: docs/bench/trend.csv
    markdown_path: docs/bench/LME-S.md

---

Optional BM25 / FTS lane

A trigger-maintained content_tsv tsvector + GIN index lifts queries that embeddings under-recall (acronyms, IDs, rare proper nouns). Enabled when v4 schema is detected; fuses with the vector lane via Reciprocal Rank Fusion (RRF, k=60). Graceful no-op on backends without the column (core.py:122-130).

---

Optional write quotas

mem.set_quota(user_id, daily_writes=...) → enforced on add against the v4 user_quotas table (core.py:592-621). Optional; unset means unlimited.

---

Optional: Ed25519 provenance signing

Enable via config (signing.enabled = true). On every add, attestor signs the canonical payload id || agent_id || t_created || content_hash with an Ed25519 key. mem.verify_memory(memory_id) returns bool (core.py:623-640). Optional, off by default — turn on for adversarial-write contexts where you need cryptographic non-repudiation.

---

The retrieval pipeline — semantic-first, six steps

attestor/retrieval/orchestrator.py runs the same six steps for every query:

1. Vector top-K — Pinecone cosine, k=50 (pgvector remains as opt-in fallback for self-contained deploys)
2. Graph narrow — Neo4j BFS depth ≤ 2 from each candidate's entity to the question entities; affinity bonus per hop (0-hop=+0.30, 1-hop=+0.20, 2-hop=+0.10; unreachable=−0.05). Discrete, not "soft".
3. Triples inject — typed-edge facts (uses, authored-by, supersedes) injected as synthetic memories
4. MMR rerank — λ=0.7
5. Confidence decay + temporal boost — recency lifts; stale, low-confidence rows fall
6. Budget fit — greedy monotonic-by-score pack into the caller's token budget

Every call writes a JSONL trace to logs/attestor_trace.jsonl (disable via ATTESTOR_TRACE=0).

2. Stand up the local stack — one command, zero questions

attestor quickstart

attestor quickstart does the whole local install non-interactively and prints every step: it writes ~/.attestor/{config.toml,attestor.yaml,.env}, brings up the three-role local stack in Docker, uses a local Ollama bge-m3 embedder (no cloud key), wires the Claude Code MCP server (./.mcp.json) + lifecycle hooks, and runs attestor doctor.

Prerequisites: Docker running, and Ollama serving bge-m3 (ollama pull bge-m3). quickstart runs a preflight that scans the ports/tools and tells you if anything is missing — it never prompts.

To reverse it later: attestor teardown (zero-question; keeps your data volumes by default — --purge also wipes them, --dry-run previews).

In Claude Code, drive the same install conversationally: /plugin marketplace add bolnet/attestor → /plugin install attestor (then enable it), and run /attestor:install-attestor — it runs attestor quickstart for you. Cloud/managed backends (Neon / RDS / Cloud SQL, Pinecone Cloud, Neo4j AuraDB) and alternative embedders (Pinecone Inference llama-text-embed-v2, Voyage voyage-4, OpenAI text-embedding-3) are configured in ~/.attestor/attestor.yaml (the single source of truth) — see docs/INSTALL.md.

attestor doctor (run automatically at the end, or any time) checks all four subsystems: Document Store (Postgres), Vector Store (Pinecone), Graph Store (Neo4j), Retrieval Pipeline. 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).