feat(graph): knowledge graph subpackage with dual-backend support

Add qp_vault.graph subpackage: GraphEngine facade, GraphStorageBackend
protocol, PostgreSQL (pg_trgm + recursive CTEs) and SQLite (FTS5 +
Python BFS) implementations. Intelligence services: KnowledgeExtractor,
EntityResolver, EntityDetector, EntityMaterializer, WikilinkResolver.
Membrane sanitization for LLM extraction. Every mutation fires VaultEvents
for capsule audit. Graph-augmented search via graph_boost parameter.

Comprehensive input validation: name/type/relation length caps, properties
size cap (50KB), tag limits, weight bounds, null byte stripping, direction
enum, self-edge/self-merge rejection, limit capping, graph_schema SQL
identifier validation.

177 graph tests + 63 security tests. 1048 total tests passing.

New files:
- src/qp_vault/graph/ (8 modules)
- src/qp_vault/membrane/sanitize.py
- tests/test_graph_*.py (8 test files)
- docs/knowledge-graph.md

Modified:
- enums.py (10 graph EventType values)
- protocols.py (GraphStorageBackend)
- storage/postgres.py (graph DDL, CTE, 20 methods, graph_schema)
- storage/sqlite.py (graph DDL, FTS5, BFS, 20 methods)
- vault.py (vault.graph property, graph_boost search)
- __init__.py (graph exports)
- pyproject.toml (graph extra)
- docs/index.md, architecture.md, api-reference.md, getting-started.md

Made-with: Cursor

Author: bradleygauthier

docs/api-reference.md

@@ -231,12 +231,15 @@ vault.search(
     as_of: date | None = None,          # Point-in-time
     deduplicate: bool = True,           # One result per resource
     explain: bool = False,              # Include scoring breakdown
+    graph_boost: bool = False,          # Boost docs mentioning detected entities
 ) -> list[SearchResult]
 ```
 
 When no embedder is configured, search automatically falls back to text-only mode (`vector_weight=0.0`, `text_weight=1.0`). This ensures search works on day one without requiring an embedding model.
 
-<!-- VERIFIED: vault.py:1051-1063 — text-only fallback -->
+When `graph_boost=True` and `vault.graph` is available, search detects entities in the query text, fetches their backlinks, and applies a 15% relevance boost to documents that mention those entities. Off by default. Best-effort: any failure falls back to standard search.
+
+<!-- VERIFIED: vault.py:1058-1075, 1172-1188 -->
 
 ### search_with_facets()
 
@@ -430,6 +433,52 @@ vault.import_vault(path: str | Path) -> list[Resource]
 
 ---
 
+## Knowledge Graph
+
+Access via `vault.graph`. Returns `GraphEngine` when the storage backend supports graphs, `None` otherwise.
+
+```python
+vault.graph -> GraphEngine | None
+```
+
+Full documentation: [Knowledge Graph Guide](knowledge-graph.md)
+
+Quick reference:
+
+```python
+# Nodes
+node = await vault.graph.create_node(name="Alice", entity_type="person")
+node = await vault.graph.get_node(node_id)
+nodes, total = await vault.graph.list_nodes(entity_type="person", limit=20)
+results = await vault.graph.search_nodes("Alice")
+updated = await vault.graph.update_node(node_id, name="Alice Smith")
+await vault.graph.delete_node(node_id)
+
+# Edges
+edge = await vault.graph.create_edge(source_id=a.id, target_id=b.id, relation_type="knows")
+edges = await vault.graph.get_edges(node_id, direction="outgoing")
+await vault.graph.delete_edge(edge_id)
+
+# Traversal + context
+neighbors = await vault.graph.neighbors(node_id, depth=2)
+context = await vault.graph.context_for([node_id])
+
+# Mentions
+await vault.graph.track_mention(node_id, resource_id, context_snippet="...")
+backlinks = await vault.graph.get_backlinks(node_id)
+
+# Cross-space + merge
+await vault.graph.add_to_space(node_id, space_id)
+merged = await vault.graph.merge_nodes(keep_id, merge_id)
+
+# Scan
+job = await vault.graph.scan(space_id)
+```
+
+<!-- VERIFIED: vault.py:253-257, graph/service.py:53-63 -->
+
+---
+
 ## Status
 
 ### status()

docs/architecture.md

@@ -30,10 +30,20 @@ src/qp_vault/
         sqlite.py         SQLite + FTS5 (default, zero-config)
         postgres.py       PostgreSQL + pgvector + pg_trgm (production)
 
+    graph/
+        models.py         GraphNode, GraphEdge, GraphMention, NeighborResult, etc.
+        service.py        GraphEngine: CRUD, traversal, merge, scan, audit events
+        extraction.py     KnowledgeExtractor: LLM-based entity/relationship extraction
+        resolution.py     EntityResolver: dedup cascade (exact + search + create)
+        detection.py      EntityDetector: in-memory name matching (no LLM)
+        materialization.py EntityMaterializer: profile.md + manifest.json generation
+        wikilinks.py      WikilinkResolver: parse + resolve [[Entity Name]] syntax
+
     membrane/
         pipeline.py       MembranePipeline: multi-stage content screening
         innate_scan.py    Pattern-based detection (regex blocklists)
         release_gate.py   Risk-proportionate gating decision
+        sanitize.py       Extraction-time input sanitization for LLM prompts
 
     encryption/
         aes_gcm.py        AES-256-GCM symmetric (FIPS 197)

docs/getting-started.md

@@ -152,6 +152,30 @@ vault.search("query", tenant_id="site-123")
 vault = Vault("./knowledge", tenant_id="site-123")
 ```
 
+## Knowledge Graph
+
+Track entities, relationships, and mentions across your vault:
+
+```python
+# Create entities
+alice = vault.graph.create_node(name="Alice", entity_type="person")
+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")
+
+# Track mentions in documents
+resource = vault.add("Alice leads engineering at Acme Corp.", name="team.md")
+vault.graph.track_mention(alice.id, resource.id, context_snippet="Alice leads engineering")
+
+# Search and traverse
+results = vault.graph.search_nodes("Alice")
+neighbors = vault.graph.neighbors(alice.id, depth=2)
+backlinks = vault.graph.get_backlinks(alice.id)
+```
+
+Works on both PostgreSQL and SQLite. See [Knowledge Graph](knowledge-graph.md) for extraction, detection, and wikilinks.
+
 ## CLI
 
 ```bash
@@ -170,6 +194,7 @@ vault status
 
 ## Next Steps
 
+- [Knowledge Graph](knowledge-graph.md): Entities, relationships, extraction, detection
 - [Trust Tiers](trust-tiers.md): How trust affects search ranking
 - [Encryption](encryption.md): AES-256-GCM, ML-KEM-768, ML-DSA-65
 - [RBAC](rbac.md): Reader/Writer/Admin roles

docs/index.md

@@ -9,6 +9,7 @@ Governed knowledge store for autonomous organizations. Every fact has provenance
 | [Getting Started](getting-started.md) | Install, first vault, add, search, grep, verify in 5 minutes |
 | [Architecture](architecture.md) | Package structure, layers, data flow, Protocol interfaces |
 | [API Reference](api-reference.md) | Complete Python SDK: Vault, AsyncVault, all methods |
+| [Knowledge Graph](knowledge-graph.md) | Entities, relationships, mentions, traversal, extraction, detection |
 | [Trust Tiers](trust-tiers.md) | CANONICAL, WORKING, EPHEMERAL, ARCHIVED and search weighting |
 | [Knowledge Lifecycle](lifecycle.md) | State machine, supersession chains, temporal validity |
 | [Memory Layers](memory-layers.md) | OPERATIONAL, STRATEGIC, COMPLIANCE with per-layer defaults |
@@ -39,7 +40,8 @@ print(results[0].content, results[0].trust_tier)
 ## Installation
 
 ```bash
-pip install qp-vault                    # SQLite, basic search, trust tiers
+pip install qp-vault                    # SQLite, basic search, trust tiers, knowledge graph
+pip install qp-vault[postgres]          # + PostgreSQL + pgvector + pg_trgm
 pip install qp-vault[encryption]        # + AES-256-GCM
 pip install qp-vault[pq]               # + ML-KEM-768, ML-DSA-65
 pip install qp-vault[all]              # Everything