Seahorse

LLMエージェントのための永続的な、bi-temporal（二時間軸）メモリ — ローカルファースト、MCPネイティブ、Obsidianで閲覧可能。

pip install seahorse-memory
seahorse init myvault && seahorse remember "Sergio lives in Madrid"
seahorse recall "where does Sergio live?"

なぜ

LLMエージェントはすべてのセッションをゼロから開始します。コンテキストウィンドウはメモリではありません。これはリセットされるスクラッチパッドであり、エージェントが何週間もの作業で学んだことを保持するには小さすぎます。これを修正しようとするツールには、それぞれの問題があります。

• 彼らはひどく忘れ去ります。 多くのメモリシステムは事実を際限なく蓄積し、矛盾を解決しません。エージェントは、ユーザーがマドリードとバルセロナの両方に住んでいると「記憶」し、どちらが現在なのかを知る手段がありません。

• それらは不透明です。 メモリは人間が読めず、編集できず、監査できない独自のデータベースに住んでいます。エージェントが間違っていても、それを修正する方法がありません。

• それらには、取り込むのにコストがかかります。 すべてのエピソードがLLMを経由するため、数千件の小さな事実を書くのは実際の費用がかかります。

• あなたを閉じ込めます。 メモリシステムを採用することは、そのランタイム、プロバイダー、またはエコシステムを採用することを意味することがよくあります。

• そのベンチマークは信用できません。 この分野の数値は再現が困難です。LOCOMOベンチマークのゴールド解答の6.4%は不正確で、Mem0の再現は壊れており（issue #2800）、MTEBの埋め込みスコアはメモリ検索性能を予測しません（LMEB、arXiv 2603.12572）。

Seahorseは別のアプローチをとります。エージェントが書き込んで読み出し、人間が読んで修正できる、オープンで移植性のあるbi-temporal（二時間軸）メモリ標準であり、特定のランタイムやプロバイダーにあなたを閉じ込めません。

Related MCP server: agentcairn

対象者

• エージェントを構築する開発者（Claude Code、Cursor、Codex、または独自のエージェント）で、エージェントにセッションを越えた決定やコンテキストを覚えてもらいたい方。

• Obsidianパワーユーザーで、ノートを単なる静的なアーカイブではなく、エージェントが照会・維持できるナレッジベースにしたい方。

• 移植性のあるメモリを求めるチーム — 履歴を再生することなくベンダー間で移行できる形式です。

ユースケース: Claude Codeで永続メモリを使用する

Seahorseを実感する最も速い方法は、Claude Codeにセッション間で持続するメモリを持たせることです。3つの手順です。

1. セッションを記録します。 seahorse setup は、オブザーバーフックを ~/.claude/settings.json にインストールします。seahorse observe start は、キャプチャワーカーを実行します。すべてのセッションはエピソードとして記録されます。skip-first（ほぼゼロコス、演出なし、決定的な要約付き）。

seahorse setup
seahorse observe start

2. セッション間で思い出します。 SessionStartフックが seahorse context を次のセッションに注入するため、エージェントは以前学んだことから始まります。seahorse recall で直接尋ねます。

seahorse context
seahorse recall "what did we decide about the API design?"

3. 既存のメモリを取り込みます。 すでに claude-mem を使用している場合、seahorse import はその観察を正規のエピソードに移行します。再生もロックインもありません。

seahorse import --mode commit

重要な違いは、エージェントがObsidianで編集するのと同じVaultに書き込むことです。すべてのエピソードはYAMLフロントマターを持つMarkdownファイルです。つまり、読める、編集できる、gitで差分できます、人間が監査できます。エージェントのメモリはブラックボックスではなく、あなたのノートです。

エージェントから使う（MCP）

Seahorseはエージェントのために作られています。メモリ操作面は、MCPを話すエージェントなら誰でも接続できるstdio MCPサーバー（io.seahorse.memory/v1）です。CLIは人間とスクリプト用です。エージェントは seahorse-mcp に話しかけます。

Claude Codeにサーバーを登録する（ローカルスコープ、デフォルト）:

claude mcp add seahorse-mcp -- uvx --from seahorse-memory seahorse-mcp --vault "${HOME}/myvault"

-- は必須です。これは Claude 自身のフラグとサーバーコマンドを分離します。--scope project を使用すると、.mcp.json（gitにコミットされる）を介してチームとサーバーを共有できます。claude mcp list で確認してください（✔ Connected と表示されます）。claude mcp get seahorse-mcp でも確認できます。

または、プロジェクトルートの .mcp.json に設定します（任意のMCPクライアントで動作します）:

{
  "mcpServers": {
    "seahorse-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "seahorse-memory", "seahorse-mcp", "--vault", "${HOME}/myvault"]
    }
  }
}

注：.mcp.jsonでは ~ は展開されません。${HOME} または絶対パスを使用してください。（ settings.json 内の mcpServers は黙って無視されます。MCPサーバーは、ユーザー/ローカルスコープでは ~/.claude.json に、プロジェクトスコープでは .mcp.json に配置されます。）

接続すると、エージェントには14のメモリツールが見えます。 remember, rethink, recall_timeline, recall_full, improve, forget, build_pit, skill_add, skill_show, skill_list, skill_search, freshness_view, audit_log, follow_supersedes_chain（エージェントサーフェス を参照）。)

オブザーバー（ seahorse setup ）は別の構成です。Claude Codeのセッションをエピソードとして取り込みます。MCPサーバーは、エージェントがメモリを 読み書き するための方法です。これらの連携する — セッションを取得し、それらの間で検索（recall）します。

仕組み

graph LR
    A[Claude Code / any MCP agent] -- stdio MCP io.seahorse.memory/v1 --> S[seahorse-mcp]
    S --> E[Bi-temporal engine]
    E --> DB[(sqlite3 + sqlite-vec + FTS5)]
    E --> V[Obsidian vault: markdown + F3.1 frontmatter]
    H[Human in Obsidian] --> V

エージェントは、stdio MCP経由で seahorse-mcp と通信します。エンジンはすべてのエピソードを2回保存します。1回は単一ファイルのSQLiteデータベース（ベクトル検索用のsqlite-vec、全文用のFTS5）、もう1回は、ボルト内のF3.2フロントマターを持つMarkdownファイルとしてです。人間は同じMarkdownを編集します。フォーマットはバージョン管理され文書化されています docs/f3.1-format.md。

クイックスタート

# Install (PyPI):
pip install seahorse-memory
# …or with uv:
uv tool install seahorse-memory
# For hybrid semantic retrieval (FastEmbed ONNX, downloads mE5-small on first
# embed): pip install "seahorse-memory[embeddings]"
# For the multi-LLM extraction path (LiteLLM): pip install "seahorse-memory[llm]"

# Create a vault and write your first episode:
seahorse init myvault
seahorse remember "Sergio lives in Madrid" --title home
seahorse recall "madrid"

# Improve and forget (append-only; history is preserved):
seahorse improve <ep_id> "Sergio lives in Barcelona" --reason correction
seahorse forget <ep_id> --reason done

# Session capture, context, and consolidation:
# Install the observer (writes [observe] + merges the Claude Code hooks into
# ~/.claude/settings.json):
seahorse setup
# Start the observer (unix socket + worker), then the next session is captured
# automatically (skip-first, redacted, deterministic summary):
seahorse observe start
seahorse observe status
# Bootstrap context by recency (the SessionStart hook injects this):
seahorse context
# Distill recurrent episodes into semantic knowledge notes (N≥3, idempotent):
seahorse consolidate
# Remove the observer:
seahorse setup --uninstall

# Serve an agent over stdio MCP (io.seahorse.memory/v1):
seahorse-mcp --vault myvault
# …equivalently:
seahorse mcp --vault myvault

seahorse コンソールスクリプトは人間とシェルスクリプト用です。seahorse-mcp はエージェント用です。seahorse mcp サブコマンドは seahorse-mcp と同じstdioサーバーを呼び出すため、両方のエージェントエントリポイントは同等です。エージェント接続には、エージェントから使う（MCP） を参照してください。

前提条件

• Python ≥ 3.11（最近の3.11/3.12/3.13ならどれでも動作します）。インタープリタの sqlite3 が enable_load_extension をサポートしている必要があります（sqlite-vecが必要）。ほとんどの標準ビルドでサポートしています。サポートしていない場合、 seahorse doctor がFAILとバーできます。

• Obsidian はオプションです。 Seahorse は任意のMarkdownディレクトリで動作します。 seahorse init はプレーンなフォルダに .seahorse/ サイドファイルを作成します。Obsidian はその同じフォルダの人間向けエディタです。 .obsidian/ ディレクトリは、Seahorse によって無視され、決して必須ではありません。

レガシーObsidian Lockerの移行

既存のObsidianノート（フロントマーがないか、レガシーな tags / created フロントマター使用）は、まだ正規フォーマットではありません。 seahorse index rebuild はそれらのノートに対して正直に失敗します。 seahorse frontmatter migrate はそれらを変換します。

# Preview: classify every note, write nothing (always exit 0):
seahorse frontmatter migrate --vault myvault --dry-run
# Apply: convert legacy notes, leave canonical notes untouched, refuse
# incompatible notes:
seahorse frontmatter migrate --vault myvault
# Rebuild the sidecar index from the converted notes:
seahorse index rebuild --vault myvault

移行インが互換性のないノートによってブロックされると、97 で即終了します。マニフェストのまとめがまず表示されるため、どのノートの手動解決が必要かが確認できます。 --resume は最後のマニフェストから変更されていないノートをスキップします。 --batch-size はマニフェストのチェックポイント頻度を設定します。移行は seahorse init の前に動作します（.md ファイルとマニフェストのみ触ります）。

初回実行: セマンティック埋め込みモデル（mE5-small、約235MB）は最初の remember / recall で遅延ダウンロードされます。CLIが通知するため、最初の呼び出しがハング(\ hang)にように見えることはありません。 seahorse status は、アクティブな検索モードを表示します（ハイブリッドRRF（モデルキャッシュ済み） vs 現在の状態の一覧表示 — セマンティック検索用に seahorse-memory[embeddings] をインストールしてください ）。

他のメモリツールとの比較

検証済みの事実の比較であり、ランキングではありません。出典: プロジェクトの最先端分析（研究ノート](https://github.com/ssanvi-builds/seahorse) と下記の引用を参照）。

凡例: ✓ はい・~ 一部・✗ いいえ・— 未検証

最も重要な2つの事実: mem0 は自分のベンチマーク数字を生み出す機能を Paywall で閉じ込め , Zep はセルフホストをやめてクラウド限定にした。Seahorse はデフォルトがローカルファストで、ベンチマークハーネスをレポジトリに公開し、メモリフォーマットをポータブルに保つので、落とし込まることがありません。

ベンチマーク

Seahorse は再現可能なベンチマークハーネス（LMEB-S、これは LongMemEval ベンチマークの一部）を同梱し、独自の数値も公開しています。ただし、注記付きです。目的はリーダーボードではなく、誠実で再現可能な計測です。

注意: 実行は部分的サブセット（n≈470–500 問、フルデータセットではない）を使用し、関連性は人間まかない小さなLLMで判定しています。また、リクルだけを測定していて、エージェントの最終回答ではなく。クロスエンコーダーの再ランはテストされ、却下しました。 recall@10 を 1.2 秒の遅延で 0.11 に落とすためです。完全な方法論と再現コマンドは docs/benchmark.md にあります。

この数値は、サブセットと小型審判による検索ランキングのみを測定したものであり、他のメモリシステムが公表するエンドツーモードの精度スコア（例: Graphiti 63.8%、Mem0 94.8、Hindsight 91.4%）とは比較できません。比較しないための方法は docs/benchmark.md を参照してください。

FAQ

エピソードとは何ですか？ 単一のメモリレコードです。YAML フロントマー付きの Marwown ファイルで、2 つの時間軸（valid_at — 真実になったとき、 created_at — 記録されたとき）と来、情報源、認識タイプを持ちます。フォーマットはバージョン管理され、docs/f3.1-format.md に文書化されています。

なぜObsidianなのか？ 人間がメモリシステムの一部であるからです。エージェントはあなたが書る同じ Vault に書き込みます。Markdown は読み取り可能、gitでdiff可能、監査可能です。エージェントが間違っている場合、あなたはデータベースではなくノートを修正します。

claude-memとはどのように違いますか？ claude-mem は自分のスキーマでセッション観測値を保存します。Seahorse は、相互運用可能な bi-temporal なオープン標準と、ポータブルなフォーマットと人間が読めるレイヤを提供します。さらに seahorse import が claude-mem の観測結果を正規のエピソードに移行するため、競合者ではなく橋渡しの存在です。

LLMは必要ですか？ いいえ。決定的なスキップパスが、書き込みの大半のデフォルトです（コストほぼゼロ）。LLM抽出はオプショナル（seahorse-memory[llm]）であり、それを正当化する少数のエピソードに限定されます。

無料ですか？ はい。Apache-2.0、ローカルファースト、ゼロインフラ。管理されたSaaSとエンタープライズティアは将来予定されています（プロジェクトの戦略ノートを参照）。

コントリビュートは？ 開発環境のセットアップ、テスト/リントコマンド、プルリクエストのワークフローは、CONTRIBUTING.md を参照してください。

ロードマップ

構築済み・次のステップ・プロジエクトの方向性についてはROADMAP.md を参照してください。リリース履歴はCHANGELEOG.md にあり。

エージエント・コンサーフェス — 7つのメモリネイティヴ・プリミティヴ + 7つのプ確ロージャル／読み取り専用ツール

stdio MCP（io.seahorse.memory/v1、プロトコルは 2025-11-25 に固定）経由で公開され、CLIでもミラーされています。これらは汎用CRUDではなく、memory primitives です。エージェントは、人間が memory について語るように remember / recall / improve / forget を呼び出します。

7つのプリミティブ（書き込み＋取得）：

さらに、7つのプロシージャル／読み取り専用ツール（スキル＋ファサード内観）：

3つの取得レベルはプログレッシブ・ディスクローズを実現します：まず低コストの一覧（INDEX）、必要に応じたチェーン（TIMELINE）、そして必要な場合のみ完全なレコード（FULL）。これにより、一般的なパスを低コストに保ちます。

動作するもの

• 双時間・追記専用のエピソードストア−stdlib sqlite3 + sqlite-vec（FTS5 ◇ * vec0）。自動マイグレーションするスキーマ。

• 7つのメモリネイティブ・プリミティブ＋7つのプロシージャル／読み取り専用ツールを、CLIとstdio MCPの両方に提供（計14ツール）。

• プログレッシブ・ディスクローズ（INDEX / TIMELINE / FULL）とポイント・イン・タイム・プロジェクション。

• ハイブリッド意味検索：recall は関連性でランク付けします — sqlite-vec kNN+FTS5 BM25 を Reciprocal Rank Fusion で融合し、実際のエンベーダーが接続されている場合はポイント・イン・タイム・ルーティング（state_at / known_at）を使用します。書き込みパスと seahorse index rebuild は vec0/FTS を構築します（ベストエフォート — エンベーダーの障害がエピソード書き込みを失敗させることはありません）。

• 正直な縮退：embeddings エクストラなし（またはベクターが未構築）の場合、recall は現在状態のリスト（スコア 0.0、ランクなし）にフォールバックし、point-in-timeでのリコールは拒否されます — エンジンはランクなしでも動作を維持します。

• オプトイン減衰ランキング（デフォルトオフ）：FAMA スタイル・エビングハウス忘却曲線が、古い知識を age に応じて重み付けします（score' = score · 2^(-age/half_life)）。タイプごとに半減期の事前分布があります。デフォルトではオフで、純粋な RRF フィンガープリントはビット比較可能なままです。

• LLM抽出：実本のマルチLLMパス（ollama / gemini / groq / openrouter / openai / anthropic / deepseek / vllm、ローカルファースト）で、厳密なスキーマバリデータ＋修復ループ、リトライ／フォールバックチェーン、実効コストキャップを備えています。ローカル・無料帯モデルは $0 です。seahorse init --llm で初期化され、スキップパスは多数の書き込みで、ほぼゼロコストのデフォルトのままです。

• ローカルファースト CI ゲート：実際の抽出パスは、先祖モデルの中で最も弱い ollama/qwen3:0.6b モデルに対して CI で実行され、バリデータとリトアループが主体を担わなければなりません。ネイティブな構造化出力や強力なモデルに黙って依存していません。

• 置き換え（improve）とソフト削除（forget）により、完全な履歴を執行保持します。

• バッチ蒸留（seahorse consolidate）：多数のエピソードを一つの統合ノートに蒸留 — デフォルトは決定的で、オプトインの LLM 合成（--synthesis）と置き換え（--supersede）により、統合ノートがソースを置き換えます。

• Frontmatter インポート／エクスポート（Obsidian vault レイヤー向け。マークダウンを、人間が読めるポータブルなオンディスク契約にする）。

• レガシーヴォールの移行：seahorse frontmatter migrate は、--dry-run プレビューと --resume で、レガシーの Obsidian ノートを変換します。互換性がないノーを持たない場合は膨大な移行を honest にコード 97 で停止します。

• honest の終了コードと、stderr 上の構造化 {"error":{...}} エンベロープにより、エージェントとスクリプトが seahorse_code / cli_code で判定的に分岐できます。

一部のCLI コマンドは実装されていますが、あえて理由とともに exit code 75 (expire, revalidate, index verify) を返します。つまり、非実装イン代わりに相手黙って no-op にするのではなく、サーフェスに正直です。llm_partial は完全に予約されたままです。

技術スタック

• Python ≥ 3.11。 ストレージには stdlib sqlite3 + sqlite-vec（ゼロインフラウ file; vec0 仮想テーブル + FTS5）。

• numpy はニューラル埋め込み Blob のシェイプに使用。

• Pydantic v2 は必須の Episode コントラクト（コアタイプシステム）。

• Typer は CLI サーフェス（人間とスクリプト）用— CLI に限定。seahorse.cli に閉じて。

• stdio JSON-RPC 2.0 は MCP エージェントサーフェス（手書きのフレーミング、stdlib のみの seahorse.mcp パッケージ — import sea horse.mcp で Typer はロードされません）。

• ruamel.yaml と python-frontmatter は frontmatter アダプターに限定。

• FastEmbed ONNX + onnxruntime（embeddings エクストラ、デフォルトインストールには含まれない）：mE5-small バンドルは既定 model_O4.onnx（fp32 約235MB）— int8/fp16 バイナリは Apple Silicon にポータブルそうでなく、オープンなフォーマットは Windows/Linux/macOS で動かねばなりません。portable な int8 バンドルが次の測定対応です。

• LiteLLM（llm エクストラ、デフォルトでは含まれない）：LLM抽出パスのため5000以上のプロバイダーをまとめます。エクストラなしでも seahorse.llm はインポート可能（契約 + StubLLMClient）で、実際のパスはセットアップヒント付きで LLM→スキップに低下します。

FastAPI / SQLAlchemy / Postgres スタックは、後日マルチエージェント層（Postgres + pgvector）で予定です。README は対象アーキテクチャではなく現在提供されるもの見えます。

テスト

• ユニット＋統合：uv run pytest（カバレッジ80%ゲート）。

• フレッシュユーザーE2E：scripts/e2e-fresh-user.sh — クリーン分離したHOMEから、インストール → init → コアCLI → 埋め込み → LLM → import → MCP のフルフロー（実際の ~/.claude / ~/.claude-mem は触らない）。

• 環境マトリクス：scripts/e2e-matrix.sh — 組み合わせ（インストール方法 × extras × Obsidian × Ollama × オンライン/オフライン × vault 状態 × 並行度）でのフレッシュユーザーフロー、--ci-subset はCIセーフな組み合わせ (core_min + uv_sync_dev)、--list は全組み合わせ表示。

• コアストレスが想定：scripts/stress-core.sh — 1000エピソードをインジェクトし、recall --top-k 100 のp95 ≤ 250ms（インプロセスINDEX内）、同時 single-writer、re-index、冪等 import、improve/forget チェーン。

コントリビューション

コントリビューは歓迎です。CONTRIBUTING.md の開発セットアップ手順とテスト/リント/PR フローを参照してください。リリース履歴は CHANGELOG.md にあります。

ライセンス

Apache-2.0。LICENSE を参照してください。

現状

v0.10.0. メモリエンジンはクリーンインストールからエンドツーエンドで動作します：エピソードの書き込み、ハイブリッド意味検索による再構想、実LLMパス（ローカルファースト、CI ゲート）で抽出、改善、検索、そして stdio MCP 上のエージェント提供が行えます。 recall はベクターが入された場合に順位順になり、それ以外は美しくなてこう。 ある状態のリストに縮減されます。オプトインの減衰ランキング（デフォルトオフ）は古い知識を年齢で低重みします。seahorse import は claude-mem の観察をエピソードに移行します。seahorse consolidate とスティル化命令は多くのエピソードを一つの統合資料 note に変換し、任意の LLM仲介と置き談をします。ベンチマークツールは警告と再現コマンドをdocs/benchmaker.mdに同梱します。次の項目は What works と ROADMAP.md を参照してください。