Veracium

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. *(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]"   # core + the reference LLM provider

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.

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

Use (library)

from veracium import Memory, EvidenceAuthor, EvidenceContext

from veracium.llm.anthropic import AnthropicComplete

mem = Memory(llm=AnthropicComplete()) # or pass your own Complete callable

Remember interactions. author says WHO wrote the event; context is

your positive attestation of HOW you captured it. Without a context the

content class floors to derived(THIRD_PARTY) — never assertable — so a

host that means "I captured this first-hand" says so:

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", # third-party content needs a source id context=EvidenceContext.direct())

Recall grounded, provenance-flagged context for a prompt.

ctx = mem.recall("alice", "suggest a lunch spot") print(ctx.context) # states the vegetarian constraint; the $900 "claim" is

rendered under a never-assert flag, not as a fact.

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.

Use (MCP)

veracium-mcp exposes remember / recall / answer / maintain tools 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](https://veracium-ai.github.io/Veracium/)

• [examples/demo.ipynb](examples/demo.ipynb) — the scam-email injection demo, runnable end to end (open in Colab).
• [examples/langchain_memory.py](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](docs/concepts.md) — the mental model: edges vs episodes vs the compiled wiki, provenance & authorship, quarantine, the abstention gate, lifecycle.
• [docs/recipes.md](docs/recipes.md) — short copy-paste examples, one per capability (quarantine, mixed provenance, budgeted recall, portability, feedback verbs, audit, local models).
• [docs/api.md](docs/api.md) — the public API: Memory, MemoryConfig, EvidenceAuthor, providing your own LLM callable or store.
• [docs/mcp.md](docs/mcp.md) — running and registering the MCP server.
• [docs/design-rationale.md](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](docs/telemetry.md) — the opt-in, anonymous, content-free usage statistics (off by default).
• [docs/diagnostics.md](docs/diagnostics.md) — opt-in error reporting: local-first error log, consented + redacted send.
• [ROADMAP.md](ROADMAP.md) · [CHANGELOG.md](CHANGELOG.md)

Status

The validated layered design is implemented, tested (44 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