🧠 Synapse — a context vault for the LLM age

One private knowledge graph you point any AI tool at — so you never re-explain yourself. Markdown for knowledge, SQLite for records, one ontology, and an agent that keeps it healthy. Runs entirely on hardware you control.

The problem it solves

We live in an LLM world, and every tool starts from zero. You paste the same context into ChatGPT, then again into Claude, then again next week — your knowledge scattered across chat logs, notes apps, and your own memory. The models are powerful; the context is the bottleneck.

Synapse is the fix: a single, typed knowledge graph that lives on your machine and that any AI tool can read from and write to through a reviewable gate. Capture once, link it, and every future question — in any CLI — starts with the full picture. Your second brain, version-controlled and yours.

What it is, concretely:

• Markdown-in-Git is canonical for knowledge (notes, journal, plans, projects, people).
• Local SQLite is canonical for records (contacts, accounts, finances, health, places) — queried read-only.
• One ontology joins them; generated projections keep both sides in sync without duplication.
• An agent keeps it healthy — detecting drift and proposing every change as a diff a human merges.
• LLM- and data-agnostic. Nothing is tied to one model vendor or one person's data. The reference runtime is OpenCode on a local Ollama model over Tailscale — no API key, no cloud, no subscription in the core loop.

Contents

Quick start · Your first commands · Ask the vault + semantic recall · Pluggable runtime (--cli) · A day in the life · How it works · Get started (template) · npm package · More

🚀 Quick start

cd /path/to/your-vault
npm install @eborja/synapse@^0.1.7   # or: npm install ../path/to/synapse-framework
npx synapse install                        # dry-run
npx synapse install --write                # wire agents.sh + editor dirs
exec $SHELL
synapse agents                             # ← list agents (or: vault-agents)
synapse hubs                               # ← list hub targets (or: vault-hubs)

The engine is the @eborja/synapse npm package (bin/synapse, lib/*, agents.sh). Your vault keeps only content + _meta/tools/context.manifest.json. After install, synapse <sub> is the unified front door (engine + shell).

⚡ Your first commands

Type an agent's name, point it at a target, optionally describe a task. The agent launches with the full briefing (mission + rules + skills + the target's neighborhood) compiled deterministically — no copy-paste:

curator                                          # run the steward — detect drift across the vault
curator hub-finances                             # scope it to one domain hub
oracle hub-finances "did I note anything about budgeting?"   # ask the vault — read-only, cited
reconciler hub-contacts                          # fix one drifted domain's notes/views
ingester inbox/2026-06-15.md                     # atomize a freeform capture into typed notes + rows

Syntax: <agent> [<target>] [--profile lean|standard|fat] ["task"]. A hub-* target auto-upgrades a lean agent to standard. → Full command reference, env vars & flags: doc-cli-reference.

🔮 Ask the vault + semantic recall

The oracle answers questions grounded in your vault — read-only, every claim cited back to the note that owns it, never a fabrication:

oracle hub-finances "what did I decide about the emergency fund?"

What makes the answer good is semantic recall — an opt-in second retrieval phase. The render engine is deterministic: it follows typed links, so it only reaches what you explicitly connected. Semantic recall adds the missing half — embedding-based search that finds conceptually-related notes across the whole vault, regardless of links or wording, and appends them under a clearly-labeled ## Semantically related (not yet linked) section. This is classic hybrid retrieval (graph + vector).

Turn it on (all local, no new deps):

ollama pull mxbai-embed-large          # one-time, on the Ollama host that serves your model
synapse embeddings    # build db/synapse.db's note_vectors index (the maintainer keeps it fresh)

Embeddings come from the same local Ollama that runs the agents — no API key, no cloud. Results are additive, labeled, and non-authoritative: a similarity hit never silently drives a change, and when a hit is genuinely relevant the agent promotes it to a typed related: link — so semantic discovery feeds the deterministic graph, and the vault grows more precise the more you use it.

→ Full detail: doc-semantic-recall · rule-semantic-suggests-links-decide · tool-ollama-embeddings.

🔌 Pluggable runtime (--cli)

OpenCode is the default runtime, not the only one. The same rendered briefing can be handed to a swappable sink with --cli — so you can drive Synapse with whatever tool you like:

curator hub-finances "rebuild summaries"                  # → OpenCode (default, local Ollama)
curator hub-finances "rebuild summaries" --cli claude     # → Claude Code, scoped to the repo dir
oracle hub-health "trend since April?"   --cli clip       # → copy the briefing to the clipboard
reconciler hub-contacts                  --cli print      # → write the briefing to stdout, pipe anywhere

The render + semantic pipeline is identical for every sink — only the final hand-off differs. That's the whole trick: maintain the public framework with a powerful cloud CLI while a private vault stays on local OpenCode, using the same commands. Set a default with export SYNAPSE_CLI=…; pick your model with export SYNAPSE_MODEL=ollama/<your-model>.

→ Full detail: doc-runtime-wiring · all sinks, env vars & TUI behavior in doc-cli-reference.

🔁 A day in the life

Follow one thought through the whole system:

# 1. CAPTURE — dump a freeform thought into inbox/ (zero friction: no schema, no decision).
echo "called the plumber, \$180, fixed the leak" >> inbox/2026-06-15.md

# 2. INGEST — atomize it into typed notes + proposed migration rows (records ride a migration file).
ingester inbox/2026-06-15.md          # opens a PR you review; on merge, migrations apply + views regenerate

# 3. ASK — later, query the vault; semantic recall surfaces notes you never explicitly linked.
oracle hub-finances "how much have I spent on home repairs?"

# 4. MAINTAIN — the steward keeps the graph schema-clean and the views current.
curator hub-finances "summaries look stale"     # detect → heal the unambiguous → escalate the rest → PR
synapse lint --strict              # confirm the vault is schema-clean

That's the loop: capture freely → the agent structures it → ask anything → an agent keeps it healthy — every write a reviewable diff, nothing applied unattended.

🧠 How it works (in brief)

Every command renders a briefing by combining three things, then hands it to your chosen runtime. The render is deterministic: same inputs → byte-identical briefing, so agent runs are reproducible.

| You pick… | = | What it is | Examples | |---|:--:|---|---| | ① an Agent | the method (what job) | mission + rules + skills + tools | curator · reconciler · ingester · oracle | | ② a Target | the what (which domain/unit) | the knowledge to act on | hub-finances · a note id | | ③ a Profile | the dial (how much context) | lean (~4K) · standard (~15K) · fat (~30K) | which relationship roles to pull |

The four agents — three writers + one reader. Maker ≠ checker: the agent that writes an edit never approves it. Click a name to open and tune its file.

| Agent | Job | |---|---| | 🧹 agent-curator | steward — detect drift, heal the unambiguous, dispatch + verify, open one human-gated PR | | 🔧 agent-reconciler | scoped doer — reconcile ONE drifted unit against its source (no PR, no DB write) | | 📥 agent-ingester | capture — atomize one inbox/ dump into typed notes + proposed migration rows | | 🔮 agent-oracle | reader — grounded, cited Q&A over a domain's closure + semantic recall (never writes) |

The graph is hub-and-spoke. One master hub links out to seven domain hubs; members roll up automatically (a note's related: ["[[hub-x]]"] makes it a member of hub-x — the hub is never edited by hand).

                          [[hub-synapse]]   ← master hub: architecture · domains · method
                               │
   ┌──────────┬───────────┬────┼────┬───────────┬────────────┬──────────────┐
hub-finances hub-contacts hub-health hub-places hub-journal hub-projects hub-social-media

Two substrates, one gate. Markdown is canonical for knowledge, SQLite for records; where they meet, one side is canonical and the other is a generated, never-hand-edited projection. Records never mutate unattended — every DB change rides a migration file through a human gate. Governance is per-repo: the framework is fully PR-gated, vault Markdown self-heals, and the records DB is gated everywhere.

→ Deeper: the in-vault map hub-synapse · doc-agent-architecture · doc-storage-model · doc-governance-model · context-engine-guide.

🌱 Get started

Synapse ships two layers:

1. @eborja/synapse — the publishable tooling package (bin/, lib/, agents.sh, schema/).
2. Reference vault content in this repo — agents, rules, docs, starter hubs, migrations/0001-*.sql (not in the npm tarball; kept so you can copy a private vault).

Option A — new private vault (recommended)

mkdir my-vault && cd my-vault
npm init -y
npm install @eborja/synapse@^0.1.7
# copy schema example → your ontology dial
mkdir -p _meta/tools
cp node_modules/@eborja/synapse/schema/context.manifest.example.json \
   _meta/tools/context.manifest.json
# copy starter agents/rules/hubs from the template repo if you want them, or author your own
npx synapse setup --write      # Ollama + embed model (optional)
npx synapse install --write    # shell CLI + editor wiring
npx synapse migrate            # create db/synapse.db from migrations/
exec $SHELL
synapse agents && synapse hubs

Option B — use this repo as a template

1. Click "Use this template" (or clone), keep it private, and treat it as your vault.
2. Prerequisites: Node 22+ (.nvmrc pins 22), OpenCode (or Claude/Cursor via --cli), Ollama.
3. From the vault root: npm install (links @eborja/synapse if present) → npx synapse install --write → npx synapse migrate → exec $SHELL.
4. Set export VAULT_USER="Your Name", fill migrations/0002-owner.sql from the example, migrate again.
5. Capture into inbox/, then ingester ….

Updating the engine later is an npm bump, not a git merge of tooling files. See doc-fork-and-extend.

📦 npm package — tooling only

Distribute and update the engine without forking vault content:

{
  "dependencies": {
    "@eborja/synapse": "^0.1.7"
  },
  "scripts": {
    "vault:render": "synapse render",
    "vault:lint": "synapse lint",
    "vault:migrate": "synapse migrate",
    "vault:install": "synapse install"
  }
}

npm install
npx synapse setup --write     # Ollama + embed model (optional; deterministic tools work without it)
npx synapse install --write   # shell + editor wiring

Alternate installs (dev / pin a git SHA): npm install github:eborjaa/synapse#v0.1.7 or file:../synapse-framework.

The consumer keeps context.manifest.json under _meta/tools/ (flat) or context-vault/_meta/tools/ (nested). Copy schema/context.manifest.example.json. Vault resolution: $SYNAPSE_VAULT → ancestor walk from $PWD. See CHANGELOG.md and doc-fork-and-extend.

| Command | Does | |---|---| | synapse render <id> … | Typed-ontology briefing | | synapse augment … --task | render + semantic recall | | synapse lint [--strict] | Vault health-check | | synapse embeddings | Rebuild note_vectors | | synapse index / views / migrate | SQL projections + migrations | | synapse setup / install | Runtime + shell wiring | | synapse agents / hubs / help | Shell discovery (after install --write; vault-* equals) |

📚 More

• Full command reference (every command, env var, flag, runtime sink) → doc-cli-reference
• Browse the graph in Obsidian (color-coded by type) → doc-repo-layout
• The privacy gate (framework readable, vault sealed; vault-gate on|off) → doc-deployment-gate
• Staying healthy (lint, pre-commit hook, the nightly curator loop) → doc-maintainer-loop · loop-maintain-synapse
• Engine package (@eborja/synapse vs your private vault; npm bump to update tooling) → doc-fork-and-extend
• Extending (new note / rule / agent / domain / migration) → _meta/conventions.md · CONTRIBUTING.md
• The vision & full architecture → doc-vision · hub-synapse

🙏 Acknowledgments

Special thanks to @JavierCorado — for teaching me and inspiring me to develop this. Synapse builds on Andrej Karpathy's "LLM Wiki" gist (the seed idea), OpenCode, Ollama, Obsidian, Node's built-in SQLite, Reciprocal Rank Fusion (sqlite-vec as the scale-up path), and MemPalace. Full credits → CREDITS.md.

License

MIT © 2026 Emmanuel Borja. Use the pattern with any model and any data.