Synapse: recipes

Eight workflows you’ll re-run more than once. Every command works against the workspace from TUTORIAL.md; follow that first if you haven’t.

1. Import people from a CSV

You have contacts.csv:

name,role,project
Maria Silva,focal,cliente-alfa
João Santos,dev,cliente-alfa
Carla Lima,pm,cliente-beta

A two-liner:

tail -n +2 contacts.csv | while IFS=, read -r name role project; do
  slug=$(syn person add "$name" --format json | jq -r '.id // empty')
  [ -n "$slug" ] && syn person link "$slug" --project "$project" --role "$role"
done

syn person add is idempotent on slug: re-running skips existing people.

2. Weekly review: what changed in the last seven days

syn search "" --format json | jq '[.[] | select(.updated >= (now - 7*86400 | todate))]'

For tasks specifically:

syn task list --status in_progress
syn task list --status blocked

Pair with syn graph to see who owns what:

for slug in $(syn task list --status in_progress --format json | jq -r '.[].id'); do
  echo "=== $slug ==="
  syn graph task "$slug"
done

3. Find stale tasks

A task is stale when updated is older than a threshold. Use syn export --as json for ad-hoc analysis:

syn export --as json --out /tmp/dump.json
jq '[.entities[] | select(.type == "task" and .status != "concluded" and .updated < (now - 14*86400 | todate))
       | {id, title, owner, updated}]' /tmp/dump.json

Tweak the 14 to the staleness window you care about.

4. Per-project briefing for an external party

Export only what they need to see:

PROJECT=cliente-alfa
syn export --as json --out /tmp/full.json

jq --arg p "$PROJECT" '
  {
    project:   (.entities[] | select(.type=="project" and .id==$p)),
    people:    [.entities[] | select(.type=="person" and .frontmatter.memberships[]?.project == $p)],
    apis:      [.entities[] | select(.type=="api" and (.frontmatter.projects // []) | index($p))],
    decisions: [.entities[] | select(.type=="note" and .frontmatter.kind=="decision")],
  }
' /tmp/full.json > /tmp/briefing.json

Or render the whole workspace and hand them a URL:

syn export --as html --out /tmp/brain-site
python3 -m http.server -d /tmp/brain-site 8765
# open http://localhost:8765

5. Let the AI propose, you sign off in batch

Working with Claude Code on a long thread, end the session with:

syn pending list             # what is queued
syn pending show 1           # spot-check the largest one
syn pending accept 1
syn pending accept 2
syn pending reject 3 --prune # AI was wrong on this one, prune for audit hygiene

Tip: alias acc='syn pending accept', rej='syn pending reject' for fast triage.

6. Rename and merge tags

Tags drift over time (auth, authentication, Auth). Collapse them:

syn tag list                 # see counts
syn tag rename Auth auth
syn tag merge authentication auth

Both commands rewrite frontmatter on every affected entity and re-index in the same transaction (BR-6.1).

7. Cross-workspace federation with the LLM

After syn ws include on multiple workspaces (see TUTORIAL §6), Claude Code can route across them:

“Compare how cliente-alfa (work-brain) handles webhooks vs. the pattern in personal-brain.”

Claude calls list_workspaces, picks the relevant ones from each description/topics, then federated_search and get_entity_from. Workspaces you didn’t opt in are invisible: neither Claude nor any other client can probe their existence.

Curate identity fields so routing works well:

cd ~/work-brain
syn ws topic add payments
syn ws topic add webhooks
syn ws tag add internal

(Or let Claude propose them via add_workspace_topic; same pending-queue flow as recipe 5.)

8. Continuous reindex while editing

If you’re polishing a few notes in your editor:

syn watch --debounce-ms 500

Every save triggers a debounced reindex. Cancel with Ctrl-C.

Pair with syn open <slug>:

syn open decisao-pkce          # opens in $EDITOR, reindexes on close

9. Turn on semantic search for an existing workspace (v0.5)

The default binary already includes the semantic layer (SYN-168); the real gate is the model download, which happens only on consent. The syn init onboarding prompt offers it for new workspaces; for an existing one, syn embed --all is the consent step. (Footprint, cache location, offline use, privacy and licenses: MODELS.md.)

syn embed --check              # "models_ready: false" → models not downloaded yet
syn embed --all                # first run downloads ~2.5 GB of models (consent), then embeds everything
syn embed --check              # "models_ready: true · embedded: N · model: fastembed:bge-m3@…"

syn embed --check is read-only; it reports models_ready without downloading anything. Until you run syn embed --all, writes save without embedding and syn search degrades to FTS + graph; nothing blocks. (On a minimal core build: --no-default-features --features mcp: the embed command and the vector legs are absent entirely.)

From now on every new write is embedded automatically. If you later switch embedding_model in .synapse/config.toml, re-run syn embed --all: it re-embeds only the rows whose stored model no longer matches. To start clean: syn embed --reset-cache && syn embed --all.

10. Choose the right search mode

syn search "billing webhook retries"      # hybrid (default): best recall, blends meaning + words + graph
syn search --semantic "race condition"    # vector-only: "find conceptually similar", even with no shared words
syn search --no-vector webhook-v2         # FTS + graph: exact-term + link traversal, no model load (fast)

Rule of thumb: hybrid for “find what I mean”, --semantic for “find things like this”, --no-vector when you know the term and want zero cold-start.

11. Review NER-proposed entities

The insertion-time pipeline (BR-13) links mentions to existing entities and proposes new ones it can’t resolve, rather than creating them silently:

syn note add "Sync with Carina about the Stripe migration" --kind meeting
syn pending list                          # → a create_entity_from_ner proposal for "Carina" / "Stripe"
syn pending show 1                        # inspect the proposed type + title
syn pending accept 1                      # materialise it, or `reject 1` to dismiss

This keeps the graph growing from what you actually write, while BR-12.3 guarantees nothing is created without your sign-off.

12. Grade search results to tune ranking (v0.6 prep)

syn search "checkout eligibility flag" --grade
#   [1/4] entity   remote-config            Remote Config
#       relevant? [y/N/skip] y
#   ...
#   recorded 4 judgment(s) → .synapse/search-labels.ndjson

The labels accumulate as NDJSON; a future release reads them to tune the hybrid ranking to your sense of relevance. Grade a few dozen real queries and the data is there when v0.6 needs it.

Found a recipe worth sharing? Open a PR on this file.