supermemory

Supermemory v5

Supermemory はドキュメントを保存し、そこからメモリを抽出して、ランキング付きの検索結果、対象ごとに維持されるプロフィール、ソースのチャンクという3つの情報を返します。すべての呼び出しは1つの名前空間に限定されます。名前空間にはユーザー ID、プロジェクト ID、または分離したい任意の境界を指定できます。

このスキルが対象とするのはv5です。レガシーの v3 および v4 API は非推奨で、2026年12月31日に提供を終了します。コードベースに containerTag、customId、/v3/、/v4/ がある場合は、レガシー API を使用しています。npx supermemory@latest migrate を実行すると、アップグレードを行うコーディングエージェントが起動します。

このスキルが対応するバージョン

クライアント	バージョン	インストール
TypeScript SDK と CLI	supermemory 5.x	npm i supermemory
Python SDK	supermemory 5.x	pip install -U supermemory
フレームワークツール（Vercel AI SDK、OpenAI、Mastra、VoltAgent、Claude memory）	@supermemory/tools 3.x	npm i @supermemory/tools supermemory
Python フレームワークラッパー（supermemory-openai-sdk、supermemory-agent-framework、pipecat、livekit、cartesia）	依然としてレガシー API を使用	v5 リリースが提供されるまでは、コア Python SDK の使用を推奨します

コアモデル

• 名前空間：分離の境界です。1つのドキュメントが属する名前空間は必ず1つです。1つのリクエストで2つの名前空間を送信してはならず、ドキュメント ID からスコープを推測してはなりません。
• ドキュメント：追加するデータです。テキスト、URL、またはファイルを指定します。安定した id を設定し、同じ id を繰り返し指定すると、新しいドキュメントが作成されるのではなく、同じドキュメントに追加または差分が反映されます。会話にはこれを使用します。1つのセッション ID に、1つのドキュメントを対応させます。
• メモリ：ドキュメントから抽出される事実です。メモリを直接書き込むことはありません。ドキュメントを追加すると、エンジンがメモリを形成、更新し、バージョン管理します。
• プロフィール：名前空間の対象について維持される情報です。static な事実、dynamic な最近のコンテキスト、任意の名前付き buckets で構成されます。
• チャンク：ソーステキストの一部です。生のコンテンツを対象とする従来の RAG には、searchMode: "chunks" を使って検索します。
• 処理：add は { id, status } を返し、処理はバックグラウンドで続行されます。抽出とインデックス作成の状況は system.status で追跡できます。メモリの形成状況は system.dreamingStatus で追跡でき、完了まで数分かかる場合があります。デフォルトの dreaming: "dynamic" では、新しい名前空間で数分間、メモリが0件、プロフィールが空になることがあります。クイックスタート、テスト、または次の手順ですぐにメモリを読み込む必要がある場合は、dreaming: "instant" を使用してください。instant ではドキュメントごとに追加の操作が1回分課金されます。

正式な API サーフェス

ベース URL は https://api.supermemory.ai です。ルートはバージョンなしで、/v5 はパスのプレフィックスではありません。すべてのリクエストで、Authorization: Bearer sm_... による認証が必要です。

メソッドとパス	用途
POST /ns/{namespace}/document	テキストまたは URL を追加します
POST /ns/{namespace}/document/batch	1～600 件のドキュメントを追加します
POST /ns/{namespace}/document/file	ファイルをアップロードします（マルチパート）
GET /ns/{namespace}/document/{id}?include=chunks,memories	ドキュメントとそこから派生したデータを読み取ります
PATCH /ns/{namespace}/document/{id}	コンテンツまたはメタデータを更新します
POST /ns/{namespace}/document/file/{id}, PATCH .../file/{id}	ファイルドキュメントを置き換えるか、一部を更新します
{ "ids": [...] } を指定して DELETE /ns/{namespace}/document	1～100 件のドキュメントを削除します
POST /ns/{namespace}/search	メモリー、チャンク、またはその両方を検索します
POST /ns/{namespace}/profile	維持されているプロフィールを読み取ります
GET, PUT, DELETE /ns/{namespace}/profile/buckets	名前付きプロフィールバケットを管理します
POST /ns/{namespace}/list/{documents|chunks|memories}?page&limit&sort&order	ページ分割された一覧を取得します。本文で filter を指定することもできます
GET /ns/{namespace}/memories/{id}?include=related,documents	1 件のメモリーとその履歴を読み取ります
{ "ids": [...] } を指定して DELETE /ns/{namespace}/memories	指定したメモリーを削除します
{ "query", "dryRun" } を指定して DELETE /ns/{namespace}/memories/semantic	意味に基づいてメモリーを検索します。まずプレビューを表示します
GET /namespaces, GET /ns/{namespace}, PATCH /ns/{namespace}, DELETE /ns/{namespace}?moveTo=	名前空間の一覧表示、設定、削除、または移動
GET /connectors, /ns/{namespace}/connectors...	OAuth および設定用コネクター（Notion、Drive、ウェブクローラー、S3、...）
GET, PATCH /organization	組織全体の設定

パラメーターの指定場所：GET のオプションはクエリ文字列で指定します。POST、PATCH、PUT のオプションは JSON 本文で指定し、ファイルのアップロードではフォームフィールドを使います。一覧のページネーションはクエリ文字列で指定します。誤った場所に指定すると 400 が返されます。

SDK クイックスタート

両方の SDK に共通するルールは 1 つです。まず URL の値を位置引数として指定し（namespace、次に該当する場合は id）、その後に残りのすべての値を 1 つのオブジェクトにまとめて指定します。

import { Supermemory } from "supermemory"

const client = new Supermemory() // reads SUPERMEMORY_API_KEY

await client.add("user_alex", {
  content: "Alex prefers morning meetings and works in design.",
  id: "conv_2026_10_14",
  metadata: { source: "chat" },
  dreaming: "instant",
})

const { results } = await client.search("user_alex", { query: "when does Alex like to meet?", limit: 5 })
const { profile } = await client.profile("user_alex")

from supermemory import Supermemory

client = Supermemory()  # reads SUPERMEMORY_API_KEY

client.add("user_alex", content="Alex prefers morning meetings.", id="conv_2026_10_14", dreaming="instant")
response = client.search("user_alex", query="when does Alex like to meet?", limit=5)
profile = client.profile("user_alex")

メソッドの対応表（Python では同じメソッドが snake_case になります）：

呼び出し	エンドポイント
client.add(namespace, { content, id?, metadata?, supportingContext?, group?, date?, taskType?, dreaming? })	POST /ns/{ns}/document
client.search(namespace, { query, searchMode?, limit?, threshold?, filter?, include?, rerank?, rewriteQuery? })	POST /ns/{ns}/search
client.profile(namespace, { filter?, buckets? })	POST /ns/{ns}/profile
client.list(namespace, "documents" | "chunks" | "memories", { page?, limit?, sort?, order?, filter? })	POST /ns/{ns}/list/{type}
client.documents.get(namespace, id, { include? }), .update, .delete(namespace, { ids }), .batchAdd, .uploadFile, .replaceWithFile, .updateFile	/ns/{ns}/document...
client.memories.forget(namespace, { ids }), .forgetMatching(namespace, { query, dryRun })	/ns/{ns}/memories...
client.profiles.getBuckets, .setBuckets, .deleteBuckets	/ns/{ns}/profile/buckets
client.namespaces.list, .get, .update, .delete(namespace, { moveTo? })	/namespaces, /ns/{ns}
client.connectors.listAll, .list, .create, .get, .update, .delete, .sync	/connectors, /ns/{ns}/connectors...
client.organization.get, .update	/organization

検索オプション

オプション	値	デフォルト	用途
searchMode	hybrid、memories、chunks	hybrid	学習済みの事実にはmemories、ソーステキストを対象にしたRAGにはchunks、1つのランキングリストで両方を検索するにはhybridを使用します
threshold	0～1	0.3	精度を高めるには値を上げ、再現率を高めるには値を下げます
limit	整数	10
rerank	none、order、aggregate	none	orderは順序を並べ替え、aggregateは重複する結果を統合します
rewriteQuery	ブール値	false	曖昧なクエリや会話形式のクエリを拡張します
include	{ documents, related, forgotten }のブール値	すべてfalse	ソースドキュメント、関連するメモリのバージョン、または忘却されたメモリを付加します
filter	型付き式。下記参照	なし	メタデータによるフィルタリング

各結果には、id、memoryまたはchunk（場合によっては両方）、similarity、metadata、isLatest、isInference、systemのタイムスタンプ、および要求された場合はincludedが含まれます。フィールドの有無に応じて処理してください。

型付きフィルター

検索、プロフィール、一覧で共通のfilterオブジェクトを1つ使用します。JSON文字列は使いません。

filter: {
  operator: "and",
  operands: [
    { field: "source", operator: "eq", value: "slack" },
    { field: "priority", operator: "gte", value: 3 },
  ],
}

演算子：eq、neq、gt、gte、lt、lte、contains、notContains、arrayContains、arrayNotContains、およびoperandsを伴うand／or。フィールド名はそのままキーとして扱われます。customer.planは1つのキーであり、パスではありません。ネストは最大5階層、各グループのオペランドは最大200個です。

パターン

チャットボットまたはアシスタント。 回答の前に、継続的な事実にはprofile(namespace)を、関連するメモリにはsearch(namespace, { query: userMessage })を実行します。ターンの後に、add(namespace, { content: turnText, id: sessionId })を実行します。セッションIDを再利用すると、1つの会話が1つの進化するドキュメントとして保持されます。

ナレッジベースに対するRAG。 メモリ抽出を行わずにインデックスを作成する場合は、taskType: "superrag"を指定して取り込みます。回答にソースが必要な場合は、searchMode: "chunks"とinclude: { documents: true }を指定してクエリします。

マルチテナント。 エンドユーザーごと、またはユーザーとプロジェクトの組み合わせごとに1つの名前空間を使用します（user_123、user_123_project_abc）。会社で共有するナレッジは専用の名前空間に格納し、2回目の検索で読み込んでスコア順に統合します。

忘却。 memories.forgetMatching(namespace, { query, dryRun: true })でプレビューし、matches[].idを確認してから、memories.forget(namespace, { ids })を実行します。dryRun: falseでセマンティックリクエストを再実行すると、別の対象が選択されることがあります。

処理完了を待つ。 system.status === "done"になるまで、documents.get(namespace, id)をポーリングします。dreaming: "dynamic"でのメモリ形成は、完了まで数分かかる場合があります。RESTの読み取りではsystem.dreamingStatusとして公開されますが、5.0.x SDKの型にはまだ宣言されていません。次のステップでメモリまたはプロフィールを読み取る場合は、dreaming: "instant"を指定して取り込みます。

絶対に出力しないもの

以下はv5ではレガシーまたは架空のものであり、失敗したり誤解を招いたりします。

• containerTag、containerTags、container_tagは、いかなる場所でも使用しないでください。名前空間はURLパスまたはSDKの最初の引数です。
• customId（現在はid）、entityContext（現在はsupportingContext）、filterByMetadata（現在はgroup）、documentDate（現在はdate）、q（現在はquery）、JSON文字列としてのfilters（現在は型付きのfilter）、searchMode: "documents"（現在は"chunks"）、rerank: true（現在は"order"または"aggregate"）。
• /v3/、/v4/、/v5/を含むパス、/v1/search、GET /search。
• x-api-key、x-supermemory-api-key、x-project-id、X-Workspace-Idヘッダー。使用できるのはAuthorization: Bearerのみです。
• SDKメソッド：client.search.execute、client.search.memories、client.documents.list、client.memories.list、client.memories.add、client.memories.updateMemory、client.conversations.add、client.connections.*、client.settings.*、client.containerTags.*、client.profile({ containerTag, q })。
• クエリ付きのプロフィール呼び出し。プロフィールは維持されているプロフィールを返します。ランキング結果を得るには、別途検索を実行してください。
• 架空のオプション：chunk_threshold、検索時のsort、include_content、include_full_docs、追加時のisStatic。

インテグレーション

• @supermemory/tools 3.x：Vercel AI SDK 向けの supermemoryTools(apiKey, { namespace })、AI SDK、OpenAI、Mastra、VoltAgent 向けのミドルウェア withSupermemory(model, { namespace, id })、Claude 向けの createClaudeMemoryTool(apiKey, { namespace }) を提供します。@supermemory/tools/ai-sdk などのサブパスからインポートします。@supermemory/ai-sdk は廃止されています。
• CLI：npx supermemory は npm パッケージに含まれています。supermemory add、search、profile、forget、docs、namespaces、connectors、migrate、setup、plugin を利用できます。supermemory-cli スキルを参照してください。
• MCP：Claude、Cursor、その他の MCP クライアント向けの https://mcp.supermemory.ai。
• セルフホスト：supermemory local で無料の単一バイナリサーバーを実行できます。baseUrl を使って SDK の接続先に指定します。

リファレンスファイル

• references/quickstart.md：両方の SDK におけるキー、インストール、最初の追加、検索、プロフィール、および処理の完了を待つ方法。
• references/sdk-guide.md：すべての SDK メソッドのオプション、レスポンス、エラー、再試行、タイムアウト。
• references/api-reference.md：すべての REST エンドポイントのリクエストとレスポンスの形式、および cURL の例。
• references/sdk-integrations.md：@supermemory/tools とフレームワークの統合コード。
• references/use-cases.md：チャットボット、タスクアシスタント、RAG、サポート、マルチテナントアプリの完全な例。
• references/architecture.md：ドキュメントがメモリになる仕組み、バージョン管理、検索。

最新の正式情報：［v5 API リファレンス］(https://api.supermemory.ai/v5/reference)、［ドキュメント］(https://supermemory.ai/docs)、［v5 移行ガイド］(https://supermemory.ai/docs/migration/api-v5)、および［GitHub］(https://github.com/supermemoryai) 上の SDK README。