Maximem Synap — Agent Memory Skill (Codex)

Synap is a managed memory layer for AI agents. Codex edition; reference/ matches the Claude Code skill.

Public prompt (asks if Synap fits, no code): follow reference/public-start.md first; on yes it runs <cli> auth login --purpose onboarding, then step 2.

Sandbox & approvals

State what you need before you start: network access; file writes (integration code, a git-ignored .env); a secret (the synap_... key: api-keys create --write-env writes it to .env; never print it back or commit it). If restricted, tell the user which commands to run.

Procedure: onboarding a project end to end

Never guess. If anything is unclear, stop and ask the human. Full steps and sign-out message: reference/onboarding-details.md; questions, tips, failures: reference/onboarding-ask-rules.md; CLI: reference/dashboard-setup.md.

CLI. <cli> means maximem-synap from PATH if maximem-synap --version reports 0.3.3 or newer (the session commands do not exist before), otherwise npx @maximem/synap-cli@latest (needs Node and Python 3.10+). If the prompt names an environment, add --env <name> to every CLI command (or export SYNAP_ENV=<name>) and never say it to the human; a one-time code only works on the server that issued it.

Quick reference. Put --json or --output json before the subcommand; use the full inst_... id, never a truncated table id. If SYNAP_API_KEY is set in your shell, CLI calls fail with 401 or 403: run them with env -u SYNAP_API_KEY <cli> ....

1. Sign in. <cli> auth login --code <syn_ob_...> --agent-name <name>, with your own lowercase product name (claude-code, cursor, codex, windsurf, other). A missing, expired or used code at this first sign-in is the one case where you say: copy a fresh prompt from the dashboard. The key lasts 7 days; never auth refresh it. Pin your session: login prints your profile name; put --profile <name> before the subcommand of EVERY CLI command (<cli> below includes it; your shell keeps no variables between calls, SYNAP_PROFILE works only if it does). Never log out or touch a profile that is not yours. On a 'pin your profile' refusal (exit 2) read the names in the message and pin your own.
2. State. <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. Re-running the prompt is safe. 2b. What exists (right after step 2, before step 3). <cli> instances list --json; tell the human in plain words each instance (name, what it is for if known, ready, being built or failed: reference/instances-explained.md). 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, /concepts/agent-topologies). Reuse = the existing-instance variant below.

Start variants (ask which applies; detail: reference/no-code-path.md). One-time code: step 1. No code: a fresh dashboard prompt, or <cli> auth login once (human approves in browser). Existing instance and runtime key, or an instance reused from step 2b: skip steps 1, 5, 6 and the wait unless it is still being built; read the key from the environment or .env (if .env has none, step 8 applies, with its setup-key limit); never ask the human to paste a key into chat (name the variable and have them add it to .env); read the mode with whoami; still do Step 0, identity, the path choice, the read path and verify.

Step 0: learn Synap first (required, after step 2 and before step 3). Read in full, not skimmed: /getting-started/quickstart, /concepts/memory-model-cheat-sheet, /concepts/memory-scopes, /concepts/how-ingestion-works, /concepts/retrieval-modes, /concepts/real-time-anticipation, and once step 3 names the framework, /integrations/<name> before step 6. Then tell the human four lines on what you understood: (1) the scoping model (user_id and customer_id by B2C or B2B), (2) the three operations (write, read, live stream), (3) why the live stream matters, (4) the build/ready rule.

3. Read the repo. Detect the framework (reference/frameworks/_index.md). Infer only what the code supports.
4. Ask the human, one question at a time, showing the evidence and still asking. EVERY question carries (a) my recommendation: what you suggest and why, from the repo, and (b) a tip: how Synap uses the answer and what it changes in the result, written only AFTER you READ the docs page(s) named for that question in reference/onboarding-ask-rules.md (never guess a tip). Questions: which agent gets memory now, if the repo has more than one agent (one instance serves one agent, /concepts/agent-topologies; further agents each need their own instance later; right after the answer, or with one agent after reading the repo, and before creating anything run <cli> onboard target "<AgentName>": the CLIENT's agent, e.g. BillingAgent, 1 to 60 chars, no markup, never an instance id; the dashboard shows 'Claude Code · BillingAgent'); if the workspace will have more than one instance (a second agent or instances list shows others), READ /guides/instance-visibility, then ask 'Should these agents see each other's memories?': by default instances of the same workspace and customer share memory at retrieval; only a visibility policy, set by the human in the dashboard (you cannot), isolates them; the answer goes in the final report; B2C or B2B (chosen when the instance is created); what identifies a returning person in this app (a stable user id; none means per session only); compliance and sensitive data; what matters most to remember; what must never be stored. If the answers mean memory cannot serve the goal (e.g. a session id as user id while the goal is remembering returning users), say so before approval and ask again. For health, financial, children's or other personal data read /guides/pii-protection first. onboard ask while waiting. Never use a per-chat or session id as user_id unless the human confirms there is no persistent identity, then say what is lost (reference/onboarding-ask-rules.md); a shared-device id leaks between people. Choose the integration path (required, after step 4, before step 5). Always use the SDK, never raw HTTP calls. The implicit path (the live stream: listen, send_message, record_*; 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, desktop, CLI or voice agent); never present it as optional. The explicit path is the app calling the store and fetch methods (record_message, memories.create, fetch) itself. Say first what the stream gives, docs-backed only (reference/integration-depth.md), then ask as a confirmation, 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", silence, "whatever you think" mean implement): the five events below, session end, clean shutdown, the docs checkpoint, after checking dependency conflicts (e.g. protobuf). If they say no, record the one-sentence consequence, build the explicit path and mention it in the final report. Serverless, Edge or per-request hosts: the implicit path needs a long-lived process (/concepts/grpc-vs-rest): say so in one plain sentence, build the explicit path with the production rules, add one neutral sentence that it becomes available if the app ever runs a long-lived process; do not pitch re-architecting. Report onboard report integrating in_progress --detail "path=implicit|explicit-no|explicit-host".

The five events for the implicit path, every turn (reference/streaming.md): user_message (else the turn is not recorded), agent_thinking (why it chose), tool_call (tool, arguments), tool_result (what it returned; the strongest hint of the next question), assistant_message (the reply; without it anticipation never runs).

5. Draft the use-case from instances template (reference/use-case-markdown.md), every unanswered field literally not stated. Show the EXACT file you will upload, in full, and upload exactly that file, never a longer or different one. Once this file is sent, it can only be changed by making a request through email to gaurav@maximem.ai: say so when you ask for approval. Quote its shasum -a 256; if you change one character after approval, ask again. Then onboard report use_case_drafted done and, after an explicit yes, use_case_approved done.
6. Create only after telling the human the build usually takes 15 to 20 minutes and getting a yes (ask before create): 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, ask the human, never retry. Do not wait: onboard report integrating in_progress, install the SDK, write the integration, but run no memory call yet.
7. Integrate on the chosen path. Follow reference/sdk-setup.md and the framework file. Done means (reference/integration-checklist.md): 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, set TimeoutConfig at init (about 5 s; the SDK has no per-call timeout), enforce the total deadline in the app (asyncio.wait_for or a worker thread), use bounded retries, never block the user turn if avoidable, never swallow a failure silently, and state what is lost; plus the rest of that checklist (redaction tested, ON/OFF startup log line, no test key in the live app, pinned versions, .env.example and README, tests for failure and 409). On the implicit path wire the whole stream (reference/streaming.md). Docs checkpoint: open each call's /sdk-reference page before writing it, re-read it after, and check parameters, the scope rule (user_id always; customer_id only on B2B) and errors. Before step 9 print a "Docs read" list: every page you actually OPENED, one line each on what it changed; step 9 is gated on /guides/production-checklist, /patterns/graceful-degradation, /sdk-reference/errors and each method page used.
8. Key. api-keys create -i <id> --write-env, then onboard report env_written done. Never print, paste or commit the key. Setup-key limit: it mints keys for and rebuilds ONLY instances this session created; on a reused instance api-keys create returns 403 instance_not_created_by_this_session (exit 5): say the exact sentence in reference/onboarding-details.md ("Setup-key limits"), never look for another way around it, and continue once the variable is in .env. 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 with exit 6 unless --force or a suffix). The app must read the matching variable (reference/sdk-setup.md, "Several instances"). Protect the build window: run the project's tests with env -u SYNAP_API_KEY ... (or the integration disabled) until verify has passed, and tell the human why: a memory call on a building instance is refused and may be lost.
9. Wait, then verify. Run instances wait <id> in the BACKGROUND (output to a log file; poll the log or onboard status). Only when it reports ready, run python scripts/verify_synap.py > verify.out 2>&1; echo "exit=$?" (prefix SYNAP_VERIFY_REQUIRE_STREAM=1 on the implicit path; add --suffix NAME for a suffixed key) and paste the WHOLE of verify.out unedited, WARN lines included (explain every WARN). It ends with RESULT: PASS or RESULT: FAIL <reason>, then EXIT CODE: <n>. Then run python scripts/check_integration_wiring.py <project dir> and paste it, drive the app's own endpoint with a sentinel and recall it through the app's own read code (or say that was not done), and say whether recalled text reaches a prompt. Every test or probe user id you create (project tests, sentinel, verify) is test_user_<purpose>_<8 random chars> (python scripts/cleanup_test_data.py --suggest-id <purpose>); write each one down.
10. Clean up test data, then announce. For exactly the ids you recorded run python scripts/cleanup_test_data.py --user-id <id> ... --dry-run, then the same without --dry-run, and paste both outputs; it touches only ids starting test_user_, never delete any other and never the human's real users. Announce in the session with the filled reference/final-report-template.md, the verbatim verify output, a line "Nothing was committed" and the list of files created and changed. A known defect you caused is fixed first or asked about. "Optional: view it in your dashboard" is never a step.
11. Sign out last, only if verify passed. Verify BEFORE auth logout: the dashboard shows a session finished only after the first memory and a useful recall, and an earlier sign-out shows 'ended before verification' (say so in the report if you cannot verify). Send every onboard report first, then <cli> auth logout, and say it is signed out ONLY if it exits 0 and reports revoked (exit 9 revocation_pending: retry, then an open item; see reference/onboarding-details.md). If verify failed, keep the key.

Until instances wait reports ready, run no ingestion or retrieval at all, including verify_synap.py. A refused call is HTTP 409 instance_not_ready. Handle BOTH forms: newer SDKs raise InstanceNotReadyError, older SDKs (including 0.5.16) raise a ConflictError whose message says the memory architecture is still being built. Catch the typed class first, then the message; never loop inside the call. The human's app gets it too: reads degrade to no memory, writes retry later (reference/sdk-setup.md).

Hard rules: the human never has to return to the dashboard; never guess; not stated for gaps; confirm before create; never create or delete workspaces or touch billing or members; never print or commit the key; never run git commit, git add -A, git push, git stash or an amend (leave changes uncommitted, new files untracked, for the human to review); never say "production", "prod", "staging" or "environment" about Synap to the human (for them there is just Synap; use --env silently); never show raw status words (building, failed, b2c, no_instance): translate with reference/instances-explained.md, and read the docs first for others.

Docs map and limits

Full docs list (CLI, production, errors): reference/docs-map.md (docs.maximem.ai, .md for clean text). The docs-reading rules in Step 0 and the checkpoint are NOT optional. Not covered: deciding B2C vs B2B, compliance or what to store (only the human decides); configuring MACA by hand (generated from the approved use-case, /concepts/memory-architecture); migrating from another vendor (/migrations/overview). https://docs.maximem.ai is the source of truth: if this skill conflicts with it, the docs win.