{
  "markdown": "# Veracium\n\n<!-- mcp-name: io.github.veracium-ai/veracium -->\n\n[![tests](https://github.com/veracium-ai/Veracium/actions/workflows/test.yml/badge.svg)](https://github.com/veracium-ai/Veracium/actions/workflows/test.yml)\n[![PyPI](https://img.shields.io/pypi/v/veracium)](https://pypi.org/project/veracium/)\n[![Python](https://img.shields.io/pypi/pyversions/veracium)](https://pypi.org/project/veracium/)\n[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n\n**Veracium is a provenance-aware memory plug-in for agentic systems** —\ndurable, per-user memory that resists the injection and confabulation failures\nthat plague naive agent memory. Provenance means every fact tracks *who said\nit*: a claim from an email your agent merely read can never become a \"fact\" it\nasserts. It remembers what the user said, past interactions, and what worked —\nand it remembers where each of those came from.\n\nVeracium is the production distillation of an evaluation-driven research project\n(`agent-memory`): every design choice below traces to a measured finding, and the\nresearch's synthetic-corpus harness is reused as the regression suite.\n\n**Research:** the evaluation instrument behind those findings — a longitudinal\nbenchmark for agent memory — is described in Q. Spencer, *\"Ground Truth First:\nA Longitudinal Evaluation Instrument for Agent Memory, and the Tenure Crossover\nin Memory-Architecture Rankings\"* ([arXiv:2607.21962](https://arxiv.org/abs/2607.21962), 2026).\n\n## Why it's shaped this way\n\n- **Typed graph + dated episodes are the store of record.** Entity facts live as\n  relational edges (with unforgeable provenance); interaction history lives as\n  dated episodes. A curated \"wiki\" view is compiled from them and cached — never\n  the source of truth. *(The layered design won on both short and 9-week horizons;\n  flat stores each failed one regime.)*\n- **Supersession, never erasure.** Functional facts (preference, employer,\n  deadline) keep one current value with the prior value retained as history —\n  \"what did X used to be?\" stays answerable. *(The category commercial memory\n  systems handle worst; Veracium's strongest.)*\n- **Representation is a security control.** Third-party claims (received email,\n  external docs) are quarantined *structurally* — stored as `third_party_claim`\n  edges with the claimant as subject, never as user facts. Content-type quarantine\n  catches obligation/debt/renewal claims regardless of how plausible they look.\n  *(Held against a full plausibility ladder incl. contact-impersonation.)*\n  **What this is, and is not:** the store governs retention, retrieval,\n  description and recommendation — what it will *say* and how it labels it.\n  It does not instantiate, authorize or execute anything; those belong to the\n  host's harness. Without an exclusive harness path that consumes the labels,\n  Veracium's trust classes are **advisory labelling, not enforcement**.\n- **Bring your own model.** Veracium never owns your API keys or model choice; it\n  calls a `Complete` callable you supply. A reference Anthropic provider ships in\n  the box.\n- **Embedded by default.** Zero external services: one SQLite file. Swap in\n  Neo4j/Postgres later via the `Store` interface.\n\n## Install\n\n```bash\npip install \"veracium[anthropic]\"   # core + the reference LLM provider\n```\n\nExtras: `[mcp]` adds the MCP server, `[dev]` adds pytest. The core alone depends\nonly on `pydantic`. To work from source instead:\n\n```bash\ngit clone https://github.com/veracium-ai/Veracium.git && cd Veracium\npip install -e \".[anthropic,dev]\"\n```\n\nLinks: [docs](https://veracium-ai.github.io/Veracium/) · [veracium.ai](https://veracium.ai) · [PyPI](https://pypi.org/project/veracium/)\n\n## Use (library)\n\n```python\nfrom veracium import Memory, EvidenceAuthor, EvidenceContext\nfrom veracium.llm.anthropic import AnthropicComplete\n\nmem = Memory(llm=AnthropicComplete())   # or pass your own Complete callable\n\n# Remember interactions. `author` says WHO wrote the event; `context` is\n# your positive attestation of HOW you captured it. Without a context the\n# content class floors to derived(THIRD_PARTY) — never assertable — so a\n# host that means \"I captured this first-hand\" says so:\nmem.remember(\"alice\", \"USER: I'm vegetarian and have a dog named Ollie.\",\n             context=EvidenceContext.direct())\nmem.remember(\"alice\", \"From billing@scam: you owe $900.\",\n             author=EvidenceAuthor.THIRD_PARTY, event_type=\"email\",\n             context=EvidenceContext.direct())\n\n# Recall grounded, provenance-flagged context for a prompt.\nctx = mem.recall(\"alice\", \"suggest a lunch spot\")\nprint(ctx.context)   # states the vegetarian constraint; the $900 \"claim\" is\n                     # rendered under a never-assert flag, not as a fact.\n```\n\nNo Anthropic API key? `AnthropicComplete` is just a convenience — Veracium calls any\n`Complete` callable you supply. To run without SDK/key setup, wrap a client you\nalready have; `examples/claude_cli_provider.py` wraps the `claude` CLI as a\ndrop-in provider (`from claude_cli_provider import ClaudeCLIComplete`), and\n`examples/openai_provider.py` wraps any OpenAI-compatible chat-completions API\n(OpenAI itself, vLLM, Ollama's `/v1` endpoint) via `OpenAIComplete` — point it\nat a local server with `OpenAIComplete(base_url=...)` and override `models` with\nwhatever model name your server serves.\n\n## Use (MCP)\n\n`veracium-mcp` exposes `remember` / `recall` / `answer` / `maintain` tools to any\nMCP-compatible agent (Claude Desktop/Code, others) with no host-side Python. See\n[docs/mcp.md](docs/mcp.md) for the config JSON and tool reference.\n\n## Documentation\n\nHosted docs: **[veracium-ai.github.io/Veracium](https://veracium-ai.github.io/Veracium/)**\n\n- **[examples/demo.ipynb](examples/demo.ipynb)** — the scam-email injection demo,\n  runnable end to end ([open in Colab](https://colab.research.google.com/github/veracium-ai/Veracium/blob/main/examples/demo.ipynb)).\n- **[examples/langchain_memory.py](examples/langchain_memory.py)** — Veracium as\n  the long-term memory layer of a LangChain chat app (session-keyed hybrid:\n  LangChain buffers recent turns, Veracium holds durable facts with provenance\n  and quarantine; your existing LangChain model powers both sides).\n- **[docs/concepts.md](docs/concepts.md)** — the mental model: edges vs episodes\n  vs the compiled wiki, provenance & authorship, quarantine, the abstention gate,\n  lifecycle.\n- **[docs/recipes.md](docs/recipes.md)** — short copy-paste examples, one per\n  capability (quarantine, mixed provenance, budgeted recall, portability,\n  feedback verbs, audit, local models).\n- **[docs/api.md](docs/api.md)** — the public API: `Memory`, `MemoryConfig`,\n  `EvidenceAuthor`, providing your own LLM callable or store.\n- **[docs/mcp.md](docs/mcp.md)** — running and registering the MCP server.\n- **[docs/design-rationale.md](docs/design-rationale.md)** — why there's no\n  `update()`/`delete()`, no LLM-free extraction, no TTL purging — and what's\n  genuinely on the roadmap.\n- **[docs/telemetry.md](docs/telemetry.md)** — the opt-in, anonymous, content-free usage statistics (off by default).\n- **[docs/diagnostics.md](docs/diagnostics.md)** — opt-in error reporting: local-first error log, consented + redacted send.\n- **[ROADMAP.md](ROADMAP.md)** · **[CHANGELOG.md](CHANGELOG.md)**\n\n## Status\n\nThe validated layered design is implemented, tested (44 offline tests, plus\nopt-in live tiers: the acceptance eval and a real-corpus robustness harness),\nand passes its own research-claim bar (5/5, 0 injection asserts). Roadmap\nv0.1–v0.7 complete, plus opt-in telemetry, a self-check, consented error\nreporting, and an operation audit log. See [ROADMAP.md](ROADMAP.md).\n\n## License\n\nMIT\n",
  "bytes": 7709,
  "sha": "443e466d96b315149a3298196e6b2c22f6fc176e3638e1eba227804c8ee9a9c5",
  "repo_slug": "veracium-ai/veracium",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_veracium_ai_veracium_4acb82fc/readme"
}