context-vault-ai 0.3.1

A temporal, governed context layer for agentic AI systems — bitemporal, attributed, permissioned Claims.

Context Vault

A temporal, governed context layer for agentic AI systems. Every piece of agent context is stored as a versioned, time-bound, access-controlled, auditable claim — so agents retrieve facts that are current, permissioned, traceable, and reconcilable across agents.

Other memory systems help your agent remember more. Context Vault makes sure it remembers what's true, what it's allowed to know, and proves what it knew.

The 60-second on-ramp (no databases, no API key)

pip install context-vault-ai
context-vault demo               # the full governed-memory tour, fully offline

# zero-setup trial — in-memory store (ephemeral; great for evaluating)
import os; os.environ.setdefault("VAULT_STORE", "memory")

from context_vault import Memory
m = Memory()
m.remember("Priya prefers email and is on the Pro plan", user="priya")  # needs ANTHROPIC_API_KEY
print(m.recall("how do I contact Priya?", user="priya"))      # prompt-ready, governed
m.forget("contact preference", user="priya")                  # archived, never deleted

remember / recall / forget are thin aliases over the five operations — so you get the simple API and the governed engine (conflict-checked writes, deny-by-default ACL, point-in-time reads, an immutable audit trail) underneath. Notes for the first run: free-text remember needs ANTHROPIC_API_KEY (the Claude extractor) — without a key, assert structured facts via m.vault.assert_claim_from(...); for the durable store drop the env var, run docker compose up -d first (Neo4j + Postgres), and use with Memory() as m: (or call m.close()) so the connection pool releases cleanly.

See docs/STATUS.md for the current state and docs/PLAN.md for the architecture, decisions, and roadmap.

Quickstart

# 1. bring up Neo4j + Postgres
docker compose up -d

# 2. the killer demo — no API key needed (heuristic judge + hash embeddings)
uv run python eval/killer_demo.py

# 3. tests (8 unit + 4 live integration)
uv run --extra dev pytest -q

# 4. validate the conflict detector in isolation
uv run python eval/run_eval.py --judge heuristic          # safe baseline
export ANTHROPIC_API_KEY=sk-...
uv run python eval/run_eval.py --judge claude             # the real judge

# 5. run with the real LLM judge + semantic embeddings end-to-end
export ANTHROPIC_API_KEY=sk-...
uv run --extra embeddings python eval/killer_demo.py

# 6. MCP server (stdio)
uv run python -m context_vault.mcp_server

# 7. HTTP API + admin console
uv run uvicorn context_vault.http_api:app --port 8000
#   → REST at http://localhost:8000 ; admin console at http://localhost:8000/admin

# 8. TypeScript SDK (frontend) — drives the running backend end-to-end
cd sdk-ts && npm install && npm run build && npm run example

HTTP API: sign up → get a key → use it

No admin dance, no caller-invented secret — POST /signup provisions an org and returns a server-minted cv_… key (shown once):

# 1. sign up — creates the org + admin and returns an API key (and a session cookie)
KEY=$(curl -s -X POST localhost:8000/signup -H 'content-type: application/json' \
  -d '{"org":"Acme","username":"[e-mail]","password":"demo1234"}' \
  | python -c 'import sys,json; print(json.load(sys.stdin)["api_key"])')

# 2. use it — assert a time-bound, permissioned fact, then resolve it
curl -X POST localhost:8000/assert -H "authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d '{"subject":"Priya","predicate":"lives in","object":"London","valid_from":"2024-06-01"}'

curl -X POST localhost:8000/resolve -H "authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d '{"query":"where does Priya live?","as_of":"2026-06-01"}'

# 3. mint a key for a new agent under your tenant (admin session/key; returned once)
curl -X POST localhost:8000/keys -H "authorization: Bearer $KEY" \
  -H 'content-type: application/json' -d '{"name":"agent-a","labels":[]}'

POST /principals and /admin/* are admin-only and fail-closed — they require VAULT_ADMIN_KEY to be set (the dev compose stack sets one). Onboarding via /signup + /keys needs no admin key.

Validation (real Anthropic key)

The conflict detector — the make-or-break component — was validated with the real Claude judge: 93.1% accuracy, 0% silent-corruption, 0 false-alarms on the gold set (uv run python eval/run_eval.py --judge claude). The killer demo, LLM extraction, and real semantic embeddings were all exercised end-to-end.

Documentation

• docs/SPEC.md — the product specification (source of truth)
• docs/QUICKSTART.md — zero → first governed retrieval (~5 min)
• docs/TESTING.md — test it end-to-end yourself with real data
• docs/PRODUCT.md — product overview: personas, flowcharts, how the whole product works (PM view)
• docs/ARCHITECTURE.md — full architecture diagrams + end-to-end pipeline with I/O
• docs/PLAN.md — architecture, decisions, consistency model, status
• docs/ROADMAP.md — product roadmap (Tiers 0–3 done; Tier 4 next)
• docs/MCP.md — register the MCP server with Claude Desktop / Code
• docs/FEDERATION.md — front your existing vector store
• CHANGELOG.md · sdk-ts/README.md (TypeScript SDK)

CLI

context-vault serve --port 8000           # API + admin console
context-vault register-principal --id a --labels team:x --api-key k
context-vault assert --principal a --subject Priya --predicate "lives in" --object London
context-vault resolve --principal a --query "where does Priya live?" --as-of 2026-06-01

SDK in 6 lines

from context_vault.app import build_vault
from context_vault.sdk import VaultClient
from context_vault.models.principal import Principal

vault = build_vault(); vault.init()
client = VaultClient(vault, Principal(id="agent-a", role="agent", labels=["team:sales"]))
client.assert_fact("Priya", "lives in", "London")
for c in client.resolve("where does Priya live?"):
    print(c.edge_str())

The conflict taxonomy

Contradiction detection is not binary. On Assert, a new claim's relation to an existing one is exactly one of:

Relation	Meaning	Action
CONTRADICTION	incompatible over overlapping validity	flag for review
TEMPORAL_SUPERSESSION	functional fact updated over time	supersede (close old)
REFINEMENT	compatible and more specific	branch (keep both)
DUPLICATE	restates the same fact	merge
INDEPENDENT	different facts, can coexist	no action
UNSURE	judge not confident	flag (never auto-mutate)

Collapsing these into "conflict / no-conflict" is exactly how a vault silently corrupts itself.

Architecture (module map)

The five operations — assert · resolve · reconcile · decay · audit — run against live Neo4j + Postgres, exposed via the Memory façade, an MCP server, a Python SDK, a TypeScript SDK, and the HTTP API. Opt-in framework adapters drop the Vault into an existing agent stack as governed memory — LangGraph/LangChain, Claude Agent SDK, CrewAI, and LlamaIndex (see docs/MCP.md). (For the full current inventory see docs/STATUS.md; for diagrams + the end-to-end pipeline see docs/ARCHITECTURE.md.)

Layer	Module
Memory façade (remember/recall/forget)	context_vault/memory.py
Claim primitive + conflict taxonomy	context_vault/models/
Conflict detection (normalize → pre-filter → judge → decide)	context_vault/conflict/
Embeddings (sentence-transformer + hash fallback)	context_vault/embed/
Neo4j claim store (reified claims, vector index, bitemporal)	context_vault/store/
Policy engine (per-claim ACL, deny-by-default)	context_vault/policy/
Append-only hash-chained audit log (Postgres)	context_vault/audit/
LLM claim extraction (review queue + auto-confirm)	context_vault/extract/
Reconciliation policy chain (trust→confidence→recency→human)	context_vault/reconcile/
Decay (confidence aging) + history compression	context_vault/vault.py
Multi-agent workspaces (partitioned beliefs)	models/claim.py, vault.py
Vault orchestrator (the 5 operations)	context_vault/vault.py
MCP server + in-process SDK	context_vault/mcp_server.py, sdk.py
HTTP transport (REST API + key→principal auth + CORS) + HTTP SDK	context_vault/http_api.py, http_client.py
Admin / audit console (single-page UI)	context_vault/admin_ui.py → GET /admin
TypeScript SDK (frontend → HTTP API)	sdk-ts/ (context-vault-sdk)