AI coding agents: start with AGENTS.md. It contains build and test commands, the subpackage map, code style, crypto allowlist, and the guardrails (async-only, Membrane-gated ingest, CID invariant).

The Architecture

A Vault is a governed store of knowledge resources. Each resource is screened by the Membrane, chunked, hashed, trust-classified, and indexed for hybrid search. RBAC controls who can read, write, or administer.

┌─────────────────────────────────────────────────────────────────┐
│                          VAULT                                  │
├──────────────┬──────────────────────────────────────────────────┤
│  RBAC        │  READER · WRITER · ADMIN permission matrix       │
│  MEMBRANE    │  Innate scan → Release gate → Index/Quarantine   │
│  INGEST      │  Parse → Chunk → SHA3-256 CID → Embed → Store    │
│  GOVERN      │  Trust tiers · Lifecycle · Data classification   │
│  RETRIEVE    │  Hybrid search · Trust-weighted · Time-travel    │
│  GRAPH       │  Entities · Edges · Traversal · Extraction       │
│  VERIFY      │  Merkle tree · CID per chunk · Proof export      │
│  AUDIT       │  Every write → VaultEvent → Capsule (opt.)       │
│  ENCRYPT     │  AES-256-GCM · ML-KEM-768 · ML-DSA-65            │
├──────────────┴──────────────────────────────────────────────────┤
│  Trust weights: CANONICAL 1.5x · WORKING 1.0x · EPHEMERAL 0.7x  │
│  FIPS 202 · FIPS 197 · FIPS 203 · FIPS 204                      │
└─────────────────────────────────────────────────────────────────┘

Knowledge that can't be verified can't be trusted.

Why qp-vault

Vector databases store embeddings and return them by similarity. When something goes wrong, or when a regulator asks "was this the current policy at the time?", similarity search is not enough.

qp-vault solves three problems that vector databases do not:

1. Trust-weighted retrieval. Every resource has a trust tier (CANONICAL, WORKING, EPHEMERAL, ARCHIVED) that multiplies its search relevance. A CANONICAL SOP at 0.6 similarity outranks a WORKING draft at 0.8 similarity. This is not metadata filtering; it is a scoring function that ensures authoritative knowledge surfaces first, every time, without manual curation.

2. Cryptographic content integrity. Every chunk receives a SHA3-256 content ID at ingest. Every resource receives a Merkle root over its chunk CIDs. The entire vault has a root hash. Any modification to any chunk, in any resource, changes the vault's Merkle root. Auditors can verify a single resource without downloading the vault, using an exported Merkle proof. No trust in the storage layer is required.

3. Knowledge lifecycle with temporal validity. Resources have lifecycles (DRAFT to ACTIVE to SUPERSEDED to ARCHIVED) with temporal validity windows. Point-in-time queries answer "what was our policy on March 15, 2024?" by returning only resources that were ACTIVE at that date. Supersession chains link v1 to v2 to v3 with cryptographic pointers. Expired resources auto-transition. None of this exists in any vector database.

Content Addressing

Every chunk is hashed with SHA3-256 and assigned a content ID:

vault://sha3-256/4cb02d65a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12

Every resource receives a Merkle root computed over its sorted chunk CIDs. The vault itself has a root hash over all resource hashes:

                    Vault Merkle Root
                    /               \
         Resource A Root      Resource B Root
         /          \              |
  hash(c1+c2)    hash(c3+c4)    hash(c5)
   /      \        /      \       |
CID(c1) CID(c2) CID(c3) CID(c4) CID(c5)

Identical content always produces the same CID. Modified content always produces a different root. Auditors verify a single resource via Merkle proof without downloading the vault.

Trust Tiers

Trust is not metadata. It is a scoring function.

Search ranking formula:

relevance = (0.7 × vector_similarity + 0.3 × text_rank) × trust_weight × freshness_decay × layer_boost

Where freshness_decay = exp(-age_days / half_life × ln2). A 180-day-old WORKING document retains 50% freshness. A CANONICAL document of the same age retains 70%.

Knowledge Lifecycle

DRAFT ──→ REVIEW ──→ ACTIVE ──→ SUPERSEDED ──→ ARCHIVED
                        │
                     EXPIRED (auto when valid_until passes)
                        │
                     ACTIVE (re-activate)

vault.transition(r.id, "review", reason="Ready for security team")
vault.transition(r.id, "active")

old, new = vault.supersede(v1_id, v2_id)        # v1 → SUPERSEDED, linked to v2
chain = vault.chain(v1_id)                        # [v1, v2, v3, ...]
results = vault.search("policy", as_of=date(2024, 3, 15))  # Time-travel
expiring = vault.expiring(days=90)                # What's about to expire?

Explore the fit with your AI coding agent

Paste this prompt into Claude Code, Cursor, Codex, or any other agent:

Read the qp-vault README and AGENTS.md at https://github.com/quantumpipes/vault.
Then survey my codebase for every knowledge surface an AI reads from (docs, wikis,
RAG indices, prompt context, retrieval pipelines). For each, evaluate whether
trust-weighted search, SHA3-256 content addressing, the Membrane, or the knowledge
graph would improve safety, accuracy, or auditability. Recommend the single
highest-leverage place to start, with concrete files and functions to change.

Install

pip install qp-vault

Combine extras with commas:

pip install qp-vault[postgres,encryption,pq,capsule,fastapi]   # Production API server
pip install qp-vault[local,encryption,cli]                       # Air-gapped deployment
pip install qp-vault[docling,integrity,cli]                      # Development

Quick Start

from qp_vault import Vault

vault = Vault("./my-knowledge")

# Add with trust tiers
vault.add("Incident response: acknowledge within 15 minutes...",
          name="sop-incident.md", trust_tier="canonical")

# Trust-weighted search (deduplicated, with freshness decay)
results = vault.search("incident response")

# Multi-keyword grep (single-pass FTS, three-signal scoring)
results = vault.grep(["incident", "response", "P0", "escalation"])

# Retrieve full content
text = vault.get_content(results[0].resource_id)

# Replace content (atomic: creates new version, supersedes old)
old, new = vault.replace(resource_id, "Updated policy v2 content")

# Verify integrity
result = vault.verify()
print(result.merkle_root)

# Export proof for auditors
proof = vault.export_proof(resource_id)

Knowledge Graph

Track entities, relationships, and mentions across your vault. Works on both PostgreSQL and SQLite.

# Create entities
alice = vault.graph.create_node(name="Alice Chen", entity_type="person",
                                properties={"role": "CTO"})
acme = vault.graph.create_node(name="Acme Corp", entity_type="company")

# Connect them
vault.graph.create_edge(source_id=alice.id, target_id=acme.id,
                        relation_type="works_at", weight=0.9)

# Search and traverse
results = vault.graph.search_nodes("Alice")
neighbors = vault.graph.neighbors(alice.id, depth=2)

# Track mentions in documents
resource = vault.add("Alice Chen leads engineering at Acme.", name="team.md")
vault.graph.track_mention(alice.id, resource.id,
                          context_snippet="Alice Chen leads engineering")

# Backlinks: find all documents mentioning an entity
backlinks = vault.graph.get_backlinks(alice.id)

# Build LLM context from graph relationships
context = vault.graph.context_for([alice.id, acme.id])

# Graph-augmented search: boost docs mentioning detected entities
results = vault.search("Alice project updates", graph_boost=True)

Intelligence services for extraction, detection, resolution, materialization, and wikilinks. See Knowledge Graph docs.

Multi-Tenancy

vault.add("content", tenant_id="site-123")
vault.search("query", tenant_id="site-123")      # Scoped to tenant

# Or lock the vault to a single tenant
vault = Vault("./knowledge", tenant_id="site-123")

RBAC

vault = Vault("./knowledge", role="reader")       # Search, get, verify only
vault = Vault("./knowledge", role="writer")       # + add, update, delete
vault = Vault("./knowledge", role="admin")        # + export, import, config

Batch Import

resources = vault.add_batch(["doc1.md", "doc2.md", "doc3.md"], trust_tier="working")

Memory Layers

from qp_vault import MemoryLayer

ops = vault.layer(MemoryLayer.OPERATIONAL)        # SOPs, runbooks (boost=1.5x)
strategic = vault.layer(MemoryLayer.STRATEGIC)     # ADRs, decisions (trust=CANONICAL)
compliance = vault.layer(MemoryLayer.COMPLIANCE)   # Audit evidence (reads audited)

Health Scoring

score = vault.health()                # Vault-wide (0-100)
score = vault.health(resource.id)     # Per-resource

Content Screening (Membrane)

Content is screened before indexing. Prompt injection, jailbreak, XSS, and code injection attempts are quarantined.

vault.add("ignore all previous instructions")  # Quarantined automatically

Plugin System

from qp_vault.plugins import embedder, parser

@embedder("my-model")
class MyEmbedder:
    dimensions = 768
    async def embed(self, texts):
        return my_model.encode(texts)

Three discovery methods: explicit registration, entry_points, or --plugins-dir (air-gap).

Encryption

from qp_vault.encryption import AESGCMEncryptor, HybridEncryptor

# Classical
enc = AESGCMEncryptor()
ciphertext = enc.encrypt(b"secret")

# Post-quantum hybrid (ML-KEM-768 + AES-256-GCM)
enc = HybridEncryptor()
pub, sec = enc.generate_keypair()
ciphertext = enc.encrypt(b"classified", pub)

Event Streaming

from qp_vault.streaming import VaultEventStream

stream = VaultEventStream()
vault = AsyncVault("./knowledge", auditor=stream)

async for event in stream.subscribe():
    print(f"{event.event_type}: {event.resource_name}")

Import / Export

await vault.export_vault("backup.json")
await vault.import_vault("backup.json")

CLI

vault init ./knowledge
vault add report.pdf --trust canonical
vault search "revenue projections" --top-k 5
vault list --trust canonical --tenant site-123
vault verify
vault health
vault delete <id>
vault transition <id> review --reason "Ready for review"
vault content <id>
vault replace <id> new-version.md
vault export backup.json

15 commands. Exit codes: 0 = pass, 1 = fail. Designed for CI: vault verify && deploy.

FastAPI

from qp_vault.integrations.fastapi_routes import create_vault_router

router = create_vault_router(vault)
app.include_router(router, prefix="/v1/vault")
# 22+ endpoints: resources, search, faceted search, verify, health,
# lifecycle, collections, provenance, batch, export, content

Web Explorer

A single-file, no-build, air-gap-safe browser UI for reading a vault. Folder tree, inline markdown reader, full-text search, semantic icons, and keyboard navigation, with zero network requests.

cd examples/web-explorer
python generate_manifest.py /path/to/your/vault --title "My Vault"
open index.html

See examples/web-explorer/ and the Web Explorer guide.

Security

No deprecated cryptography. No runtime network dependencies. Air-gapped operation supported. Full threat model in docs/security.md.

Part of the Quantum Pipes Stack

Each independently useful. Together, the governed AI platform for autonomous organizations.

Documentation

Contributing

See CONTRIBUTING.md. Bug fixes with tests, new plugins (embedders, parsers, policies), and documentation improvements are welcome.

License

Apache License 2.0.