Skip to content

capability-index.md

Latest commit

 

History

History
119 lines (107 loc) · 9.98 KB

capability-index.md

File metadata and controls

119 lines (107 loc) · 9.98 KB
Raw

Capability Index — what contextdb is, is not, and where it stops

One page to orient a new reader or an agent before it reads anything else: what contextdb actually does, what it deliberately does not do, and the numbers that bound it. Every claim below is backed by a doc section or a test in this repo — this page is a map, not a new source of truth.

What contextdb is

  • An embedded, schema-free, multi-model database. Relational tables, graph traversal, and vector similarity search, all under one MVCC transaction, in a single file, in a single process. See Why contextdb? and Architecture.
  • A policy engine, not just storage. STATE MACHINE, DAG, IMMUTABLE, PROPAGATE, RETAIN, and HISTORY CURRENT ONLY are declared in table DDL and enforced by the database itself, not by application code or bypassable triggers. See Query Language.
  • PostgreSQL-compatible SQL for relational work, pgvector syntax (<=>) for vector search, and a bounded subset of SQL/PGQ GRAPH_TABLE ... MATCH for graph queries — familiar surface, not a new query language to learn.
  • Bidirectional dial-by-key sync. Every database syncs changesets with a declared, per-table conflict policy (SYNC CONFLICT KEEP FIRST | KEEP LATEST) over the Iroh transport — nodes reach each other by cryptographic identity, no broker installed by default. See Architecture — Sync. This release emits and accepts only sync protocol 7. Envelopes using any other protocol version are refused.
  • A durable work ledger and a media/blob plane, both pure library surfaces today (no CLI flag): jobs/claims/leases for distributing work across machines, and content-addressed blob ingest/fetch/reclaim for large media. See Architecture.
  • A CLI, a REPL, and a Rust library — contextdb/contextdb-server binaries plus the contextdb-engine crate as an embeddable dependency. See CLI Reference and Getting Started.
  • Maintained vector search. A vector column may declare local PARTITION_KEY layouts and an effective default limit of 256 live-plus-snapshot-retained layouts. One, several, or all authorized layouts produce one global top-k; a partition is not a tenant, authorization rule, or sync direction. Maintained indexed routes have an at-least-95% recall-at-10 acceptance target against exact search on the same stored column. AUTO_INDEX_AT and HNSW (M, EF_CONSTRUCTION, EF_SEARCH) are declarable per-column workload policy; default silence keeps the compatibility profile. See Query Language and Architecture.

What contextdb is not

  • Not a schema. The agentic-memory tables used as running examples throughout these docs (decisions, observations, intentions, digests) are one example schema you can delete or replace. See the README and Why contextdb?.
  • Not a general-purpose database. The SQL/PGQ graph subset covers bounded traversal for agentic workloads, not the full standard; contextdb is a focused tool for agent memory, not a data warehouse. See the Design Envelope.
  • Not a message broker or a third-party relay by default. The default configuration contacts no external service; a self-hosted or opt-in iroh-relay is only for introducing peers across networks that can't reach each other directly. See Architecture — Sync.
  • Not multi-tenant orchestration. --tenant-id is a sync namespace — every client and server sharing one tenant ID replicate with each other. Running many isolated tenants behind one deployment, cross-tenant intelligence, and managed hosting are commercial-layer concerns outside this repo, not something contextdb itself provides.
  • Not a majority-vote distributed system. Conflict arbitration is declared per table (KEEP FIRST / KEEP LATEST) and, for the five hub-refereed work-ledger tables, hardcoded to keep_first — there is no quorum or leader election; a hub is a specific, addressable machine an edge dials.
  • Not yet bound to Python or TypeScript. Rust library and CLI today; other language bindings are on the roadmap (README).
  • Schema vocabulary a peer cannot read holds back only that table. The holdback names the affected table, missing capability, and node to upgrade while unrelated tables continue; the held table resumes when the capability is available.

Where it stops — the numbers

  • Design envelope (from Why contextdb? — Design Envelope): 10K–1M rows per database, sparse graphs with bounded traversal (depth ≤ 10), append-heavy writes with small transactions, laptops and ARM64 devices as the target hardware (browser/mobile via WASM is a future direction, not shipped).
  • Nine reserved table names (work_jobs, work_claims, work_results, work_failures, work_cancellations, work_inputs, work_capabilities, peer_directory, work_node_contacts) carry a fixed, engine-owned shape and policy — an operator table using any other name is entirely unrestricted. See Architecture.
  • A table that syncs needs a declared identity (a PRIMARY KEY or an indexed id column) — the CREATE TABLE is accepted, and a keyless table declared with any sync direction other than SYNC OFF then refuses loudly at its first push rather than silently failing to replicate. See Query Language.
  • Memory and disk are configurable, not unbounded: SET MEMORY_LIMIT and SET DISK_LIMIT (or the process-start bootstrap functions) are how a caller sets a ceiling; there is no hard-coded default cap.
  • A CLI read is bounded, and a bounded read is complete or refused: one SELECT succeeds only within the declared ceilings — 500 rows and 4 MiB by default — and crossing either publishes no rows and refuses with owner_limit_exceeded. Nothing is ever silently truncated, there is no flag that disables the ceiling, and .cursor open / .cursor fetch is how a larger result is paged. The embedded Database::execute library call keeps its uncapped contract. See CLI Reference.
  • All-scope vector search is bounded, not a promise to load every layout at once. The engine fans out under the reader's work, memory, and cancellation limits and either returns one complete global answer or refuses honestly. The edge-device memory target is SET MEMORY_LIMIT 2G (CLI --memory-limit 2G), exactly 2147483648 bytes. Charged vector/index bytes and whole-process RSS, including build/repair/restart lifecycle work, are reported separately. See Architecture and CLI Reference.

Linked from AGENTS.md. This page is generated by hand today; if it drifts from the sections it cites, the cited doc is the source of truth.

Tenant-governed event custody (Unreleased)

Hub policy declaration/binding, transactional manifests, durable outcomes, lost-ack readback, and policy-governed local discard are implemented in the engine. See SQL and API guidance. A unit's complete application rows are compared with BLAKE3, and only a durable authenticated outcome ends pending delivery; a watermark is not a receipt. An old hub image that lost custody revokes old credit automatically when the edge next checks the hub, without erasing edge rows. Multi-table fleet purge and local discard each use one erasure boundary. Listed SYNC OFF predicates select each edge's independently keyed rows; repeat delivery preserves fresh later creations. The outcome journal consumes storage until its owning unit is purged or discarded locally. Logical erasure does not promise forensic secure deletion or removal from operator-held backups; those remain the separate erasure and backup-recovery boundaries.