Metadata-Version: 2.5
Name: synapse-knowledge
Version: 0.1.0
Summary: Local-first MCP service for code knowledge graphs, project context and persistent project memory
Project-URL: Homepage, https://github.com/kinguang3/Synapse
Project-URL: Repository, https://github.com/kinguang3/Synapse
Project-URL: Documentation, https://github.com/kinguang3/Synapse/tree/main/docs
Project-URL: Issues, https://github.com/kinguang3/Synapse/issues
Author-email: King <548635581@qq.com>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,code-search,coding-agents,knowledge-graph,mcp,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.11
Requires-Dist: filelock>=3.13
Requires-Dist: markdown-it-py<5,>=3
Requires-Dist: mcp<2.4,>=2.3
Requires-Dist: mdit-py-plugins<0.6,>=0.4
Requires-Dist: pathspec>=0.12
Requires-Dist: platformdirs>=4
Requires-Dist: pydantic-settings<3,>=2.2
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: rich>=13
Requires-Dist: tree-sitter-python<0.26,>=0.25
Requires-Dist: tree-sitter<0.26,>=0.25
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: httpx<1,>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: gui
Requires-Dist: fastapi<1,>=0.115; extra == 'gui'
Requires-Dist: uvicorn<1,>=0.30; extra == 'gui'
Description-Content-Type: text/markdown

# Synapse

English | [简体中文](https://github.com/kinguang3/Synapse/blob/main/README.zh-CN.md)

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](https://github.com/kinguang3/Synapse/blob/main/docs/reference/limitations.md).

## 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](https://docs.astral.sh/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:

```powershell
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:

```json
{
  "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`:

```powershell
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`:

```powershell
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)

```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:

```powershell
synapse config init
synapse doctor
```

Register and index a project:

```powershell
synapse projects register . --index
synapse projects status
```

Search and build context:

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

Store and recall explicit memories:

```powershell
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

```text
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:

```json
{
  "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:

```powershell
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](https://github.com/kinguang3/Synapse/blob/main/docs/reference/mcp.md).

## GUI

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

```powershell
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](https://github.com/kinguang3/Synapse/blob/main/docs/guides/configuration.md).

## Documentation

The detailed documentation is currently written in Chinese. Start from the [documentation index](https://github.com/kinguang3/Synapse/blob/main/docs/README.md).

- [Getting started](https://github.com/kinguang3/Synapse/blob/main/docs/guides/getting-started.md)
- [Configuration](https://github.com/kinguang3/Synapse/blob/main/docs/guides/configuration.md)
- [Development and testing](https://github.com/kinguang3/Synapse/blob/main/docs/guides/development.md)
- [Architecture](https://github.com/kinguang3/Synapse/blob/main/docs/architecture/overview.md)
- [CLI](https://github.com/kinguang3/Synapse/blob/main/docs/reference/cli.md)
- [MCP Server](https://github.com/kinguang3/Synapse/blob/main/docs/reference/mcp.md)
- [Data model](https://github.com/kinguang3/Synapse/blob/main/docs/reference/data-model.md)
- [Limitations](https://github.com/kinguang3/Synapse/blob/main/docs/reference/limitations.md)

## Development

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

Performance benchmark:

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

## License

Apache License 2.0. See [LICENSE](LICENSE).
