Home/Install
A pure-Rust workspace — the core cargo build needs no C/C++ toolchain: no libfuse, no async runtime, no protoc. Native engines slot in behind traits and TLS / io_uring stay opt-in features.
Clone and build the release binaries. The default build is fully offline (the hash-dev embedder is deterministic and needs no model). Run the test suite to confirm the workspace compiles and passes end-to-end.
git clone https://github.com/021flow/synafs && cd synafs cargo build --release cargo test # 73 tests: RRF/BM25 + consistency/recovery + symbols + as-of/GC/diff + FUSE + web/gRPC + C ABI/CUSE
Feature flags are off by default; turn on only what you need. Tests for the gated paths run with cargo test --features "syna-sys/io_uring syna-web/tls syna-engine/watch syna-engine/fanotify" (84 tests).
candle, CPU). This is the real-embeddings quality path.syna serve.uring::read_batch reaps many reads in a single submit/complete cycle (pure-Rust io-uring, no liburing).FAN_MARK_MOUNT). Needs root (CAP_SYS_ADMIN).tiny_http (no protoc, no async runtime), and gRPC's HTTP/2 + HPACK is hand-written. The whole core builds without a C/C++ toolchain.One binary, syna, fronts the whole engine. Each command below is real — index a tree, search it by meaning, edit through the write path, seal and travel the version DAG, then bring up the FUSE mount and the network surfaces.
# index a repo, then query by meaning syna init syna index . syna query "reciprocal rank fusion" --top 3 --lang rust syna query "validate token" --rerank symbolgraph:callers # call-graph rerank syna query "login" --as-of HEAD~1 # search code as it was then # write path → reindex → consistency token; seal & inspect history syna edit src/auth.rs --content "$(cat new.rs)" syna commit -m "checkpoint" # seal the working tree into a version syna log syna diff --symbol validate # symbol-level diff across versions syna symbols validate --relation callers # who calls it syna gc # reclaim chunks from unreachable versions # surfaces syna mount /mnt/repo # FUSE: ls /mnt/repo/.syna/query/... SYNA_TOKEN=secret syna serve --addr 127.0.0.1:5200 # HTTP API + gRPC-Web syna grpc --addr 127.0.0.1:5201 # native HTTP/2 gRPC syna watch # inotify auto-reindex (build --features watch) sudo syna watch --fanotify # whole-mount VFS watch (build --features fanotify, root) sudo syna dev # /dev/synafs CUSE device (CAP_SYS_ADMIN) syna bench # throughput · p50/p99 latency · recall@k/MRR
The default hash-dev embedder is offline and deterministic, so its vectors are non-semantic and BM25 carries ranking. For true semantic retrieval, build with --features coderank and set SYNA_EMBEDDER=coderank at index time. The model auto-downloads to ~/.cache/synafs on first use; serving reads the snapshot's embedder_id and configures the matching embedder automatically.
# build with the local semantic embedder (pure-Rust candle) cargo build --release --features coderank # index and query with real embeddings (model auto-downloads to ~/.cache/synafs) SYNA_EMBEDDER=coderank syna index <repo> syna query "authenticate a user token"
The syna-mcp binary is a first-class MCP surface — line-delimited JSON-RPC 2.0 over stdio. Build it, index the repo first, then register it. Pass the repo (the directory holding the index) as an argument.
cargo build --release # register with Claude Code (use absolute paths) claude mcp add synafs -- /ABS/PATH/SynaFS/target/release/syna-mcp /ABS/PATH/your-repo
Or wire it through a project .mcp.json:
{
"mcpServers": {
"synafs": {
"command": "/ABS/PATH/SynaFS/target/release/syna-mcp",
"args": ["/ABS/PATH/your-repo"]
}
}
}Tools exposed to the agent: search, read_span, neighbors, symbol_lookup, apply_edit, subscribe, and diff_symbol. For semantic results, index with SYNA_EMBEDDER=coderank using a coderank-built binary; the server then auto-configures the matching embedder from the snapshot.
The network surfaces bind to loopback by default. Off-loopback access requires a Bearer token (SYNA_TOKEN); TLS / mTLS is opt-in via the tls feature.
syna serve — HTTP API (REST + /events + /ws WebSocket) and gRPC-Web.syna grpc — native HTTP/2 (h2c) gRPC, same dispatch as REST.syna serve --tls-cert server.pem --tls-key server.key --client-ca clients-ca.pem (build --features tls).