SynapsesOS
Getting Started

Introduction

Synapses is a local-first, graph-based context manager for AI coding agents. It runs as an MCP server on your machine, parsing your codebase into a relational graph and serving precise, relevant context to any compatible AI agent — Claude Code, Cursor, Windsurf, Zed, and more.

The Problem

AI coding agents are powerful, but they share a set of fundamental limitations:

  • Context loss. Every session starts from scratch. The agent has no memory of what it worked on yesterday, what decisions were made, or what patterns exist in your codebase.
  • No coordination. When multiple agents (or multiple sessions of the same agent) work on a project, they have no shared understanding. One agent refactors a module while another builds on the old API.
  • Shallow understanding. Agents rely on file-level grep and glob searches. They see text, not structure. They don’t know that UserService.Create calls Repository.Insert which triggers EventBus.Publish — unless they happen to read all three files.
  • Token waste. Without structural awareness, agents dump entire files into context windows hoping the relevant parts are somewhere in there. This burns tokens and degrades response quality.

How Synapses Solves This

Synapses sits between your codebase and your AI agents. It builds a persistent, queryable graph of your code’s structure — functions, methods, types, interfaces, packages, and the relationships between them (calls, implements, imports, embeds, data flows). When an agent needs context, Synapses carves out precisely the relevant subgraph and delivers it.

Key Features

  • Code Graph with 49+ Language Parsers. AST-based parsing across Go, TypeScript, Python, Rust, Java, C#, Ruby, Swift, Kotlin, and dozens more. Every function, type, and relationship is indexed.
  • BFS Context Carving. Starting from any node, Synapses walks the graph outward using breadth-first search with configurable decay and token budgets. You get exactly the context you need — no more, no less.
  • Intent-Aware Retrieval. Tell Synapses whether you’re modifying, debugging, reviewing, or planning, and it adjusts which edges and relationships to prioritize.
  • Persistent SQLite Index. Your code graph survives across sessions. Incremental updates via a live file watcher mean the index stays current as you code.
  • Agent Task Memory. Create plans, track tasks, and pick up where you left off. Session continuity that persists across agent restarts.
  • 4-Tier Brain System. Optional LLM enrichment via Ollama — from automatic summarization (Tier 0) to architectural coordination (Tier 3).
  • Architectural Rules Enforcement. Define dependency constraints, naming conventions, and structural rules. Synapses surfaces violations before agents introduce them.
  • Federation and Monorepo Support. Manage multiple projects as a unified graph, with cross-project context when you need it.
  • 12 MCP Tools. A comprehensive tool surface for agents to query, navigate, and understand your codebase.

What Makes Synapses Different

Local-first. Your code never leaves your machine. Synapses runs entirely locally — no cloud services, no API calls (unless you opt into brain enrichment via a local Ollama instance).

Graph-based, not text-based. Most code intelligence tools are glorified search engines. Synapses understands structure. It knows that changing a function signature affects its callers, that an interface implementation must satisfy its contract, that a package’s public API is its boundary.

Agent-agnostic. Synapses speaks MCP (Model Context Protocol) over stdio. Any MCP-compatible agent can connect. You’re not locked into one editor or one AI provider.

Scale-aware. Synapses adapts its behavior based on your project’s size — from micro projects under 100 nodes to large codebases with thousands of functions and edges. Context delivery, tool recommendations, and indexing strategies all scale accordingly.

Who Is Synapses For

  • Solo developers who want their AI agent to truly understand their codebase, not just grep through it.
  • Teams where multiple developers (and their agents) need a shared understanding of code structure.
  • Anyone working on medium-to-large codebases where the AI agent’s context window isn’t big enough to hold everything, and intelligent selection matters.

Next Steps

Ready to get started? Head to Installation to set up Synapses on your machine.