Synapse: onboarding: from install to your first answer

The linear path: what you run, in order, and exactly what you’ll see, from a freshly-installed syn to a workspace your AI can reason about. In a hurry? QUICKSTART is the same journey as a six-command cheat-sheet. Going deep on the AI loop? That’s TUTORIAL.

Prerequisite: syn is on your PATH. If not, INSTALL.md is one paragraph (and notes the Linux glibc ≥ 2.38 requirement for semantic search).

Step 1: Guided setup: language, defaults & who you are (syn setup)

syn setup writes your global config once per machine. As of v0.6 it is guided: after locale + output format it captures a short self-profile (name, birthdate (optional), profession, employers) saved to a global profile.toml (separate from config.toml). Press Enter to accept a default or skip an optional field:

$ syn setup
   ◉───◉
   │ ╲ │
   ◉───◉───◉
       │ ╱
       ◉

locale [en-US]:                          ← your language: en, pt-BR, es-MX, …
output format [text|json] [text]:
Full name:                               Ada Lovelace
Birthdate (YYYY-MM-DD) [skip]:           1815-12-10
Profession / headline [skip]:            Mathematician
Employers (comma-separated) [skip]:      Analytical Engine Co.
✓ identity saved for Ada Lovelace → ~/.../synapse/profile.toml

Language precedence is --lang > SYNAPSE_LANG > system locale > en. The profile is captured once and seeded into every workspace as your self person (Step 5): “capture once, seed everywhere” (BR-14, ADR-020).

Compulsory on a fresh interactive run, never blocking otherwise (BR-14.1). syn init runs this guided setup inline the first time on a TTY. In a non-interactive context (CI, pipe, --no-input, SYNAPSE_AGENT) it falls back to silent defaults and skips identity: automation never waits on a prompt. Override the profile path with SYNAPSE_PROFILE.

Step 2: Create your first workspace (syn init)

A workspace keeps current knowledge in Markdown with operational metadata beside it. Create one:

$ syn init ~/brain
workspace initialised at /Users/you/brain
seeded manifest /Users/you/brain/SYNAPSE.md
registered in workspace registry (id: brain-a1b2c3)

What just happened:

• the canonical folders (projects/ people/ entities/ apis/ tasks/ notes/) and the .synapse/ metadata directory were created. The search projection is rebuildable; the whole directory is not a disposable cache;
• SYNAPSE.md: the workspace’s identity card: was seeded. Its name defaults to the folder name (brain); open it and replace the “Describe what this workspace is about…” brief with one concrete paragraph. That text is what the AI reads to route questions across workspaces;
• the workspace was registered so federation and syn ws can find it. It starts private and non-shareable: nothing is shared until you opt in.

Keep .synapse/ with the selected workspace backup. It can hold configuration, pending proposals/review guards, durable transaction recovery data, retained source images, receipts and signing/trust policy. Markdown can rebuild derived retrieval data, but cannot recreate lost pending rows or missing historical evidence. Signing keys may use separately configured paths and need their own preservation policy. See architecture before removing an index or metadata directory.

(Messages appear in your configured language: the example above is en; on pt-BR you’d see “workspace inicializado em …”.)

Step 3: The semantic models (one-time, with your consent)

Right after syn init, on a fresh interactive setup, Synapse asks once whether to download the on-device search models:

Semantic search is built in: Synapse can find notes by meaning (not just
keywords) and grow the graph from people/tools it spots in your text. It
needs a one-time ~2.5 GB model download (cached, shared across every
workspace on this machine).
Download the models now? [Y/n]

• Yes → downloads ~2.5 GB once (shared across all your workspaces), then meaning-search is live.
• No / skip → Synapse runs as a keyword + graph brain. You keep syn search, syn graph, links, MCP: everything except meaning-search and automatic entity discovery. Turn it on any time with syn embed --all.

Either way nothing blocks, and nothing downloads silently. Check the state: read-only, never triggers a download:

$ syn embed --check
entities                0
embedded_total          0
models_ready            false      ← not downloaded yet

Footprint, cache location, offline/air-gapped use, privacy and licenses: MODELS.md.

Step 4: Capture what’s in your head

syn project add "Client Alpha" --status active
syn person  add "Maria Silva" --email maria@company.com --job-title "Tech Lead"
syn person  link maria-silva --project client-alpha --role focal
syn note    add "Why we picked PKCE" --kind decision --project client-alpha --tag auth

Each prints what it created (project "Client Alpha" created (id: client-alpha)). Slugs derive automatically; the YAML on disk is plain and hand-editable. In an acknowledged governed workspace, external edits require explicit reconciliation; reindexing does not approve them. A person exists once and is referenced by every project they touch.

Step 5: Your identity & CV

Synapse can carry a portable, signed record of your work across employers. The anchor is one person entity that represents you, flagged self: true. As of v0.6 you don’t create it by hand: if you completed the guided setup (Step 1), syn init already seeded this self person into the workspace from your global profile (name, birthdate, headline, and your employers as linked entity(kind=org) nodes). Confirm with:

syn person show <your-slug>   # self: true, birthdate, headline, affiliations

No profile yet (e.g. a non-interactive install)? Run syn setup to capture it: the next syn init seeds the self person. Or set self: true by hand on the entity that represents you. (cv/identity export will tell you to do exactly this if no self person exists.)

With your self person in place:

syn identity keygen          # ed25519 keypair for signing the bundle
syn experience add "Tech Lead, Payments" --target project/client-alpha --role tech-lead
syn cv export                # deterministic Markdown CV from the graph

“Who you are” is captured once by the guided syn setup (name, birthdate, profession, employers → global profile.toml) and seeded as exactly one self person per workspace on syn init (BR-14 / SYN-171/172). cv/identity export require that single self person and point you at syn setup if it’s missing. See IDENTITY.md.

Step 6: Search it, and hand it to your AI

syn search alpha                      # keyword (FTS5): fast, exact-term
syn search "the payments decision"    # hybrid (if models are on): matches meaning
syn graph project client-alpha        # walk the links
syn mcp                               # expose the workspace to Claude Code over stdio

Point Claude Code at the workspace so it can retrieve your recorded facts and their context. Check its citations and conclusions; access to stored knowledge does not guarantee a correct answer. The full human + AI loop (propose/accept/audit, federation and freshness) is TUTORIAL.md.

You’re set

If something looks off, syn doctor is always your first stop.