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/hybridretrieval.
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, andsummary. - Memory list API with project/type/query filters,
limit/offsetpagination, 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/hybridretrieval 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
uvxanduv toolinstallation - 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_listsynapse_project_statussynapse_searchsynapse_relatedsynapse_explore_graphsynapse_contextsynapse_remembersynapse_recallsynapse_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.
- Getting started
- Configuration
- Development and testing
- Architecture
- CLI
- MCP Server
- Data model
- Limitations
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.