@contextq/edge

@contextq/edge

T379: an offline-first ContextQ replica. Postgres -> SQLite, pgvector -> sqlite-vec, Elasticsearch -> FTS5. Boots from a Memory Interchange Format (MIF v1.0) export and serves hybrid search fully offline; optionally syncs back to a parent ContextQ instance via the existing MIF export/import HTTP endpoints, reconciling concurrent edits with a hybrid-logical-clock CRDT.

Standalone package (own package.json/tsconfig.json, same convention as ../mcp/): no import path back into the main server's src/. The MIF wire format is deliberately designed to be reimplemented by a third party (../docs/interchange/mif-spec.md), and this package is that third party -- a handful of files under src/mif/ are therefore vendored ports of the main package's src/utils/tar.ts / mif-canonical.ts / interchange-keys.service.ts, not shared imports.

Status

• Phase (a) -- read-only offline replica: shipped. contextq-edge boot <bundle.tar.gz> verifies the bundle's Ed25519 signature + every blob's SHA-256, materializes it into local SQLite, and serves hybrid (FTS5 + optional sqlite-vec ANN) search with zero network calls.
• Phase (b) -- offline writes + sync: working prototype. Local writes are HLC-stamped and appended to an append-only commit log (local_write_log); ctx_sync push/pull reconciles against a parent over the existing POST /api/interchange/export/.../import endpoints (no server change required). Proven against a real running instance -- see scripts/live-sync-proof.ts.
• Phase (c) -- CRDT conflict resolution: working prototype. LWW-register per scalar field (src/crdt.ts's lwwMerge), OR-Set for tags (src/crdt.ts's OrSet). Full design, what's genuinely wired vs. prototype-only, and three interop gotchas discovered while proving the live round-trip: docs/edge-crdt-sync-design.md.

Install

cd edge
npm install
npx tsc --noEmit   # typecheck
npm test           # 14 unit tests, no network/DB required

CLI

# Phase (a): boot offline from a MIF export, optionally serve search over HTTP
contextq-edge boot ./mif-export-acme.tar.gz --db ./edge.sqlite
contextq-edge boot ./mif-export-acme.tar.gz --db ./edge.sqlite --serve --port 47321

# Serve an empty (or existing) local store with no bundle
contextq-edge serve --state-dir ./edge-state --port 47321

# Search the local replica (works even with the network off)
contextq-edge search "deployment runbook" --db ./edge.sqlite --workspace acme --limit 5

# Phase (b): author a context entirely offline
contextq-edge create --db ./edge.sqlite --workspace acme --type reference \
  --name "Offline note" --content "written on a plane"

# Phase (b): reconcile with a parent instance
contextq-edge sync pull --db ./edge.sqlite --parent-url http://localhost:38200 \
  --api-key sk_live_... --workspace acme
contextq-edge sync push --db ./edge.sqlite --parent-url http://localhost:38200 \
  --api-key sk_live_...

HTTP server (serve, boot --serve)

Listens on 127.0.0.1 only (default port 47321). The state directory (default ~/Library/Application Support/contextq/local/ on macOS, ${XDG_DATA_HOME:-~/.local/share}/contextq/local/ on Linux) holds edge.sqlite, its signing key, token (mode 600) and endpoint.json (URL and pid while running). Every route except GET /health needs Authorization: Bearer <token>; a foreign Host or a non-loopback Origin is refused. Contract: docs/arch/edge-local-only-contract.md.

GET /health (capability handshake, no token), POST /search, POST /contexts, GET /contexts, GET /contexts/:ref, GET /workspaces, PATCH /contexts/:ref, POST /contexts/:ref/tags, DELETE /contexts/:ref/tags/:tag, POST /sync/pull, POST /sync/push. Any cloud /api/* path answers needs_account.

Local mode

serve is the runtime behind ContextQ local mode (no account): contextq init --local from @contextq/cli provisions this package, runs serve, and points the Claude Code plugin at its /mcp, which advertises only ctx_save, ctx_search, ctx_get, ctx_list and agent_boot (boot-lite). contextq attach later pushes every dirty note to an account through POST /sync/push, which clears a note only for the refs the server acknowledges. Search is FTS5 keyword search unless a query vector is supplied over REST.

Live sync proof

scripts/live-sync-proof.ts is an ops script (like the main package's scripts/backfill.ts), not part of npm test -- it needs a real running ContextQ instance:

PARENT_URL=http://localhost:38200 \
PARENT_API_KEY=sk_live_... \
PARENT_WORKSPACE=acme \
npx tsx scripts/live-sync-proof.ts

It pulls a real export, creates a context entirely offline, pushes it, independently re-exports from the parent to confirm the create landed, edits that same context offline, pushes again, and independently re-exports again to confirm the edit landed in place (not as a duplicate row) -- every step is verified by re-fetching from the parent, not by trusting an HTTP 200.

Known limitations

See docs/edge-crdt-sync-design.md section 3 (scope) and section 5 (discovered interop gotchas) for the full, honest list -- in short: tag/link sync against the parent is snapshot-granularity (not field-level) because the parent's MIF export doesn't carry edge's op log; links and chunks are pull-only; and editing a pre-existing native parent context in place requires that context to already carry a persisted external_id (one edge itself created, or one sourced from a connector/prior MIF import) -- MIF v1.0's idempotency key is not retroactively assignable to an arbitrary native row from the edge side.

Releasing

Whoever publishes runs bash scripts/check-npm-pack.sh edge from the repo root and publishes the tarball= file it prints, never a bare npm publish in this directory: the check refuses sourcemaps, TypeScript source and tests in the real tarball (T922).