io.github.veracium-ai/veracium
Provenance-aware memory for AI agents: quarantine, abstention gate, supersession-with-history.
Open source Open in the app JSON README (API)
About
Provenance-aware memory for AI agents: quarantine, abstention gate, supersession-with-history.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- veracium-ai
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.16.0
- Stars
- 8
- Forks
- 1
- Last push
- 2026-09-04T19:09:55Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:38
- Updated
- 2026-08-29 04:01:38
- Origin id
io.github.veracium-ai/veracium
README
# Veracium
<!-- mcp-name: io.github.veracium-ai/veracium -->
[](https://github.com/veracium-ai/Veracium/actions/workflows/test.yml)
[](https://pypi.org/project/veracium/)
[](https://pypi.org/project/veracium/)
[](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.** Functional facts (preference, employer,
deadline) keep one current value with the prior value retained as history —
"what did X used to be?" stays answerable. *(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.)*
- **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
```
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",
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