Semurg agent memory

Semurg

AI エージェント向けのメモリレイヤーです。ナレッジグラフ、ベクトル、グラフ RAG を単一のエンジンに搭載し、ゼロから構築しました。お使いのハードウェアで実行できます。このファイルでは、コーディングエージェント向けに、ノードのインストール方法、コーディングエージェントの接続方法、エージェントが MCP または HTTP 経由で呼び出すメモリツール、各クライアントでの同じ呼び出し方法、Semurg が公開する内容、ノード上で構築するアプリが従うルールを説明します。ここに記載するすべてのコマンド、ツール、ルート、クライアント呼び出しは、ソースから読み取り、このファイルの公開前にソースと照合し、公開する各リリースに対して実行しています。

ノードをインストールする

インストールする前にご確認ください。Semurg は、AVX2 以降に対応した Intel および AMD の x86_64 プロセッサーで動作し、2 CPU スレッドと 4 GB 以上のメモリが必要です。インストーラーを使用する場合は Ubuntu 24.04 で、Docker を使用する場合はその他の x86_64 Linux で動作します（インストーラーは別のシステムでは停止し、その環境で使える docker run コマンドを表示します）。現時点では Mac、Windows、ARM 向けのビルドはありません（同じリリースからビルドして提供予定です）。Mac または Windows マシンからは、接続可能な Linux マシンでノードを実行してください。Mac および Windows の Docker Desktop はテスト中です。インストーラーの実行には root 権限が必要です。

ご自身が管理する Linux マシンで、1 つのコマンドを実行します。最初の行は、スクリプトを実行せずに表示します。

curl -fsSL https://one.semurg.io/install | less
curl -fsSL https://one.semurg.io/install | sudo bash

インストーラーの最後に SUCCESS バナーが表示され、ノードの API トークンが出力されます。データディレクトリはローカルの ext4 または xfs ファイルシステム上に置く必要があります。インストーラーはこれを確認し、条件を満たさない場合は停止します。ノードを 1 つだけ使用する場合、ライセンスキーは不要です。

トークンをシェルに設定し、認証が有効であることを確認します（トークンなしでは 401、ありでは 200 が返ります）。

TOKEN=$(sudo grep '^SEMURG_API_TOKEN=' /etc/semurg/semurg.env | cut -d= -f2-)
curl -si http://127.0.0.1:4000/v1/whoami | head -1
curl -si -H "Authorization: Bearer $TOKEN" http://127.0.0.1:4000/v1/whoami | head -1

コーディングエージェントを接続する

Claude Code：ユーザースコープのエントリーを1つ、Claude Code 独自のコマンドで登録します。Claude Code を起動するシェルで実行してください。このエントリーに保存されるのは変数への参照だけであり、トークン自体は保存されません。アドレスには、新規インストールしたノードが提供するものを指定します。独自の TLS プロキシを経由する場合は、その https アドレスを使用してください。

export SEMURG_API_TOKEN=<the API token your node printed at install>
claude mcp add-json --scope user semurg '{"type":"http","url":"http://127.0.0.1:4000/v1/mcp","headers":{"Authorization":"Bearer ${SEMURG_API_TOKEN}","X-Semurg-Scope":"default"}}'
# Claude Code は起動時に SEMURG_API_TOKEN 環境変数からトークンを読み取ります

リリース r11.101.20261016.3097008 で接続を確認しました。このリリースで提供されるすべてのメモリツールが、Claude Code 独自のクライアントに一覧表示されました。

Claude Desktop：macOS と Windows で動作し、Semurg は Linux x86_64 で動作するため、ノードには次のいずれかの方法で 127.0.0.1:4000 から接続します。Windows マシンでは、同じマシン上の WSL2（Ubuntu 24.04）でノードを実行してください（Windows の Docker Desktop はテスト中です）。それ以外の場合は、Linux マシンでノードを実行し、ssh -N -L 4000:127.0.0.1:4000 you@your-node を使ってポートをデスクトップに転送してください。こうすれば、トークンがプレーンな HTTP でネットワークを通過することはありません。サインイン（OAuth）を使用する HTTPS 経由のリモートノードについては、まだここでは扱いません。Claude Desktop はローカル（stdio）の MCP サーバーのみを起動するため、npx（Node.js が必要）で実行する mcp-remote ブリッジを使って、ノードのストリーミング可能な HTTP エンドポイントに接続します。以下を claude_desktop_config.json（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）に記述し、 を実際のトークンに置き換えてから、Claude Desktop を再起動してください。このファイルにはトークンが保存されるため、他人に見られないようにしてください。

{
  "mcpServers": {
    "semurg": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:4000/v1/mcp",
               "--header", "Authorization:${SEMURG_AUTH}",
               "--header", "X-Semurg-Scope:default"],
      "env": { "SEMURG_AUTH": "Bearer <token>" }
    }
  }
}

結果は未確認です。他の MCP クライアントの場合：ノード上の POST /v1/mcp にストリーミング可能な HTTP で接続し、Authorization: Bearer ヘッダーを指定します。X-Semurg-Scope ヘッダーは任意です。各エージェントの設定：https://one.semurg.io/agents

MCP 経由のエージェントメモリ

エンドポイント：ノード上の POST /v1/mcp です。ストリーミング可能な HTTP で通信し、ノードの API トークンをベアラートークンとして受け取ります。任意の X-Semurg-Scope ヘッダーで、接続のデフォルトスコープを設定できます。

comms_bind_address を除くすべてのツールは scope を受け取ります。Namespace。同じノード上で同じスコープを使用するエージェントは、これらの事実を共有します。別のスコープはプライベートです。接続で X-Semurg-Scope ヘッダーを設定している場合は省略できます。

memory_status（読み取り専用）

このノードで共有メモリが有効かどうか、および事実が保存されている自分のスコープを報告します。scope を指定すると、そのスコープのオントロジーの概要も取得できます。そこには、保持しているエンティティ型と関係型の数、最も大きなクラス（最大50件）とそのメンバー数（members_bound が「exact」の場合は、忘却のたびに1つずつ減少する実際のメンバー数を示し、64メンバーを超える場合も正確です）、すでに使用している関係型（spellings に記載されたとおりの正確な表記で再利用してください）、および名前のマージモードが含まれます。読み取り専用です。他のメモリ呼び出しが失敗した場合は、最初に呼び出してください。

Parameters:

• user_id（string）：キー内のエンドユーザーを指定する場合に任意で設定します（1つのアプリに複数のエンドユーザーがいる場合）。指定すると、指定した各スコープはそのエンドユーザー専用となり、異なるエンドユーザー同士が交わることはありません。これは mem0 の user_id と同様にアプリレベルで分離するものです。ユーザーごとのトークンがセキュリティ境界となります。接続で X-Semurg-User ヘッダーを設定している場合、そのヘッダーがエンドユーザーとなり、異なる user_id は拒否されます。「:」は使用できません。最大256バイトです。

memory_remember（書き込み）

エージェントの記憶を保存します。あなたは抽出役です。テキスト（content または messages）を保存するときは必ず、見つけたエンティティと関係を facts として同じ呼び出しで送信してください。それらは一度に保存されます。また、このノードのローカルモデルよりも速く、優れた抽出ができます。このローカルモデルは、facts なしで送信されたテキストをバックグラウンドでCPU上でゆっくり読み取ります（モデルがインストールされていない場合は、まったく読み取りません）。

content：生テキスト（メモ、文書）を今すぐ保存します。文末で約100～200語の区切りに分割され、各区切りは、すでに保存されているか、横に facts として送信された、名前が記載されているエンティティにリンクされます。応答には extraction（facts を送信した場合は agent_facts、送信していない場合は known_names_only）、エンティティに到達しない区切りの数を示す unlinked_passages、および meaning が含まれます。ノードに埋め込みモデルがある場合は queued となり（区切りのベクトルは応答の直後に書き込まれ、memory_status に状態が表示されます）、モデルがない場合は not_armed となります（モデルがインストールされると区切りが埋め込まれます）。

facts を指定しない場合、ノードにインストールされている抽出モデルが応答後に保存済みのテキストを読み取り、エンティティ、タイプ、関係を追加します。各関係は、見つかった区切りを根拠として示します。model_extraction には、pending（ディスクへの書き込み待ち）、done（抽出済み）、failed（区切りの処理が3回失敗し、名前が示されます）、other_model（別のモデルで抽出済み）、not_installed、not_serving、または could_not_judge がモデル名とともに表示されます。facts を指定した場合、モデルは実行されません。

messages：会話 [{role, content}] を、1ターンにつき1行の単一テキストとして保存します。ターンをまたいで区切られることはありません。それ以外は content と同じです。

facts：自分で抽出したエンティティ [{name, type}] と関係 [{source, target, type}] です。たとえば、タイプは WORKS_AT です。タイプはクラスであり、大文字と小文字の違いを除いて一致します。

passages：後で検索するテキスト [{text, mentions, key?}] を、モデルを使わずに今すぐ保存します。mentions は、そのテキストが対象とするエンティティの名前です（指定された名前のとおりに保存されます。名前がテキスト内に大文字と小文字の違いを除いて出現しない場合、その区切りは名前とともに拒否されます）。memory_context は、該当するエンティティのいずれかに到達したとき、区切り全体を返します。content と passages は同じ呼び出しで指定できません。

date（ISO 8601形式。例：2026-10-01）は、これが述べられた日付です。呼び出しのソースとともに保持され、そのソースが返す内容とともに返されます。同じ内容を同じ日付で再度保存しても変更はなく、already が返されます。

1回の呼び出しで指定できる上限：エンティティ1,000件、関係5,000件、content 1,048,576バイト、テキスト合計1,048,576バイトを保持する区切り1,000件、mentions 合計1,000件。各区切りは最大65,536バイトです。名前、mention、key はそれぞれ最大1,024バイトです。

source は任意の出典ラベルで、呼び出し時に事実が想起されると、その事実とともに返されます。タイプや関係を新たに考案する前に、スコープを指定して memory_status を呼び出し、ontology.top_classes のクラスと ontology.relations の関係を再利用してください。表記は、それぞれの spellings に記載されたものと完全に同じにしてください（異なる表記は別の関係として扱われ、同じ事実が二重に保存されます）。各 remember 呼び出しでは、以前に保存したエンティティも含め、すべての関係の両端を entities に記載してください。 パラメーター：

• content (string)：記憶する生テキストです。保存時に文の区切りで分割されます。同じ呼び出しで、その中から見つけたエンティティと関係を facts として送信してください。
• date (string)：発言または事実が成立した日時です。ISO 8601 形式で指定します（2026-10-01 または 2026-10-01T09:30:00Z）。省略可能です。
• facts (object)：保存する内容からあなたが抽出したエンティティとその関係です。即時に保存され、モデルの実行はありません。
• messages (array)：1つのテキストとして記憶する会話です。各ターンを1行に記述します。content や passages と併用しないでください。
• passages (array)：後で再び見つけられるように、即時に保存するテキストです。各パッセージには、それに関するエンティティを指定します。
• source (string)：省略可能なソースラベルです（ファイル名など）。各引用では、ソース名として表示されます。同じラベルで後から送信した facts（かつ「date」がない場合）は、そのラベルで保存したドキュメントに関連付けられるため、引用にはそのテキストが引用されます。何も保存されていないラベル、date を指定した呼び出し、属性の現在値を変更する呼び出し、または8件を超えるドキュメントを示すラベル（1つのファイルを多数のパッセージとして保存した場合）は、それぞれ独自のソースとして扱われ、ラベルがソース名になります（返信の source_label_state には、関連付け済みの場合は attached、新しいソースの場合は new_source、日付付きの独自ソースの場合は dated_own_source、値が変更された独自ソースの場合は value_changed_own_source、多数のドキュメントに関連付けられない場合は many_documents_not_attached と示されます）。
• user_id (string)：キー内の省略可能なエンドユーザーです（1つのアプリに複数のエンドユーザーを設定できます）。この場合、指定する各スコープはそのエンドユーザー専用となり、異なるエンドユーザーが交わることはありません。アプリレベルの分離は mem0 の user_id と同様です。ユーザーごとのトークンがセキュリティ境界となります。接続で X-Semurg-User ヘッダーが設定されている場合、そのヘッダーがエンドユーザーとなり、異なる user_id は拒否されます。「:」は使用できません。最大256バイトです。

memory_recall（読み取り専用）

1 つのエンティティについて保存されている内容を想起します。subject で指定した名前と完全一致する名前、または類似した綴りや大文字・小文字の名前（「paris」なら Paris、「Dan」なら Dana）を持つエンティティ、あるいは長い名前に含まれる単語 1 つ（「Priya」なら Priya Raman。英語の小さな単語である「the」や「of」だけでは一致しません）を見つけ、そのエンティティからグラフをたどり、つながっている事実を両方向（direction は outbound または inbound）に返します。各事実には citation（citation.source：kind は document、テキストなしでエージェントが送信した事実の場合は asserted、その事実を読み取ったドキュメントの doc_id、保存時に付けられた name ラベル、ingested_at。citation.span：そのドキュメントから引用した文、およびドキュメント全文内での Unicode コードポイントによる start と end。提供前に検証されます。該当しない場合は null で、理由は span_state に示されます。citation.found_by：見つかった方法）、保存されている場合は source_date、および見つかったシード（seed：exact、name、type）が含まれます。常に最新の状態が反映されます。たった今保存された事実も表示されます。direction が derived（derived: true）の事実は保存されたものではなく、保存済みの事実から、その関係の意味に基づいて導かれたものです（対称関係：married_to、spouse_of、sibling_of。逆関係：parent_of と child_of、owns と owned_by、employs と employed_by、manages と managed_by。推移関係：最大 6 リンクまでの part_of、located_in、contained_in）。citation.found_by.reasoning には、適用されたルールと、その根拠となる保存済みの事実が記載され、それぞれの事実は単独でも想起できます。応答には state が含まれます。値は answered、nothing_stored（名前に一致するものがなかった場合。明示的に空の回答となり、決して捏造されません）、could_not_judge（ある段階を実行できなかった場合。その段階は detail に記載されます）のいずれかです。seeding は各段階で行われた処理を示します。埋め込みモデルが有効になるまでは、meaning は not_armed となり、意味による検索は利用できません。source_id はアイテムの元となったノードの ID です（パッセージの場合はそのチャンク、事実の場合は反対側のエンティティ、エンティティまたはタイプの場合はそのものです）。そのアイテムの情報源となったドキュメントの ID ではありません。ドキュメントの ID は citation.source.doc_id です。読み取り専用です。ID（source_id、seed_id、citation.source.doc_id）は、64 ビット符号なし整数の 10 進数文字列です。受け取ったままの値を変更せずに返し、数値に変換しないでください（JavaScript の Number では正確に保持できません）。

Parameters:

• as_of (string): この時点で把握されていた内容としてメモリを読み取ります（ISO 8601 の日付または日時。日付のみの場合は、その日の UTC 終了時点）：この時点より後に保存された事実は表示されません。現在の内容を読み取る場合は省略します。
• attribute (object): 名前ではなく、属性の現在値によってエンティティを検索します。例：{"key": "ndis_number", "value": "430000001"}（任意で "type" も指定できます）。検索対象はこのスコープのみで、user_id が設定されている場合はエンドユーザー自身のスコープです。subject の代わりに指定します。
• compact (boolean): true の場合、各アイテムを 1 回だけ返します（text、kind、事実の subject／relation／object、エンティティの属性（name: value 形式）、doc_id、source、date、score、seed）。取得診断情報（chunks、seeds、seeding、traversal）は含まれず、バイト数はごくわずかになります。完全な応答が必要な場合は省略します。
• k (integer 1 to 1000): 返す事実の最大数。
• subject (string): 想起するエンティティ名。完全一致、または類似した綴りや大文字・小文字の名前を指定します。
• user_id (string): 任意のキー内のエンドユーザー（1 つのアプリに複数のエンドユーザー）：名前を指定したすべてのスコープは、そのエンドユーザー専用となり、2 人のエンドユーザーが交わることはありません。mem0 の user_id と同様のアプリレベルの分離です。ユーザーごとのトークンがセキュリティ境界として維持されます。接続で X-Semurg-User ヘッダーが設定されている場合、そのヘッダーがエンドユーザーを示し、異なる user_id は拒否されます。「:」は使用できず、最大 256 バイトです。
• valid_at (string): これまでに把握された内容にかかわらず、この時点で何が真実だったかを読み取ります（ISO 8601）。as_of と併用した場合は、as_of 時点までに把握されており、valid_at 時点で真実だった内容を読み取ります。

memory_relate（書き込み）

スコープ内の2つのエンティティ間に、型付きのエッジを1つ追加します。たとえば、Alice から Bob への MENTORS 型のエッジです。新しいエンティティは作成されます。エッジが物理的に存在するかどうかを返します。

パラメーター：

• from（string、必須）
• to（string、必須）
• type（string、必須）：関係の種類です。例：WORKS_AT。
• attributes（object）：この関係に保存される、型付きの属性です（role、frequency、ISO 日付形式の valid_from / valid_to）。エンティティの属性と同じルールに従います：{"role": "guardian_nominee", "valid_from": "2026-03-01"}。
• replaces（boolean）：true の場合、この関係は、同じ種類の他の保存済みの対象（works_at、owned_by、reports_to、lives_in）を置き換えます。それらの関係は、この呼び出しの日付（または現在の日付）で終了し、それより前の valid_at / as_of を指定すると引き続き読み取れます。古い関係を後から再び指定すると、その関係が復元されます。応答の replaces には、終了したもの（ended）、復元されたもの（restored）、保存済みの関係より古い関係（older_than_stored。履歴に保持され、新しい関係の開始時点で終了します）、およびリンクが多すぎて全件読み取れない対象（unread、状態は could_not_judge）が一覧表示されます。他の関係に追加する関係（knows、visited）では、このパラメーターを省略してください。
• user_id（string）：任意のキー内のエンドユーザーです（1つのアプリに複数のエンドユーザーがいる場合）。指定すると、名前を指定するすべてのスコープはそのエンドユーザー専用となり、エンドユーザー同士が接触することはありません。mem0 の user_id と同様に、アプリレベルで分離されます。ユーザーごとのトークンがセキュリティ境界となります。接続で X-Semurg-User ヘッダーが設定されている場合、そのヘッダーがエンドユーザーとなり、異なる user_id は拒否されます。「:」は使用できず、最大256バイトです。

memory_forget（書き込み）

スコープ内の項目を忘れさせます。1 回の呼び出しにつき 1 つだけです（subject、fact、passage、source、all、attribute のいずれかを正確に 1 つ送信します）。subject：正確な名前で指定するエンティティです。エンティティ、そのスコープ内での位置、所属する型、両端にそのエンティティがあるすべての事実、およびその名前を含む保存済みのすべてのパッセージが削除されます。そのため、想起、コンテキスト、型の検索、パッセージ検索では返されなくなります。応答には passages_hidden の数と documents_retained（他のテキストが残る保存済みドキュメント）、および passages_retained（passages_retained_why 付き）の数が含まれます。passages_retained は、名前の一部の単語を含むものの、そのエンティティに紐付けられたことのない、まだ有効なパッセージの数です。これらは、パッセージ形式またはソース形式で忘れさせるまで残ります。fact：{from, to, type}。その事実だけが対象です。両方のエンティティは残ります。passage：remember 動詞が返した doc_id です。その保存済みドキュメント全体（チャンク、エンベロープ、カタログエントリー）が対象です。そこに記載された事実とエンティティは残ります。source：ドキュメントが保存されたラベル（remember の source）です。その配下に保存されたドキュメントすべてが、パッセージ形式の場合と同様に、全体として対象になります。それらが示した事実は残ります（facts_kept: true）。一度も保存されたことのないソースは 404 になります。all：スコープとともに all: true を送信すると、スコープ全体を忘れさせます。スコープ内のすべてのエンティティ、事実、ドキュメント、パッセージと、スコープ自体が 1 回の呼び出しで対象になります（応答には件数と、残るものが示されます）。存在したことのないスコープは 404 になります。エンティティ名は完全一致です。一致しない場合、呼び出しは 404 で拒否され、確認用に近い名前が最大 3 件（「Did you mean」）提示されます。近い名前は候補として示されるだけで、忘れさせることはありません。忘れさせる操作は冪等です。すでに忘れさせたものを再度指定すると、同じ 200 と already_forgotten: true が返り、書き込みは行われません。一度も存在したことのない項目は 404 になります。後でそれを指定して remember すると、再び登録されます。このノードのどの経路からも、忘れさせたデータにはアクセスできません。ただし、現時点では物理的に消去されていません。忘れさせたデータをディスクから消去する処理はまだリリースされておらず、リリースされるまでは、ノードのディスクまたはバックアップにアクセスできる人なら誰でも、バイト列を読み取れます。reason は受け付けられますが、保存されません。

パラメーター：

• all (boolean)：スコープ形式です。true にすると、scope で指定したスコープ全体（その中のすべてのエンティティ、事実、ドキュメント、パッセージ、およびスコープ自体）を忘れさせます。存在したことのないスコープは 404 になります。同じ呼び出しを繰り返すと、already_forgotten が返ります。
• attribute (object)：属性形式です：{"subject": "", "key": ""}：その属性 1 つ（複数値のキーの場合はすべての値）を忘れさせます。エンティティと、その他の属性は残ります。
• fact (object)：事実形式です。忘れさせる事実を、memory_relate が受け取った形式で指定します。両方のエンティティは残ります。
• passage (string)：パッセージ形式です。保存済みドキュメントについて remember 動詞が返した doc_id を、10 進数の STRING として、応答どおり正確に指定します（ID は 64 ビット整数です。2^53 を超える値を JSON の数値として扱うと、ほとんどのクライアントではすでに桁が失われています）。
• reason (string)
• source (string)：ソース形式です。ドキュメントが保存されたラベルを指定します。そのラベルの配下に保存されたドキュメントはすべて全体として忘れさせられます。ただし、同じテキストが別のソースにも保存されている場合は、その別のソースの下には残り、そこからこのラベルだけが削除されます（documents_kept）。そのドキュメントが示した事実は残ります。
• subject (string)：エンティティ形式です。忘れさせるエンティティの正確な名前を指定します（綴りが近い名前は 404 で提示されますが、忘れさせることはありません）。
• user_id (string)：キー内に指定する省略可能な END USER（1 つのアプリに複数のエンドユーザーがいる場合）です。指定すると、名前を指定するすべてのスコープはそのエンドユーザー固有のものになり、2 人のエンドユーザーが互いに交わることはありません。mem0 の user_id と同様のアプリレベルの分離です。ユーザーごとのトークンがセキュリティ境界として残ります。接続で X-Semurg-User ヘッダーが設定されている場合、そのヘッダーがエンドユーザーとなり、異なる user_id は拒否されます。':' は使用できません。最大 256 バイトです。

memory_context（読み取り専用）

質問や数語に関連する記憶の内容を、順位付けして取得します。各項目には citation が付きます（1つのスコープに対する GraphRAG。引用には、その項目の情報源となった文書名と、そこから引用した文が含まれます）。query 内で保存済みエンティティを示すすべての単語またはフレーズ（完全一致、類似したつづりや大文字・小文字の違い、長い名前の単語全体1つ（「Priya Raman」に対する「Priya」など）、または単語の先頭部分（「Pri」など））、あるいは保存済みのタイプ（「どの会社」など）がシードになります。「the」「of」「is」「who」「tell」「me」「about」のような短い英単語が、それ単独で一致することはありません。シードからグラフを hops 回たどり、順位付けされた事実と、それに言及する文章が、本文、citation（citation.source：文書の場合は kind が document、エージェントがテキストなしで送信した事実の場合は asserted。読み取り元の文書の doc_id、保存時のラベルである name、ingested_at。citation.span：その文書から引用した文、全文における Unicode コードポイント単位の start と end。提供前に検証されます。span_state に理由を示し、引用箇所がない場合は null。citation.found_by：見つかった方法）、source_date、および各項目を見つけたシードとともに返されます。モデルは呼び出されません。返された内容をもとに回答を書き、citation.source.doc_id を引用してください（citation.span.text を引用します）。一致するものがない場合、state は nothing_stored となり、items は空になります（seeding に各段階で行ったことが示されます）。実行できなかった段階がある場合、could_not_judge にその段階が示されます。direction が derived（derived: true）の事実は保存されたものではありません。保存済みの事実と関係の意味から導かれたものです（対称関係：married_to、spouse_of、sibling_of。逆関係：parent_of と child_of、owns と owned_by、employs と employed_by、manages と managed_by。推移関係、最大6リンク：part_of、located_in、contained_in）。citation.found_by.reasoning には、根拠となるルールと保存済みの事実が示され、それぞれ単独で取得できます。埋め込みモデルが有効化されるまでは、meaning は not_armed のままです。質問と名前を共有しない言い換えは、有効化されるまでは見つかりません。有効化後は、質問が埋め込まれ、このスコープの文章が名前と単語の情報源とともにスコアリングされます（文章のベクトルがまだ揃っていない間は、seeding.meaning に ran と、coverage が incomplete であることが示されます）。名前による制限が2つあります。エンティティ名（ラベル）と事実の文は埋め込まれないため、文章を伴わずに保存した事実は meaning では見つかりません。また、meaning 検索で正確に検索できるのは、スコープあたり最大10,000件の文章までです。それを超えると、スコープごとのインデックスが利用可能になるまでは、件数を示す could_not_judge が返され、部分的な一覧は返されません。meaning だけによる一致は、埋め込みモデルで調整されたコサイン類似度の下限を超える必要があります。対象について何も記憶していない場合は、最も近い文章ではなく、nothing_stored が返されます。保存済みの名前が、より長い質問と一般的な単語を1つ共有するだけでも、質問への回答であるかのように返されることがあります（フランスについての質問で「capital」が保存済みの「Capital One」と一致するなど）。回答を信頼する前に、返答の grounding を確認してください。grounded は、引用された1つの項目が質問の内容語をすべてカバーしていることを意味します（複数の項目にまたがってのみカバーされる単語は related となり、reason は covered_only_across_items です）。grounded_by_meaning は、保存済みエンティティと完全一致する名前も、その文章にない名前も含まない言い換えの質問に対し、MEANING で見つかった引用付き文章が答えていることを意味します（共有されない単語は uncovered に列挙されます。質問に名前がある対象についての meaning ヒットは、その対象について述べているだけでは回答にならないため related です）。文章を読み、実際に答えている場合はそこから回答してください。related（uncovered の単語と、related として一致した保存済みの名前を含む）、uncited、nothing_stored、could_not_judge は、事実が質問に答えていないことを意味します。そのため、それらをもとに回答せず、その旨を伝えてください。source_id は、項目の元となるノードのIDです（文章の場合はそのチャンク、事実の場合は反対側のエンティティ、エンティティまたはタイプの場合はそのものです）。情報源となった文書のIDではありません。文書のIDは citation.source.doc_id です。読み取り専用です。ID（source_id、seed_ids、citation.source.doc_id）は、64ビット符号なし整数を表す10進数の文字列です。そのまま返し、数値に変換しないでください（JavaScript の Number ではこの値を正確に保持できません）。 パラメーター：

• query（文字列、必須）：質問またはいくつかの単語です。照合対象となるのは、その中のエンティティ名とタイプを表す単語です（一致、類似した綴りや大文字・小文字の違い、より長い名前に含まれる単語全体、または単語の先頭部分）。「the」や「of」のような短い英単語は、それ単独では照合されません。
• as_of（文字列）：この時点で把握されていた内容としてメモリーを読み取ります（ISO 8601 の日付または日時。日付のみの場合は、その日の UTC での終わり）。この時点より後に保存された事実は表示されません。今は指定しないでください。
• compact（ブール値）：true の場合、各項目を一度だけ返します（テキスト、種類、事実の主語／関係／目的語、エンティティの属性を「名前：値」の形式で、doc_id、ソース、日付、スコア、シード）。取得診断情報（チャンク、シード、シード処理、たどった経路）は含まれず、バイト数を大幅に節約できます。完全な返信が必要な場合は指定しないでください。
• hops（整数 0～3）：照合したエンティティからどこまでたどるかを指定します（デフォルトは 2）。
• k（整数 1～100）：返す事実の最大数を指定します（デフォルトは 8）。
• user_id（文字列）：キー内のエンドユーザーを指定する任意の項目です（1 つのアプリに複数のエンドユーザーがいる場合）。指定すると、指定したスコープはすべてそのエンドユーザー専用となり、異なるエンドユーザー同士が接触することはありません。アプリレベルの分離は mem0 の user_id と同様です。ユーザーごとのトークンがセキュリティ境界として維持されます。接続で X-Semurg-User ヘッダーが設定されている場合、そのヘッダーがエンドユーザーを指定し、異なる user_id は拒否されます。「:」は使用できません。最大 256 バイトです。
• valid_at（文字列）：それまでに把握されていた時期にかかわらず、この時点で真だった内容を読み取ります（ISO 8601）。as_of と併用すると、as_of 時点で把握されており、valid_at 時点で真だった内容を読み取ります。

memory_document（書き込み）

ドキュメント（PDF、Word の .docx、HTML ページ、UTF-8 テキストファイル）を 1 回の呼び出しでメモリーに保存します。ファイルのバイト列はこのノードのカスタム領域に格納され、テキストが解析されます（段落、見出し、リスト項目の順序を保持します。PDF の段落は行ごとではなく、ページレイアウトから再構成されます）。テキストは remember 動詞で content を保存する場合とまったく同じ形式で保存され、バイト単位で読み戻された後にのみ、ファイルがカスタム領域から削除されます。テキストが 16384 バイト以下の場合、応答には doc_id（後続の引用で指定するソース ID。10 進数の STRING）、解析済みの text（引用オフセットはこのテキストを基準とします）、および blocks（各ブロックのページ、段落、テキスト内のバイト範囲）が含まれます。それを超える場合は、代わりに text_bytes と block_count が含まれます（テキスト全体は保存され、recall と context で検索できます）。また、customs.emptied も含まれます。ファイルは content_base64（標準 base64）として送信してください。デコード後のサイズは最大 5000000 バイトです。name はファイルに付けて保存するラベルです（任意）。種類はファイル名ではなく、ファイル自体の先頭バイトから判定されます。これらの種類のドキュメントではないファイルは、保存処理の前に拒否されます（415）。途中で切れている、または破損しているドキュメントは、名前を指定して拒否され（document_corrupt、422）、何も保存されません。暗号化された PDF またはスキャンされた PDF は document_not_readable（422）となります。

パラメーター：

• content_base64（文字列、必須）：ドキュメントのバイト列を標準 base64 で指定します。
• name（文字列）：ドキュメントの名前です。出所を示すラベルとして保存されます（任意）。
• user_id（文字列）：キー内のエンドユーザーを指定する任意の項目です（1 つのアプリに複数のエンドユーザーがいる場合）。指定すると、指定したスコープはすべてそのエンドユーザー専用となり、異なるエンドユーザー同士が接触することはありません。アプリレベルの分離は mem0 の user_id と同様です。ユーザーごとのトークンがセキュリティ境界として維持されます。接続で X-Semurg-User ヘッダーが設定されている場合、そのヘッダーがエンドユーザーを指定し、異なる user_id は拒否されます。「:」は使用できません。最大 256 バイトです。

memory_export（読み取り専用）

スコープに含まれるすべてを、呼び出しごとに1ページずつエクスポートします。next が null になるまで、前の応答の next を cursor として送信します。各レコードは JSON オブジェクトです（.jsonl ファイルには1行に1つ記述します）。entity（名前、タイプ、valid_from を含む現在の属性）、fact（主語、関係、目的語、両端のタイプ、関係の属性、日付付きのソース、ended_at と replaced_by を含む current または ended の状態）、document（保存されたテキストごとに1回、その有効な箇所を順番に、日付とソースラベルとともに含みます。忘れられた箇所はエクスポートされません）、および最初のページの export ヘッダーで構成されます。memory_import はこれらのレコードを任意のスコープに取り込みます。読み取り専用です。limit はページごとに処理するカタログ項目数です（既定値は256、最大1024）。

Parameters:

• cursor (string): 前ページの next をそのまま指定します。最初のページでは省略します。
• limit (integer 1 to 1024): このページで処理するカタログ項目数（既定値は256）。
• user_id (string): キー内のエンドユーザーを指定する任意の値です（1つのアプリに複数のエンドユーザー）。指定すると、名前を指定する各スコープはそのエンドユーザー専用となり、エンドユーザー同士が交わることはありません。mem0 の user_id と同様にアプリレベルで分離されます。ユーザーごとのトークンがセキュリティ境界となります。接続で X-Semurg-User ヘッダーが設定されている場合、そのヘッダーがエンドユーザーとなり、異なる user_id は拒否されます。: は使用できません。最大256バイトです。

memory_import（書き込み）

memory_export が生成したレコードを（任意のページを任意の順序で。ページを2回送信しても重複して保存されません）、remember と同じ書き込み方式でスコープに保存します。文書はテキスト、日付、ソースラベルとともに、エンティティはタイプと属性とともに、ファクトは日付付きのソースとともに保存されます。また、終了済みのファクトは ended_at の時点で再度終了済みとして保存されるため、履歴は元の状態で読み取れます。応答にはインポート件数、スキップされた各レコード（skipped：インデックスと理由）、およびインポートで再現されない内容（not_reproduced）が含まれます。1回の呼び出しにつき最大4096レコードです。

Parameters:

• records (array, required): memory_export が返したものと完全に同じレコードです。
• user_id (string): キー内のエンドユーザーを指定する任意の値です（1つのアプリに複数のエンドユーザー）。指定すると、名前を指定する各スコープはそのエンドユーザー専用となり、エンドユーザー同士が交わることはありません。mem0 の user_id と同様にアプリレベルで分離されます。ユーザーごとのトークンがセキュリティ境界となります。接続で X-Semurg-User ヘッダーが設定されている場合、そのヘッダーがエンドユーザーとなり、異なる user_id は拒否されます。: は使用できません。最大256バイトです。

comms_bind_address（書き込み）

name@<cluster domain> 形式のアドレスを、あなた自身（トークンの ID、または user_id で指定するエンドユーザー）に割り当てます。これにより、このクラスター上の人間やエージェントが名前であなたにメッセージを送信できます。人間とエージェントは同じ呼び出しでアドレスを割り当てます。kind でどちらであるかを指定します（既定値は user）。冪等性があります。同じアドレスを再度割り当てると、bound: "already" が返されます。名前による割り当ては、address_invalid（ASCII の英字、数字、., -, _, + のみ使用可能で、@ はちょうど1つ）、domain_not_ours（クラスターのドメインは修正内容に記載されています）、address_taken（他者に割り当て済み）、kind_invalid の理由で拒否されます。書き込みには API トークンが必要です。

Parameters:

• address (string, required): 割り当てるアドレス（name@<cluster domain>）。大文字と小文字は区別されません（[email protected] = [email protected]）。
• kind (string): 割り当てる主体の種類です。user（人間。既定値）または agent です。
• user_id (string): キー内のエンドユーザーを指定する任意の値です（1つのアプリに複数のエンドユーザー）。指定すると、アドレスはそのエンドユーザーのものになります。接続で X-Semurg-User ヘッダーが設定されている場合、そのヘッダーがエンドユーザーとなり、異なる user_id は拒否されます。

HTTP で同じ動詞を使う

各ルートは、同じ名前のツールと同じフィールドを含む JSON ボディと、ヘッダー Authorization: Bearer <token> を受け取ります。

GET /v1/memory/status
POST /v1/memory/remember
POST /v1/memory/recall
POST /v1/memory/relate
POST /v1/memory/forget
POST /v1/memory/context
POST /v1/memory/document
POST /v1/memory/delete_user
POST /v1/memory/export
POST /v1/memory/import
POST /v1/memory/audit

どちらの例も、リリース r11.83.20261013.c03a884 の初期状態のノードで実行し、各回答を読み返しています。r11.101 では再実行していません。例では http://127.0.0.1:4000 を使用しています。これは初期状態のノードが提供するアドレスです。独自の TLS プロキシの背後で使用する場合は、代わりにその https アドレスを使用してください。SEMURG_API_TOKEN に、ノードの API トークンを設定してください。

curl -sS http://127.0.0.1:4000/v1/memory/remember \
  -H "Authorization: Bearer $SEMURG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scope":"demo","facts":{"entities":[{"name":"Acme","type":"Company"},{"name":"Dana","type":"Person"}],"relations":[{"source":"Dana","target":"Acme","type":"WORKS_AT"}]},"source":"curl example"}'

curl -sS http://127.0.0.1:4000/v1/memory/recall \
  -H "Authorization: Bearer $SEMURG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scope":"demo","subject":"Dana"}'

クライアント

11 言語に対応したアーカイブは https://one.semurg.io/dl/clients.tar.gz にあります。CONNECTING.md は、クライアントをノードに接続する方法を説明するガイドです。クライアントには、ノードのベース URL とトークンを指定します。各クライアントが定義しているメモリ呼び出しは、それぞれ次の名前です。

• Python (clients/python/semurg/client.py): memory_status, remember, recall, relate, forget, context
• Go (clients/go/semurg/client.go): MemoryStatus, Remember, Recall, Relate, Forget, Context
• Java (clients/java/src/main/java/io/semurg/client/SemurgClient.java): memoryStatus, remember, recall, relate, forget, context
• C# (clients/csharp/Semurg.Client/SemurgClient.cs): MemoryStatus, Remember, Recall, Relate, Forget, Context
• F# (clients/fsharp/Semurg.Client.FSharp/Client.fs): memoryStatus, remember, recall, relate, forget, context
• Elixir (clients/elixir/lib/semurg/client.ex): memory_status, remember, recall, relate, forget, context
• Erlang (clients/erlang/src/semurg_client.erl): memory_status, remember, recall, relate, forget, context
• Rust (clients/rust/src/client.rs): memory_status, remember, recall, relate, forget, memory_context
• Julia (clients/julia/src/client.jl): remember, recall, context
• C++: このクライアントにはまだメモリ呼び出しがありません。HTTP 経由でアクセスします（clients/cpp/src/client.cpp で確認済み）。
• OCaml (clients/ocaml/lib/client.ml): memory_status, remember, recall, relate, forget, context

ダウンロードして、リリースに付属するチェックサムと照合してください。

curl -fsSLO https://one.semurg.io/dl/clients.tar.gz
curl -fsSLO https://one.semurg.io/dl/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS

パッケージ：公開状況

Semurg が公開しているのは、one.semurg.io（インストーラー https://one.semurg.io/install、バンドル https://one.semurg.io/dl/semurg-r11-installer.tar.gz、https://one.semurg.io/dl/SHA256SUMS による検証対象、および上記のクライアントアーカイブ）と、以下に記載する公開レジストリのみです。それ以外では公開していません。MCP サーバーはノードに組み込まれています（上記の POST /v1/mcp）。インストールは不要です。

公開レジストリで公開中：

PyPI：

pip install semurg==0.1.1

one.semurg.io（コンテナイメージ）：

docker pull one.semurg.io/semurg:latest

現在、Semurg は npm、crates.io、NuGet、Hex、Maven Central、Go module proxy、Julia General レジストリ、opam、MCP レジストリではパッケージを公開していません。これらのレジストリで Semurg のものを名乗るパッケージは、当社のものではありません。インストールしないでください。

ノード上でのアプリの構築

アプリには2種類あります。EXTERNAL アプリは、言語や Web フレームワークを問わず、ノードのパブリック API（メモリルート、/v1/ingest、/v1/query とその操作、MCP ツール、またはクライアント）を通じて、ノードにデータを保存します。ノードがそのストアであり、以下の内容は該当しません。まずは今日、この種類のアプリを構築してください。IN-NODE アプリは、ノードに同梱される機能（Semurg が「パック」と呼ぶもの）を使ってノード内で実行される Elixir 拡張機能です。構成チェックに合格した場合に限り、Marketplace を通じて公開されます（チェックはすでに利用できますが、IN-NODE アプリの公開とインストールの仕組みは現在も構築中です）。以下の各ルールは、IN-NODE アプリに限り、チェックによって適用されます。

• アプリ独自のデータベースは持ちません。ノードがストアであり、アプリはノードのパブリックな読み取り・書き込み API を通じてのみアクセスします。
• アプリが基盤として使えるのはパックのみです。別のアプリやノード内部の仕組みを基盤にすることはできず、アプリとパックの連鎖がループすることもありません。
• 複数のパックをまたいで使用できるのは、各パックが公開すると宣言した機能だけです。
• Web インターフェースには Phoenix LiveView を使用します。コントローラーのみ、または JSON のみのインターフェースは受け付けられません。

ページ

• https://one.semurg.io/: Semurg は、AI エージェントやエージェントフレームワーク向けのメモリレイヤーです。MCP または通常の HTTP を通じて共有するメモリはセッション終了後も保持され、ナレッジグラフ、ベクトル検索、グラフ RAG を組み込み、RAM より大きな容量で、お使いのハードウェア上で動作します。10 のデータドメインに対応した、ゼロから作り上げた単一のエンジンです。各ドメインの性能を公開環境で測定しています。最初のノードは永久に無料です。
• https://one.semurg.io/agents: AI エージェント向けの共有メモリです。MCP または通常の HTTP を通じて、同じストア内の事実や関係性を記憶、想起、関連付け、忘却できます。このストアはグラフ、ベクトル、検索処理にも対応します。
• https://one.semurg.io/develop: 1つのエンジンでベクトル RAG とグラフ RAG を構築できます。データのコピーは1つだけで、ベクトルとグラフの両方を扱えます。データを書き込むと関係性も記録され、新たに習得するクエリ言語もありません。
• https://one.semurg.io/commands: Semurg がユーザーやコーディングエージェントに実行を案内するすべてのコマンドを、ソースから読み取り、公開される各リリースに対して実行します。このファイルをページとして公開しています。
• https://one.semurg.io/blog: Semurg のブログです。お知らせ、エージェントや開発者向けのハウツーガイド、エンジニアリングの掘り下げ記事、オピニオン記事を掲載しています。すべての数値に、その記録へのリンクがあります。
• https://one.semurg.io/models: オープンな言語モデルと検索モデルを掲載しています。リリース記録から生成され、1ユーザーあたりの速度と、多数のユーザー全体での速度を示します。
• https://one.semurg.io/scale: 利用期限のない最初の無料ノードから始め、容量に応じてノードのライセンスを追加できます。ノードはあくまでノードです。ライセンスはコア数、メモリ容量、ディスク容量によって変わりません。
• https://one.semurg.io/performance: 書き込み、読み込み、走査、スキャンの性能を、各リリースでクラスター全体にわたって測定しています。各数値の根拠として、マシン、接続経路、同時実行数、使用率、データの配信元を示し、リリース間の推移も掲載しています。
• https://one.semurg.io/benchmark: Semurg r11.118～r11.121 において、グラフ、ドキュメント、ベクトル＋グラフ RAG を Neo4j、ArangoDB、FalkorDB、ArcadeDB、SurrealDB などと比較測定しています。同じ質問、同じ回答、同じマシンを使い、勝った項目だけでなく、劣った項目もすべて示しています。
• https://one.semurg.io/durability: Semurg ノードが強制終了した場合、ディスク容量がいっぱいになったり、動作が遅くなったりした場合、あるいは停電した場合に、データがどうなるかを説明します。公開済みのリリースで測定し、まだテストを実行していない項目は結果待ちとして示します。
• https://one.semurg.io/cloud: Semurg Cloud では、Semurg をインストール済みの専用サーバーをレンタルできます。1台のマシンにつき1顧客で、ログインにはお客様の SSH キーのみを使用し、アップデートは Marketplace から提供されます。近日公開予定です。
• https://one.semurg.io/pricing: ノードごとの定額ライセンスです。ハードウェアの使用期間中有効な買い切り、または5年間の稼働期間にわたって生涯価格を分割した年額プランをお選びいただけます。最初のノードは永久に無料です。サポートは任意で、年間料金は生涯価格の定価の20％です。アップデートは Marketplace から無料で入手できます。
• https://one.semurg.io/consulting: Semurg 上に、組織向けのエンタープライズ環境を一式構築します。組織のデータベース、オブジェクトストア、ドキュメントをオントロジー付きの1つのナレッジグラフに同期し、お客様のハードウェア上で永続的に動作するエージェントを構築します。料金はお問い合わせください。ノードライセンスは別途ご購入いただきます。
• https://one.semurg.io/install: インストーラーをダウンロードし、公開済みのチェックサムと照合して、ご自身のマシン上でノードを実行できます。最初のノードは永久に無料です。アカウント登録、アップロード、ホームへの通信は不要です。
• https://one.semurg.io/contact: Semurg を構築した2人にご相談ください。[email protected] にメールをお送りください。すべてのメッセージを担当者が確認し、返信します。取り組んでいることや、エンジンに求める機能をお聞かせください。