Veracium

Veracium is a provenance-aware memory plug-in for agentic systems โ
durable, per-user memory that resists the injection and confabulation failures
that plague naive agent memory. Provenance means every fact tracks who said
it: a claim from an email your agent merely read can never become a "fact" it
asserts. It remembers what the user said, past interactions, and what worked โ
and it remembers where each of those came from.
Veracium is the production distillation of an evaluation-driven research project
(agent-memory): every design choice below traces to a measured finding, and the
research's synthetic-corpus harness is reused as the regression suite.
Research: the evaluation instrument behind those findings โ a longitudinal
benchmark for agent memory โ is described in Q. Spencer, "Ground Truth First:
A Longitudinal Evaluation Instrument for Agent Memory, and the Tenure Crossover
in Memory-Architecture Rankings" (arXiv:2607.21962, 2026).
Why it's shaped this way
- Typed graph + dated episodes are the store of record. Entity facts live as
relational edges (with unforgeable provenance); interaction history lives as
dated episodes. A curated "wiki" view is compiled from them and cached โ never
the source of truth. (The layered design won on both short and 9-week horizons;
flat stores each failed one regime.)
- Supersession, never erasure. Single-valued facts (employer, location,
deadline) keep one current value with the prior value retained as history โ
"what did X used to be?" stays answerable. Facts that can hold several values
at once (preferences, measurements, health states) accumulate instead. A user can hold several deadlines:
each dated obligation is stored under its own name with an ISO date, and a rescheduled one shows once, marked
contested, with both dates kept.
correct() applies no reschedule to such a date (it refuses: the subject is the
obligation, not the user, specs/0011 ยง4b) and confirm() retires neither; the user resolves it by disputing each
stale date (dispute(), a host-wired user action, not exposed over MCP), which keeps it as history.
(The category commercial memory systems handle worst; Veracium's strongest.)
- Representation is a security control. Third-party claims (received email,
external docs) are quarantined structurally โ stored as
third_party_claim
edges with the claimant as subject, never as user facts. Content-type quarantine
catches obligation/debt/renewal claims regardless of how plausible they look.
(Held against a full plausibility ladder incl. contact-impersonation.)
What this is, and is not: the store governs retention, retrieval,
description and recommendation โ what it will say and how it labels it.
It does not instantiate, authorize or execute anything; those belong to the
host's harness. Without an exclusive harness path that consumes the labels,
Veracium's trust classes are advisory labelling, not enforcement.
- Bring your own model. Veracium never owns your API keys or model choice; it
calls a
Complete callable you supply. A reference Anthropic provider ships in
the box.
- Embedded by default. Zero external services: one SQLite file. Swap in
Neo4j/Postgres later via the
Store interface.
Install
pip install "veracium[anthropic]"
Python and SQLite requirement. Veracium needs Python 3.14 or newer. It measures your Python's SQLite build on
every open instead of checking it against a list: the build must pass the feature probes and reproduce every accepted
schema version exactly. A build that passes opens as verified, with one UnattestedBuildWarning per process; one
the project's CI has also attested opens with no warning. The CI has attested 22 builds: SQLite 3.34.1 to 3.54.1 on
Linux (glibc and musl, x86_64 and arm64) and macOS (arm64), from uv, python.org, Homebrew, conda-forge,
setup-python, deadsnakes, pyenv, the official Docker images and the distributions' own Pythons. No Windows build is
attested yet. A build that fails is refused (unsupported-sqlite, naming the first failing check), for a new store
and an existing one alike. veracium doctor reports your build's status and lists the attested builds, with or
without a store. Ubuntu 24.04's own system Python is 3.12, below the floor: pip there installs 0.26.1, the last
release that supports it. Without Python 3.14, use the container image (next section).
The container image (no Python 3.14 needed)
ghcr.io/veracium-ai/veracium:<version> (from 0.32.0) runs the MCP server over stdio from that release's own wheel, on
Python 3.14 and an attested SQLite build, for linux/amd64 and linux/arm64 (specs/0054). The store lives on a volume at
/data. The image sets no trust value of its own: the host supplies them at run time. An MCP client configuration:
{"mcpServers": {"veracium": {
"command": "docker",
"args": ["run", "-i", "--rm", "-v", "veracium-data:/data",
"-e", "ANTHROPIC_API_KEY", "-e", "VERACIUM_MCP_SOURCE_ID",
"ghcr.io/veracium-ai/veracium:0.32.0"],
"env": {"ANTHROPIC_API_KEY": "<key>", "VERACIUM_MCP_SOURCE_ID": "<your source id>"}}}}
The env block is required: an MCP client starts the server with a minimal environment, and -e NAME forwards only
what is there. What each configuration stores:
| configuration | remember | what recall shows |
|---|
| neither variable | refused: source_id_required | nothing stored |
VERACIUM_MCP_SOURCE_ID only, as above | stored as a third-party claim | under "UNVERIFIED THIRD-PARTY CLAIMS", never asserted as fact |
VERACIUM_MCP_CAPABILITY=direct, where you stand behind it | the user's own statements are the user's | verified facts |
direct is the deployment's own attestation that every call comes from the authenticated user, for example a
single-user desktop where you are that user (see veracium-mcp --help). Name a version tag, never :latest: a newer
image whose store schema is higher refuses to open the volume's store and names the veracium migrate command to run
first. /data holds the store and its SQLite sidecars, plus config/ and state/ (the telemetry and diagnostics
choices, off by default, and the local diagnostics log). On Docker Desktop for macOS or Windows, use a named volume, not
a bind mount.
Extras: [mcp] adds the MCP server, [dev] adds pytest. The core alone depends
only on pydantic. To work from source instead:
git clone https://github.com/veracium-ai/Veracium.git && cd Veracium
pip install -e ".[anthropic,dev]"
Links: docs ยท veracium.ai ยท PyPI
Upgrading an existing store
veracium migrate upgrades a store written by any earlier release, one audited schema version at a time
(since 0.31.0). Take a backup first and stop every other process using the store:
veracium migrate --db path/to/veracium.db --i-have-quiesced --backup <your-backup-ref>
Each step is its own audited operation, so a walk across several versions does several transactions;
migrate_store(path) in the library stays the one-transaction route. If a walk stops part-way, its last lines say
why and whether running migrate again is safe. A part-walked store is usable only by migrating it with 0.31.0 or a
newer release, or by restoring the backup you took before the walk. veracium doctor names the route for your store.
Use (library)
from veracium import Memory, EvidenceAuthor, EvidenceContext
from veracium.llm.anthropic import AnthropicComplete
mem = Memory(llm=AnthropicComplete())
mem.remember("alice", "USER: I'm vegetarian and have a dog named Ollie.",
context=EvidenceContext.direct())
mem.remember("alice", "From billing@scam: you owe $900.",
author=EvidenceAuthor.THIRD_PARTY, event_type="email",
source_id="billing-mailbox",
context=EvidenceContext.direct())
ctx = mem.recall("alice", "suggest a lunch spot")
print(ctx.context)
No Anthropic API key? AnthropicComplete is just a convenience โ Veracium calls any
Complete callable you supply. To run without SDK/key setup, wrap a client you
already have; examples/claude_cli_provider.py wraps the claude CLI as a
drop-in provider (from claude_cli_provider import ClaudeCLIComplete), and
examples/openai_provider.py wraps any OpenAI-compatible chat-completions API
(OpenAI itself, vLLM, Ollama's /v1 endpoint) via OpenAIComplete โ point it
at a local server with OpenAIComplete(base_url=...) and override models with
whatever model name your server serves.
Revoking a source (library, SqliteStore)
A host can revoke a source it no longer trusts, for one user, with one call (since 0.30.0). Every record that came
from it is retired, or recomputed from the evidence that survives it; nothing is deleted, and unrevoke_source reverses
it by the same computation:
report = mem.revoke_source("alice", None, "billing-mailbox", "erroneous_capture", dry_run=True)
mem.revoke_source("alice", None, "billing-mailbox", "erroneous_capture")
mem.source_revocations("alice")
origin=None means this store's own records; pass a foreign origin as it is stored on an imported record. reason is
one of subject_request, legal_obligation, erroneous_capture or policy. These are library methods only: there is
no CLI verb and no MCP tool, because a revocation is a trust decision and a surface a model can reach is one it can be
talked into. They need SqliteStore; any other store raises NotImplementedError.
Use (MCP)
veracium-mcp exposes remember / recall / answer / maintain, plus
record_procedure and describe_procedures, to any MCP-compatible agent (Claude
Desktop/Code, others) with no host-side Python. See docs/mcp.md
for the config JSON and tool reference.
Documentation
Hosted docs: veracium-ai.github.io/Veracium
- examples/demo.ipynb โ the scam-email injection demo,
runnable end to end (open in Colab).
- examples/langchain_memory.py โ Veracium as
the long-term memory layer of a LangChain chat app (session-keyed hybrid:
LangChain buffers recent turns, Veracium holds durable facts with provenance
and quarantine; your existing LangChain model powers both sides).
- docs/concepts.md โ the mental model: edges vs episodes
vs the compiled wiki, provenance & authorship, quarantine, the abstention gate,
lifecycle.
- docs/recipes.md โ short copy-paste examples, one per
capability (quarantine, mixed provenance, budgeted recall, portability,
feedback verbs, audit, local models).
- docs/api.md โ the public API:
Memory, MemoryConfig,
EvidenceAuthor, providing your own LLM callable or store.
- docs/mcp.md โ running and registering the MCP server.
- docs/design-rationale.md โ why there's no
update()/delete(), no LLM-free extraction, no TTL purging โ and what's
genuinely on the roadmap.
- docs/telemetry.md โ the opt-in, anonymous, content-free usage statistics (off by default).
- docs/diagnostics.md โ opt-in error reporting: local-first error log, consented + redacted send.
- ROADMAP.md ยท CHANGELOG.md
Recent changes
- 0.31.0 โ
veracium migrate upgrades a store written by any earlier release, one audited schema version at a
time (Upgrading an existing store).
- 0.30.0 โ a host on
SqliteStore can revoke a source it no longer trusts
(Revoking a source), and maintenance can no longer raise a fact's
confidence. A host with its own Store must add expiry_transition, or maintain() raises NotImplementedError.
- 0.29.0 โ a user can hold more than one deadline. BREAKING for code that filters commitments by subject
user
or parses the briefing's DATED COMMITMENTS text.
The full record, with every upgrade note, is the CHANGELOG.
Status
The validated layered design is implemented, tested (about 9,000 offline tests, plus
opt-in live tiers: the acceptance eval and a real-corpus robustness harness),
and passes its own research-claim bar (5/5, 0 injection asserts). Roadmap
v0.1โv0.7 complete, plus opt-in telemetry, a self-check, consented error
reporting, and an operation audit log. See ROADMAP.md.
License
MIT