synapse

Status: pre-1.0, in active development. The storage kernel, indexes, and MVCC transaction layer are implemented; the agent-facing typed API is next. No semver guarantees until the API freeze at v0.1.

synapse is a Neo4j-inspired, in-memory property graph database written in Rust, purpose-built so that AI agents can record, recall, and reuse the steps they have determined for a goal they are working toward. The default deployment is in-process — every agent links the engine and owns its graph — with an optional daemon (synapsed) exposing the same engine over gRPC, HTTP, and MCP for cases where multiple agent processes share one memory.

What is in the box today

• synapse-core graph kernel — slot-based arenas with generation-stamped ids, intrusive per-node rel adjacency lists, string-interned label / rel-type / property-key tokens, and a heterogeneous Value (incl. fixed- width Vector and Bytes).
• Indexes (M2) — always-on label index (FxHashMap<LabelId, FixedBitSet>) and opt-in synchronous property B-tree index keyed by (LabelId, PropKeyId, IndexValue) with a stable cross-kind ordering. Index maintenance is inline with mutations and prevalidate-then-mutate, so a rejected op leaves no torn state.
• Transactions (M3, internal preview) — single-writer / multi-reader MVCC with snapshot-isolation semantics, atomic batch commit, and read-your-own- writes inside a tx. Snapshot acquisition is lock-free (ArcSwap<PublishedSnapshot>). Stale-snapshot commits are rejected, callers retry. A scheduled M3.5 redesign (versioned tombstones) is what unlocks the P99 record_step budget at 10k+ nodes — see crates/synapse-core/src/tx/mod.rs for the escalation order.

What is not here yet: the typed Goal/Plan/Step/Outcome API (Phase 4), the Cypher parser (Phase 5), the WAL + snapshot persistence (Phase 6), HNSW vector recall (Phase 7), and the synapsed daemon + MCP adapter (Phase 8). The crate skeletons exist with module-level docs that sketch the shape; their bodies are empty until their phase lands.

Installation

There is no published release yet. To use it as a path dependency while Phase 4 is in flight:

[dependencies]
synapse-core = { git = "https://github.com/dattgoswami/synapse" }

cargo add synapse-agent will be the documented path once the typed API lands.

Workspace layout

crates/
  synapse-core/    graph engine: store, index, tx (Phases 1–3 implemented;
                   persist, query, traverse to follow)
  synapse-agent/   typed Goal/Plan/Step/Outcome API — Phase 4
  synapse-cypher/  parser for the supported Cypher subset — Phase 5
  synapse-proto/   gRPC + HTTP wire types — Phase 8
  synapsed/        out-of-process daemon binary — Phase 8
  synapse-mcp/     MCP server adapter — Phase 8
  synapse-cli/     `synapse` CLI for embedded mode — Phase 8/9

Feature flags

Crate	Feature	Default	What it gates
synapse-core	persist	on	WAL + snapshot persistence (lands with M6)
synapse-core	hnsw	off	HNSW vector index over Value::Vector(_) props (M7)
synapse-agent	embed-onnx	off	Local ONNX embedder for recall_similar_goals (M7)
synapse-agent	embed-openai	off	REST embedder for OpenAI-compatible endpoints (M7)
synapse-mcp	mcp	off	MCP transport for the daemon adapter (M8)
synapsed	daemon	off	gRPC + HTTP transports for the daemon binary (M8)

Feature flags are declared at the workspace boundary so that downstream crates can [dependencies] synapse-core = { default-features = false } today and stay forward-compatible. Most of the feature bodies arrive in later phases.

Phase / milestone status

Phase	Title	Status
0	Workspace, CI, license, README skeleton	done
1	Kernel skeleton (M1)	done
2	Indexes (M2)	done
3	Transactions (M3, internal preview)	done — see note
4	Agent API (M4)	in progress
5	Cypher subset (M5)	planned
6	Persistence (M6)	planned
7	Vector recall (M7)	planned
8	Daemon + MCP (M8)	planned
9	SDKs, examples, docs, release polish	planned

M3 release-gate note. The commit_clone_cost bench measures ~468 µs against a 15 µs gate on the 10k-node row. M3 ships as internal-preview and the record_step P99 = 50 µs headline budget is suspended until M3.5 (versioned tombstones) lands. The transaction module documents the escalation order; do not chase the gate with the intermediate fixes — they don't reach it.

Building

scripts/dev.sh        # fmt --check, check --all-features, clippy -D warnings, test --all
cargo check --all     # quick compile check
cargo test -p synapse-core --all-features

Toolchain: Rust edition 2024 (MSRV 1.85).

CI runs the same four steps on stable and the workspace MSRV in .github/workflows/ci.yml; please run scripts/dev.sh before pushing.

Reading the code

Module-level rustdoc is the primary design documentation — every non-trivial file opens with a //! block that explains the invariants and why each choice was made. Good entry points:

• crates/synapse-core/src/store/mod.rs — kernel + cross-store id safety
• crates/synapse-core/src/store/arena.rs — generation-stamped slot arena
• crates/synapse-core/src/index/mod.rs — label + B-tree property indexes
• crates/synapse-core/src/tx/mod.rs — MVCC isolation + escalation order
• crates/synapse-core/src/tx/writer.rs — single-writer publish pipeline
• crates/synapse-core/tests/ — proptest, differential, stress, and concurrent-snapshot suites for the tx layer

See ARCHITECTURE.md for a one-page map.

License

Dual-licensed under Apache-2.0 OR MIT at your option. See LICENSE-APACHE and LICENSE-MIT.

Acknowledgments

Architectural inspiration comes from Neo4j's open-source design. synapse is not a fork or port; it is original Rust, re-derived from spec. See CONTRIBUTING.md for the rules around that.