experience-graph 0.1.0__tar.gz

experience_graph-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install ruff>=0.8
+      - run: ruff check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e ".[dev]"
+      - run: mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v

experience_graph-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tools
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Data
+data/
+*.db
+
+# Environment
+.env

experience_graph-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [--fix]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: check-yaml

experience_graph-0.1.0/CLAUDE.md

@@ -0,0 +1,110 @@
+# Experience Graph
+
+A structured experience store for AI agents. Agents record traces of their work, build a shared knowledge graph of entities and evidence, and retrieve context packs before starting new tasks. The system provides governed mutations, immutable audit logging, and policy-based access control.
+
+## Agent Guide
+
+Operational reference for interacting with the experience graph lives in `docs/agent-guide/`:
+
+| Document | What It Covers |
+|----------|----------------|
+| [trace-format.md](docs/agent-guide/trace-format.md) | Constructing and ingesting valid trace JSON |
+| [schemas.md](docs/agent-guide/schemas.md) | All Pydantic schemas with fields, types, and examples |
+| [operations.md](docs/agent-guide/operations.md) | Full CLI, REST API, MCP, and Python mutation API reference |
+| [playbooks.md](docs/agent-guide/playbooks.md) | Step-by-step procedures for common tasks |
+
+## Hard Rules
+
+- **Traces are immutable.** Once ingested, a trace cannot be modified or deleted through normal operations.
+- **All mutations go through the governed pipeline.** Validate, policy check, idempotency check, execute, emit event. No direct store writes.
+- **Use `--format json` for machine output.** All CLI commands support it. Parse JSON output, not human-readable text.
+- **Extra fields are forbidden.** All schemas use `extra="forbid"`. Unrecognized fields cause validation errors.
+- **Use `structlog` for logging.** Never use `print()` in library code.
+- **Type hints on all public APIs.**
+
+## Development Commands
+
+```bash
+# Setup
+uv pip install -e ".[dev]"
+xpg admin init
+
+# Quality
+make lint          # ruff check src/ tests/
+make format        # ruff format + fix
+make typecheck     # mypy src/
+make test          # pytest tests/ -v
+
+# CLI
+xpg admin health
+xpg admin stats
+xpg admin serve --port 8420
+xpg ingest trace <file>
+xpg ingest dbt-manifest <manifest>
+xpg ingest openlineage <events>
+xpg retrieve search "<query>"
+xpg curate promote <trace_id> --title "..." --description "..."
+xpg analyze context-effectiveness
+xpg analyze token-usage
+```
+
+## Key Files
+
+| Path | Purpose |
+|------|---------|
+| `src/xpgraph/schemas/` | All Pydantic data models |
+| `src/xpgraph/mutate/commands.py` | Operation enum, Command/CommandResult schemas |
+| `src/xpgraph/mutate/executor.py` | Governed mutation pipeline |
+| `src/xpgraph/retrieve/pack_builder.py` | Context pack assembly with telemetry |
+| `src/xpgraph/retrieve/strategies.py` | Search strategies (keyword, semantic, graph) |
+| `src/xpgraph/retrieve/formatters.py` | Token-budgeted markdown formatters |
+| `src/xpgraph/retrieve/effectiveness.py` | Context effectiveness analysis |
+| `src/xpgraph/retrieve/token_tracker.py` | Token usage tracking |
+| `src/xpgraph/retrieve/token_usage.py` | Token usage analysis and reporting |
+| `src/xpgraph/stores/base/` | Store ABCs (TraceStore, DocumentStore, GraphStore, VectorStore, EventLog, BlobStore) |
+| `src/xpgraph/stores/registry.py` | StoreRegistry — DI container with config-driven backend selection |
+| `src/xpgraph/stores/sqlite/` | SQLite store implementations (default) |
+| `src/xpgraph/stores/postgres/` | Postgres store implementations (cloud) |
+| `src/xpgraph/stores/lancedb/` | LanceDB vector store (serverless ANN) |
+| `src/xpgraph/stores/pgvector/` | pgvector store (cloud vectors) |
+| `src/xpgraph/stores/s3/` | S3 blob store (cloud files) |
+| `src/xpgraph/stores/local/` | Local filesystem blob store |
+| `src/xpgraph/mcp/server.py` | MCP Macro Tools server (8 tools, markdown responses) |
+| `src/xpgraph_cli/` | CLI commands (ingest, curate, retrieve, analyze, admin) |
+| `src/xpgraph_api/` | REST API (FastAPI routes, models) |
+| `src/xpgraph_sdk/` | Python SDK (XPGClient, skill functions) |
+| `src/xpgraph_workers/` | Workers (enrichment, learning, ingestion, maintenance) |
+| `integrations/obsidian/` | Obsidian vault indexer |
+
+## Packages
+
+| Package | Purpose |
+|---------|---------|
+| `xpgraph` | Core library — schemas, pluggable stores, mutation executor, retrieval, formatters |
+| `xpgraph_cli` | CLI (`xpg`) — ingest, curate, retrieve, analyze, admin |
+| `xpgraph_api` | REST API (`xpg-api`) — FastAPI with OpenAPI auto-generation |
+| `xpgraph_sdk` | Python SDK — XPGClient (local/remote), skill functions |
+| `xpgraph_workers` | Workers — enrichment, learning, ingestion (dbt, OpenLineage), maintenance |
+
+## Store Backends
+
+Backends are configured via `~/.xpg/config.yaml` or environment variables:
+
+| Store | Default | Local ANN | Cloud | Env Var |
+|-------|---------|-----------|-------|---------|
+| Trace | `sqlite` | | `postgres` | `XPG_PG_DSN` |
+| Document | `sqlite` | | `postgres` | `XPG_PG_DSN` |
+| Graph | `sqlite` | | `postgres` | `XPG_PG_DSN` |
+| Vector | `sqlite` | `lancedb` | `pgvector` | `XPG_PG_DSN` |
+| Event Log | `sqlite` | | `postgres` | `XPG_PG_DSN` |
+| Blob | `local` | | `s3` | `XPG_S3_BUCKET` |
+
+Graph stores support temporal versioning (SCD Type 2) with `as_of` parameter for time-travel queries.
+
+## Entry Points
+
+| Command | Target |
+|---------|--------|
+| `xpg` | `xpgraph_cli.main:app` |
+| `xpg-mcp` | `xpgraph.mcp.server:main` |
+| `xpg-api` | `xpgraph_api.app:main` |

experience_graph-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Ronsse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

experience_graph-0.1.0/Makefile

@@ -0,0 +1,29 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help install install-dev lint format typecheck test clean
+
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install package
+	uv pip install -e .
+
+install-dev: ## Install package with dev dependencies
+	uv pip install -e ".[dev]"
+
+lint: ## Run linting
+	ruff check src/ tests/
+
+format: ## Format code
+	ruff format src/ tests/
+	ruff check --fix src/ tests/
+
+typecheck: ## Run type checking
+	mypy src/
+
+test: ## Run tests
+	pytest tests/ -v
+
+clean: ## Clean build artifacts
+	rm -rf dist/ build/ *.egg-info .mypy_cache .ruff_cache .pytest_cache
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

experience_graph-0.1.0/PKG-INFO

@@ -0,0 +1,361 @@
+Metadata-Version: 2.4
+Name: experience-graph
+Version: 0.1.0
+Summary: Experience Graph — structured memory and learning for AI agents
+Project-URL: Homepage, https://github.com/experience-graph/experience-graph
+Project-URL: Documentation, https://github.com/experience-graph/experience-graph/tree/main/docs
+Project-URL: Repository, https://github.com/experience-graph/experience-graph
+Project-URL: Issues, https://github.com/experience-graph/experience-graph/issues
+Author: Nathan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,knowledge-graph,llm,mcp,memory,traces
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: structlog>=23.0
+Requires-Dist: typer>=0.9
+Requires-Dist: ulid-py>=1.1
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: cloud
+Requires-Dist: boto3>=1.34; extra == 'cloud'
+Requires-Dist: pgvector>=0.3; extra == 'cloud'
+Requires-Dist: psycopg-pool>=3.1; extra == 'cloud'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'cloud'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=0.3; extra == 'langgraph'
+Requires-Dist: langgraph>=0.2; extra == 'langgraph'
+Provides-Extra: vectors
+Requires-Dist: lancedb>=0.6; extra == 'vectors'
+Requires-Dist: numpy; extra == 'vectors'
+Requires-Dist: pandas; extra == 'vectors'
+Requires-Dist: pyarrow; extra == 'vectors'
+Description-Content-Type: text/markdown
+
+# Experience Graph
+
+A structured context graph and experience store for AI agents. Agents read from and write to a shared knowledge layer — traces, entities, evidence, precedents, and policies — so teams build institutional memory instead of starting from scratch.
+
+## What's In the Graph
+
+```
+  ┌─────────────────────────────────────────────────────────────────────┐
+  │                     THE EXPERIENCE GRAPH                            │
+  │                                                                     │
+  │  ┌───────────┐  depends_on   ┌───────────┐  part_of  ┌─────────┐  │
+  │  │  service:  │──────────────▶│  service:  │─────────▶│  team:  │  │
+  │  │  auth-api  │              │  user-db   │          │ platform │  │
+  │  └─────┬─────┘              └───────────┘          └─────────┘  │
+  │        │ touched_entity                                          │
+  │  ┌─────▼──────────────────────────────────────┐                  │
+  │  │  trace: "Added rate limiting to auth-api"  │                  │
+  │  │  ├─ step: researched existing patterns     │                  │
+  │  │  ├─ step: tool_call edit_file gateway.py   │                  │
+  │  │  ├─ step: tool_call run_tests (42 passed)  │                  │
+  │  │  └─ outcome: success                       │                  │
+  │  └─────┬──────────────────────┬───────────────┘                  │
+  │        │ used_evidence        │ promoted_to_precedent            │
+  │  ┌─────▼─────────┐    ┌──────▼──────────────────────────┐       │
+  │  │  evidence:    │    │  precedent: "Rate limiting      │       │
+  │  │  "RFC: API    │    │  pattern for API gateways"      │       │
+  │  │   guidelines" │    │  confidence: 0.85               │       │
+  │  │  uri: s3://…  │    │  applies_to: [auth, payments]   │       │
+  │  └───────────────┘    └─────────────────────────────────┘       │
+  │                                                                     │
+  │  Every node has temporal versions (valid_from / valid_to)          │
+  │  — query any past state with as_of                                 │
+  └─────────────────────────────────────────────────────────────────────┘
+```
+
+The graph captures **what agents did** (traces with steps, tool calls, reasoning, outcomes), **what they knew** (evidence — documents, snippets, file pointers with URIs to local files or S3), **what they learned** (precedents — distilled patterns extracted from successful and failed traces), and **how things relate** (13 edge types: dependencies, provenance, applicability). All nodes carry temporal versions so you can query the state of knowledge at any point in time.
+
+## How It Works
+
+```
+  AGENTS & HUMANS                     BACKGROUND WORKERS
+  read & write                        analyze & curate
+       │                                     │
+       │  ┌───────────────────────┐          │
+       ├──│ CLI  (xpg)            │          │
+       ├──│ MCP  (8 macro tools)  │  Tools   │  ┌─────────────────────┐
+       ├──│ API  (REST/FastAPI)   │──Layer──┐ ├──│ Enrichment: auto-   │
+       ├──│ SDK  (XPGClient)      │        │ │  │   tag, classify,    │
+       ├──│ OpenClaw (MCP skill)  │        │ │  │   score importance  │
+       │  └───────────────────────┘        │ │  ├─────────────────────┤
+       │                                   │ ├──│ Learning: mine      │
+       │  ┌───────────────────────┐        │ │  │   failure patterns  │
+       │  │ Context Pack Builder  │◀───────┘ │  │   into precedents   │
+       │  │ ┌─────┐ ┌─────┐      │          │  ├─────────────────────┤
+       │  │ │docs │ │graph│      │  Retrieval├──│ Ingestion: import   │
+       │  │ │FTS  │ │ BFS │      │          │  │   dbt, OpenLineage  │
+       │  │ └─────┘ └─────┘      │          │  ├─────────────────────┤
+       │  │ ┌─────┐ ┌─────┐      │          ├──│ Maintenance: prune  │
+       │  │ │trace│ │vector│     │          │  │   stale data, audit │
+       │  │ │     │ │      │     │          │  ├─────────────────────┤
+       │  │ │hist.│ │sim.  │     │          └──│ Thinking Engine:    │
+       │  │ └─────┘ └─────┘      │             │   cognition tiering │
+       │  │                      │             │   (fast→deep)       │
+       │  │ → deduplicate        │             └─────────────────────┘
+       │  │ → rank by relevance  │
+       │  │ → enforce token      │
+       │  │   budget             │
+       │  │ → emit telemetry     │
+       │  └──────────┬───────────┘
+       │             │ assembled pack
+       │             ▼
+       │  ┌──────────────────────────┐
+       │  │  Markdown context for    │
+       │  │  agent's next task       │
+       │  │  (token-budgeted,        │
+       │  │   relevance-ranked)      │
+       │  └──────────────────────────┘
+       │
+       │  ┌──────────────────────────────────────┐
+       └─▶│      Governed Write Pipeline          │
+          │  validate → policy check              │
+          │  → idempotency → execute              │
+          │  → emit event (immutable audit log)   │
+          └──────────────────────┬────────────────┘
+                                 │
+          ┌──────────────────────▼────────────────┐
+          │         Pluggable Storage              │
+          │  SQLite (local) │ Postgres (cloud)     │
+          │  pgvector       │ S3 (blobs/files)     │
+          └────────────────────────────────────────┘
+```
+
+**The feedback loop:** agents retrieve context packs before tasks, execute work, ingest traces of what happened, and record whether the task succeeded. Background workers analyze these outcomes to promote successful patterns into precedents and flag noisy context items — so the graph gets smarter over time.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+# Core (SQLite backends)
+pip install -e ".[dev]"
+
+# With cloud backends (Postgres, pgvector, S3)
+pip install -e ".[dev,cloud]"
+
+# With vector support (LanceDB, numpy, pyarrow)
+pip install -e ".[dev,vectors]"
+```
+
+## Quick Start
+
+```bash
+xpg admin init                    # Initialize stores
+xpg admin health                  # Check store health
+```
+
+## CLI
+
+```bash
+# Ingest
+xpg ingest trace trace.json       # Ingest a trace
+xpg ingest evidence evidence.json # Ingest evidence
+xpg ingest dbt-manifest manifest.json   # Import dbt lineage graph
+xpg ingest openlineage events.json      # Import OpenLineage events
+
+# Curate
+xpg curate promote TRACE_ID --title "..." --description "..."
+xpg curate link SOURCE_ID TARGET_ID
+xpg curate label ENTITY_ID important
+xpg curate feedback TRACE_ID 0.9
+
+# Retrieve
+xpg retrieve trace TRACE_ID       # Fetch a trace
+xpg retrieve search "query"       # Search documents
+xpg retrieve entity ENTITY_ID     # Fetch an entity
+xpg retrieve precedents           # List precedents
+xpg retrieve pack --intent "..."  # Assemble a retrieval pack
+
+# Analyze
+xpg analyze context-effectiveness # Which context items correlate with success
+xpg analyze token-usage           # Token budget tracking across layers
+
+# Admin
+xpg admin stats                   # Store counts
+xpg admin serve --port 8420       # Start REST API server
+```
+
+All commands support `--format json` for machine-readable output. List commands also support `--format jsonl`, `--format tsv`, `--fields`, `--truncate`, and `--quiet`.
+
+## REST API
+
+Start the API server:
+
+```bash
+xpg admin serve --port 8420
+# or
+xpg-api
+```
+
+Key endpoints:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/v1/traces` | Ingest a trace |
+| GET | `/api/v1/search?q=...` | Full-text search |
+| POST | `/api/v1/packs` | Assemble context pack |
+| GET | `/api/v1/entities/{id}` | Get entity with neighborhood |
+| POST | `/api/v1/precedents` | Promote trace to precedent |
+| POST | `/api/v1/feedback` | Record feedback |
+| GET | `/api/v1/health` | Health check |
+| GET | `/api/v1/stats` | Store statistics |
+| GET | `/api/v1/effectiveness` | Context effectiveness report |
+
+Full OpenAPI spec available at `/docs` when the server is running.
+
+## OpenClaw Integration
+
+Add structured institutional memory to OpenClaw agents in 3 steps:
+
+```bash
+pip install experience-graph && xpg admin init
+```
+
+Add to `openclaw.json`:
+
+```json
+{
+  "mcpServers": {
+    "experience-graph": {
+      "command": "xpg-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Your agent gets 8 macro tools for traces, precedents, knowledge graph, and search. See [`integrations/openclaw/`](integrations/openclaw/) for full setup guide.
+
+## MCP Server
+
+8 high-level Macro Tools returning token-budgeted markdown (not raw JSON):
+
+```bash
+xpg-mcp   # Start the MCP server
+```
+
+| Tool | Purpose |
+|------|---------|
+| `get_context` | Search docs + graph + traces, return summarized markdown pack |
+| `save_experience` | Ingest a trace |
+| `save_knowledge` | Create entity + optional relationship |
+| `save_memory` | Store a document |
+| `get_lessons` | List precedents as markdown |
+| `get_graph` | Entity + neighborhood as markdown |
+| `record_feedback` | Record task success/failure |
+| `search` | Combined doc + graph search as markdown |
+
+All tools accept `max_tokens` (default 2000) for context window budgeting.
+
+## Python SDK
+
+```python
+from xpgraph_sdk import XPGClient
+
+# Local mode (direct store access)
+client = XPGClient()
+
+# Remote mode (via REST API)
+client = XPGClient(base_url="http://localhost:8420")
+
+# Operations
+results = client.search("database migration", limit=5)
+trace_id = client.ingest_trace(trace_dict)
+entity_id = client.create_entity("auth-service", entity_type="service")
+pack = client.assemble_pack("deploy checklist for staging")
+```
+
+Skill functions return pre-summarized markdown strings for direct LLM injection:
+
+```python
+from xpgraph_sdk.skills import get_context_for_task, get_recent_activity
+
+context = get_context_for_task(client, "implement retry logic", domain="backend")
+activity = get_recent_activity(client, domain="backend", max_tokens=1500)
+```
+
+## Pluggable Storage
+
+Store backends are selected via `~/.xpg/config.yaml`:
+
+```yaml
+stores:
+  graph:
+    backend: postgres
+    dsn: postgresql://user:pass@host/db
+  vector:
+    backend: lancedb          # serverless, no external DB needed
+    # uri: /custom/path       # optional, defaults to data/stores/lancedb/
+  blob:
+    backend: s3
+    bucket: xpg-artifacts
+    region: us-east-1
+  # trace, document, event_log default to sqlite
+```
+
+Available backends:
+
+| Store | SQLite (default) | LanceDB | Postgres | Other |
+|-------|:-:|:-:|:-:|:-:|
+| Trace | `sqlite` | | `postgres` | |
+| Document | `sqlite` | | `postgres` | |
+| Graph | `sqlite` | | `postgres` | |
+| Vector | `sqlite` | `lancedb` | `pgvector` | |
+| Event Log | `sqlite` | | `postgres` | |
+| Blob | `local` | | | `s3` |
+
+**LanceDB** is the recommended vector backend for local/single-machine deployments — it's serverless (like SQLite for vectors), uses native ANN indexing with cosine similarity, and stores data as efficient Lance-format files on disk. No external database needed. Use **pgvector** for distributed/multi-server deployments.
+
+Graph stores support SCD Type 2 temporal versioning — query historical state with `as_of` parameter.
+
+## Ingestion Workers
+
+Auto-populate the knowledge graph from external data tools:
+
+```bash
+# Import dbt lineage (models, sources, dependencies)
+xpg ingest dbt-manifest target/manifest.json
+
+# Import OpenLineage events (datasets, jobs, reads/writes)
+xpg ingest openlineage lineage-events.json
+```
+
+## Development
+
+```bash
+pytest                            # Run all tests (440+)
+pytest tests/unit/ -v             # Unit tests only
+pytest -m postgres                # Postgres integration tests
+ruff check src/ tests/            # Lint
+mypy src/                         # Type check
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).