Frinus

Frinus MCP Server

φρήν + νοῦς — Frinus プラットフォームを利用して、Claude エージェントに長期的な認知メモリを提供します。

frinus-mcp は、MCP（Model Context Protocol）サーバーです。MCP クライアントである Claude Code、Cursor、Claude Desktop と、https://frinus.rdxsec.com.br でホストされている Frinus プラットフォームをつなぐブリッジです。

単独では動作しません。ローカルには何も保存せず、すべてのツール呼び出しを HTTPS 経由で Frinus アカウントに転送します。そのため、役立つ機能を使うには、次の2つが必要です。

1. Frinus アカウント（無料、カード不要）、および
2. Frinus API キー（sk-frinus-...）。

これらを用意すると、認知メモリ、ワーキングメモリ、セッション、エージェント、L0～L3 のナレッジ階層、オーケストレーションタスク、トレーニングパイプラインを網羅する70個のツールをサーバーが提供します。stdio に対応しており、MCP 対応のあらゆるクライアントで動作します。

• バージョン： 3.8.0
• ツール： 70個（ツールリファレンスを参照）
• プラットフォーム： https://frinus.rdxsec.com.br（ホスト型 SaaS — このサーバーが接続するバックエンド）
• npm パッケージ： frinus-mcp

仕組み

+-------------------+        +--------------+        +----------------------------+
| Your MCP client   | stdio  | frinus-mcp   | HTTPS  | Frinus platform            |
| (Claude Code,     | <----> | (this server,| <----> | frinus.rdxsec.com.br       |
|  Cursor, Desktop) |        |  via npx)    |        | (your memories live here)  |
+-------------------+        +--------------+        +----------------------------+

サーバーは起動時にプラットフォームに対して API キーを検証し、アカウントと組織を特定して、すべてのツール呼び出しをそこに転送します。API キーがない場合、サーバーは起動を拒否します。

ルール0 — MCP は必須です

Frinus MCP は、エージェントの長期メモリ、アイデンティティ、インテリジェンスそのものです。これがなければ、モデルはセッションをまたいで状態を保持できません。Frinus と連携するすべての Claude エージェントは、次のことを行う必要があります。

1. 会話の開始時に MCP ツール（例：session_start、memory_search、search_with_attention）にアクセスできることを確認します。
2. アクセスできない場合は、警告をユーザーに伝えます：「MCP Frinus が接続されていません。長期メモリ機能は利用できません。」
3. 些細な挨拶以外に回答する前に、**BOOT プロトコル（P1）**を実行します。
4. 生産的なセッションを終える前に、memory_store を使って学習内容を保存します。

プロトコル一式はグローバルな CLAUDE.md（Frinus 組織）に記載されています。以下の7つのプロトコルに要約しています。

始める前に — アカウントと API キー

Frinus アカウントと API キーが必要です。どちらも無料で取得できます。

1. 無料アカウントを作成する

https://frinus.rdxsec.com.br で登録します。まず始めるには、**Free プラン（R$0）**で十分です。

• メモリ100件
• 1日あたり20クエリ
• クレジットカード不要

2. API キーを生成する

ログインしたら、アカウントの Settings → API Keys を開き、新しいキーを作成します。次のような形式の値が発行されます。

sk-frinus-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

今すぐコピーしてください。セキュリティ上、この値が表示されるのは一度だけです。この値を、以下の FRINUS_API_KEY 環境変数に設定します。パスワードのように扱い、リポジトリにコミットしないでください。

始め方（ゼロから最初のメモリまで）

5分、4つのステップで完了します。

ステップ1 — アカウントを作成する

https://frinus.rdxsec.com.br で登録します（Free プラン、カード不要）。上記を参照してください。

ステップ2 — API キーを生成する

Settings → API Keys → 作成。sk-frinus-... の値をコピーします。上記を参照してください。

ステップ 3 — サーバーをクライアントに追加する

インストールは不要です。npx が必要に応じてパッケージを取得し、実行します。指定する必要があるのは API キーだけです。プラットフォームの URL はすでに本番環境を指すように設定されています。

Claude Code（ワンライナー）：

claude mcp add frinus --env FRINUS_API_KEY=sk-frinus-... -- npx -y frinus-mcp@latest

Cursor / Claude Desktop / 任意のクライアント（設定 JSON）：

{
  "mcpServers": {
    "frinus": {
      "command": "npx",
      "args": ["-y", "frinus-mcp@latest"],
      "env": {
        "FRINUS_API_KEY": "sk-frinus-..."
      }
    }
  }
}

設定ファイルの場所：

• Claude Code： ~/.claude.json の mcpServers 内。
• Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）／~/.config/claude/claude_desktop_config.json（Linux）。または、ワンクリックで使える .mcpb 拡張機能を利用し、API キーを貼り付けるだけです。
• Cursor： ~/.cursor/mcp.json の mcpServers 内。

新しいサーバーを読み込ませるため、クライアントを再起動してください。

sk-frinus-... をステップ 2 で取得した実際のキーに置き換えてください。通常、設定するのは FRINUS_API_KEY のみです。すべてのバックエンド URL は、ホスト型プラットフォームを指すように設定されています。全項目とセルフホスト時の上書き方法については、環境変数を参照してください。

ステップ 4 — 最初のメモリーで動作を検証する

クライアントで、エージェントに何かを保存して思い出すよう依頼します。

Store this in Frinus memory: "Our staging DB is reset every night at 02:00 UTC."

次に、同じセッションまたは後のセッションで以下を依頼します。

What time does our staging DB reset?

内部では、エージェントが memory_store を呼び出した後、memory_search ／ search_with_attention を呼び出します。思い出した内容が返ってくれば、ブリッジは正常に動作しています。同じメモリーがウェブアプリ（https://frinus.rdxsec.com.br）にも表示されることを確認できます。

環境変数

通常の使用では、設定するのは FRINUS_API_KEY のみです。サービス URL はすでにホスト型プラットフォームを指しているため、セルフホストする場合を除き変更しないでください（詳細 — セルフホストを参照）。

変数	デフォルト値（ホスト型プラットフォーム）	説明
FRINUS_API_KEY	必須	個人用 API キー（sk-frinus-...）。起動時にアカウントと組織を特定します。
MEMORY_SERVICE_URL	https://frinus-memory.rdxsec.com.br	Memory Engine のベース URL
FRINUS_CP_URL	https://frinus-api.rdxsec.com.br	Control Plane のベース URL（アカウント、組織、API キー、請求）
AGENT_SERVICE_URL	https://frinus-agents.rdxsec.com.br	Agent Service のベース URL（エージェント、呼び出し、スキル）
FRINUS_MEMORY_API_KEY	—	FRINUS_API_KEY のレガシーフォールバック

起動時にサーバーはプラットフォームに対して API キーを検証し、組織とログイン中のユーザーを特定します。検証に失敗すると、サーバーは [FATAL] とともに処理を中止し、クライアントにエラーを表示します。Settings → API Keys でキーを再確認してください。

7 つのプロトコル

プロトコル	タイミング	ツール	目的
P1 — BOOT	各セッションの開始時	session_start、working_memory_get、search_with_attention	アイデンティティ、直近の状態、関連するコンテキストを読み込む
P2 — CONSULT	あらゆるアクションの前	search_with_attention、session_context、memory_reinforce、memory_weaken	関連するメモリーを取得、評価、強化する
P3 — PLAN	タスクの計画時	memory_store(procedural)、working_memory_add、stream_capture	計画、作業状態、アーキテクチャ上の決定を永続化する
P4 — CAPTURE	2～3 回のやり取りごと	heartbeat_tick、working_memory_add、memory_store(episodic)、stream_capture	進捗、バグ、パターンを継続的に記録する
P5 — LEARN	新しい知識が得られたとき	training_teach、training_qa、training_stats、stream_process、sleep_run	事実や手順を教え、統合サイクルを実行する
P6 — AUDIT	メンテナンス時	consolidation_detect_conflicts、consolidation_resolve_conflict、consolidation_detect_redundant、hierarchy_consolidate	矛盾や重複を検出し、メモリーを統合する
P7 — CLOSE	セッションの終了時	session_summary、stream_process、memory_store、hierarchy_consolidate、session_end	要約し、ストリーム項目を昇格させ、学習内容を永続化する

詳細なプロトコルスクリプトは、エージェントの CLAUDE.md にあります。上の表を、Frinus と統合されたすべてのエージェントが守るべき契約として扱ってください。

ツールリファレンス

ドメイン別に分類された70個のツールです。すべてのツールはテキストコンテンツを返します。ペイロードはMCPのTool仕様に従います。完全なJSONスキーマはsrc/tools/definitions.tsにあります。

メモリ（7）

認知的な長期記憶：エピソード記憶（起きたこと）、意味記憶（知っていること）、手続き記憶（物事の進め方）。

ツール	説明
memory_store	メモリを作成します。agent_idとcontentは必須です。memory_type ∈ {episodic, semantic, procedural}。scope ∈ {user, agent, universe, organization}。importanceは0～1です。
memory_search	意味的類似性で検索します。フィルター：agent_id、memory_types、limit。
memory_get	memory_idでメモリを取得します（全コンテンツ、メタデータ、関連度）。
memory_list	agent_idのメモリを、任意の種類フィルターを指定して一覧表示します。
memory_delete	memory_idでメモリを完全に削除します。
memory_reinforce	有用なメモリの関連度を高めます（memory_id、boost 0～1、デフォルトは0.1）。
memory_weaken	古くなったメモリの重みを下げます（memory_id、penalty 0～1、デフォルトは0.2）。

作業メモリ（3）

短期的で、コンテキストに紐づく状態です。ミラーの法則：コンテキストごとに最大7項目で、最も古い項目は自動的に削除されます。デフォルトのTTLは30分（最大2時間）です。

ツール	説明
working_memory_get	コンテキストの現在の状態を読み込みます。タスク開始時には必ず呼び出してください。
working_memory_add	現在の状態を永続化します。コンテキスト形式：agent:{uuid}、universe:{uuid}、organization:{uuid}。
working_memory_clear	コンテキストの全項目を削除します。

セッション（5）

セッションは、ストリーム、作業メモリ、キャプチャをまとめる論理コンテナです。

ツール	説明
session_start	エージェントのセッションを開始します。session_idを返します。サブエージェントへの継承にはparent_session_idを指定できます。
session_end	セッションを終了し、要約を確定します。
session_context	作業メモリと長期記憶の取得結果を組み合わせ、抽出されたセッションのトピックで補強します。
session_summary	構造化された要約（決定事項、学び、保留中の項目）を生成します。
session_clear	セッションを終了せずに、その作業状態を消去します。

ストリーム（4）

継続的なキャプチャパイプラインです。項目はバッチ処理され、スコア付けされたうえで、重要なものが永続メモリに昇格されます。

ツール	説明
stream_capture	セッションに紐づく入力／出力／内部メモを記録します。
stream_get_session	session_idでキャプチャされたすべての項目を再生します。
stream_get_recent	セッションをまたいだ最近のストリーム項目を取得します（フィルター可能）。
stream_process	保留中の項目を長期記憶に昇格させます（手動で実行。スケジューラーも5分ごとに実行します）。

コンテキストとアテンション（2）

ツール	説明
memory_get_context	タスクの説明に合わせて、トークン数の上限内に収まるコンテキストウィンドウを構築します。
search_with_attention	タスクの種類を考慮した重み付けによるRAGです。task_type ∈ {implementation, debug, deploy, documentation, review}によって、memory_typeの重みを決定します。

ユーザー（2）

ツール	説明
user_register	メモリシステムにユーザーを登録します（冪等）。
user_get_context	ユーザーメモリとテナントコンテキストを組み合わせて取得します。

メンテナンス（2）

ツール	説明
heartbeat_tick	エージェント向けの軽量なティックです。関連度の減衰と軽量な統合を進めます。
sleep_run	スリープサイクルを実行します。phases ⊆ {evaluation, forgetting, consolidation, relevance}。スケジューラーの通常スリープ／深いスリープを再現します。

統合（3）

ツール	説明
consolidation_detect_conflicts	類似度のしきい値を超える、競合の可能性があるメモリを提示します。
consolidation_resolve_conflict	一方のメモリを保持し、もう一方を文書化された解決メモで置き換えます。
consolidation_detect_redundant	統合または削除の候補となる、ほぼ重複した項目を見つけます。

メモリ階層（2）

ツール	説明
hierarchy_consolidate	関連する複数のメモリを、より上位の要約メモリにまとめます。
hierarchy_get_tree	ルートメモリの統合ツリーを確認します。

エージェント（6）

エージェントの CRUD と、オーケストレーションによる呼び出しを行います。

ツール	説明
agent_create	ユニバースまたはチームの範囲内で、エージェントを作成します（テンプレートから作成することもできます）。
agent_list	呼び出し元のテナントに属するエージェントを一覧表示します。API キーによってスコープが自動設定されます。
agent_get	agent_id でエージェントを取得します。
agent_update	ペルソナ、チーム、ユニバースなどを更新します。
agent_delete	エージェントを削除します。
agent_invoke	タスクを指定してエージェントをプログラムから呼び出します。ツール呼び出しと最終回答を返します。委任に使用します。

ユニバース（4）

ユニバースとは、テナントの範囲内にあるナレッジドメインです。L0〜L3 の階層を保持します。

ツール	説明
universe_create	呼び出し元の組織にユニバースを作成します。スラッグ、名前、説明を指定します。
universe_list	解決された組織のユニバースを一覧表示します。
universe_update	ユニバース（名前、説明）を更新します。
universe_hierarchy	ステータスアイコン付きで、ユニバースの L0 → L3 ツリー全体をたどります。

ナレッジ階層 L0〜L3（16）

Universe
  └─ Concept   (L0)  body of knowledge
       └─ Theme  (L1)  thematic split
            └─ Topic   (L2)  unit of work (status: pending / in_progress / completed)
                 └─ Point   (L3)  atomic knowledge unit

各レベルで create、list、update、delete を利用できます。

• L0 概念：concept_create、concept_list、concept_update、concept_delete
• L1 テーマ：theme_create、theme_list、theme_update、theme_delete
• L2 トピック：topic_create、topic_list、topic_update、topic_delete
• L3 ポイント：point_create、point_list、point_update、point_delete

topic_update と point_update は status フィールドを受け付け、エージェントが進捗を記録できます。

トレーニングパイプライン（6）

ファクト、手順、Q&A ペア、ドキュメント全体を使って、システムを明示的にトレーニングします。

ツール	説明
training_teach	ファクトまたは手順を追加します。type ∈ {semantic, procedural}。
training_qa	{question, answer} の pairs を使ってトレーニングします。
training_stats	コーパス全体のカバレッジ統計を表示します。
training_gaps	検出されたナレッジの不足や、カバーが不十分なトピックを表示します。
training_recent	トレーニングで直近に取り込まれたメモリを表示します。

オーケストレーション — タスク（4）

Memory Engine のタスクテーブルが、マルチエージェントのオーケストレーションを制御します。

ツール	説明
task_create	タスク（タイトル、説明、任意の assigned_agent_id、親タスク）を作成します。
task_get	タスクを完全な状態とともに取得します。
task_list	フィルター（ステータス、エージェント、親）を指定してタスクを一覧表示します。
task_update	ステータス、出力、割り当てを更新します。

スキル（4）

エージェントに割り当てる再利用可能な動作です。

ツール	説明
skill_list	テナントで利用可能なスキルを一覧表示します。
skill_assign	エージェントにスキルを割り当てます。
skill_remove	エージェントからスキルを解除します。
skill_agent_list	指定したエージェントが所有するスキルを一覧表示します。

認証情報保管庫（5）— credential_exec ブローカー

Control Plane に暗号化して保存した認証情報を、メモリから credential_ref で参照します。

ツール	説明
credential_store	認証情報を暗号化して参照名（例：mysql_x）のもとに保存します。
credential_get	シークレット以外のメタデータのみ（ホスト／ユーザー／DB／ポートと、credential_exec が注入する環境変数）を確認します。値は返しません。
credential_exec	認証情報を子プロセスの環境変数に注入して、コマンドを実行します。 stdout／stderr／exit_code のみを返し、シークレットがモデル、画面、ディスクに渡ることはありません。
credential_list	保存済みの認証情報の参照名を一覧表示します（シークレットデータは含みません）。
credential_delete	保存済みの認証情報を削除します。

シークレット取り扱いの原則 — サーバー側のブローカーで扱い、値として渡さない。モデルがシークレットの値を受け取ることはありません。平文、一時ファイル、シークレットを含むシェルスニペットも渡しません。認証情報を使用するには、credential_exec を呼び出します。MCP サーバー（npx -y frinus-mcp@latest でローカルですでに実行中）が保管庫から認証情報を取得し、その各フィールドを子プロセスの環境変数に注入します。argv に含めることも、モデルが目にするテキストに含めることもありません。コマンドは shell:false（シェルインジェクションなし）で実行し、出力のみを返します。

// MYSQL_PWD / MYSQL_USER / MYSQL_HOST are pre-injected → standard clients just work
credential_exec(ref="mysql_prod", argv=["mysql", "-e", "SELECT 1"])
credential_exec(ref="pg_prod",    argv=["psql",  "-c", "SELECT 1"])

// For anything else, read the injected vars inside an explicit shell:
credential_exec(ref="jira_x", argv=["sh","-c",
  "curl -sS -H \"Authorization: Bearer $CRED_TOKEN\" \"$CRED_BASE_URL/whoami\""])

認証情報に含まれる場合に注入される環境変数：password／secret／token → MYSQL_PWD、PGPASSWORD、CRED_PASSWORD；user／username → CRED_USER、MYSQL_USER、PGUSER；host → CRED_HOST、MYSQL_HOST、PGHOST；port → CRED_PORT、MYSQL_TCP_PORT、PGPORT；database → CRED_DATABASE、PGDATABASE；その他のスカラー値 → CRED_<UPPER_SNAKE>（例：base_url → CRED_BASE_URL）。argv は文字列の配列でなければなりません（シェルコマンド文字列は不可。どうしてもシェルが必要な場合は ["sh","-c","..."] を使用してください）。タイムアウトは 30s、出力上限は 256 KiB です。すべて npm パッケージに含まれています。ユーザーは何もインストールせず、PATH を編集せず、追加のコマンドも実行する必要はありません。必要なのは、最新状態の MCP だけです。

メモリの種類

種類	用途	例
episodic	発生したことを記録する	Bug: payment endpoint returned 500. Cause: missing null check on customer.address. Fix: guard + 422 response. File: services/payment.py
semantic	事実や知識を保存する	`MemoryResponse now includes universe_id (UUID
procedural	手順を記録する	Procedure: rotate-claude-credentials. Steps: 1) aws ecr login, 2) kubectl set image deployment/agent..., 3) verify pod is Ready. Caveat: deployment is named "agent", not "agent-service".

スコープ

スコープ	可視範囲	用途
user	保存したユーザーのみ	個人の好みや履歴
agent	保存したエージェントのみ	エージェント専用のメモ
universe	ユニバース（部門）内のすべてのエージェント	共有ドメイン知識
organization	テナント内のすべてのエージェント	組織全体の手順や事実

旧来の agent / project / global スコープは、project_id とともに廃止されました。組織内の分離境界として、プロジェクトに代わりユニバースが導入されました。

ベストプラクティス

メモリに必要な形式 — 今後の検索結果を一定にするために使用します。

• バグ： Bug: <description>. Cause: <root cause>. Fix: <solution>. File: <path>
• パターン： Pattern: <description>. When to use: <context>. File: <path>
• 手順： Procedure: <name>. Steps: 1) ... 2) ... 3) .... Caveats: <warnings>

運用ガイドライン：

1. 必ず最初に起動します。 回答する前に、session_start + working_memory_get + search_with_attention を呼び出します。
2. 使用時に強化／弱化します。 呼び出したメモリが役立った場合は memory_reinforce を実行します。誤っていた場合は memory_weaken を実行し、置き換えます。
3. 2～3ターンごとに記録します。 状態には working_memory_add、決定事項には stream_capture、明確になった知見には memory_store を使用します。
4. 適切な task_type を選択します。 search_with_attention はタスクに応じてメモリの種類に重み付けします。debug ではエピソード記憶、documentation では意味記憶、deploy では手続き記憶が優先されます。
5. 最後まで処理します。 セッションを終了する際は session_summary + stream_process + session_end を実行します。バッチが大きくなったら、より深く統合するために sleep_run を実行します。
6. 不要な情報が増える前に監査します。 定期的に consolidation_detect_conflicts + consolidation_detect_redundant を実行すると、検索精度を保てます。

アーキテクチャ

+---------------------+       +------------------+       +----------------------+
| Claude Agent /      | <---> | Frinus MCP       | <---> | Memory Engine        |
| Claude Code         | stdio | (this server)    | HTTPS | (memories, sessions, |
+---------------------+       +------------------+       |  hierarchy, tasks)   |
                                |                        +----------------------+
                                |                                  |
                                |                                  v
                                |                        +----------------------+
                                |                        | PostgreSQL+pgvector  |
                                |                        | + Apache AGE (graph) |
                                |                        +----------------------+
                                |
                                +---HTTPS---> Control Plane (universes, orgs)
                                +---HTTPS---> Agent Service (agents, invocation, skills)

• Memory Engine はメモリ、ワーキングメモリ、セッション、ストリーム、L0～L3 の階層、トレーニング、スリープサイクル、タスク、スキルを管理します。
• Control Plane は組織、ユニバース、メンバー、API キー、課金、認証情報、ホワイトラベル、LLM キーを管理します。
• Agent Service はエージェントのランタイム、ツールのディスパッチ、チームへのルーティング、ペルソナ、呼び出しを管理します。

テナント分離には、テナントごとにデータベースを使用します。MCP は起動時に API キーからテナントの組織 ID を特定するため、org_id を手動で渡す必要はありません。

高度な設定 — セルフホスト／ローカル開発

上記の設定はすべて、ホステッドプラットフォーム（https://frinus.rdxsec.com.br）を対象としており、ほとんどの方はこの設定を使用します。独自の Frinus スタックを実行する場合（またはローカルバックエンドに対して MCP を開発する場合）は、ソースからビルドし、3 つの URL を上書きします。

git clone https://github.com/frinus-ai/frinus-mcp && cd frinus-mcp
npm install
npm run build      # emits dist/index.js

{
  "mcpServers": {
    "frinus": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/dist/index.js"],
      "env": {
        "FRINUS_API_KEY": "sk-frinus-...",
        "MEMORY_SERVICE_URL": "http://localhost:8001",
        "FRINUS_CP_URL": "http://localhost:8000",
        "AGENT_SERVICE_URL": "http://localhost:8002"
      }
    }
  }
}

公開（メンテナー向け）

# 1) npm package — powers `npx -y frinus-mcp` everywhere
npm version <patch|minor|major>
npm publish                      # prepublishOnly runs the build

# 2) .mcpb bundle — powers the Claude Desktop one-click install
npm run pack:mcpb                # -> frinus.mcpb
gh release upload v<version> frinus.mcpb --repo frinus-ai/frinus-mcp --clobber
# Frontend points at: releases/latest/download/frinus.mcpb

開発

mcp/
  src/
    index.ts                       Entry: MCP server, dispatch, auth bootstrap
    client/
      memory-client.ts             HTTP client + identity state for Memory Engine
      cp-client.ts                 HTTP client for Control Plane
      agent-client.ts              HTTP client for Agent Service
    tools/
      definitions.ts               Tool schemas (70 tools)
      handlers.ts                  Tool handlers (70 handlers)
    capture/
      interaction-capture.ts       Auto stream capture for every tool call
    types/
      index.ts                     Shared types
  dist/                            Compiled output (npm run build)
  package.json
  tsconfig.json

スクリプト：

npm run build     # tsc to dist/
npm run dev       # tsx hot reload (src/index.ts)
npm start         # node dist/index.js

型チェック：TypeScript 5.6 以降、ES モジュール、axios。

ライセンス

ライセンス条項については、リポジトリのルートを参照してください。