Related Pages

Related topics: System Architecture and Data Flow, Public API and Extensibility

Overview and Core Concepts

Veracium is a typed-memory layer for AI applications. It sits between a host application and a language model, transforming raw conversational events into a persistent, queryable memory graph that can be recalled with budget-aware control over what the model is allowed to assert. The package is published as veracium on PyPI and ships an optional MCP server (veracium[mcp]) that exposes its core verbs to MCP-compatible clients. Source: pyproject.toml:1-40, docs/mcp.md:1-30.

Purpose and Scope

The library addresses a single problem: language models are stateless, and ad-hoc prompt-stuffing of past context leaks untrusted text into the model's output. Veracium replaces that pattern with an explicit, provable pipeline. Events are ingested through a single verb, normalized into typed graph edges with provenance, and gated at recall time so that only assertable facts can reach the compiled context.

The release history shows the design evolving around five capability gaps — budget-aware recall, portable memory, forget, feedback, and audit log — addressed in v0.2.0 and stabilized through v0.2.4. Source: README.md:1-60, docs/index.md:1-40, v0.2.0 release notes.

Core Abstractions

Memory Verbs

Veracium's public surface is the Memory object exported from veracium and documented in docs/concepts.md. The four primary verbs are:

• remember(...) — ingest a new event, distill it into edges, persist it.
• recall(...) — assemble a budget-aware, gated context for a query.
• answer(...) — a recall plus a model call, returning a grounded response.
• maintain(...) — housekeeping operations (forget, feedback, audit).

Two host-query helpers were added in v0.2.1: Memory.list_entities() returns distinct entity ids with edge and episode counts (used for proactive-recall planning and coverage audits), and Memory.edges_since(user_id, since) returns edges learned after a date filtered on provenance. Source: src/veracium/__init__.py:1-40, v0.2.1 release notes.

Typed Edges and Provenance

The store-of-record is a set of typed graph edges with provenance, not raw chat logs. Every edge carries its source episode, its trust label, and the actor that produced it. This shape is what makes the gate meaningful: provenance decides whether a fact is assertable, use-only, or dropped. Source: src/veracium/schema.py:1-80, docs/concepts.md:1-60.

The robustness tier completed in v0.1.5–v0.1.7 hardened exactly this surface: the JSON parser prefers the first object over a stray list (v0.1.5), use_only inferences are no longer fed into the compiled wiki (v0.1.6), and third-party text embedded inside a SYSTEM/USER-authored event no longer acquires that event's trust — the "system-event laundering" fix (v0.1.7). Source: v0.1.5, v0.1.6, v0.1.7 release notes.

Architecture

The package is intentionally small and swappable at three boundaries: the LLM provider, the store backend, and the surface area exposed to hosts (Python API or MCP).

Bring-your-own-model is a first-class design point: any callable matching the Complete contract works, so OpenAI-compatible APIs (OpenAI, vLLM, Ollama's OpenAI endpoint) plug in without changes to Veracium itself. Source: src/veracium/llm/anthropic.py:1-60, examples/claude_cli_provider.py:1-31, GitHub issue #3.

The Store interface is deliberately small — edges, episodes, invalidation, and per-user isolation — and SqliteStore is the reference implementation. Postgres (JSONB rows, mirroring the SQLite shape) and Neo4j (native graph queries over memory, paths, and neighborhoods) are the most-requested production backends and follow the same contract. Source: src/veracium/store/base.py:1-60, src/veracium/store/sqlite.py:1-120, GitHub issues #1 and #2.

Operational Touchpoints

The CLI provides three operational entry points used during installation and onboarding. veracium-mcp --help and --version (fixed in v0.2.2) print cleanly rather than silently booting the stdio server; unknown arguments now fail with a pointer to --help; a boot failure such as a missing ANTHROPIC_API_KEY exits with a single clear message. veracium selfcheck (v0.2.4) preflights the provider — a missing SDK or missing key exits with one install hint rather than a misleading scorecard where an erroring check was conservatively scored as an assert. The MCP server is also Registry-ready: the README carries the mcp-name validation marker and server.json sits at the repo root, so Veracium is publishable to registry.modelcontextprotocol.io. Source: v0.2.2, v0.2.3, v0.2.4 release notes, docs/mcp.md:1-60.

Where to Go Next

• For the verb-by-verb reference, see docs/concepts.md.
• For MCP client configuration, see docs/mcp.md; client recipes (Claude Code .mcp.json, Claude Desktop, editor-agnostic) are tracked in GitHub issue #4.
• For a working minimal provider, copy examples/claude_cli_provider.py and adapt it to the Complete contract — or write an openai_provider.py per issue #3.
• For a new store backend, implement the Store interface in src/veracium/store/base.py; SqliteStore is the reference.

Related Pages

Related topics: Overview and Core Concepts, Public API and Extensibility, MCP Server, CLI, and Operations

System Architecture and Data Flow

Veracium is a memory layer for LLM applications: a typed graph-edge store with provenance, accessed through a small verb surface (remember, recall, answer, maintain, plus forget, feedback, list_entities, edges_since), and backed by a pluggable LLM provider. The architecture separates the distill/write path (turn text into edges) from the assemble/read path (turn edges into an answer), with a security gate sitting between storage and compilation.

Components

The system is organized into the following layers:

• Ingest — parses incoming events and asks the LLM to distill typed graph edges. Source: src/veracium/ingest.py:1-120.
• Graph — the canonical edge model (typed edges carrying provenance metadata). Source: src/veracium/graph.py:1-80.
• Store — persistence. The Store interface in src/veracium/store/base.py:1-60 defines edges, episodes, invalidation, and per-user isolation; SqliteStore in src/veracium/store/sqlite.py:1-200 is the reference implementation, with Postgres and Neo4j requested as additional backends in issues #1 and #2.
• Gate — partitions recalled edges by trust, keeping third-party inferences (use_only) out of the compiled wiki (v0.1.3, v0.1.6, v0.1.7). Source: src/veracium/gate.py:1-200.
• Compile — assembles the grounded wiki from the gate's assertable block. Source: src/veracium/compile.py:1-160.
• LLM providers — any callable matching the Complete contract; the Anthropic reference lives under src/veracium/llm/ and a 31-line worked example is examples/claude_cli_provider.py:1-31. An OpenAI-compatible example is requested in issue #3.
• MCP server — veracium[mcp] exposes the verb surface to MCP clients (remember / recall / answer / maintain); see docs/mcp.md. Copy-paste client recipes for Claude Code, Claude Desktop, and an editor-agnostic example are requested in issue #4.

Data flow

flowchart LR
  Caller[Host / MCP client] -->|remember| Ingest
  Ingest -->|Complete prompt| LLM[(LLM provider)]
  LLM --> Ingest
  Ingest -->|edges + episode| Store[(Store:<br/>base.py / sqlite.py)]
  Caller -->|recall| Gate
  Store --> Gate
  Gate -->|GROUNDED block| Compile
  Compile -->|wiki| Caller
  Caller -->|answer| LLM
  LLM --> Caller

Write path (remember). Ingest extracts a JSON object from the distill response — extract_json prefers the first JSON object so a stray [] cannot crash the parser (v0.1.5) — materializes edges and an episode, and writes them through the Store interface. Provenance travels with each edge so later reads can distinguish user-authored facts from third-party inferences. Source: src/veracium/ingest.py:1-120.

Read path (recall → answer). Recall pulls edges from the store, the gate partitions them by trust (closing the *system-event laundering* bypass in v0.1.7 and enforcing use_only in the wiki path in v0.1.6), and compile produces a wiki from the grounded block only. The wiki is then placed back into the gate's assertable block so any fact reaching the wiki can be asserted by the answering LLM. Source: src/veracium/gate.py:1-200 and src/veracium/compile.py:1-160.

Host queries. Memory.list_entities() and Memory.edges_since(user_id, since) (v0.2.1) let the calling application enumerate what the system knows and what was learned after a date — useful for proactive-recall planning and coverage audits. Source: src/veracium/store/base.py:1-60.

Pluggability and extensions

The architecture is intentionally narrow so production deployments can swap each layer independently:

Source: src/veracium/store/base.py:1-60, examples/claude_cli_provider.py:1-31, docs/mcp.md.

Reliability hooks

Two non-functional properties are enforced in code rather than left to prompts:

• JSON robustness — extract_json prefers the first JSON object, so list-shaped or prose-debris distill responses no longer crash remember() (v0.1.5). Source: src/veracium/ingest.py:1-120.
• Boot and diagnostic clarity — veracium-mcp --help/--version and veracium selfcheck exit with one-line diagnostics instead of stack traces (v0.2.2, v0.2.4). The selfcheck preflights the provider so a missing SDK or missing ANTHROPIC_API_KEY exits with one clear install hint instead of producing a misleading scorecard. Source: docs/mcp.md.

Related Pages

Related topics: System Architecture and Data Flow, MCP Server, CLI, and Operations

Public API and Extensibility

Veracium exposes a small, deliberate surface designed to be embedded into other agents and extended at three seams: the Memory class (the runtime API), the Complete callable contract (the model seam), and the Store interface (the persistence seam). The MCP server and the veracium CLI are thin wrappers around Memory, so anything reachable from Python is also reachable from a tool-calling host or the command line. The design intent is bring-your-own-model and bring-your-own-store: a single Anthropic-compatible callable and the reference SqliteStore ship in-tree, and the same contracts admit OpenAI-compatible endpoints (OpenAI, vLLM, Ollama's OpenAI mode) and alternate backends (Postgres, Neo4j).

The `Memory` class — runtime surface

The Memory class is the host-facing entry point. It is constructed with a user_id, a model provider, and a Store; from then on hosts call a stable set of verbs. The core ingest/recall loop is four verbs — remember(), recall(), answer(), maintain() — augmented by maintenance verbs added in v0.2.0 (forget, feedback) and host-query verbs added in v0.2.1 (list_entities, edges_since). Source: src/veracium/memory.py:1-80

The host-query verbs are explicitly motivated by the first production consumer's intelligence layer: list_entities() powers proactive-recall planning and coverage audits, and edges_since() powers incremental update streams with provenance filtering. Source: src/veracium/memory.py:120-180

LLM extensibility — the `Complete` contract

The model seam is a single Python callable. Any object matching the Complete protocol — def complete(messages, **kwargs) -> str — can replace the Anthropic default. The reference implementation lives in src/veracium/llm/anthropic.py, and the minimal CLI-based example ships as examples/claude_cli_provider.py (31 lines). Source: src/veracium/llm/base.py:1-40 Source: src/veracium/llm/anthropic.py:1-60

Community issue #3 flags the absence of examples/openai_provider.py. The expected recipe covers OpenAI, vLLM, and Ollama's OpenAI-compatible endpoint. The working pattern — visible in the CLI example — is to wrap the upstream SDK call (client.chat.completions.create(...)) so it returns a single string with the same kwargs contract; no other Veracium changes are required. Source: examples/claude_cli_provider.py:1-31

A practical consequence of this seam: veracium selfcheck (added in v0.2.4) preflights the configured provider before running the rest of the suite. If the SDK is missing or ANTHROPIC_API_KEY is unset, the check exits with one install hint rather than a misleading FAIL … injection asserts=1 scorecard. The same preflight surfaces misconfigured custom providers. Source: src/veracium/cli.py:1-120

Store extensibility — the `Store` interface

The persistence seam is the Store abstract base class in src/veracium/store/base.py. The contract is deliberately small: typed graph edges with provenance, episode rows, explicit invalidation, and per-user isolation. SqliteStore in src/veracium/store/sqlite.py is the reference implementation and the contract's executable spec. Source: src/veracium/store/base.py:1-80 Source: src/veracium/store/sqlite.py:1-200

Two production-grade backends are tracked as community issues (#1 Postgres, #2 Neo4j). The contribution shape is the same in both: implement the Store ABC, keep per-user isolation airtight (no cross-tenant joins), and prefer native query features where they help — JSONB rows for Postgres, native graph traversals for Neo4j. Mirroring the SQLite table shape is a viable starting point. Source: src/veracium/store/base.py:40-120

MCP server and CLI — external surfaces

Both the MCP server and the CLI delegate to Memory. The MCP server (installed as veracium[mcp], launched via veracium-mcp) re-presents the four core verbs — remember, recall, answer, maintain — alongside host queries and maintenance verbs, so any MCP-speaking client (Claude Code, Claude Desktop, other editors) drives the same runtime as a Python host. As of v0.2.2 the server honors --help and --version, rejects unknown arguments, and emits a single-line boot error on misconfiguration (e.g. missing ANTHROPIC_API_KEY). As of v0.2.3 it ships the MCP Registry metadata (mcp-name validation marker, repo-root server.json) for publishing to registry.modelcontextprotocol.io. Source: src/veracium/mcp/server.py:1-160 Source: docs/mcp.md:1-80

Community issue #4 notes that docs/mcp.md describes the server but does not yet include copy-paste client configs. The expected additions are a Claude Code .mcp.json snippet, a Claude Desktop snippet, and one editor-agnostic example — all three are pure documentation work, since the server contract is already stable and the runtime API it exposes is the Memory surface described above.

Related Pages

Related topics: Overview and Core Concepts, Public API and Extensibility

Related Source Files</summary>

The following source files were used to generate this page:

• src/veracium/mcp_server.py
• src/veracium/cli.py
• src/veracium/selfcheck.py
• src/veracium/telemetry.py
• src/veracium/diagnostics.py
• src/veracium/audit.py

MCP Server, CLI, and Operations

The "MCP Server, CLI, and Operations" surface is the operational layer of Veracium: it exposes the memory engine to MCP-capable hosts, drives the user-facing veracium command-line entry point, and ships the diagnostic, telemetry, and audit helpers that production consumers rely on. This page covers the moving parts a deployer or integrator actually touches — the stdio server, the CLI verbs, the selfcheck scorecard, and the surrounding observability machinery.

MCP Server (`veracium[mcp]`)

The MCP server is delivered as an optional extra and is the canonical way to wire Veracium into MCP-aware hosts (Claude Code, Claude Desktop, and any editor with an MCP client). It speaks stdio and exposes the four memory verbs over the MCP tool interface: remember, recall, answer, and maintain (Source: src/veracium/mcp_server.py:1-80). The server is thin by design: each tool hands off to the underlying Memory instance, so the security gates and provenance logic implemented in the core engine are preserved end-to-end (Source: src/veracium/mcp_server.py:80-160).

Until v0.2.2, the binary would silently boot the stdio server even when invoked with arguments — a confusing first install. The current CLI wrapper recognises --help and --version, rejects unknown arguments with a pointer to --help, and converts boot failures (e.g. a missing ANTHROPIC_API_KEY) into a single clear line instead of a stack trace (Source: src/veracium/cli.py:1-120).

For the MCP Registry, the package ships the mcp-name validation marker in the README and a registry-conformant server.json at the repository root, so Veracium is discoverable through registry.modelcontextprotocol.io. The local docs file (docs/mcp.md) was updated in v0.2.3 to describe the PyPI install flow rather than the older clone-and-install path (Source: src/veracium/mcp_server.py:160-220).

A commonly requested addition is a recipes section with copy-paste client configs for Claude Code (.mcp.json), Claude Desktop, and one editor-agnostic example. This is tracked in issue #4 and is the main documentation gap for the MCP surface (Source: docs/mcp.md:1-40).

CLI Entry Point and Subcommands

The veracium command is implemented in cli.py and dispatches to subcommands. The two most important operators are:

• veracium-mcp — launches the stdio MCP server described above; argument handling enforces --help/--version and produces clear boot errors (Source: src/veracium/cli.py:1-120).
• veracium selfcheck — runs the verification scorecard and is the recommended first step after install (Source: src/veracium/cli.py:120-200).

The CLI defers argument parsing to small helpers rather than pulling in a heavyweight framework, which keeps the import path fast — important for the stdio server, where every millisecond of startup matters.

Selfcheck and Provider Preflight

veracium selfcheck is the operations command that asks "is this install actually working?". It runs a series of checks including the injection-resistance guarantee and the grounded/ungrounded partition enforced by the security gate.

Before v0.2.4, a missing provider SDK or a missing ANTHROPIC_API_KEY would crash the run and — because an erroring check was conservatively scored as an assert — would produce a misleading FAIL … injection asserts=1 scorecard that read exactly like the injection guarantee failing. As of v0.2.4, the command first preflights the provider: it checks the SDK is importable and the required API key is present, and exits with a single clear install hint if either is missing. The scorecard only runs against a known-good provider, so its pass/fail output is now meaningful (Source: src/veracium/selfcheck.py:1-160).

Operations: Diagnostics, Telemetry, and Audit

Beyond the CLI verbs, the operations surface is composed of three cooperating modules:

• diagnostics.py — diagnostic helpers used by selfcheck and the MCP server to gather environment state (provider, store, schema version) for support bundles (Source: src/veracium/diagnostics.py:1-120).
• telemetry.py — the lightweight telemetry layer; event types are scoped to operator-relevant signals (provider preflight results, store backends, host-query calls) rather than user content (Source: src/veracium/telemetry.py:1-140).
• audit.py — the audit log introduced in v0.2.0. It records forget and feedback verbs alongside provenance metadata so maintainers can answer "who changed what, when" without scraping the edges table (Source: src/veracium/audit.py:1-160).

A typical operations flow is: install → veracium selfcheck (provider preflight + injection/grounded checks) → register the MCP server with the host → monitor via telemetry → consult the audit log for changes. The table below summarises the responsibilities.

Together, these modules define the boundary between the in-process memory engine and the outside world. Anything that crosses that boundary — an MCP tool call, a selfcheck run, a maintainer query — passes through this layer and its security gates.

Doramagic Pitfall Log

Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

1. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/veracium-ai/Veracium

2. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/veracium-ai/Veracium

3. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/veracium-ai/Veracium

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/veracium-ai/Veracium

5. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/veracium-ai/Veracium

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/veracium-ai/Veracium

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using Veracium with real data or production workflows.

• Docs: MCP client recipes (Claude Code, other MCP clients) - github / github_issue
• Provider example: OpenAI-compatible Complete callable - github / github_issue
• Store backend: Neo4j - github / github_issue
• Store backend: Postgres - github / github_issue
• v0.2.4 — selfcheck provider preflight - github / github_release
• v0.2.3 — MCP Registry readiness - github / github_release
• v0.2.2 — veracium-mcp --help/--version + clear boot errors - github / github_release
• v0.2.1 — host queries: list_entities() + edges_since() - github / github_release
• v0.2.0 — budget-aware recall, portable memory, forget, feedback verbs, a - github / github_release
• v0.1.7 — system-event laundering fix (security) + derived_from - github / github_release
• v0.1.6 — use_only enforcement completed for the wiki path (security) - github / github_release
• v0.1.5 — survive list-shaped distill responses; robustness tier complete - github / github_release