Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
Lead team-sharing docs with the one-shared-server mode
anirudhkumar-nanonets66b2ff5e0256
diff --git a/README.md b/README.mdindex c75ba6a9..b3ae18aa 100644--- a/README.md+++ b/README.md@@ -39,6 +39,8 @@ Open the page, point **“Ingest a folder of documents”** at any folder of `.pEverything runs on your machine (the server binds to localhost only). Set `OPENROUTER_API_KEY` to upgrade to LLM-written answers and cloud extraction; without it, retrieval and the graph stay fully local.+Running it for your whole team? One `docker compose up` gives everyone the same graph at one URL — see [Team sharing](#team-sharing).+### Runs locally by default — keys are optionalOut of the box the engine needs **no accounts and no cloud calls**:@@ -115,6 +117,11 @@ context-graph stats# Point at a specific graph filecontext-graph --db ./team-graph.db query "auth"++# Team sharing — git mode (see "Team sharing" below)+context-graph sync # pull teammates' graph.jsonl, re-merge, write it back+context-graph push # write the graph to a committable graph.jsonl+context-graph pull # import + re-merge a teammate's graph.jsonl```---@@ -150,18 +157,77 @@ Tools exposed:| `context_ingest_file` | Ingest files from disk, including **PDFs** (parsed automatically) || `context_ingest_dir` | Ingest a whole **directory** of docs (PDF/MD/TXT), recursively || `context_export` | Write the graph to an interactive **HTML** visualization |+| `context_sync` | Team sharing (git mode): import + re-merge the shared `graph.jsonl`, then write it back || `context_stats` | Report how much the graph currently holds |A natural agent workflow: **read context → do the task → contribute what you learned.**---+## Team sharing++A solo graph is one SQLite file. To share one across a team, pick a mode. All three keep the local-first default intact (team sync is **opt-in**).++### The easy mode — one shared server (recommended)++This is how nearly every self-hosted team tool works (Vaultwarden, Outline, BookStack): one instance, one URL, everyone's browser. No sync to configure, contributions land in the same graph instantly, and there is exactly one copy of the truth.++```bash+docker compose up -d+docker compose logs | grep token # the share link, with access token+```++The graph persists to `./data/graph.db`; drop documents into `./docs` and ingest them from the UI as `/docs`. When exposed beyond localhost the API requires the access token from the logs (pin it with `CONTEXT_GRAPH_WEB_TOKEN`).++No server to put it on? Run it on any machine and share it over [Tailscale](https://tailscale.com) without opening a port to the internet:++```bash+context-graph-web &+tailscale serve localhost:4680 # private HTTPS URL, visible only to your tailnet+```++The two modes below sync **between separate graphs** instead — no shared server at all. Both rely on the graph's **conflict-free merge**: observations are a grow-only counter and free-text fields are last-writer-wins, so re-importing the same facts never double-counts and merge order never changes the result.++### Mode A — Git-native (zero infra)++Commit the graph to your repo as a human-diffable file and let git move it around.++```bash+# You: capture the merged graph and commit it+context-graph sync+git add .context-graph/graph.jsonl && git commit -m "sync context graph" && git push++# A teammate: get the latest and converge their local graph+git pull+context-graph sync+```++`sync` imports the committed `.context-graph/graph.jsonl`, re-merges it into the local graph, and writes the merged result back. It's idempotent (safe to run repeatedly) and commutative (order-independent), so two teammates' additions always converge. The repo's `.gitignore` keeps the local SQLite replica private while tracking `graph.jsonl`. Best for teams already living in git who want no servers and offline-friendly sharing; the only friction is the occasional merge conflict on the file, resolved by re-running `sync`.++### Mode B — Shared store (libSQL / Turso embedded replica)++Point the engine at a shared libSQL primary. Each machine keeps a **local replica** (fast local reads); writes go to the primary, so everyone merges against authoritative shared state in near-real-time — no commit/pull step.++```bash+export CONTEXT_GRAPH_SYNC_URL="libsql://your-db.turso.io" # or http://your-sqld:8080+export CONTEXT_GRAPH_AUTH_TOKEN="…" # token for the primary+export CONTEXT_GRAPH_DB="./.context-graph/graph.db" # local replica file+# optional: CONTEXT_GRAPH_SYNC_INTERVAL=30 (background pull, seconds)+context-graph query "auth" # reads local; writes sync to the primary+```++Works with **Turso Cloud** or a **self-hosted `sqld`**. Best for teams that want live shared memory and are OK running (or renting) one small database; the friction is provisioning that primary and a token once.++> Both modes assume one embedding model per graph (see the note under *How it works*). Imports across mismatched embedding dimensions keep the facts but drop the incompatible vectors, and warn you to re-ingest sources to re-embed.++---+## How the graph gets smarter over timeEvery entity and relationship carries a `confidence` score and an `observations` count.- **Dedup on write.** When new knowledge comes in, each entity is matched against existing nodes by exact name/alias **and** embedding similarity (cosine ≥ `mergeThreshold`). A match is *merged*, not duplicated.-- **Reinforcement.** Each re-observation increments `observations` and nudges `confidence` toward 1.0. Facts seen across many docs/agents rise to the top; one-off mentions stay low-confidence.+- **Reinforcement.** Each observation is recorded under the id of the document/contribution that made it, so `observations` is a grow-only counter and `confidence` is *derived* from it (seen-often facts rise toward 1.0; one-offs stay low). Because the counter merges by taking the max per source, re-importing the same records is a no-op — reinforcement survives team sync without double-counting.- **Provenance.** Every node/edge tracks which documents and agents contributed to it.- **Grounding.** Source passages are kept as retrievable evidence and returned alongside the structured graph.@@ -182,7 +248,7 @@ This is what makes contributions compound: the tenth agent to confirm a fact str└────────────────────────┘```-- **Storage** — SQLite (via `better-sqlite3`) by default; swap in your own `GraphStore`.+- **Storage** — SQLite (via `better-sqlite3`) by default; a libSQL/Turso embedded replica for shared team graphs (set `CONTEXT_GRAPH_SYNC_URL`); or swap in your own `GraphStore`.- **Extraction** — local **Ollama** (`llama3.2` by default) using structured JSON output; automatically upgrades to **OpenRouter** (`openai/gpt-4o-mini` by default, any tool-calling model) if `OPENROUTER_API_KEY` is set.- **Embeddings** — local **in-process** model (`Xenova/all-MiniLM-L6-v2`, 384-dim) by default; automatically upgrades to **OpenAI** (`text-embedding-3-small`) if `OPENAI_API_KEY` is set.- **Retrieval** — semantic match over entities + one-hop graph expansion + supporting source passages.@@ -198,6 +264,10 @@ Everything is configurable via constructor options, environment variables, or de```tsnew ContextGraphEngine({dbPath: "./.context-graph/graph.db", // CONTEXT_GRAPH_DB+ // Team sharing — Mode B (libSQL/Turso embedded replica; opt-in):+ syncUrl: process.env.CONTEXT_GRAPH_SYNC_URL, // libsql://… or http://your-sqld+ authToken: process.env.CONTEXT_GRAPH_AUTH_TOKEN,+ syncIntervalSeconds: undefined, // CONTEXT_GRAPH_SYNC_INTERVAL (background pull)// Cloud (used automatically when set):openrouterApiKey: process.env.OPENROUTER_API_KEY,openrouterModel: "openai/gpt-4o-mini", // CONTEXT_GRAPH_OPENROUTER_MODEL