Operational memory for agents, with governed changes, preserved history, and explicit integrity checks.
Keep decisions, API knowledge and runbooks useful beyond the conversation that created them.
Get started · Workflow · Evidence · Architecture · Documentation
Source and release scope: the diagrams and capability descriptions below refer to this source tree. Distributed binaries can lag behind it. Check
syn --version, the release notes and the relevant contract before depending on a newer command or integration.
What Synapse is
Synapse is a local operational knowledge layer for developers and AI agents. Store project context as Markdown, retrieve it through CLI or MCP, and review changes through governed proposal paths. Your Git workflow and existing authoring tools remain useful.
The distinction is continuity with evidence: a decision should survive the task, keep its source context and expose what was checked before another agent relies on it. Synapse complements Notion, Obsidian, documentation repositories and retrieval engines such as QMD, Mem0 and Zep. It can run alone or supply knowledge to a host such as Soma.
| Responsibility | What Synapse provides |
|---|---|
| Preserve useful context | Typed Markdown records for projects, APIs, people, decisions, tasks and runbooks |
| Govern changes | Proposals, policy checks, explicit review and supported reversal |
| Inspect evidence | Recorded provenance, retained history and scoped verification reports |
| Retrieve for the next task | Local search, source citations and bounded process/MCP responses |
Why it matters
An agent result becomes useful memory through a reviewable change. The local knowledge process contract always queues its proposals; an operator reviews the exact payload before acceptance. Other write paths follow their configured policy, including documented safe application rules.
Each step has a separate responsibility. Review assesses a proposed change. The transaction preserves its recorded decision. Verification checks named properties over the selected records. None of these alone establishes the truth of every sentence or the absence of every natural-language contradiction.
| Evidence | What to inspect | Boundary |
|---|---|---|
| Recorded changes | syn blame, syn diff, syn audit verify | Attribution text alone is not authenticated team identity |
| Storage projection | syn verify | A skipped check means missing prerequisites, not a pass |
| Governed source suffix | syn state verify and selected assurance profile | Explicit baseline, retention, trust and witness inputs determine coverage |
| Historical state | syn at <ref>, syn audit replay | Replay determinism and complete source reconstruction are distinct checks |
| Structured contradictions | Scoped diagnostics and deep verification | Exact supported fields, intervals and references; general prose remains unknown |
Optional model assessments stay advisory. The current grouped EN/PT experiment did not meet its conflict-recall gate, so no classifier is enabled by default. See the measured results and limitations.
Get started
Install from the public distribution repository. Review release verification for checksums, signatures and the expected publisher before running a downloaded executable.
curl -fsSL https://raw.githubusercontent.com/romulofebasi/synapse-releases/main/install.sh | sh
# Alternatively, with Node 18+:
npx @febasi/synapse init ~/brain
npm install -g @febasi/synapse
Create a workspace, record a project and connect an MCP-compatible assistant:
syn init ~/brain
cd ~/brain
syn project add "Payments Platform"
syn person add "Maria Silva" --email maria@company.com --job-title "Tech Lead"
syn person link maria-silva --project payments-platform --role focal
syn api add "Payments API" --auth oauth2 --owner maria-silva
syn search payments
syn mcp install
syn verify
The first interactive syn init offers an optional semantic-model download, about 2.5 GB.
Keyword and graph retrieval work without it. Models are local by default; network providers
require explicit configuration. See models, installation
and the guided tutorial.
How it fits together
Two interfaces call the same core. Markdown is the current content source; SQLite holds a rebuildable search projection and operational state. Pending review rows have their own retention requirements and cannot be recreated merely by reindexing Markdown. Governed source records, retained images and receipts live in separate evidence metadata.
The current source exposes 42 MCP tools, including the versioned knowledge process contract. A host can select a verified binary, read bounded source-cited passages, propose a result and preserve the review boundary. The contract requires no HTTP daemon or additional memory database.
The architecture guide explains layering, transaction recovery and trust boundaries. The MCP reference documents the actual interface.
Knowledge in your existing workflow
Synapse supplies operational memory. Soma supplies an operator workspace for preparing context, supervising work and reviewing results. Other hosts can use the same bounded process contract without adopting Soma.
Current source adapters read Git/Markdown and optional GitHub with fresh revision and access checks. A detected change produces review candidates. It does not silently replace accepted knowledge or write back upstream. Notion, Jira, Confluence and further authoring-tool adapters remain separate integration work.
Local-owner note acceptance and authenticated shared publication use different authority paths. The local knowledge process contract rejects shared authority. Shared source-derived acceptance remains disabled until its dedicated authenticated host workflow is available. See source adapters, source evolution and the shared source contract.
The proof
Evidence should name the workload and its limits. The stored retrieval fixture asks the same 20 questions while six synthetic professional contexts accumulate from 77 to 463 entities. The chart below plots those recorded observations, with no competitor or hypothetical baseline.
This is an internal engineering measurement on macOS arm64, not a field study or a guarantee for other corpora. The original retrieval run did not record its source commit. At the 463-entity endpoint, 17 of 20 target facts rank first and all 20 appear in the top ten. Raw observations: persona-recall.json.
| Additional evidence | What it establishes |
|---|---|
| Agent-in-the-loop benchmark | Bounded insertion, correction, structured conflict and retrieval scenarios; inspect sample sizes and confidence intervals |
| Verification scope | Named invariants, skipped checks, selected trust and explicit exclusions |
| Durable transactions | Crash recovery from retained prepare data and exact SQLite decision markers |
| Governed source history | Acknowledged limited baseline, retained images and independently selected witness checks |
| Shared integration | Current host/authority protocol and the distinction between runtime evidence and a human adoption pilot |
The benchmark harness is in synapse-bench/ in the source repository. Results describe their
recorded run, not universal semantic consistency or every distributed binary.
Day to day
| Intent | Starting point |
|---|---|
| Capture a project fact | syn capture "Maria now owns the Payments API" |
| Inspect recent changes | syn digest |
| Review queued proposals | syn pending list |
| Reverse a supported local write | syn undo |
| Query supported recorded time | syn search payments --as-of 2026-05-01 |
| Check knowledge changes in CI | Memory CI guide |
Review the command contract and selected policy before accepting proposals in bulk.
Documentation
| Start with a task | Reference |
|---|---|
| First workspace and assistant connection | Onboarding, tutorial, MCP |
| Install or verify an artifact | Installation, signed release verification |
| Integrate a host such as Soma | Knowledge process contract, shared source |
| Monitor external knowledge changes | Source adapters, source evolution |
| Understand assurance and evidence | Provability, provenance, auditability |
| Inspect system design | Architecture, ADRs, business rules |
| Find every command and option | CLI reference, configuration, models |
| Assess measured behavior | Benchmarks, plain-language explanation |
Status
The source tree continues to evolve beyond the last packaged release. Consult CHANGELOG.md for source changes and release notes for the exact published artifacts. Markdown schema, CLI and MCP compatibility follow the documented semantic-versioning policy. Experimental adapters and planned integrations keep their own explicit status.
Synapse is part of Febasi’s work to turn practical engineering into reusable capabilities. The product remains usable as a standalone local tool and as an additive knowledge component.
On the name
A synapse passes a signal from one neuron to the next. Synapse carries project knowledge from one task to the next. Lil Syn, the connected indigo mascot, is the human face of that idea.
License
MIT. See LICENSE.
