Skip to main content

Synapse

English | 简体中文

Synapse is a local-first MCP service that gives AI coding agents a structured code knowledge graph, project context retrieval, and persistent project memory. It stores projects, source code, documentation, explicit memories, and their relationships in SQLite, and exposes the same knowledge through MCP, CLI, and a local GUI.

Status

Synapse is usable today as a local-first knowledge service:

  • Local knowledge engine with Python/Markdown parsing, SQLite FTS5, reference resolution, graph-expanded retrieval, and crash-safe indexing.
  • A local stdio MCP Server with 9 project-scoped tools for search, graph exploration, context, and memory.
  • A CLI covering project management, indexing, search, context, and the full memory loop.
  • An optional local GUI for graph exploration, search, memory browsing, context preview, and index status/trigger.
  • Memory APIs with type/query filters, server-side pagination, exact totals, and a 20-row GUI browser.
  • Capability boundaries are aligned: MCP, CLI, and GUI expose only keyword / hybrid retrieval.

Not yet implemented: file watching, embedding/vector retrieval, memory editing/versioning, and cloud sync.

semantic is not true vector semantic retrieval and is not exposed by any entrypoint; there is no embedding model or vector index yet.

Known limitations: synapse_recall returns summaries and snippets, so callers must use synapse_memory_get for full memory content and tags; context ranking is lexical/graph-based rather than semantic; and the knowledge graph does not fully model constructor parameter injection. See Limitations.

Features

  • Python AST parsing (tree-sitter) and structural Markdown parsing.
  • File-level node fallback for other common text formats.
  • SQLite + FTS5 full-text search, including Chinese unigram/bigram indexing.
  • Code reference resolution, cross-file relationships, and graph-expanded retrieval.
  • Query-aware project context that ranks relevant modules, covers distinct paths, and trims optional sections to a token budget.
  • Explicit memory types: fact, experience, decision, preference, and summary.
  • Memory list API with project/type/query filters, limit / offset pagination, and exact filtered totals.
  • GUI Memory browser with 20-row server-side pages, exact range/total display, keyword and type filters, and stale-response protection.
  • Project-level FileLock to prevent concurrent indexing of the same project.
  • After a process crash, interrupted index runs are marked, unfinished tasks are cancelled, and the next scan safely rebuilds.
  • Local stdio MCP Server that reuses the same Core, configuration, and data directory.
  • MCP exposes only keyword / hybrid retrieval by default, rather than presenting unavailable semantic retrieval as implemented.
  • MCP tools enforce project scope and validate node ownership to prevent cross-project reads.
  • Local GUI workspace for graph exploration, search, memory inspection, context preview, and index status/trigger; it talks to the same Core and never opens SQLite directly.

Requirements

  • Python 3.11+
  • uv for uvx and uv tool installation
  • Windows 10/11, Linux, or macOS
  • SQLite with FTS5 enabled (usually available in the SQLite bundled with Python)

Install from PyPI

Run the MCP server without a global install:

uvx --from synapse-knowledge synapse-mcp

uvx downloads the package into an isolated cache and replaces nothing in your project. Projects, configuration, and memories stay in the same SYNAPSE_HOME or platform data directory, so upgrading the package does not delete data.

MCP client configuration:

{
  "mcpServers": {
    "synapse": {
      "command": "uvx",
      "args": ["--from", "synapse-knowledge", "synapse-mcp"]
    }
  }
}

Register and index a project before using project-scoped tools. Install the CLI once with uv:

uv tool install synapse-knowledge
synapse config init
synapse doctor
synapse projects register . --index

If you prefer one-off commands, run the same CLI through uvx:

uvx --from synapse-knowledge synapse projects register . --index

If both CLI and MCP set SYNAPSE_HOME, use the same value in both places. When omitted, both use the same platform default directory.

Quick start from source (Windows PowerShell)

cd C:\path\to\Synapse
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[dev]"

Initialize configuration and check the environment:

synapse config init
synapse doctor

Register and index a project:

synapse projects register . --index
synapse projects status

Search and build context:

synapse search "ContextBuilder" --limit 5
synapse context . --max-tokens 1200
synapse context . --query "retrieval module" --max-tokens 700

Store and recall explicit memories:

synapse remember . "Use SQLite FTS5 for local retrieval." --type decision --title "Use FTS5"
synapse recall "FTS5" --limit 5

Query, indexing, memory, and project-management commands support --json for agents and scripts; version prints plain text only.

Common commands

synapse projects list
synapse projects register <path> [--name NAME] [--index]
synapse projects status [reference]
synapse index [reference] [--full] [--workers N]
synapse search <query> [--project REF] [--limit N] [--mode keyword|hybrid]
synapse related <node_id>
synapse explore <node_id> [--depth N] [--direction outgoing|incoming|both]
synapse remember <project> <content> [--type TYPE] [--title TITLE] [--tag TAG]
synapse recall <query> [--project REF]
synapse memory-get <node_id> [--project REF]
synapse context <project> [--max-tokens N] [--section SECTION] [--query QUERY]
synapse config show
synapse config init
synapse doctor
synapse version

MCP Server

The recommended setup is uvx, which keeps the MCP server isolated and always resolves the published package:

{
  "mcpServers": {
    "synapse": {
      "command": "uvx",
      "args": ["--from", "synapse-knowledge", "synapse-mcp"],
      "env": {
        "SYNAPSE_HOME": "C:\\path\\to\\synapse-home"
      }
    }
  }
}

For a source checkout, use the synapse-mcp entry point or start the server as a module:

synapse-mcp
python -m synapse.integrations.mcp

This is a local stdio MCP Server and does not listen on a port.

Available tools:

  • synapse_projects_list
  • synapse_project_status
  • synapse_search
  • synapse_related
  • synapse_explore_graph
  • synapse_context
  • synapse_remember
  • synapse_recall
  • synapse_memory_get

All project-scoped tools require a registered project. synapse_remember writes to the local SQLite database; the other tools are read-only. Use synapse_recall to find a memory, then synapse_memory_get with its node_id to read the full content and tags. stdout carries only MCP JSON-RPC, while logs go to stderr. See the MCP documentation.

GUI

A local knowledge workspace for developers is included as an optional extra:

python -m pip install -e ".[gui]"
python -m synapse.integrations.gui --port 8765

Open http://127.0.0.1:8765/ and connect with the access token printed by the server, or set SYNAPSE_GUI_TOKEN before starting it. The GUI reads the same <home>/synapse.db as MCP and CLI and never opens SQLite directly.

  • Pages: Overview, Knowledge Graph, Search, Memory, Context, Indexing.
  • Knowledge edits are not implemented yet; the Indexing page can start an index run through the same Core and project-level lock.
  • Requests require a local bearer token and pass Host/Origin checks.

Data location

The default directory is determined by platformdirs:

  • Windows: %LOCALAPPDATA%\Synapse\Synapse\
  • Configuration: <home>\config.toml
  • Database: <home>\synapse.db
  • Lock files: <home>\locks\index-<project_id>.lock

Override these paths with SYNAPSE_HOME and SYNAPSE_CONFIG. See the configuration documentation.

Documentation

The detailed documentation is currently written in Chinese. Start from the documentation index.

Development

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m mypy src

Performance benchmark:

.\.venv\Scripts\python.exe scripts\benchmark.py --project . --runs 3

License

Apache License 2.0. See LICENSE.

Metadata

Release files for synapse-knowledge 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for synapse-knowledge 0.1.0
File Size Uploaded Provenance Actions
synapse_knowledge-0.1.0.tar.gz 377.2 kB Without provenance Details for synapse_knowledge-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for synapse-knowledge 0.1.0
File Interpreter ABI Platform Actions
synapse_knowledge-0.1.0-py3-none-any.whl Python 3 none any Details for synapse_knowledge-0.1.0-py3-none-any.whl

Total release size: 671.6 kB

Release files / synapse_knowledge-0.1.0.tar.gz

Download URL synapse_knowledge-0.1.0.tar.gz
Size 377.2 kB
Tags Source
SHA-256 checksum
How to use checksums
e60354abb18ba163e470aa2cfd24c120dcd618a1db55e813f5261742ce306ec8
BLAKE2b-256 checksum
How to use checksums
b2318b1277a3473b31682ee04b384c5059eff4f6d687b8bebd92ff12e807088b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Release files / synapse_knowledge-0.1.0-py3-none-any.whl

Download URL synapse_knowledge-0.1.0-py3-none-any.whl
Size 294.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e2117ef7b22b4f2b233cd480ee17db3a153fdf1be9e6b6b58d74e64dacd702b7
BLAKE2b-256 checksum
How to use checksums
8facdfc514c5ff1081ea78662ce1f080de117432032f8f03f6f9a3f866c5b4aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Security for synapse-knowledge 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page