Local knowledge for AI coding agents.
Code graph, project context and persistent memory — all on your machine.
Install · Features · MCP · CLI · GUI · Docs
English · 简体中文
Local-first, open source, and yours to run. One SQLite workspace shared by MCP, CLI and GUI. No cloud account required.
Highlights
- Local-first SQLite knowledge graph with Python/Markdown parsing, FTS5 search, Chinese indexing, reference resolution, graph-expanded retrieval, and crash-safe indexing.
- Local stdio MCP server with 9 project-scoped tools for search, graph exploration, context, and memory.
- CLI for project management, indexing, search, context, and the full memory workflow.
- Optional local GUI for graph exploration, search, memory browsing, context preview, and index management.
keywordandhybridretrieval only; no fake semantic mode.- Project-level locking prevents concurrent indexing of the same project; interrupted runs recover on the next scan.
Not yet implemented: file watching, embedding/vector retrieval, memory editing/versioning, and cloud sync.
Known limitations: synapse_recall returns summaries and snippets, so use synapse_memory_get for full memory content and tags; context ranking is lexical/graph-based; and constructor parameter injection is not fully modeled. See Limitations.
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
Use uvx to run the MCP server without a global install:
uvx --from synapse-knowledge synapse-mcp
For MCP clients, use this configuration:
{
"mcpServers": {
"synapse": {
"command": "uvx",
"args": ["--from", "synapse-knowledge", "synapse-mcp"]
}
}
}
Install the CLI once, then register and index a project:
uv tool install synapse-knowledge
synapse config init
synapse doctor
synapse projects register . --index
uvx uses an isolated cache and does not modify your project. Projects, configuration, and memories stay under SYNAPSE_HOME or the platform default directory, so package upgrades do not delete data.
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]"
synapse config init
synapse projects register . --index
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 configuration is shown in Install from PyPI. Add env.SYNAPSE_HOME only when you need a custom data directory.
For a source checkout, use synapse-mcp or python -m synapse.integrations.mcp. This is a local stdio 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.1
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.1.tar.gz | 378.4 kB | Without provenance | Details for synapse_knowledge-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| synapse_knowledge-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for synapse_knowledge-0.1.1-py3-none-any.whl |
Total release size: 672.3 kB
Release files / synapse_knowledge-0.1.1.tar.gz
| Download URL | synapse_knowledge-0.1.1.tar.gz |
|---|---|
| Size | 378.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fa02238f2f1a5e7c3d6533ec3f7d1428654de37e85a4d64e414f19d9dda1a525
|
|
BLAKE2b-256 checksum How to use checksums |
feeb1049045b48e5ee3eec8d691fa6f63d2bb174f853d53174284be10a62703f
|
| 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.1-py3-none-any.whl
| Download URL | synapse_knowledge-0.1.1-py3-none-any.whl |
|---|---|
| Size | 293.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
08c79e708cd04032d1031a4c2fc0a4ef00296b73f13f19554c5db16f9a09149c
|
|
BLAKE2b-256 checksum How to use checksums |
189d801d552ca175ca14279d32db2ef8f68d2766810615953e531455c2849607
|
| 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.1
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.