Metadata-Version: 2.4
Name: context-vault-ai
Version: 0.3.1
Summary: A temporal, governed context layer for agentic AI systems — bitemporal, attributed, permissioned Claims.
Project-URL: Homepage, https://github.com/RajdeepDas43/context-graph-vault
Project-URL: Documentation, https://github.com/RajdeepDas43/context-graph-vault/blob/main/docs/SPEC.md
Project-URL: Repository, https://github.com/RajdeepDas43/context-graph-vault
Project-URL: Issues, https://github.com/RajdeepDas43/context-graph-vault/issues
Project-URL: Changelog, https://github.com/RajdeepDas43/context-graph-vault/blob/main/CHANGELOG.md
Author: Context Vault
License: MIT
License-File: LICENSE
Keywords: agent-memory,audit,bitemporal,context,governance,mcp,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40
Requires-Dist: fastapi>=0.110
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2
Requires-Dist: neo4j>=5.26
Requires-Dist: numpy>=1.26
Requires-Dist: psycopg-pool>=3.2
Requires-Dist: psycopg[binary]>=3.1
Requires-Dist: pydantic>=2.6
Requires-Dist: uvicorn>=0.29
Provides-Extra: agent-framework
Requires-Dist: agent-framework-core>=1.0; extra == 'agent-framework'
Provides-Extra: claude-agent-sdk
Requires-Dist: claude-agent-sdk>=0.2; extra == 'claude-agent-sdk'
Provides-Extra: crewai
Requires-Dist: crewai>=1.0; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: asn1crypto>=1.5; extra == 'dev'
Requires-Dist: cryptography>=42; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.6; extra == 'embeddings'
Provides-Extra: federation
Requires-Dist: httpx>=0.27; extra == 'federation'
Provides-Extra: langgraph
Requires-Dist: langchain-core>=0.3; extra == 'langgraph'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.12; extra == 'llamaindex'
Provides-Extra: oidc
Requires-Dist: httpx>=0.27; extra == 'oidc'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'oidc'
Provides-Extra: telemetry-collector
Requires-Dist: fastapi>=0.110; extra == 'telemetry-collector'
Requires-Dist: psycopg[binary]>=3.1; extra == 'telemetry-collector'
Requires-Dist: uvicorn>=0.29; extra == 'telemetry-collector'
Provides-Extra: tsa
Requires-Dist: asn1crypto>=1.5; extra == 'tsa'
Requires-Dist: cryptography>=42; extra == 'tsa'
Description-Content-Type: text/markdown

# Context Vault

<!-- mcp-name: io.github.rajdeepdas43/context-vault -->

[![PyPI](https://img.shields.io/pypi/v/context-vault-ai)](https://pypi.org/project/context-vault-ai/)
[![PyPI downloads](https://img.shields.io/pypi/dm/context-vault-ai)](https://pypistats.org/packages/context-vault-ai)
[![npm downloads](https://img.shields.io/npm/dw/context-vault-sdk)](https://www.npmjs.com/package/context-vault-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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)

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

```python
# 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`](docs/STATUS.md) for the current state and
[`docs/PLAN.md`](docs/PLAN.md) for the architecture, decisions, and roadmap.

## Quickstart

```bash
# 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):

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

## CLI
```bash
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

```python
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`](docs/MCP.md#framework-adapters)). (For
the full current inventory see [`docs/STATUS.md`](docs/STATUS.md); for diagrams + the
end-to-end pipeline see [`docs/ARCHITECTURE.md`](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`) |
