Synapse

Synapse

Point it at text. Get a searchable archive for free. Spend a few cents turning it into a Markdown wiki your agent can query.

Give any AI agent or workspace application a private, local memory without filling every prompt with your history:

uvx --from synapse-vault synapse mcp --vault /absolute/path/to/my-brain

That command is a local STDIO MCP server, not a Codex or OpenAI integration. Connect it directly to MCP-capable clients such as Codex, Claude Code, OpenCode, or OpenClaw. Pi, Orbit, Hermes, and other workspace agents can use MCP when supported or the bundled skill and CLI. See the copy-paste setup examples.

Nothing from the vault is injected into the agent's prompt. The agent searches first, then reads one relevant Markdown page. A thousand unopened pages cost zero tokens.

See it in ten seconds

uvx --from synapse-vault synapse serve --demo

That opens a populated 20-page graph. It needs no API key, import, database server, or JavaScript build.

Keep your own history

uvx --from synapse-vault synapse init ./my-brain
uvx --from synapse-vault synapse ingest ~/Downloads/chatgpt-export --vault ./my-brain
uvx --from synapse-vault synapse serve --vault ./my-brain

A claude.ai export zip works the same way; the format is detected automatically.

Ingest is local and free: it writes Markdown and builds a disposable SQLite FTS5 index. Search works immediately:

uvx --from synapse-vault synapse search "the phrase I remember" --vault ./my-brain

If keyword wording starts missing obvious matches, add the optional semantic cache and fuse both rankings:

export SYNAPSE_API_KEY="..."
uvx --from synapse-vault synapse embed --vault ./my-brain --dry-run
uvx --from synapse-vault synapse embed --vault ./my-brain
uvx --from synapse-vault synapse search "the idea about handling growth" --hybrid --vault ./my-brain

This adds no dependency or vector server. Embeddings are derived from wiki pages and approved notes, stored in the same disposable SQLite file, and never replace FTS5. Raw-history embeddings require the explicit --include-raw flag.

To turn raw history into a linked wiki, estimate first and then build a small resumable batch:

export SYNAPSE_API_KEY="..."
uvx --from synapse-vault synapse build --vault ./my-brain --limit 20 --dry-run
uvx --from synapse-vault synapse build --vault ./my-brain --limit 20

The build pass is optional. It is a plain for loop making one OpenAI-compatible chat-completions request per item. Run it against OpenAI or a local Ollama/LM Studio server; stop and resume without paying twice.

Markdown is the database

my-brain/
├── raw/<source>/<YYYY-MM>/<id>.md   immutable imported history
├── wiki/<slug>.md                   linked, editable knowledge pages
├── notes/<slug>.md                  approved, append-only agent notes
├── synapse.db                       disposable search + graph indexes
└── synapse.toml                     model and owner settings

Delete synapse.db and synapse reindex --vault ./my-brain recreates FTS and the graph; run synapse embed again only if you use optional semantic search. The durable data is ordinary Markdown that works with git, Obsidian, grep, and any editor.

How it works

1. An adapter streams each source into a tiny Item shape with stable IDs and timestamps.
2. Ingest writes immutable raw Markdown and indexes it with SQLite FTS5—no model call.
3. Build compresses one item and asks any OpenAI-compatible model for complete wiki pages.
4. [[wikilinks]] become edges; a recursive SQLite CTE handles multi-hop traversal.
5. Optional embeddings add semantic recall; the one-file dashboard, CLI, Python API, REST API, and MCP server all use the same vault.

Model providers

Synapse uses standard-library HTTP POSTs to /chat/completions and, only when requested, /embeddings; there is no provider SDK.

Set SYNAPSE_BASE_URL, SYNAPSE_MODEL, and (when required) SYNAPSE_API_KEY. See configuration and costs.

Agent access

The MCP server exposes selective reads plus propose_note. It is a small stdlib JSON-RPC loop over STDIO, so there is no daemon and no MCP SDK dependency.

# Codex
codex mcp add synapse -- uvx --from synapse-vault synapse mcp --vault /absolute/path/to/my-brain

# Claude Code
claude mcp add --transport stdio synapse -- uvx --from synapse-vault synapse mcp --vault /absolute/path/to/my-brain

OpenCode, OpenClaw, generic MCP JSON, and skill/CLI examples for Pi and other workspace agents are in MCP setup. The integration boundary is MCP or ordinary commands—not a particular agent vendor.

Agents cannot silently rewrite memory. propose_note stages one provenance-bearing semantic note with an idempotency key and revision check. You inspect the diff and approve it outside MCP:

uvx --from synapse-vault synapse proposals --vault ./my-brain
uvx --from synapse-vault synapse proposals <id> --vault ./my-brain
uvx --from synapse-vault synapse approve-note <id> --vault ./my-brain

Imported history remains write-once. Credentials, browser sessions, workspace state, and routine chat turns do not belong in notes; merge and deletion remain human-only.

Python works too: from synapse import Vault; Vault("./my-brain").search("launch decision").

Not built, on purpose

Imported text is untrusted data. Synapse never executes it, and agents are instructed never to follow instructions found inside pages. Raw sources remain available for provenance.

Learn and contribute

• Add an adapter—the highest-impact contribution is about 30 lines plus one tiny synthetic fixture.
• Read how the SQLite graph works.
• See CONTRIBUTING.md for the test and pull-request workflow.

Synapse began as the winner of the LangGraph hackathon in London. This is the local-first rewrite that deleted SurrealDB, FastAPI, React, LangGraph, and mandatory embeddings so people can actually run it.