Synapse

Synapse turns scattered history into a linked local knowledge graph

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

PyPI Python 3.11+ zero runtime dependencies MIT

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

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

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
├── synapse.db                       disposable FTS5 + graph index
└── synapse.toml                     model and owner settings

Delete synapse.db and synapse reindex --vault ./my-brain recreates it. The durable data is ordinary Markdown that works with git, Obsidian, grep, and any editor.

How it works

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

Model providers

Synapse uses one standard-library HTTP POST to /chat/completions; there is no provider SDK.

Provider	Base URL	Status
OpenAI	`https://api.openai.com/v1`	Tested with `gpt-4o-mini`
Ollama	`http://localhost:11434/v1`	Compatible; not yet in CI
LM Studio	`http://localhost:1234/v1`	Compatible; not yet in CI
OpenRouter	`https://openrouter.ai/api/v1`	Compatible; community verification wanted
Groq	`https://api.groq.com/openai/v1`	Compatible; community verification wanted
Together	`https://api.together.xyz/v1`	Compatible; community verification wanted
DeepSeek	`https://api.deepseek.com/v1`	Compatible; community verification wanted

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

Agent access

The MCP server exposes search, read_page, list_pages, neighbors, and read_source. 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.

Python works too:

from synapse import Vault

matches = Vault("./my-brain").search("launch decision")

Not built, on purpose

Not built	Why
Embeddings	FTS5 is free, inspectable, and needs no migration or per-item API call. Add vectors only after measured recall failures.
Graph database	Personal graphs fit in SQLite; a ten-line recursive CTE handles traversal.
Auth or cloud sync	Synapse is single-user and binds only to `127.0.0.1`. Your files stay yours.
Agent framework	The processing pipeline is a resumable loop, not an application graph.
Automatic merge/delete	A model never silently destroys a human-editable page.
PDF/DOCX parser	Those dependencies would break the zero-dependency promise; convert with Pandoc or MarkItDown first.

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 embeddings so people can actually run it.

synapse