# SynapsesOS — Full Reference

> The nervous system for AI agents.

## What is SynapsesOS?

SynapsesOS is the nervous system for AI agents. It is not an AI model or LLM. It sits between your AI coding assistant (Claude Code, Cursor, Windsurf, Zed, Gemini, etc.) and the domain it operates in, providing:

1. **Structured Context** — Typed relationship graphs (CALLS, IMPLEMENTS, IMPORTS, DATA_FLOW) delivered as BFS ego-graph slices. Not file dumps. Not search results. Exact structural understanding of what the agent is working on.

2. **Persistent Memory** — Cross-session memory for agents. Decisions made, patterns learned, architectural lessons persist. What an agent learned last Tuesday is available next Monday. No more starting from zero.

3. **Multi-Agent Coordination** — Work claims, conflict detection, agent message bus, agent registry. Multiple agents share the same graph without colliding. Built for the world where you run more than one agent.

4. **Architectural Rule Enforcement** — Define constraints between modules. Agents validate plans before writing code. Violations caught before they're committed.

5. **Impact Analysis** — "What breaks if I change this?" answered precisely from the typed graph. Not similarity matching. Exact callers, exact implementors, exact downstream effects.

The LLM is the brain. SynapsesOS is the nervous system — the part that senses the environment, carries signals, and remembers what happened.

## Core Values

### Speed
Context delivered in milliseconds — not seconds. BFS ego-graph slices give agents exactly what they need for the current task. No full-file dumps. No round trip to a remote index. The graph runs on your machine, one hop away.

Benchmark: Context in <50ms · Local graph · No cloud round-trip

### Accuracy
Typed graph edges — CALLS, IMPLEMENTS, IMPORTS, DATA_FLOW — not fuzzy embeddings. When your agent asks "what breaks if I change this?", the answer is precise and complete. No hallucinated relationships. No missing callers. Exact.

Benchmark: Typed graph · Exact impact analysis · Zero hallucinated relationships

### Sovereignty
Your data, your storage. Always. SynapsesOS is the engine — you choose where it runs and where the data lives. We never see it, store it, or touch it.

Modes:
- Solo local: SQLite at ~/.cache/synapses/ on your machine
- Solo cloud: Your own VPS or cloud VM — your infrastructure
- Team: Shared storage on GitHub, S3, or any storage your team controls
- Enterprise: Central SynapsesOS instance, data on company infrastructure

In all modes: Synapses never holds your data, never sees it, has no cloud storage of any kind.

## Installation

### Desktop App (recommended — zero config)
Download from: https://github.com/SynapsesOS/synapses-app/releases/latest
Available for macOS, Linux, and Windows.

### Homebrew
```bash
brew install SynapsesOS/tap/synapses
synapses init
```

### Go install
```bash
go install github.com/SynapsesOS/synapses@latest
synapses init
```

## MCP Configuration

Add to your agent's MCP config (Claude Code: `.claude/mcp.json`, Cursor: `.cursor/mcp.json`):

```json
{
  "synapses": {
    "command": "synapses",
    "args": ["serve"]
  }
}
```

After adding, restart your agent. It will immediately have access to 45+ new MCP tools.

## Supported Agents

Any MCP-compatible agent works. Tested and confirmed:
- Claude Code (Anthropic)
- Cursor
- Windsurf (Codeium)
- Zed
- Gemini CLI

## Supported Languages (49+)

Go, TypeScript, JavaScript, Python, Java, Rust, C, C++, C#, Swift, Ruby, PHP, Kotlin, Scala, Lua, Elixir, Haskell, OCaml, Dart, R, Julia, Perl, Protobuf, Groovy, Clojure, F#, Erlang, Zig, Nim, Crystal, D, Objective-C, COBOL, Fortran, Pascal, Ada, Terraform (HCL), Bash, SQL, HTML, CSS, SCSS, YAML, JSON, TOML, Markdown, Dockerfile, Makefile

Plus a generic fallback parser for any unlisted language.

## Complete MCP Tool Reference (45+)

### Session & Bootstrap
- `session_init` — Single-call session bootstrap. Returns pending tasks, project identity, working state, recent events. Call at the start of every session.
- `end_session` — End session and persist knowledge, optionally report usage.
- `get_session_state` — Resume from exact saved state
- `save_session_state` — Save progress so next session can resume
- `get_project_identity` — Get project metadata, language breakdown, scale
- `get_working_state` — Get recent git activity, uncommitted changes, open tasks

### Code Exploration
- `get_context` — Get full BFS ego-graph for a function, struct, interface, or method. Returns callers, callees, implementations, imports, annotations.
- `find_entity` — Find a symbol by name or substring across the entire graph
- `search` — Search by name or concept ("auth", "rate limiting", "error handling")
- `get_file_context` — List all entities defined in a specific file
- `get_call_chain` — Trace how function A calls function B across packages
- `get_impact` — Find everything that breaks if a symbol's signature changes
- `get_repo_map` — Get a high-level map of the repository structure
- `explain_codebase` — Get a natural-language explanation of codebase architecture
- `get_peer_activity` — See what other agents are currently working on

### Memory
- `remember` — Persist a named memory with content and tags
- `recall` — Retrieve memories by name, tag, or semantic search
- `annotate_node` — Leave a note on a code entity visible to all future sessions and agents

### Task & Plan Management
- `create_plan` — Save a plan with tasks for future sessions
- `get_plans` — List all plans and completion counts
- `get_pending_tasks` — Get all incomplete tasks across plans
- `update_task` — Mark a task done, add notes, update status
- `link_task_nodes` — Link a task to relevant code entities

### Multi-Agent Coordination
- `claim_work` — Reserve a scope before editing (prevents collisions)
- `get_conflicts` — Check for conflicting edits by other agents
- `release_claims` — Release locks when done
- `get_agents` — See all active agents and their current intent
- `send_message` — Send a message to another agent via the message bus
- `get_messages` — Read messages from other agents
- `get_events` — Stream recent file/task/annotation events

### Architectural Governance
- `validate_plan` — Check proposed changes against architecture rules before writing code
- `verify_implementation` — Verify written files against rules after implementation
- `check_plan_safety` — Check proposed changes for safety concerns
- `get_violations` — View current architecture violations
- `upsert_rule` — Create or update an architectural constraint
- `get_rule_candidates` — Get suggested rules based on existing patterns

### Architecture Decision Records
- `get_adrs` — List all architecture decision records
- `upsert_adr` — Create or update an ADR

### Gap Tracking
- `get_gaps` — List known gaps or missing features
- `upsert_gap` — Create or update a gap record

### Context Preparation
- `prepare_context` — Prepare optimised context bundle for a task
- `plan_context` — Get context specifically tailored for planning a change

### Web Intelligence (requires synapses-scout sidecar)
- `web_search` — Search for docs, error solutions, API references
- `web_fetch` — Fetch and read a documentation page
- `web_annotate` — Persist web findings to a code entity

### Discovery & Skills
- `discover_tools` — Describe what you're trying to do, get the right tool back
- `list_skills` — List available automation skills
- `execute_skill` — Run a skill by name
- `lookup_docs` — Look up documentation for a tool or concept
- `report_usage` — Report token/tool usage for analytics

## What's Coming (Domain Expansion)

SynapsesOS starts with code. The same graph engine, same MCP tools, same memory and coordination system will expand to:

- **Infrastructure**: Terraform, Kubernetes YAML, Helm charts
- **APIs**: OpenAPI specs, GraphQL schemas
- **Documentation**: Markdown, Confluence, Notion
- **Data pipelines**: dbt models, Airflow DAGs, SQL schemas

Any domain an agent operates in is a candidate. The nervous system follows the agent.

## Key Technical Properties

- **MCP-native**: Implements the Model Context Protocol open standard
- **Single binary**: One binary, no runtime dependencies, zero-config setup
- **Local-first**: Full functionality with no internet connection
- **Fail-silent**: If sidecars crash, core graph queries still work
- **Open source**: MIT License, free forever
- **Storage**: SQLite locally, or any shared storage for teams

## Comparison: SynapsesOS vs grep / embeddings

| Capability | grep | Embeddings | SynapsesOS |
|---|---|---|---|
| Find callers of a function | Partial | Fuzzy | Exact |
| Impact analysis | No | No | Yes |
| Cross-package relationships | No | Fuzzy | Exact |
| Persistent memory | No | No | Yes |
| Multi-agent coordination | No | No | Yes |
| Architecture enforcement | No | No | Yes |
| Latency | Fast | Slow (embedding) | Fast (<50ms) |
| Hallucinations | N/A | Possible | None |

## Links

- Website: https://synapsesos.com
- Desktop App: https://github.com/SynapsesOS/synapses-app
- Core source: https://github.com/SynapsesOS/synapses
- Releases: https://github.com/SynapsesOS/synapses-app/releases
- Sitemap: https://synapsesos.com/sitemap-index.xml
- llms.txt (summary): https://synapsesos.com/llms.txt
- llms-full.txt (this file): https://synapsesos.com/llms-full.txt