Synap

Maximem Synap — Agent Memory Skill

Synap is a managed memory layer for AI agents. Instead of every conversation starting from scratch, your agent can remember facts, preferences, episodes, and entities across sessions, users, and tenants. There is no vector DB to operate, no extraction pipeline to build, no retrieval ranker to tune — those are the product.

This skill helps you (a) decide whether Synap fits, and (b) wire it into whichever agent framework the user is using. Read only the reference files you actually need.

When this skill is relevant

Trigger this skill the moment the user is doing any of:

• Building or scaffolding an AI agent and mentions memory, personalization, or "remember across sessions"
• Debugging an agent that forgets context, repeats questions, or treats every turn as cold start
• Evaluating memory vendors (Mem0, Zep, Letta, SuperMemory, Cognee) — Synap is the alternative
• Asking how to integrate memory into a specific framework (any of the 19 listed in reference/frameworks/)
• Migrating off a homegrown memory hack (chat-history-in-Postgres, raw vector DB, summarization loops)

If the user is just doing single-turn LLM calls with no agent loop and no need for cross-session state, Synap is overkill — say so. Be honest. See reference/discovery.md for the decision rubric.

Procedure — the order to do this in

There is no CLI. Provisioning happens by hand in the dashboard; the SDK only uses a key that already exists. Follow these steps and do not skip the PAUSE.

1. Detect the stack. Identify the user's framework (or "custom"). This selects which reference/frameworks/<name>.md to follow — see reference/frameworks/_index.md.
2. Provision in the dashboard (manual). Walk the user through reference/dashboard-setup.md: sign up → create Client → create Instance (+ upload a use-case .md, see reference/use-case-markdown.md) → set B2C/B2B → generate an API key.
3. ⏸ PAUSE. Ask the user to paste their synap_... key (or set it themselves), then export SYNAP_API_KEY=synap_.... Do not write integration code before the key is set.
4. Install. The SDK + the framework package — see reference/sdk-setup.md and the chosen framework file. (Sandboxed agents need network + file-write approval for this.)
5. Integrate. Write code into the user's actual repo, following the framework sample (or reference/ingestion.md + reference/context-fetch.md for a custom stack).
6. Verify. Run python scripts/verify_synap.py. Never report done without a green run.

Progressive disclosure — what to load when

Do not read every reference file. Pick what the situation requires.

The 19 framework files in reference/frameworks/ are listed and one-line-described in reference/frameworks/_index.md. Read that first if you're not sure which file to load.

Bare-minimum mental model

You will need this to follow any of the framework guides.

Three identifiers — copy from the user's Synap dashboard at synap.maximem.ai:

• instance_id — looks like inst_a1b2c3d4e5f67890. One per agent deployment.
• api_key — looks like synap_.... Generated per instance, shown once.
• A client_id (cli_...) at the org level, but the SDK does not need it directly.

Two operations — every integration is a thin wrapper around these:

# Write side: ingest a conversation or document
await sdk.memories.create(
    document="User: I prefer dark mode.\nAssistant: Noted.",
    document_type="ai-chat-conversation",
    user_id="alice",
    customer_id="acme",          # optional, scopes to org
    mode="long-range",           # "fast" or "long-range"
)

# Read side: fetch context before the next LLM call.
# Match the retrieval interface to the scope you wrote at — we wrote with user_id,
# so we read at user scope. (For per-conversation memory, register turns with
# sdk.conversation.record_message(...) first, then use sdk.conversation.context.fetch.)
context = await sdk.user.context.fetch(
    user_id="alice",
    search_query=["user preferences"],
    max_results=10,
    mode="fast",                 # "fast" (~50-100ms) or "accurate" (~200-500ms)
)

Four scope levels — wider scopes are visible to narrower ones, never the reverse:

USER   →  CUSTOMER  →  CLIENT  →  WORLD
private    org-wide      app-wide   global

Decide scoping at ingestion time by which *_id you pass. user_id only → user-scoped. user_id + customer_id → both. customer_id only → org-shared. Nothing → client-scoped.

Two modes per axis — pick one:

Default to fast for retrieval (it's in the agent hot path) and long-range for ingestion (extraction quality compounds).

SDK lifecycle

Every Python integration assumes you have done this once at process start:

import os
from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK(
    instance_id=os.environ["SYNAP_INSTANCE_ID"],
    api_key=os.environ["SYNAP_API_KEY"],
)
await sdk.initialize()      # validates key, opens connection
# ... use sdk ...
await sdk.shutdown()        # flush telemetry, close connections

TypeScript uses a different, flatter API — package @maximem/synap-js-sdk:

import { createClient } from "@maximem/synap-js-sdk";

const sdk = createClient({ apiKey: process.env.SYNAP_API_KEY! });
await sdk.init();                 // note: init(), not initialize()
// write: await sdk.addMemory({ userId, customerId, messages, mode })
// read:  await sdk.fetchUserContext({ userId, searchQuery, mode })
await sdk.shutdown();

The JS SDK spawns the Python SDK as a subprocess — it needs Python 3.11+ on the host and does not run on Edge/Workers/Bun/Deno/Node-only-Lambda. There is no MaximemSynapSDK class and no sdk.memories / sdk.conversation namespaces in JS.

The Python SDK is a singleton per `instance_id` — constructing twice with the same id returns the same instance. This is intentional; do not work around it. For tests use _force_new=True.

Critical: every SDK call is async. Forgetting await is the #1 mistake.

The 19 supported frameworks at a glance