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.

Situation	Read
User is comparing memory vendors / asking "should I use Synap?"	reference/discovery.md
User has decided on Synap and is starting fresh	reference/sdk-setup.md then the relevant reference/frameworks/*.md
User is using one of the 19 supported frameworks	reference/sdk-setup.md + reference/frameworks/<framework>.md
User wants memory in an MCP client (no code)	reference/frameworks/mcp.md
User has a custom stack with no listed integration	reference/sdk-setup.md + reference/ingestion.md + reference/context-fetch.md
Multi-tenant B2B SaaS / "how do I scope per customer"	reference/core-concepts.md (scopes section)
Going to production / shipping	reference/production.md
Errors at runtime	reference/sdk-setup.md (error handling section)

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:

	fast	accurate / long-range
Ingestion	Lightweight extraction, seconds	Full pipeline + graph, seconds-to-minutes
Retrieval	Vector only, ~50-100ms	Vector + graph + multi-signal rank, ~200-500ms

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";

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

| Framework | Package | Language | Style |
| --- | --- | --- | --- |
| LangChain | `synap-langchain` | Python | History + callback + retriever + tools |
| LangGraph | `synap-langgraph` | Python | Checkpointer + cross-thread Store |
| LlamaIndex | `synap-llamaindex` | Python | `BaseMemory` + retriever |
| OpenAI Agents SDK | `synap-openai-agents` | Python | Function tools |
| Pydantic AI | `synap-pydantic-ai` | Python | Deps + auto-registered tools |
| CrewAI | `synap-crewai` | Python | `StorageBackend` |
| AutoGen | `synap-autogen` | Python | `BaseTool` |
| Google ADK | `synap-google-adk` | Python | `FunctionTool` factory |
| Haystack | `synap-haystack` | Python | Pipeline components |
| Agno | `synap-agno` | Python | `InMemoryDb` subclass |
| Semantic Kernel | `synap-semantic-kernel` | Python | Kernel plugin |
| Microsoft Agent Framework | `synap-microsoft-agent` | Python | Context + history providers |
| NVIDIA NeMo Agent Toolkit | `synap-nemo-agent-toolkit` | Python | `MemoryEditor` |
| LiveKit Agents | `synap-livekit-agents` | Python | Preload + recording + tools |
| Pipecat | `synap-pipecat` | Python | Frame processors |
| Claude Agent SDK | `synap-claude-agent` / `@maximem/synap-claude-agent` | Py + TS | Hooks + MCP server |
| Mastra | `@maximem/synap-mastra` | TypeScript | `SynapMemory` + tools |
| Vercel AI SDK | `@maximem/synap-vercel-adk` | TypeScript | Model middleware |

For any of these, jump to `reference/frameworks/<name>.md`. They share a contract:

- **Read failures degrade gracefully** — context fetch errors return empty results and log; the agent keeps running.
- **Write failures surface explicitly** — ingestion errors raise `SynapIntegrationError` (or framework equivalent).
- **Same scoping model** — every helper accepts `user_id`, optional `customer_id`, optional `conversation_id`.

## Custom stack (no integration package)

If the user's framework isn't in the list (rare), they wire `sdk.memories.create()` and `sdk.conversation.context.fetch()` directly. See `reference/ingestion.md` and `reference/context-fetch.md`.

## Defaults to use unless told otherwise

When generating code, default to:

- Read environment variables `SYNAP_INSTANCE_ID` and `SYNAP_API_KEY`. Never hardcode.
- Ingestion `mode="long-range"`, `document_type="ai-chat-conversation"`.
- Retrieval `mode="fast"`, `max_results=10`.
- Always pass `user_id`. Add `customer_id` only if the user mentions multi-tenant / B2B / orgs.
- `conversation_id` must be a valid UUID — if the user passes a session string, wrap it: `str(uuid5(NAMESPACE_URL, session_str))`.

## What this skill does NOT do

- Configure MACA (Memory Architecture Configuration). That's a YAML file in the dashboard. Mention it exists; point to `https://docs.maximem.ai/concepts/customized-memory-architectures` and let the user configure it themselves.
- Create instances or API keys. The user must do this from `https://synap.maximem.ai`. The skill should never attempt to provision.
- Migrate data from another memory vendor. Point to `https://docs.maximem.ai/migration/overview`.

## Authoritative source

Every claim in this skill is grounded in `https://docs.maximem.ai`. If something here conflicts with the live docs, the live docs win. When in doubt, fetch the relevant `https://docs.maximem.ai/<path>.md` URL — Mintlify serves a clean markdown version of every page.

`https://docs.maximem.ai/llms.txt` is the canonical machine-readable index of all pages.

---
*Accurate as of `maximem-synap` 0.2.6 (Python) · `@maximem/synap-js-sdk` 0.3.0 (JS) — verified 2026-06-20. Source of truth: https://docs.maximem.ai (append `.md` to any page).*