Maximem Synap: agent rules (single-file edition)

Self-sufficient: copy this file alone into AGENTS.md, .cursor/rules/synap.mdc or .clinerules. The full skill (npx skills add maximem-ai/maximem_synap_sdk --skill synap -y) has more detail and wins.

Never guess. If anything is unclear, stop and ask the human. Never ask the human to paste a key into chat.

Start (ask which applies)

• One-time code (syn_ob_...): from step 1. Public prompt (asks if Synap fits): reference/public-start.md, ending in <cli> auth login --purpose onboarding. Neither: a fresh dashboard prompt or <cli> auth login, then step 2.
• Already has an instance and a runtime key, or reuses one from step 2b: skip sign-in, use-case, create and wait (unless still being built); read the key from the environment or .env (none: step 10, with its setup-key limit). Read B2C or B2B from whoami (equals_customer is B2C, strict is B2B), then Step 0, identity, depth, integrate, verify.

<cli> means maximem-synap from PATH if maximem-synap --version is 0.3.3 or newer (the session commands do not exist before), else npx @maximem/synap-cli@latest (Node and Python 3.10+). If the prompt names an environment add --env <name> to every command. Put --json before the subcommand. If SYNAP_API_KEY is set in your shell run CLI commands with env -u SYNAP_API_KEY.

The steps

1. Sign in: <cli> auth login --code <syn_ob_...> --agent-name <claude-code|cursor|codex|windsurf|other>. A missing, expired or used code is the one case to say "copy a fresh prompt from the dashboard". Login prints your profile name: put --profile <name> before the subcommand of EVERY CLI command (SYNAP_PROFILE works only if your shell persists); never log out or touch a profile that is not yours; on a 'pin your profile' refusal (exit 2) pin your own from the names in the message.
2. <cli> onboard status shows this session's steps and a read-only list of OTHER sessions. Trust only steps you reported yourself; other sessions are someone else's work: never act on them, answer their questions, or skip drafting, approval or creation because they look done. 2b. What exists: <cli> instances list --json; tell the human in plain words each instance (name, purpose if known, ready, being built or failed: see the glossary). If any exist, ask ONE question with your recommendation and tip: reuse one or create a new one. Recommend reuse only if it is for THIS agent (one instance serves one agent).
3. Step 0, learn Synap first: read in full https://docs.maximem.ai (each .md): /getting-started/quickstart, /concepts/memory-model-cheat-sheet, /concepts/memory-scopes, /concepts/how-ingestion-works, /concepts/retrieval-modes, /concepts/real-time-anticipation and your framework's /integrations/<name>. Tell the human four lines on what you understood (scoping, the three operations, the live stream, the build/ready rule).
4. Read the repo; infer only what the code supports.
5. One question at a time, showing evidence and still asking. EVERY question carries my recommendation (what you suggest and why) and a tip (how Synap uses the answer and what it changes; write it only after reading the docs page named for that question in onboarding-ask-rules.md). Questions: which agent gets memory now, if the repo has more than one agent (one instance serves one agent, /concepts/agent-topologies.md; others need their own; then, before creating anything, <cli> onboard target "<AgentName>": the CLIENT's agent, e.g. BillingAgent, 1 to 60 chars, no markup, never an instance id); with more than one instance in the workspace, READ /guides/instance-visibility.md, then ask "Should these agents see each other's memories?" (recommend: handing off for the same users, share; different audiences or compliance, isolate; the default is shared, only a policy the human sets in the dashboard, Instance visibility, isolates them; answer in the final report); B2C or B2B (chosen when the instance is created); what identifies a returning person (a stable user id); compliance and sensitive data (read /guides/pii-protection.md for health, financial or children's data); what to remember; what never to store. Never use a per-session id as user_id unless the human confirms there is no persistent identity, then say what is lost (returning memory, profile, per-person erasure); a shared-device id leaks between people.
6. Choose the integration path. Always use the SDK, never raw HTTP calls. The implicit path (the live stream: the app reports events and Synap works as they flow) is the DEFAULT for any app that can run a long-lived process (server, worker, container, voice or desktop); never present it as optional. Say first what it gives (docs-backed: context prepared before the agent asks, turns recorded with no write calls, delivery that survives dropped connections), then confirm, default yes: "I will wire the live stream so you get X, Y, Z. Tell me if you do not want it." Implement it FULLY unless the human EXPLICITLY says no ("I do not know" or silence = implement); if they say no, record the one-sentence consequence, use the explicit path and report it. On serverless, Edge or short-lived hosts say in one plain sentence it needs a long-lived process (/concepts/grpc-vs-rest.md), use the explicit path with the production rules, add one neutral sentence that it becomes available if the app ever runs one; do not pitch re-architecting. Check dependency conflicts (protobuf) first. Report onboard report integrating in_progress --detail "path=implicit|explicit-no|explicit-host".
7. Draft the use-case from <cli> instances template, every unanswered field literally not stated. Show the exact file in full, quote its shasum -a 256, upload exactly that file (once sent, it can only be changed by making a request through email to gaurav@maximem.ai: say so), ask again after any change, then onboard report use_case_drafted done and, after an explicit yes, use_case_approved done.
8. Say the build usually takes 15 to 20 minutes and get a yes (ask before create): <cli> instances create --name ... --relationship b2c|b2b --from-file usecase.md. A 409 instance_name_taken: ask whether to reuse it or rename. A 409 instance_limit_reached or 429: stop and ask the human, never retry. Do not wait.
9. Integrate. Done means: the READ is wired into the model prompt (write-only is not done; say where) and memory informs while the app's own rules decide; writes init the SDK once, use about a 5 s timeout and bounded retries, never block the user turn if avoidable, never swallow a failure silently, and say what is lost on failure; redaction tested; one startup log line saying ON or OFF; versions pinned; .env.example and README updated; tests for failure, 409 and redaction. Open each call's /sdk-reference page before and after writing it; print a "Docs read" list of pages you actually opened (/guides/production-checklist, /patterns/graceful-degradation, /sdk-reference/errors and each method page used) before verifying.
10. <cli> api-keys create -i <id> --write-env, then onboard report env_written done. Never print or commit the key. This setup key manages ONLY instances this session created: on a reused one a 403 instance_not_created_by_this_session (exit 5) means say: "This setup key only manages instances this session created itself. Please create the API key for <instance name> in the dashboard (API keys page) and add it to the project's .env as <VARIABLE>; I will not look for another way around it." Never ask for the key in chat. One key per instance: if the project will have more than one Synap instance (ask when unsure) add --env-suffix NAME (letters, digits, underscore), which writes SYNAP_API_KEY_<NAME> and SYNAP_INSTANCE_ID_<NAME>; never save several as plain SYNAP_API_KEY (the CLI refuses, exit 6, unless --force or a suffix). The app reads the matching variable explicitly (sdk-setup.md). Run the project's tests with env -u SYNAP_API_KEY until verify passes.
11. Run <cli> instances wait <id> in the BACKGROUND (log file; poll it). No ingestion or retrieval, including verify_synap.py, before it reports ready. A refused call is HTTP 409 instance_not_ready: newer SDKs raise InstanceNotReadyError, older ones (including 0.5.16) a ConflictError saying the memory architecture is still being built; handle both, typed first, wait the stated time, never loop inside the call.
12. Run SYNAP_VERIFY_REQUIRE_STREAM=1 python scripts/verify_synap.py > verify.out 2>&1; echo "exit=$?" (no prefix if the host cannot run the stream; --suffix NAME for a suffixed key) and paste verify.out unedited, WARN lines included; it ends with RESULT: and EXIT CODE:. Run scripts/check_integration_wiring.py and drive the app's own endpoint with a sentinel. Every test or probe user id you create is test_user_<purpose>_<8 random chars>: write each down. Before announcing run python scripts/cleanup_test_data.py --user-id <id> ... --dry-run, then without it, for exactly those ids; paste both outputs (only test_user_ ids; never delete any other, never the human's real users). Announce with the filled final-report template (every line answered; "Nothing was committed"; files created and changed). Verify comes BEFORE auth logout: the dashboard shows finished only after the first memory and a useful recall, else "ended before verification" (report line: "Dashboard shows finished only after the first memory and a useful recall: <yes/no>"). Then, only if verify passed, <cli> auth logout last, after every onboard report; say it is signed out ONLY if it exits 0 and reports revoked (exit 9 revocation_pending: still active until expiry; retry, then an open item).

The implicit path: send all five events every turn

• user_message and assistant_message: send_message(event_type=...); without the first the turn is not recorded, without the second anticipation never runs.
• agent_thinking: record_thinking(...). tool_call: record_tool_call(...). tool_result: record_tool_result(...).

One stream per process: listen() at startup, end_session when a conversation ends, stop_listening() on shutdown. Never hand-set role on tool or reasoning events; never stream a turn and also memories.create() its text. Scope: user_id always; customer_id only on B2B; conversation_id must be a UUID.

Hard rules

never create or delete workspaces or touch billing or members; never run git commit, git add -A, git push, git stash or an amend (leave changes uncommitted, new files untracked); never say "production", "prod", "staging" or "environment" about Synap to the human (just Synap; use --env silently); never show raw status words (building, failed, b2c, no_instance): translate them with the glossary (docs first for others); a known defect you caused is fixed or asked about first; the human never has to go back to the dashboard. The live docs win over this file.

Instances in plain words (glossary)

An instance is the memory space Synap built for one agent; a key opens exactly one (/concepts/memory-scopes.md). Say:

• building, attempt 2 of 3: Synap is preparing the memory design (15 to 20 minutes; it retries up to three times itself). ready: finished. failed: not built after three tries; restart from the same file. awaiting_review: waiting for the Synap team.
• b2c/equals_customer: each end user has private memory. b2b/strict: users belong to a customer organization.
• onboard status words no_instance, no_api_key, no_ingestion, no_retrieval: nothing created, no key, nothing written, nothing read back; activated: it works. no_agent is not a Synap word; never say it.

Where the detail is

Raw files (https://raw.githubusercontent.com/maximem-ai/maximem_synap_sdk/main/skills/synap/): reference/ public-start.md, onboarding-details.md, onboarding-ask-rules.md, instances-explained.md, integration-checklist.md, final-report-template.md, sdk-setup.md, streaming.md, frameworks/<name>.md; scripts/ verify_synap.py, check_integration_wiring.py, cleanup_test_data.py.