# https://github.com/veracium-ai/Veracium Project Manual

Generated at: 2026-07-29 01:18:21 UTC

## Table of Contents

- [Overview and Core Concepts](#page-overview)
- [System Architecture and Data Flow](#page-architecture)
- [Public API and Extensibility](#page-api-extensibility)
- [MCP Server, CLI, and Operations](#page-ops-integrations)

<a id='page-overview'></a>

## Overview and Core Concepts

### Related Pages

Related topics: [System Architecture and Data Flow](#page-architecture), [Public API and Extensibility](#page-api-extensibility)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/veracium-ai/Veracium/blob/main/README.md)
- [docs/index.md](https://github.com/veracium-ai/Veracium/blob/main/docs/index.md)
- [docs/concepts.md](https://github.com/veracium-ai/Veracium/blob/main/docs/concepts.md)
- [docs/mcp.md](https://github.com/veracium-ai/Veracium/blob/main/docs/mcp.md)
- [pyproject.toml](https://github.com/veracium-ai/Veracium/blob/main/pyproject.toml)
- [src/veracium/__init__.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/__init__.py)
- [src/veracium/schema.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/schema.py)
- [src/veracium/store/base.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/base.py)
- [src/veracium/store/sqlite.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/sqlite.py)
- [src/veracium/llm/anthropic.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/llm/anthropic.py)
- [examples/claude_cli_provider.py](https://github.com/veracium-ai/Veracium/blob/main/examples/claude_cli_provider.py)
</details>

# 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).

| Layer | Reference implementation | Swappable contract |
|---|---|---|
| LLM provider | `AnthropicComplete` in `src/veracium/llm/anthropic.py` | Any callable matching `Complete` (see `examples/claude_cli_provider.py`, 31 lines) |
| Store | `SqliteStore` in `src/veracium/store/sqlite.py` | `Store` interface in `src/veracium/store/base.py` — edges, episodes, invalidation, per-user isolation |
| Host surface | `Memory` Python class | MCP server exposing `remember` / `recall` / `answer` / `maintain` |

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.

---

<a id='page-architecture'></a>

## System Architecture and Data Flow

### Related Pages

Related topics: [Overview and Core Concepts](#page-overview), [Public API and Extensibility](#page-api-extensibility), [MCP Server, CLI, and Operations](#page-ops-integrations)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/veracium/ingest.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/ingest.py)
- [src/veracium/gate.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/gate.py)
- [src/veracium/compile.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/compile.py)
- [src/veracium/graph.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/graph.py)
- [src/veracium/store/base.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/base.py)
- [src/veracium/store/sqlite.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/sqlite.py)
- [src/veracium/llm/](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/llm/)
- [examples/claude_cli_provider.py](https://github.com/veracium-ai/Veracium/blob/main/examples/claude_cli_provider.py)
- [docs/mcp.md](https://github.com/veracium-ai/Veracium/blob/main/docs/mcp.md)
</details>

# 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](https://github.com/veracium-ai/Veracium/issues/1) and [#2](https://github.com/veracium-ai/Veracium/issues/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/](https://github.com/veracium-ai/Veracium/blob/main/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](https://github.com/veracium-ai/Veracium/issues/3).
- **MCP server** — `veracium[mcp]` exposes the verb surface to MCP clients (remember / recall / answer / maintain); see [docs/mcp.md](https://github.com/veracium-ai/Veracium/blob/main/docs/mcp.md). Copy-paste client recipes for Claude Code, Claude Desktop, and an editor-agnostic example are requested in issue [#4](https://github.com/veracium-ai/Veracium/issues/4).

## Data flow

```mermaid
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:

| Concern | Interface | Reference | Requested |
|---|---|---|---|
| LLM | `Complete` callable | `src/veracium/llm/`, `examples/claude_cli_provider.py` | OpenAI-compatible example (#3) |
| Store | `Store` (edges, episodes, invalidation, per-user) | `src/veracium/store/sqlite.py` | Postgres (#1), Neo4j (#2) |
| Surface | MCP verbs | `veracium-mcp`, `docs/mcp.md` | Client recipes (#4) |
| UX | `veracium selfcheck` | v0.2.4 preflights the provider | — |

Source: [src/veracium/store/base.py:1-60](), [examples/claude_cli_provider.py:1-31](), [docs/mcp.md](https://github.com/veracium-ai/Veracium/blob/main/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](https://github.com/veracium-ai/Veracium/blob/main/docs/mcp.md).

---

<a id='page-api-extensibility'></a>

## Public API and Extensibility

### Related Pages

Related topics: [System Architecture and Data Flow](#page-architecture), [MCP Server, CLI, and Operations](#page-ops-integrations)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/veracium/memory.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/memory.py)
- [src/veracium/store/base.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/base.py)
- [src/veracium/store/sqlite.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/sqlite.py)
- [src/veracium/llm/base.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/llm/base.py)
- [src/veracium/llm/anthropic.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/llm/anthropic.py)
- [examples/claude_cli_provider.py](https://github.com/veracium-ai/Veracium/blob/main/examples/claude_cli_provider.py)
- [examples/openai_provider.py](https://github.com/veracium-ai/Veracium/blob/main/examples/openai_provider.py)
- [src/veracium/mcp/server.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/mcp/server.py)
- [src/veracium/cli.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/cli.py)
- [docs/mcp.md](https://github.com/veracium-ai/Veracium/blob/main/docs/mcp.md)
</details>

# 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]()`

| Verb | Purpose | Added in |
|---|---|---|
| `remember(text, kind=USER)` | Distill an episode into typed edges | initial |
| `recall(query)` | Compile a budgeted, gated context block | initial |
| `answer(query)` | Compose a citable response | initial |
| `maintain()` | Run memory hygiene / decay | initial |
| `forget(...)` | Targeted invalidation | v0.2.0 |
| `feedback(...)` | Record a quality signal on an edge | v0.2.0 |
| `list_entities()` | Distinct ids with edge/episode counts | v0.2.1 |
| `edges_since(since)` | New edges after a timestamp, provenance-filtered | v0.2.1 |

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.

---

<a id='page-ops-integrations'></a>

## MCP Server, CLI, and Operations

### Related Pages

Related topics: [Overview and Core Concepts](#page-overview), [Public API and Extensibility](#page-api-extensibility)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- Source: [src/veracium/mcp_server.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/mcp_server.py)
- Source: [src/veracium/cli.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/cli.py)
- Source: [src/veracium/selfcheck.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/selfcheck.py)
- Source: [src/veracium/telemetry.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/telemetry.py)
- Source: [src/veracium/diagnostics.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/diagnostics.py)
- Source: [src/veracium/audit.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/audit.py)
</details>

Related Source Files</summary>

The following source files were used to generate this page:

- [src/veracium/mcp_server.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/mcp_server.py)
- [src/veracium/cli.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/cli.py)
- [src/veracium/selfcheck.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/selfcheck.py)
- [src/veracium/telemetry.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/telemetry.py)
- [src/veracium/diagnostics.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/diagnostics.py)
- [src/veracium/audit.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/audit.py)
</details>

# 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.

| Module | Role | Primary consumer |
|---|---|---|
| `mcp_server.py` | stdio MCP server, tools: remember/recall/answer/maintain | MCP hosts |
| `cli.py` | `veracium`, `veracium-mcp`, `veracium selfcheck` | operators |
| `selfcheck.py` | verification scorecard + provider preflight | operators |
| `diagnostics.py` | environment snapshots for support | selfcheck, MCP server |
| `telemetry.py` | operational telemetry | dashboards |
| `audit.py` | forget/feedback audit log | maintainers |

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.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: veracium-ai/Veracium

Summary: 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
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/veracium-ai/Veracium

## 2. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/veracium-ai/Veracium

## 3. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/veracium-ai/Veracium

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/veracium-ai/Veracium

## 5. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/veracium-ai/Veracium

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/veracium-ai/Veracium

<!-- canonical_name: veracium-ai/Veracium; human_manual_source: deepwiki_human_wiki -->