Veracium

KO | EN

gitlite — search

#claude #database #nlp #privacy #bash #php #c #gemini #html #react

(★ 9)

Provenance-aware memory for AI agents.

File Explorer

ZIP Download

- - bug.yml
  - config.yml
  - feature.yml
  - integration.yml
- - docs.yml
  - mcp-publish.yml
  - test.yml
- pull_request_template.md
- README.md
- results.jsonl
- run_bench.py
- - coverage-selection-balanced-02.md
  - coverage-selection-balanced-03.md
  - coverage-selection-balanced-04.md
  - coverage-selection-balanced-05.md
  - coverage-selection-balanced-06.md
- api.md
- concepts.md
- design-rationale.md
- diagnostics.md
- index.md
- mcp.md
- recipes.md
- telemetry.md
- - briefing.sh
  - capture.sh
  - README.md
  - settings.example.json
- claude_cli_provider.py
- demo.ipynb
- langchain_memory.py
- openai_provider.py
- - 0001-v10-20260823T1734Z.tar.gz.sha256
  - 0001-v11-20260823T1813Z.tar.gz.sha256
  - 0001-v12-20260824T1705Z.tar.gz.sha256
  - 0001-v13-20260824T2230Z.tar.gz.sha256
  - 0001-v14-20260824T2340Z.tar.gz.sha256
  - 0001-v15-20260825T0158Z.tar.gz.sha256
  - 0001-v16-20260825T0248Z.tar.gz.sha256
  - 0001-v17-20260825T0325Z.tar.gz.sha256
  - 0001-v18-20260825T2140Z.tar.gz.sha256
  - 0001-v3-20260823T0028Z.tar.gz.sha256
  - 0001-v4-20260823T0218Z.tar.gz.sha256
  - 0001-v5-20260823T0509Z.tar.gz.sha256
  - 0001-v6-20260823T1108Z.tar.gz.sha256
  - 0001-v7-20260823T1233Z.tar.gz.sha256
  - 0001-v8-20260823T1342Z.tar.gz.sha256
  - 0001-v9-20260823T1548Z.tar.gz.sha256
  - 0004-0022-0023-v1-20260817T1611Z.tar.gz.sha256
  - 0004-0022-0023-v2-20260817T1910Z.tar.gz.sha256
  - 0011-v1-20260826T1103Z.tar.gz.sha256
  - 0011-v10-20260828T1421Z.tar.gz.sha256
  - 0011-v11-20260828T1543Z.tar.gz.sha256
  - 0011-v12-20260828T1759Z.tar.gz.sha256
  - 0011-v13-20260828T1922Z.tar.gz.sha256
  - 0011-v14-20260828T2300Z.tar.gz.sha256
  - 0011-v15-20260829T0023Z.tar.gz.sha256
  - 0011-v16-20260829T0155Z.tar.gz.sha256
  - 0011-v17-20260829T0334Z.tar.gz.sha256
  - 0011-v18-20260829T0555Z.tar.gz.sha256
  - 0011-v19-20260829T1119Z.tar.gz.sha256
  - 0011-v2-20260826T2255Z.tar.gz.sha256
  - 0011-v3-20260827T0155Z.tar.gz.sha256
  - 0011-v4-20260827T1034Z.tar.gz.sha256
  - 0011-v5-20260827T2156Z.tar.gz.sha256
  - 0011-v6-20260828T0211Z.tar.gz.sha256
  - 0011-v7-20260828T0303Z.tar.gz.sha256
  - 0011-v8-20260828T0536Z.tar.gz.sha256
  - 0011-v9-20260828T1143Z.tar.gz.sha256
  - 0020-0021-v10-20260816T0027Z.tar.gz.sha256
  - 0020-0021-v11-20260816T0106Z.tar.gz.sha256
  - 0020-0021-v12-20260816T0144Z.tar.gz.sha256
  - 0020-0021-v13-20260816T0214Z.tar.gz.sha256
  - 0020-0021-v14-20260816T1053Z.tar.gz.sha256
  - 0020-0021-v15-20260816T1159Z.tar.gz.sha256
  - 0020-0021-v3-20260815T1608Z.tar.gz.sha256
  - 0020-0021-v4-20260815T1641Z.tar.gz.sha256
  - 0020-0021-v5-20260815T1901Z.tar.gz.sha256
  - 0020-0021-v6-20260815T1926Z.tar.gz.sha256
  - 0020-0021-v7-20260815T1948Z.tar.gz.sha256
  - 0020-0021-v8-20260815T2010Z.tar.gz.sha256
  - 0020-0021-v9-20260815T2214Z.tar.gz.sha256
  - 0020-v2-20260815T1526Z.tar.gz.sha256
  - 0022-0023-v10-20260818T0159Z.tar.gz.sha256
  - 0022-0023-v11-20260818T0222Z.tar.gz.sha256
  - 0022-0023-v12-20260818T0313Z.tar.gz.sha256
  - 0022-0023-v13-20260818T0957Z.tar.gz.sha256
  - 0022-0023-v14-20260818T1144Z.tar.gz.sha256
  - 0022-0023-v15-20260818T2257Z.tar.gz.sha256
  - 0022-0023-v16-20260819T0136Z.tar.gz.sha256
  - 0022-0023-v17-20260819T0252Z.tar.gz.sha256
  - 0022-0023-v18-20260819T1247Z.tar.gz.sha256
  - 0022-0023-v19-20260820T0032Z.tar.gz.sha256
  - 0022-0023-v20-20260820T0140Z.tar.gz.sha256
  - 0022-0023-v21-20260820T1029Z.tar.gz.sha256
  - 0022-0023-v3-20260817T1949Z.tar.gz.sha256
  - 0022-0023-v4-20260817T2030Z.tar.gz.sha256
  - 0022-0023-v5-20260817T2123Z.tar.gz.sha256
  - 0022-0023-v6-20260817T2217Z.tar.gz.sha256
  - 0022-0023-v7-20260817T2249Z.tar.gz.sha256
  - 0022-0023-v8-20260818T0055Z.tar.gz.sha256
  - 0022-0023-v9-20260818T0126Z.tar.gz.sha256
  - 0024-0025-v1-20260821T0452Z.tar.gz.sha256
  - 0024-0025-v10-20260821T2249Z.tar.gz.sha256
  - 0024-0025-v11-20260821T2335Z.tar.gz.sha256
  - 0024-0025-v12-20260822T0037Z.tar.gz.sha256
  - 0024-0025-v13-20260823T2156Z.tar.gz.sha256
  - 0024-0025-v14-20260823T2308Z.tar.gz.sha256
  - 0024-0025-v15-20260824T0018Z.tar.gz.sha256
  - 0024-0025-v16-20260824T0126Z.tar.gz.sha256
  - 0024-0025-v17-20260824T0350Z.tar.gz.sha256
  - 0024-0025-v18-20260824T0427Z.tar.gz.sha256
  - 0024-0025-v19-20260824T1036Z.tar.gz.sha256
  - 0024-0025-v2-20260821T0630Z.tar.gz.sha256
  - 0024-0025-v20-20260824T1138Z.tar.gz.sha256
  - 0024-0025-v21-20260824T1209Z.tar.gz.sha256
  - 0024-0025-v22-20260824T1238Z.tar.gz.sha256
  - 0024-0025-v23-20260824T1429Z.tar.gz.sha256
  - 0024-0025-v24-20260824T1517Z.tar.gz.sha256
  - 0024-0025-v3-20260821T1100Z.tar.gz.sha256
  - 0024-0025-v4-20260821T1308Z.tar.gz.sha256
  - 0024-0025-v5-20260821T1520Z.tar.gz.sha256
  - 0024-0025-v6-20260821T1724Z.tar.gz.sha256
  - 0024-0025-v7-20260821T1816Z.tar.gz.sha256
  - 0024-0025-v8-20260821T1904Z.tar.gz.sha256
  - 0024-0025-v9-20260821T2210Z.tar.gz.sha256
  - 0026-v1-20260826T1432Z.tar.gz.sha256
  - 0026-v10-20260830T1321Z.tar.gz.sha256
  - 0026-v11-20260830T1621Z.tar.gz.sha256
  - 0026-v12-20260830T1741Z.tar.gz.sha256
  - 0026-v2-20260829T1526Z.tar.gz.sha256
  - 0026-v3-20260829T1752Z.tar.gz.sha256
  - 0026-v4-20260829T1926Z.tar.gz.sha256
  - 0026-v5-20260829T2225Z.tar.gz.sha256
  - 0026-v6-20260829T2345Z.tar.gz.sha256
  - 0026-v7-20260830T0120Z.tar.gz.sha256
  - 0026-v8-20260830T0226Z.tar.gz.sha256
  - 0026-v9-20260830T1208Z.tar.gz.sha256
  - INDEX.md
- - 0002-audit-manifest.md
  - 0020-read-surfaces.md
  - 0021-combining-sites.md
  - migration_0013_evidence.json
  - README.md
  - schema_policy.json
- - collected_header.txt
  - collected_header_0001.txt
  - collected_header_0011.txt
  - collected_header_0024_0025.txt
  - collected_header_0026.txt
  - manifest.txt
  - manifest_0001.txt
  - manifest_0011.txt
  - manifest_0024_0025.txt
  - manifest_0026.txt
  - out_of_scope_0026.txt
- 0001-generated-content-trust-class.md
- 0002-maintenance-provenance-invariant.md
- 0003-supersession-authority.md
- 0004-derived-views-and-revocation.md
- 0005-import-trust-boundary.md
- 0006-source-identity.md
- 0007-store-schema-versioning.md
- 0008-staleness-clearing.md
- 0009-outcome-authorship-history.md
- 0010-crash-safe-consolidation.md
- 0011-subject-scoped-entitlement.md
- 0012-observation-renewal.md
- 0013-store-migrations.md
- 0014-maintenance-attribution.md
- 0015-supersession-telemetry-counters.md
- 0016-sourcetype-deletion.md
- 0017-token-usage-telemetry.md
- 0018-release-migration-orchestrator.md
- 0019-ungrounded-flag.md
- 0020-scoped-recall.md
- 0021-scope-under-maintenance.md
- 0022-source-revocation.md
- 0023-non-revival-under-maintenance.md
- 0024-authorship-before-structural-quarantine.md
- 0025-relation-vocabulary-enforcement.md
- 0026-label-value-agreement.md
- 0027-semantic-hybrid-recall.md
- 0028-as-of-query.md
- 0029-transaction-time-carrier.md
- 0030-time-relative-classification.md
- 0031-agent-facing-trust-surface.md
- 0032-valid-from-predicate.md
- 0037-procedural-basis.md
- 0038-extraction-speech-act.md
- 0039-degradation-visibility.md
- ALLOCATION.md
- allocation.py
- audit_dispositions.py
- audit_manifest.py
- check_a1_carriers.py
- check_spec_reference.py
- citation_debt.py
- closure_findings.py
- COLLECTED_HEADER_DESIGN.md
- collected_record.py
- collected_render.py
- combining_sites.py
- evidence_transcript.py
- findings.py
- generated_block.py
- ladder.py
- lint_rulings.py
- lint_withdrawn.py
- migrations_0013.py
- monotone.py
- package_identity.py
- PROCESS.md
- read_surface_dispositions.py
- read_surfaces.py
- render_archives.py
- render_closure.py
- render_index.py
- render_ladder.py
- render_operation.py
- render_status.py
- retrospective_debt.py
- REVIEW_LESSONS.md
- review_lessons.py
- REVIEWER_GUIDE.md
- reviews.py
- runtime_probe.py
- schema_evidence.py
- schema_model.py
- seal_package.py
- skip_inventory.py
- STATUS.md
- TEMPLATE.md
- verify_a1_patch.py
- verify_extracted.py
- withdrawn_phrases.py
- - __init__.py
  - _json.py
  - agreement.py
  - audit.py
  - authority.py
  - budgets.py
  - cli.py
  - combining.py
  - compile.py
  - config.py
  - contribution.py
  - diagnostics.py
  - doctor.py
  - dryrun.py
  - gate.py
  - graph.py
  - grounding.py
  - ingest.py
  - introspect.py
  - lifecycle.py
  - mcp_server.py
  - portability.py
  - proactive.py
  - procedural_gate.py
  - procedures.py
  - prompts.py
  - registry.py
  - schema.py
  - scope.py
  - scope_linkage.py
  - scope_read.py
  - selfcheck.py
  - semantic.py
  - source_identity.py
  - telemetry.py
  - usage.py
  - why.py
- - run_eval.py
  - scenarios.json
  - test_semantic_recall_gate.py
- - adapter.py
  - cache.py
  - draw_r2.py
  - exposure.py
  - freeze.py
  - judge.sh
  - manifest.py
  - providers.py
  - README.md
  - report.py
  - run_longmemeval.py
  - strictness.py
  - test_exposure.py
  - test_freeze.py
  - test_manifest.py
  - test_run_wiring.py
  - variance.py
- - adapter.py
  - invariants.py
  - run_robustness.py
- conftest.py
- test_0001_generated_content_trust.py
- test_0003_supersession_contested.py
- test_0003_supersession_guard.py
- test_0003_supersession_recall.py
- test_0003_supersession_store.py
- test_0004_wiki_revocation.py
- test_0005_import_boundary.py
- test_0006_require_source_id.py
- test_0006_source_identity.py
- test_0009_import_migration.py
- test_0009_runtime_invariants.py
- test_0010_consolidate_recovery.py
- test_0010_consolidation_primitives.py
- test_0010_visibility_reservation.py
- test_0011_entitlement.py
- test_0011_mutant_registry.py
- test_0011_policy_matrix.py
- test_0012_budgets.py
- test_0012_budgets_render.py
- test_0012_collapse.py
- test_0012_currency_renewal.py
- test_0013_presend_gates.py
- test_0014_ledger.py
- test_0014_maintenance_attribution.py
- test_0014_portability.py
- test_0014_receipt_split.py
- test_0014_schema.py
- test_0015_counters.py
- test_0015_lifecycle.py
- test_0016_d1_deprecation.py
- test_0016_d2_deletion.py
- test_0017_usage.py
- test_0018_orchestrator.py
- test_0019_ungrounded.py
- test_0020_read_surfaces.py
- test_0020_scope_core.py
- test_0020_scope_vectors.py
- test_0021_import_linkage.py
- test_0021_maintain_scope.py
- test_0021_schema_v8.py
- test_0022_revocation_operation.py
- test_0022_revoke_source.py
- test_0022_sweep_vectors.py
- test_0023_assertable.py
- test_0023_inventory.py
- test_0023_non_revival.py
- test_0023_quarantine_at_birth.py
- test_0023_resurfacing_pin.py
- test_0024_authorship.py
- test_0025_enforcement.py
- test_0025_receipt_states.py
- test_0025_subject_grammar.py
- test_0026_relay_lexicon.py
- test_0027_policy_lane.py
- test_0027_policy_receipt.py
- test_0027_semantic_recall.py
- test_0028_asof_absence.py
- test_0028_reason_resolution_table.py
- test_0028_resolution.py
- test_0028_successor_lookup.py
- test_0028_window_transcript.py
- test_0029_carrier.py
- test_0029_lock_refusal_form.py
- test_0030_asof.py
- test_0030_closure_ledger.py
- test_0031_phase_a.py
- test_0031_phase_a_docs.py
- test_0031_proposal_ddl.py
- test_0037_capture.py
- test_0037_corpus_pin.py
- test_0037_procedural.py
- test_0037_producer_stamp.py
- test_0038_corpus_pin.py
- test_0038_instruction_enforcement.py
- test_0038_oracle_pin.py
- test_0039_answer_shapes.py
- test_0039_degradation_visibility.py
- test_absorption.py
- test_audit.py
- test_collected_header.py
- test_compile_gate.py
- test_confirm_contract_0008.py
- test_confirmation_types_0008.py
- test_consolidation_provenance.py
- test_diagnostics.py
- test_doctor_cli.py
- test_dryrun_cli.py
- test_eval.py
- test_feedback.py
- test_host_queries.py
- test_introspect_cli.py
- test_lifecycle.py
- test_longmemeval.py
- test_maintenance_invariant.py
- test_mcp.py
- test_metered.py
- test_migrate_cli.py
- test_migrations_0013.py
- test_oracle_set_disposition.py
- test_outcomes.py
- test_portability.py
- test_proactive.py
- test_render_origin.py
- test_robustness.py
- test_s2_valid_from_predicate.py
- test_schema_model.py
- test_schema_v3_migration.py
- test_seam_model_0029_0030.py
- test_seam_model_0029_0030_store.py
- test_selfcheck.py
- test_smoke.py
- test_spec_allocation.py
- test_spec_closure_present.py
- test_spec_gate.py
- test_staleness_clearing_0008.py
- test_store_versioning.py
- test_telemetry.py
- test_telemetry_claims.py
- test_why_cli.py
- test_withdrawn_gate_bites.py
- tests_support_0037.py
.gitignore
CHANGELOG.md
CITATION.cff
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
mkdocs.yml
pyproject.toml
README.md
ROADMAP.md
SECURITY.md
server.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![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)](https://raw.githubusercontent.com/veracium-ai/Veracium/main/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.)*
  **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
```

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

Veracium

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README