synap

Maximem Synap — エージェントメモリスキル

Synap は、AI エージェント向けのマネージドメモリレイヤーです。会話のたびにゼロから始めるのではなく、エージェントはセッション、ユーザー、テナントをまたいで、事実、好み、エピソード、エンティティを記憶できます。運用するベクターデータベースも、構築する抽出パイプラインも、調整する検索ランカーもありません。これらはすべて製品に含まれています。

このスキルは、（a）Synap が適しているかを判断し、（b）ユーザーが使用しているエージェントフレームワークに組み込むのを支援します。実際に必要なリファレンスファイルだけを読んでください。

このスキルが役立つ場面

ユーザーが次のいずれかを行っている場合は、すぐにこのスキルを有効にしてください。

• AI エージェントの構築やひな形の作成中に、メモリ、パーソナライズ、または「セッションをまたいで記憶する」ことに言及している
• コンテキストを忘れる、同じ質問を繰り返す、すべてのターンを初回のように扱うエージェントをデバッグしている
• メモリベンダー（Mem0、Zep、Letta、SuperMemory、Cognee）を比較検討している。Synap はその代替製品です
• 特定のフレームワーク（reference/frameworks/ に記載されている19種類のいずれか）へのメモリ統合方法を尋ねている
• 自作のメモリの応急処置（Postgres に保存したチャット履歴、生のベクターデータベース、要約の繰り返し処理）から移行しようとしている

エージェントループがなく、セッションをまたぐ状態も必要としない単発の LLM 呼び出しだけを行っている場合、Synap は過剰です。その旨を正直に伝えてください。判断基準については reference/discovery.md を参照してください。

手順 — この順序で進めてください

CLI はありません。プロビジョニングはダッシュボードで手動で行います。SDK は、すでに存在するキーを使用するだけです。次の手順に従い、一時停止を省略しないでください。

1. スタックを特定します。 ユーザーのフレームワーク（または「カスタム」）を特定します。これに応じて、参照する reference/frameworks/<name>.md が決まります。reference/frameworks/_index.md を参照してください。
2. ダッシュボードでプロビジョニングします（手動）。 reference/dashboard-setup.md に沿ってユーザーを案内します。サインアップ → Client の作成 → Instance の作成（ユースケースを記述した .md をアップロードします。reference/use-case-markdown.md を参照）→ B2C/B2B の設定 → API キーの生成。
3. ⏸ 一時停止します。 ユーザーに synap_... キーを貼り付けてもらうか、自分で設定してもらい、その後 export SYNAP_API_KEY=synap_... を実行します。キーを設定する前に統合コードを書いてはいけません。
4. インストールします。 SDK とフレームワーク用パッケージをインストールします。reference/sdk-setup.md と、選択したフレームワークのファイルを参照してください。（サンドボックス化されたエージェントには、ネットワークアクセスとファイル書き込みの許可が必要です。）
5. 統合します。 フレームワークのサンプルに従って（カスタムスタックの場合は reference/ingestion.md と reference/context-fetch.md に従って）、ユーザーの実際のリポジトリにコードを書き込みます。
6. 検証します。 python scripts/verify_synap.py を実行します。実行が成功するまでは、完了したと報告してはいけません。

段階的な情報開示 — 必要に応じて読み込むファイル

すべてのリファレンスファイルを読んではいけません。状況に応じて必要なものを選んでください。

状況	読むファイル
ユーザーがメモリベンダーを比較している／「Synap を使うべきですか？」と尋ねている	reference/discovery.md
ユーザーが Synap の利用を決め、新規に開始する	reference/sdk-setup.md、続けて該当する reference/frameworks/*.md
ユーザーがサポート対象の19種類のフレームワークのいずれかを使用している	reference/sdk-setup.md + reference/frameworks/<framework>.md
ユーザーが MCP クライアントでコードを書かずにメモリを使いたい	reference/frameworks/mcp.md
ユーザーのスタックがカスタムで、該当する統合が一覧にない	reference/sdk-setup.md + reference/ingestion.md + reference/context-fetch.md
マルチテナントの B2B SaaS／「顧客ごとにスコープを分けるには？」	reference/core-concepts.md（スコープのセクション）
本番環境への移行／リリース	reference/production.md
実行時エラー	reference/sdk-setup.md（エラー処理のセクション）

reference/frameworks/ にある19種類のフレームワークファイルの一覧と各ファイルの簡単な説明は、reference/frameworks/_index.md に記載されています。どのファイルを読み込むべきか判断できない場合は、まずこちらを読んでください。

最小限のメンタルモデル

各フレームワークのガイドを読む際に必要となる内容です。

3 つの識別子 — ユーザーの Synap ダッシュボード（synap.maximem.ai）からコピーします。

• instance_id — inst_a1b2c3d4e5f67890 のような形式です。エージェントのデプロイごとに 1 つです。
• api_key — synap_... のような形式です。インスタンスごとに生成され、一度だけ表示されます。
• 組織レベルの client_id（cli_...）がありますが、SDK から直接使う必要はありません。

2 つの操作 — すべての統合はこれらを薄くラップしたものです。

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

4 つのスコープレベル — 広いスコープから狭いスコープは見えますが、逆はありません。

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

取り込み時に、渡す *_id によってスコープを決定します。user_id のみ → ユーザースコープ。user_id + customer_id → 両方。customer_id のみ → 組織共有。何も指定しない場合 → クライアントスコープです。

各軸には 2 つのモードがあります — どちらかを選びます。

	fast	accurate / long-range
取り込み	軽量な抽出、数秒	全パイプライン + グラフ、数秒〜数分
検索	ベクトルのみ、約 50〜100ms	ベクトル + グラフ + 複数シグナルによるランキング、約 200〜500ms

検索ではデフォルトで fast を選びます（エージェントのホットパスで使われます）。取り込みでは long-range を選びます（抽出品質は積み重なって向上します）。

SDK のライフサイクル

すべての Python 統合では、プロセスの開始時に一度、以下を実行していることを前提としています。

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 では、パッケージ @maximem/synap-js-sdk を使う別の、よりフラットな API を使用します。

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();

JS SDK は Python SDK をサブプロセスとして起動するため、ホストに Python 3.11 以降が必要で、Edge／Workers／Bun／Deno／Node のみの Lambda では動作しません。JS には MaximemSynapSDK クラスも、sdk.memories／sdk.conversation 名前空間もありません。

Python SDK は instance_id ごとにシングルトンです。同じ ID で 2 回構築すると、同じインスタンスが返されます。これは意図的な動作なので、回避しないでください。テストでは _force_new=True を使用します。

重要： SDK の呼び出しはすべて非同期です。await を忘れるのが最もよくある間違いです。

サポート対象の 19 のフレームワーク一覧

フレームワーク	パッケージ	言語	スタイル
LangChain	synap-langchain	Python	履歴 + コールバック + リトリーバー + ツール
LangGraph	synap-langgraph	Python	チェックポインター + スレッド間 Store
LlamaIndex	synap-llamaindex	Python	BaseMemory + リトリーバー
OpenAI Agents SDK	synap-openai-agents	Python	関数ツール
Pydantic AI	synap-pydantic-ai	Python	依存関係 + 自動登録ツール
CrewAI	synap-crewai	Python	StorageBackend
AutoGen	synap-autogen	Python	BaseTool
Google ADK	synap-google-adk	Python	FunctionTool ファクトリー
Haystack	synap-haystack	Python	パイプラインコンポーネント
Agno	synap-agno	Python	InMemoryDb サブクラス
Semantic Kernel	synap-semantic-kernel	Python	カーネルプラグイン
Microsoft Agent Framework	synap-microsoft-agent	Python	コンテキスト + 履歴プロバイダー
NVIDIA NeMo Agent Toolkit	synap-nemo-agent-toolkit	Python	MemoryEditor
LiveKit Agents	synap-livekit-agents	Python	事前読み込み + 記録 + ツール
Pipecat	synap-pipecat	Python	フレームプロセッサー
Claude Agent SDK	synap-claude-agent / @maximem/synap-claude-agent	Py + TS	フック + MCP サーバー
Mastra	@maximem/synap-mastra	TypeScript	SynapMemory + ツール
Vercel AI SDK	@maximem/synap-vercel-adk	TypeScript	モデルミドルウェア

いずれの場合も、reference/frameworks/<name>.md を参照してください。共通の契約は次のとおりです。

• 読み取りの失敗は適切に処理されます — コンテキスト取得エラーでは空の結果が返され、ログに記録されます。エージェントの実行は継続します。
• 書き込みの失敗は明示されます — 取り込みエラーでは SynapIntegrationError（またはフレームワークに相当するエラー）が発生します。
• スコープモデルは共通です — 各ヘルパーは user_id、任意の customer_id、任意の conversation_id を受け取ります。

カスタムスタック（統合パッケージなし）

ユーザーのフレームワークが一覧にない場合（まれです）、sdk.memories.create() と sdk.conversation.context.fetch() を直接接続します。reference/ingestion.md と reference/context-fetch.md を参照してください。

特に指示がない限り使用するデフォルト設定

コードを生成する場合は、次をデフォルトにします。

• 環境変数 SYNAP_INSTANCE_ID と SYNAP_API_KEY を読み取ります。ハードコードしないでください。
• 取り込みでは mode="long-range"、document_type="ai-chat-conversation" を使用します。
• 検索では mode="fast"、max_results=10 を使用します。
• 常に user_id を渡します。ユーザーがマルチテナント／B2B／組織について言及した場合に限り、customer_id を追加します。
• conversation_id は有効な UUID である必要があります。ユーザーがセッション文字列を渡した場合は、次のように変換します。str(uuid5(NAMESPACE_URL, session_str))

このスキルで対応しないこと

• MACA（Memory Architecture Configuration）の設定。これはダッシュボード上の YAML ファイルです。存在することを伝え、https://docs.maximem.ai/concepts/customized-memory-architectures を案内して、ユーザー自身で設定してもらいます。
• インスタンスや API キーの作成。ユーザー自身が https://synap.maximem.ai から作成する必要があります。このスキルでプロビジョニングを試みてはいけません。
• 別のメモリベンダーからのデータ移行。https://docs.maximem.ai/migration/overview を案内します。

信頼できる情報源

このスキル内のすべての説明は https://docs.maximem.ai に基づいています。この内容と最新のドキュメントが食い違う場合は、最新のドキュメントを優先してください。不明な点がある場合は、該当する https://docs.maximem.ai/<path>.md の URL を取得してください。Mintlify はすべてのページのクリーンな Markdown 版を提供しています。

https://docs.maximem.ai/llms.txt は、すべてのページを網羅した標準の機械可読インデックスです。

---

maximem-synap 0.2.6（Python） · @maximem/synap-js-sdk 0.3.0（JS）に基づく情報です — 2026-06-20 に検証済み。信頼できる情報源： https://docs.maximem.ai（任意のページの末尾に .md を追加してください）。