Introduction

Get Synapse running in under 60 seconds and understand how it works.

Synapse is a local, Git-aware structural context engine for AI coding agents. Instead of dumping entire files into an LLM's context window, it serves your agent exactly the right symbols, call graphs, and architectural memory — in under 9.2ms.

Why Synapse?

Most AI coding agents struggle with large codebases because they either:

  • Dump entire files into the context window (token-expensive, slow, noisy)
  • Use vector RAG that matches semantically but misses exact call relationships
  • Have no memory between sessions — agents repeat the same mistakes

Synapse solves all three with a 3-layer local context infrastructure stored in a single .synap/synap.db SQLite file.

Quickstart — 3 Commands

Step 1: Install

pip install synap-git

Or with uv (recommended):

uv tool install synap-git

Step 2: Initialize your repository

Run this inside any Git repository:

synap init .

This builds the local SQLite AST graph across all source files using Tree-sitter. No network calls are made.

Step 3: Connect your IDE agent

Start the FastMCP stdio server and mount it in your IDE:

synap start .

Then get the exact config snippet for your tool:

synap mcp config .

The 3-Layer Context Model

Synapse organizes all context into three distinct layers:

| Layer | Name | What it stores | |---|---|---| | L1 | Structural Code Graph | AST symbols, caller/callee edges, Git OIDs — in SQLite WAL | | L2 | Semantic Wiki | Markdown summaries of files and modules under .synap/wiki/ | | L3 | Behavioral Memory | Checkpoints, architectural decisions, and auto-extracted revert lessons |

Supported IDEs & Agents

Synapse connects to any MCP-compatible agent over stdio:

  • Cursor — .cursor/mcp.json
  • Claude Code — claude mcp add synapse synap -- mcp start .
  • Windsurf — mcp_config.json
  • Roo Code / Cline — MCP settings JSON
  • Any custom agent — synap mcp start .

Next Steps

Synapse Engine — v2.4.0
GitHubPyPI← Home