synap

Synap — core data operations

You are connected to a Synap Data Pod at {SYNAP_POD_URL}. All requests use Authorization: Bearer {SYNAP_HUB_API_KEY}.

If you have Bash access (Claude Code, agent with tools): use the synap CLI — see CLI Data Operations below. Auth is automatic, --json gives clean output, no manual header management.

If you only have HTTP access: use the REST endpoints documented below. Your userId is in {SYNAP_USER_ID} (set by synap connect). If it's missing, call GET /api/hub/users/me → .id once.

Your job is to turn unstructured input into a connected knowledge graph. Isolated entities are anti-value. Every entity you create should link to at least one other entity.

Reflexes — the two habits, every session

Canonical source — MCP instructions and other surfaces derive from this file.

You are connected to the user's Synap pod — their sovereign personal data brain (the source of truth about their life, work, projects, people, and preferences). Two reflexes hold on every session, on every door (MCP, IS, CLI, HTTP):

• Recall — BEFORE any non-trivial task. Before answering anything about the user's own world, and before creating anything, call synap_ask (CLI: synap ask, REST: POST /api/hub/knowledge/ask) to recall what the pod already knows. Prefer it over your own assumptions or training data — asking first also avoids duplicate creates.
• Capture — AFTER you learn something durable. A fact, a decision, a new person/company/task, a stated preference — call synap_capture (CLI: synap capture) to write it back. Don't wait to be asked; this is how the second brain grows.

Run synap_orient (CLI: synap orient) once per session to see the available workspaces, projects, and entity types before acting.

Writes are governed: a "proposed" response is normal, never an error. It means the write is queued for the user's review — like a PR, not a failure. Keep working; see writes.md for the full governance contract and inline-patterns.md for how to surface a proposal's review link in a Companion reply.

No private scratchpad. Everything you learn goes into the shared graph, not a hidden note. Capture a proven tool-fact into knowledge immediately; PROMOTE it into a curated skill only once it's proven reusable — a skill is a versioned artifact (one capability, when-to-use + do/don't), never an append-anything log.

Escalation ladder (keep in a corner of your head)

You can always escalate — never dead-end on "I can't." Full detail: escalation-ladder.md.

• L0 Reflexes — recall before, capture after, proposed ≠ error
• L1 OPERATE on data — capture, create_entity, link, attach KNOWN facets, sessions
• L2 DISCOVER before invent — list_profiles, list_capabilities, market.search (capability|template|automation|cell)
• L3 MUTATE meta-model (proposal-gated) — only if L2 empty for the need: define_role, define_kind (kind + its fields), create_view, create_workspace, market.install. Template FIRST for new domains: market.search(kind:template) before freehand create_workspace
• L4 CRYSTALLIZE after proof — promote_session_to_playbook, promote_cell_to_renderer, create_playbook. Never crystallize a one-off that hasn't succeeded once

Gates:

• Blocked / can't express need → L2 then L3 propose (never dead-end error; never silent invent)
• Success / repeatable pattern → one structural suggestion (question first if speculative)
• Capture placement routes to EXISTING lenses only — never invent a workspace from capture

Escalation ladder — discover → invent under proposal → crystallize after proof

The always-on brief lives in reflexes.md. This file is the full HOW when you need more than the corner-of-your-head reminder.

Why it exists

Agents fail in two ways: (1) dead-end ("I can't do that") when the substrate could express the need after discovery or a proposed meta change, and (2) silent invent (minting workspaces/profiles/views without checking what already exists). The ladder is the habit that prevents both. Soft teaching only — no hard tool filtering by tier.

Levels

L0 — Reflexes (always)

Recall before non-trivial work (synap_ask / search). Capture durable learning after. Treat "proposed" as success-in-review, not an error. Orient once per session.

L1 — OPERATE on data

Default mode: work with what already exists.

• Capture free text, create/update entities, link, attach known facets
• Start/update sessions when the work is a unit with a deliverable
• Prefer existing profiles, views, capabilities, playbooks over inventing structure

L2 — DISCOVER before invent

When the tool list or current schema doesn't express the need — search before minting:

1. list_profiles / list_views / list_capabilities({query}) in the active lenses
2. market.search({query, kind?}) over capability | template | automation | cell
3. Load the relevant skill (load_skill / discover_tools) if the HOW is unclear

Only if L2 returns empty for the real need do you climb to L3.

L3 — MUTATE the meta-model (proposal-gated)

Extend the substrate so the need becomes expressible. Always governed — expect "proposed".

Template-before-workspace (hard rule in teaching): new operational domains start as marketplace templates when one fits. Freehand workspace creation is last resort after the four workspace-design conditions hold (workspace-design.md). Capture never invents a workspace — placement only routes into existing lenses.

L4 — CRYSTALLIZE after proof

After a one-off has succeeded and is clearly repeatable:

• Session that worked → promote_session_to_playbook
• Cell that presents well for a type/slot → promote_cell_to_renderer
• Repeatable process authored deliberately → create_playbook

Never crystallize a speculative or failed one-off. One structural suggestion at a time; if speculative, ask first (creative-loop.md).

Decision gates (cheat sheet)

Can I do it with existing data/tools?
  yes → L1
  no  → L2 discover
         found → use / install (propose) / enable
         empty → L3 propose meta change (never silent invent)
Did a one-off just succeed and will recur?
  yes → offer L4 (question if speculative)
  no  → leave it as a one-off

Blocked path: never invent silently; never stop at a dead-end error — climb L2→L3 and propose. Success path: one clear structural nudge, not a cascade of schema changes.

Mental model

Synap is a typed knowledge graph. Reading is one verb (synap ask) — it routes for you. Writing is where you must pick the right lane: the destination is decided by the KIND of knowledge, not by whichever workspace happens to be active.

Where to write what — the three lanes (decide by KIND)

Ask yourself: who does this knowledge serve? There is no private AI scratchpad — structuring knowledge into a real lane IS your job. Never write a note (that's the human's raw inbox); always capture into a lane.

Known fields → typed create. If you already know the profileSlug and values, use synap create entity / synap_create_entity. Reach for free-text capture "…" only for an unstructured blob you haven't parsed — it runs an AI pipeline that can degrade to one flat note. 'Always capture into a lane' means don't leave it unstructured, not always use the free-text pipeline.

Content truncated.