# Veracium

<!-- mcp-name: io.github.veracium-ai/veracium -->

[![tests](https://github.com/veracium-ai/Veracium/actions/workflows/test.yml/badge.svg)](https://github.com/veracium-ai/Veracium/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/veracium)](https://pypi.org/project/veracium/)
[![Python](https://img.shields.io/pypi/pyversions/veracium)](https://pypi.org/project/veracium/)
[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

**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](https://arxiv.org/abs/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

```bash
pip install "veracium[anthropic]"   # core + the reference LLM provider
```

> **Python and SQLite requirement.** Veracium needs Python 3.14 or newer, and it currently opens or creates a store
> only on the one SQLite build it has been qualified on: SQLite 3.45.1 as packaged by Ubuntu 24.04. A Python 3.14
> linked against that system SQLite runs, as GitHub's setup-python builds do; uv's, python.org's and Homebrew's 3.14
> builds bundle a newer SQLite and refuse, even a fresh 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. On every other SQLite
> build — including other 3.45.1 builds, since the check is on the exact build — it refuses to create a store AND
> refuses to open an existing one, so moving to a Python whose SQLite differs leaves earlier stores unopenable
> there until that build is supported. A version check can
> only show that yours is refused: if `python -c "import sqlite3; print(sqlite3.sqlite_version)"` prints anything
> but 3.45.1, it is; 3.45.1 is necessary, not sufficient. Wider SQLite support is planned.

Extras: `[mcp]` adds the MCP server, `[dev]` adds pytest. The core alone depends
only on `pydantic`. To work from source instead:

```bash
git clone https://github.com/veracium-ai/Veracium.git && cd Veracium
pip install -e ".[anthropic,dev]"
```

Links: [docs](https://veracium-ai.github.io/Veracium/) · [veracium.ai](https://veracium.ai) · [PyPI](https://pypi.org/project/veracium/)

## Use (library)

```python
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](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](https://colab.research.google.com/github/veracium-ai/Veracium/blob/main/examples/demo.ipynb)).
- **[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](ROADMAP.md).

## License

MIT