{"id":47793803,"url":"https://github.com/context-graph-ai/contextdb","last_synced_at":"2026-04-03T16:01:25.999Z","repository":{"id":348780576,"uuid":"1173996036","full_name":"context-graph-ai/contextdb","owner":"context-graph-ai","description":"Embedded database for agentic memory — relational, graph, and vector under unified MVCC transactions","archived":false,"fork":false,"pushed_at":"2026-04-03T05:22:34.000Z","size":827,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T06:43:46.085Z","etag":null,"topics":["agentic-memory","database","embedded-database","graph-database","rust","vector-database","vector-search"],"latest_commit_sha":null,"homepage":"https://contextdb.tech","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/context-graph-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-06T00:51:34.000Z","updated_at":"2026-04-03T05:22:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"49d9b89c-fbb1-4eca-9947-3cb107a614f3","html_url":"https://github.com/context-graph-ai/contextdb","commit_stats":null,"previous_names":["context-graph-ai/contextdb"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/context-graph-ai/contextdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/context-graph-ai%2Fcontextdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/context-graph-ai%2Fcontextdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/context-graph-ai%2Fcontextdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/context-graph-ai%2Fcontextdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/context-graph-ai","download_url":"https://codeload.github.com/context-graph-ai/contextdb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/context-graph-ai%2Fcontextdb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31362678,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T15:19:21.178Z","status":"ssl_error","status_checked_at":"2026-04-03T15:19:20.670Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-memory","database","embedded-database","graph-database","rust","vector-database","vector-search"],"created_at":"2026-04-03T16:00:43.154Z","updated_at":"2026-04-03T16:01:25.971Z","avatar_url":"https://github.com/context-graph-ai.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CI](https://github.com/context-graph-ai/contextdb/actions/workflows/ci.yml/badge.svg)](https://github.com/context-graph-ai/contextdb/actions/workflows/ci.yml)\n[![Crates.io](https://img.shields.io/crates/v/contextdb-engine)](https://crates.io/crates/contextdb-engine)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)\n[![docs.rs](https://docs.rs/contextdb-engine/badge.svg)](https://docs.rs/contextdb-engine)\n\n# contextdb\n\nAn embedded database for agentic memory systems. Relational storage, graph traversal, and vector similarity search under unified MVCC transactions — in a single file, in a single process. Every agent, device, or service runs its own contextdb. They sync bidirectionally through a central server over WebSocket — knowledge learned by one becomes available to all, with per-table conflict resolution. No port forwarding, no VPN — WebSocket traverses NAT out of the box.\n\nIf you're building agent memory today, you're probably stitching together SQLite for state, a vector database for embeddings, and application code for graph traversal. contextdb replaces all three — and adds **enforceable policy constraints** (state machines, DAG enforcement, cascading propagation) that the database guarantees, not application code.\n\n```\ncontextdb\u003e UPDATE decisions SET status = 'draft' WHERE id = '550e8400...';\nError: invalid state transition: active -\u003e draft\n```\n\nNo triggers. No application-side validation. The database enforces it.\n\n**Familiar conventions, nothing new to learn:** PostgreSQL-compatible SQL, [pgvector](https://github.com/pgvector/pgvector) syntax for vector search (`\u003c=\u003e`), and [SQL/PGQ](https://www.iso.org/standard/76120.html)-style `GRAPH_TABLE ... MATCH` for graph queries — the subset that matters for bounded traversal, not the full standard.\n\n**Language support:** contextdb is a Rust library and CLI today. Python and TypeScript bindings are on the roadmap — contributions welcome.\n\n**Website:** [contextdb.tech](https://contextdb.tech) · **Docs:** [contextdb.tech/docs](https://contextdb.tech/docs/)\n\nSee [Why contextdb?](docs/why-contextdb.md) for the full problem statement, or jump to [Getting Started](docs/getting-started.md) to try it in 2 minutes.\n\n## Why Not SQLite + Extensions?\n\n| Capability | SQLite + extensions | contextdb |\n|---|---|---|\n| Vector search | sqlite-vec (separate extension, no unified transactions with relational data) | Built-in, auto-HNSW at 1K vectors, pre-filtered search, same MVCC transaction as rows |\n| Graph traversal | Recursive CTEs (unbounded, no cycle detection) | SQL/PGQ with bounded BFS, DAG enforcement, typed edges |\n| State machines | CHECK constraints + triggers (bypassable) | `STATE MACHINE` in DDL, enforced by the database engine |\n| Atomic cross-model updates | Application-level coordination | Single MVCC transaction across relational + graph + vector |\n| Sync | Build your own | Bidirectional collaborative sync — each database syncs changesets with conflict resolution, not WAL pages |\n| Immutable tables | Not enforceable (triggers are bypassable) | `IMMUTABLE` keyword, enforced by the database engine |\n| Cascading invalidation | Application code | `PROPAGATE` in DDL — state changes cascade along edges and FKs |\n\n## Use It As a Library\n\ncontextdb is an embedded database. The primary interface is the Rust API:\n\n```rust\nuse contextdb_engine::Database;\nuse std::collections::HashMap;\nuse std::sync::Arc;\n\nlet db = Database::open(std::path::Path::new(\"./my.db\"))?;\n// or: Database::open_memory() for ephemeral\n\nlet params = HashMap::new();\n\ndb.execute(\n    \"CREATE TABLE observations (\n       id UUID PRIMARY KEY,\n       data JSON,\n       embedding VECTOR(384)\n     ) IMMUTABLE\",\n    \u0026params,\n)?;\n\n// Insert with parameters\nlet mut params = HashMap::new();\nparams.insert(\"id\".into(), Value::Uuid(uuid::Uuid::new_v4()));\nparams.insert(\"data\".into(), Value::Json(serde_json::json!({\"type\": \"sensor\"})));\nparams.insert(\"embedding\".into(), Value::Vector(vec![0.1; 384]));\n\ndb.execute(\n    \"INSERT INTO observations (id, data, embedding) VALUES ($id, $data, $embedding)\",\n    \u0026params,\n)?;\n\n// Vector similarity search\nlet mut query_params = HashMap::new();\nquery_params.insert(\"query\".into(), Value::Vector(vec![0.1; 384]));\n\nlet result = db.execute(\n    \"SELECT id, data FROM observations ORDER BY embedding \u003c=\u003e $query LIMIT 10\",\n    \u0026query_params,\n)?;\n\n// Graph traversal\nlet result = db.execute(\n    \"SELECT target_id FROM GRAPH_TABLE(\n       edges MATCH (a)-[:DEPENDS_ON]-\u003e{1,3}(b)\n       WHERE a.id = $start\n       COLUMNS (b.id AS target_id)\n     )\",\n    \u0026params,\n)?;\n\n// Subscribe to commits\nlet rx = db.subscribe();\n// rx is a std::sync::mpsc::Receiver\u003cCommitEvent\u003e\n```\n\n### One Query, Three Subsystems\n\nFind semantically similar observations within a graph neighborhood, filtered by relational predicates — a query that would take ~40 lines of Python across SQLite, ChromaDB, and a hand-rolled BFS:\n\n```sql\nWITH neighborhood AS (\n  SELECT b_id FROM GRAPH_TABLE(\n    edges MATCH (start)-[:RELATES_TO]-\u003e{1,3}(related)\n    WHERE start.id = $entity_id\n    COLUMNS (related.id AS b_id)\n  )\n),\ncandidates AS (\n  SELECT o.id, o.data, o.embedding\n  FROM observations o\n  INNER JOIN neighborhood n ON o.entity_id = n.b_id\n  WHERE o.observation_type = 'config_change'\n)\nSELECT id, data FROM candidates\nORDER BY embedding \u003c=\u003e $query_embedding\nLIMIT 5\n```\n\nOne query. One transaction. One process.\n\nAdd to your `Cargo.toml`:\n\n```toml\n[dependencies]\ncontextdb-engine = \"0.3.2\"\ncontextdb-core = \"0.3.2\"\n```\n\n## Install\n\n```bash\n# Install the CLI\ncargo install contextdb-cli\n\n# Or run the server (no clone needed)\ncurl -O https://raw.githubusercontent.com/context-graph-ai/contextdb/main/docker-compose.yml\ncurl -O https://raw.githubusercontent.com/context-graph-ai/contextdb/main/nats.conf\ndocker compose up\n```\n\n## Or Explore With the CLI\n\n```bash\ncargo build --release -p contextdb-cli\n./target/release/contextdb-cli :memory:\n```\n\n```\ncontextdb\u003e CREATE TABLE decisions (id UUID PRIMARY KEY, status TEXT NOT NULL)\n           STATE MACHINE (status: draft -\u003e [active, rejected], active -\u003e [superseded]);\nok (rows_affected=0)\n\ncontextdb\u003e INSERT INTO decisions VALUES ('550e8400-e29b-41d4-a716-446655440000', 'draft');\nok (rows_affected=1)\n\ncontextdb\u003e UPDATE decisions SET status = 'active' WHERE id = '550e8400-e29b-41d4-a716-446655440000';\nok (rows_affected=1)\n\ncontextdb\u003e UPDATE decisions SET status = 'draft' WHERE id = '550e8400-e29b-41d4-a716-446655440000';\nError: invalid state transition: active -\u003e draft\n\ncontextdb\u003e .schema decisions\nCREATE TABLE decisions (\n  id UUID NOT NULL PRIMARY KEY,\n  status TEXT NOT NULL\n)\nSTATE MACHINE (status: active -\u003e [superseded], draft -\u003e [active, rejected])\n```\n\n## What It Does\n\n**Relational (PostgreSQL-compatible SQL)** — SELECT, INSERT, UPDATE, DELETE, JOINs (INNER/LEFT), CTEs, upsert (`ON CONFLICT DO UPDATE`), DISTINCT, LIMIT, IN with subqueries, LIKE, BETWEEN, parameter binding (`$name`).\n\n**Graph (SQL/PGQ-style)** — `GRAPH_TABLE(... MATCH ...)` following SQL/PGQ conventions for bounded BFS, typed edges, variable-length paths (`{1,3}`), and direction control. DAG constraint enforcement prevents cycles. State propagation cascades changes along graph edges.\n\n**Vector (pgvector conventions)** — Cosine similarity search via `\u003c=\u003e`. Auto-switches between brute-force (\u003c 1000 vectors) and HNSW indexing. Pre-filtered search narrows candidates before scoring.\n\n**Unified transactions** — One transaction atomically updates relational rows, graph adjacency structures, and vector indexes. One read snapshot sees consistent state across all three. MVCC with consistent snapshots — readers never block writers.\n\n**Enforceable policy constraints** — `IMMUTABLE` tables, `STATE MACHINE` column transitions, `DAG` cycle prevention, `RETAIN` with TTL expiry, `PROPAGATE` for cascading state changes along edges and foreign keys. Enforced by the database — no application code can bypass them.\n\n**Collaborative sync** — Every contextdb instance is a full read-write database. Each runs a SyncClient that syncs bidirectionally with a central SyncServer over NATS (WebSocket for clients behind NAT, native protocol for server-to-server). Offline-first: each database works independently, syncing changesets when connected. Per-table conflict resolution (LatestWins, ServerWins, EdgeWins) and per-table sync direction (Push, Pull, Both, None) give you fine-grained control over what flows where. The server runs the same contextdb engine — self-host it, or point your databases at a hosted server.\n\n**Persistence** — Single-file storage via redb. Crash-safe. Compute/storage separated via the `WriteSetApplicator` trait (local redb for open source, object store for enterprise).\n\n**Plugin system** — `DatabasePlugin` trait with lifecycle hooks (`pre_commit`, `post_commit`, `on_open`, `on_close`, `on_ddl`, `on_query`, `post_query`, `health`, `describe`, `on_sync_push`, `on_sync_pull`). Applications inject plugins via `Database::open_with_plugin()`.\n\n**Subscriptions** — `db.subscribe()` returns a broadcast channel of `CommitEvent`s for reactive downstream processing.\n\n## Scale Envelope\n\ncontextdb is designed for agentic memory, not data warehousing:\n\n- 10K-1M rows\n- Sparse graphs with bounded traversal (depth \u003c= 10)\n- Append-heavy writes, small transactions\n- Configurable memory budget via `SET MEMORY_LIMIT` (no hard-coded ceiling)\n- Configurable file-growth budget via `SET DISK_LIMIT` / `SHOW DISK_LIMIT` or `--disk-limit` / `CONTEXTDB_DISK_LIMIT` for file-backed databases\n- Laptops, ARM64 devices (browser and mobile via Rust's WASM target are future directions)\n\n## Documentation\n\nFull documentation is available at [contextdb.tech/docs](https://contextdb.tech/docs/), or browse the source files:\n\n| Doc | What it covers |\n|-----|---------------|\n| **[Getting Started](docs/getting-started.md)** | Build, first REPL session, library embedding — 2 minutes |\n| **[Why contextdb?](docs/why-contextdb.md)** | Problem statement, design philosophy, comparison with alternatives |\n| **[Usage Scenarios](docs/usage-scenarios.md)** | 16 problem-first walkthroughs: constraints, graph queries, vector search, sync, propagation |\n| **[Query Language](docs/query-language.md)** | SQL, graph MATCH, vector search, constraints, built-in functions |\n| **[CLI Reference](docs/cli.md)** | REPL commands, sync commands, non-interactive scripting |\n| **[Architecture](docs/architecture.md)** | Crate map, storage engine, MVCC, sync protocol, plugin system |\n\n## Architecture\n\n10-crate Rust workspace:\n\n| Crate | Role |\n|-------|------|\n| `contextdb-core` | Types, executor traits, errors, table metadata |\n| `contextdb-tx` | MVCC transaction manager with deferred-apply write sets |\n| `contextdb-relational` | Relational executor (scan, insert, upsert, delete) |\n| `contextdb-graph` | Graph executor (bounded BFS, adjacency index, DAG enforcement) |\n| `contextdb-vector` | Vector executor (cosine similarity, HNSW, pre-filtered search) |\n| `contextdb-parser` | SQL parser (pest grammar with GRAPH_TABLE + vector extensions) |\n| `contextdb-planner` | Rule-based query planner |\n| `contextdb-engine` | Database engine — wires all subsystems, plugin API, subscriptions |\n| `contextdb-server` | Sync server and client (NATS transport, conflict resolution) |\n| `contextdb-cli` | Interactive CLI REPL |\n\n## Building\n\n```bash\ncargo build --workspace\ncargo test --workspace\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontext-graph-ai%2Fcontextdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcontext-graph-ai%2Fcontextdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontext-graph-ai%2Fcontextdb/lists"}