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.

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

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

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).