Octobrain

Octobrain

AI アシスタントのための永続メモリ — 会話をまたいで保持される知見、意思決定、知識を保存します。

MCP Registry：mcp-name: io.github.Muvon/octobrain

目次

• Octobrain を選ぶ理由
• クイックスタート
• インストール
• 使い方
• 機能
• ベンチマーク
• 設定
• メモリの種類
• MCP 統合
• ストレージの場所
• コントリビューション
• ライセンス

Octobrain は AI アシスタントに長期記憶を提供します。コードに関する知見、アーキテクチャ上の決定、バグ修正、知識を保存し、将来のセッションでセマンティック検索を使って取得できます。CLI ツールとしても、Claude Desktop やその他の AI ツールと連携する MCP サーバーとしても動作します。

Octobrain を選ぶ理由

AI アシスタントは、会話を始めるたびにコンテキストがゼロの状態から始まります。プロジェクトや好み、決定事項を毎回説明しなければなりません。Octobrain はこの繰り返しを解消します。

• 永続メモリ — 知見をセッション内だけでなく、セッションをまたいで保持します
• セマンティック検索 — 完全一致するキーワードではなく、意味からメモリを見つけます
• 自動リンク — 関連するメモリを自動的に接続します（ツェッテルカステン方式）
• ナレッジのインデックス作成 — ドキュメント、記事、ファイルを取り込んで検索できるようにします
• MCP 統合 — Claude Desktop やその他の MCP 対応ツールで動作します

クイックスタート

# Install from crates.io
cargo install octobrain

# Store your first memory
octobrain memory memorize --title "API Design Pattern" \
  --content "Use REST for CRUD, GraphQL for complex queries" \
  --memory-type architecture --tags "api,design"

# Search memories
octobrain memory remember "how should I design APIs"

# Start MCP server for Claude Desktop integration
octobrain mcp

インストール

crates.io から（推奨）

cargo install octobrain

ソースから

# Clone and build
git clone https://github.com/muvon/octobrain.git
cd octobrain
cargo build --release

# Binary location
./target/release/octobrain --help

Docker

docker pull ghcr.io/muvon/octobrain:latest

Homebrew（macOS/Linux）

brew install muvon/tap/octobrain

機能フラグ

Octobrain は複数の埋め込みプロバイダーに対応しています。

フラグ	説明	API キーが必要
fastembed	FastEmbed によるローカル埋め込み	いいえ
huggingface	HuggingFace によるローカル埋め込み	いいえ
(default)	fastembed と huggingface の両方	いいえ
(no features)	API ベース：Voyage、OpenAI、Google、Jina	はい

# Build with local embeddings (default, no API keys needed)
cargo build --release

# Build with API-based embeddings only
cargo build --no-default-features --release

API ベースの埋め込みを使う場合は、該当する環境変数を設定してください。

• Voyage AI の場合は VOYAGE_API_KEY
• OpenAI の場合は OPENAI_API_KEY
• Google の場合は GOOGLE_API_KEY
• Jina の場合は JINA_API_KEY

使い方

メモリ管理

知見、意思決定、コンテキストを保存して取得します。

すべての memory サブコマンドで、次のグローバルフラグを使用できます。

• --scope <string> — プロジェクトスコープを上書きします（デフォルトでは Git リモートから自動検出）
• --role <string> — ロールで絞り込みます（例：「developer」、「reviewer」）

# Store a memory
octobrain memory memorize --title "API Design" \
  --content "Use REST for CRUD, GraphQL for complex queries" \
  --memory-type architecture --tags "api,design"

# Search memories (semantic search)
octobrain memory remember "api design patterns"

# Multi-query search for broader coverage
octobrain memory remember "authentication" "security" "jwt"

# Get a memory by ID
octobrain memory get <id>

# Get recent memories
octobrain memory recent --limit 20

# Filter by type
octobrain memory by-type architecture --limit 10

# Filter by tags
octobrain memory by-tags "api,security"

# Find memories related to files
octobrain memory for-files "src/main.rs,src/lib.rs"

# Update a memory
octobrain memory update <id> --title "New Title" --add-tags "new-tag"

# Delete a memory
octobrain memory forget --memory-id <id>

# Get memories relevant to the current Git commit
octobrain memory current-commit

# Show memory statistics
octobrain memory stats

# Clean up old/low-importance memories
octobrain memory cleanup

# Compact tables and refresh indices (run when searches slow down)
octobrain memory maintenance

# ⚠️ Delete ALL memory data
octobrain memory clear-all --yes

メモリの統合

ゴールを終了し、それに寄与したすべてのメモリを統合した要約にまとめます。

# Consolidate a goal (Achieves-link sources → Consolidated state, importance dampened)
octobrain memory consolidate <goal-id> --summary "Final summary"

# Sleep consolidation: auto-cluster recent similar memories
octobrain memory sleep-consolidate --threshold 0.85 --min-size 3

メモリ間の関連付け

関連するメモリを接続し、コンテキストが豊富な検索を可能にします。

# Create a relationship between memories
octobrain memory relate <source-id> <target-id> \
  --relationship-type "depends_on" \
  --description "Source requires target to function"

# View relationships for a memory
octobrain memory relationships <memory-id>

# Find related memories through relationships
octobrain memory related <memory-id>

# Auto-link similar memories (Zettelkasten-style)
octobrain memory auto-link <memory-id>

# Explore memory graph
octobrain memory graph <memory-id> --depth 2

ナレッジベース

Web コンテンツ、ドキュメント、ファイルのインデックスを作成して検索します。

# Index a URL
octobrain knowledge index https://docs.rs/tokio/latest/tokio/

# Index a local file (.txt, .md, .pdf, .docx, .html)
octobrain knowledge index ./docs/architecture.md

# Search knowledge base
octobrain knowledge search "how to handle async tasks"

# Search within a specific source (auto-indexes if outdated)
octobrain knowledge search "spawn blocking" --source https://docs.rs/tokio/

# Read full content of a URL or local file
octobrain knowledge read https://docs.rs/tokio/latest/tokio/

# Search indexed content by regex pattern
octobrain knowledge match "spawn_blocking|block_in_place"

# Store raw text content
octobrain knowledge store "meeting-notes" --content "Discussion points..."

# List indexed sources
octobrain knowledge list --limit 20

# Show statistics
octobrain knowledge stats

# Delete a source
octobrain knowledge delete https://example.com/docs

# Delete stored content by key
octobrain knowledge delete-stored "meeting-notes"

ナレッジボックス

プロジェクトに紐づけて管理する、Git ベースのナレッジバンドルをインポートして同期します。

# Import a remote git repo as a knowledge box
octobrain box import https://github.com/org/docs-repo.git

# Import at global scope (visible in every project)
octobrain box import https://github.com/org/docs-repo.git --global

# Pull and re-index all subscribed boxes + local .box/ directories
octobrain box sync

# List subscribed boxes
octobrain box list

# Remove a box
octobrain box remove github.com/org/docs-repo

MCP サーバー

Claude Desktop やその他の AI ツールと連携するための MCP サーバーとして実行します：

# Start with stdio transport (for Claude Desktop)
octobrain mcp

# Start with HTTP transport (for web-based tools)
octobrain mcp --bind 0.0.0.0:12345

利用可能な MCP ツール：

ツール	説明
memorize	メタデータ付きで記憶を保存します。インラインの関連付けには、オプションで related_to を指定できます
remember	フィルターを使ったセマンティック検索を行い、1 ホップ先のグラフ近傍を返します
forget	記憶を削除します（確認が必要です）
knowledge	command フィールドを介して search、store、delete、read、match を実行する統合ツール
Claude Desktop の設定については、MCP 連携を参照してください。

機能

• セマンティック検索 — 完全一致するキーワードではなく、ベクトル埋め込みを使って意味から記憶を検索します
• ハイブリッド検索 — BM25 全文検索とベクトル類似度を組み合わせ、検索結果を改善します
• 再ランキングのサポート — プラグイン可能なクロスエンコーダー再ランキング段階です（プロバイダーに依存します）
• 自動リンク — 意味的に類似した記憶を自動的に関連付けます（ツェッテルカステン方式）
• 時間経過による減衰 — エビングハウスの忘却曲線を用いて重要度を管理します
• ナレッジのインデックス化 — URL、PDF、ドキュメントを取り込んで検索できるようにします
• プロジェクトのスコープ設定 — Git プロジェクトごとに記憶を分離するか、複数のプロジェクトで共有します
• ロールによるフィルタリング — ロール（developer、reviewer など）で記憶にタグを付けます
• クエリ拡張（HyDE-lite） — 疎なクエリで再現率を 10～30％向上させる疑似関連性フィードバックです
• MCP プロトコル — AI ツール連携のための MCP 2026-07-28 完全準拠

ベンチマーク

標準の BEIR データセットにおける octobrain のナレッジシステムの検索品質です。指標は nDCG@10 で、完全ローカルで実行し、LLM による評価は行わず、ハーネスのデフォルトの埋め込みモデル bge-small-en-v1.5（384 次元、パラメーター数 3,300 万）を使用します。各コーパスのパッセージは octobrain の実際の検索経路でインデックス化され、公式の qrels に対してスコア化されます（指標は pytrec_eval の結果を再現します）。

データセット	octobrain ベクトル	octobrain ハイブリッド	BM25¹	bge-small-en-v1.5²
SciFact（5.2K ドキュメント、300 クエリ）	0.722	0.742	0.665	0.713
NFCorpus（3.6K ドキュメント、323 クエリ）	0.341	0.363	0.325	0.343

• ベクトル = 密ベクトルのみの検索です。埋め込みモデルが公開している BEIR の数値を再現します（ハーネスの妥当性を検証します）。
• ハイブリッド = BM25 とベクトルを Reciprocal Rank Fusion（k=60）で融合したものです。octobrain のデフォルトです。埋め込みのみの場合より nDCG@10 が 2 ポイント向上し、両方のデータセットで従来の BM25 を上回ります。

¹ BEIR 論文に記載された標準的な BM25（Anserini/Lucene、k1=0.9 b=0.4）。 ² bge-small-en-v1.5 モデルカードより（MTEB）。

対象範囲：ここでは、埋め込み、BM25 融合、再ランキングからなるランキング層を測定しています。BEIR のパッセージは事前にチャンク化されているため、octobrain のチャンク化戦略はここでは評価されません。

⚠️ 再ランカーの状況： fastembed モデルでは、クロスエンコーダー再ランカーは現在何も行わず、ハイブリッド検索のみの場合とバイト単位で同一の結果になります。調査が完了するまで、上記の数値には再ランキングを含めていません。詳細については、benches/README.mdを参照してください。

再現方法（データセットをダウンロードし、リリースバイナリーをビルドして、完全オフラインで実行します）：

cd benches && bash scripts/run_retrieval.sh

設定

設定は ~/.local/share/octobrain/config.toml に保存されます。初回実行時に書き込まれるテンプレートには、すべてのオプションが妥当なデフォルト値とともに定義されています。ただし、設定の読み込みは厳密です。手動でフィールドを削除すると、デフォルト値にフォールバックせず、起動に失敗します。

設定ファイルの場所は OCTOBRAIN_CONFIG_PATH=/path/to/config.toml で上書きできます。

主な設定

セクション	オプション	デフォルト	説明
[embedding]	model	fastembed:Qdrant/all-MiniLM-L6-v2-onnx	埋め込みモデル（provider:model 形式）。デフォルトはローカルの fastembed モデルで、API キーは不要です。CPU で動作します。
[search]	similarity_threshold	0.3	関連性の最小値（0.0～1.0）
[search.hybrid]	enabled	true	BM25 とベクトルの融合を有効にします
[search.reranker]	enabled	true	クロスエンコーダーによる再ランキングを有効にします
[search.hyde]	enabled	true	疑似関連性フィードバックによるクエリ拡張
[memory]	max_memories	10000	保存するメモリの最大数
[memory]	auto_linking_enabled	true	類似するメモリを自動的に接続します
[knowledge]	chunk_size	1200	チャンクあたりの文字数
[embedding]	batch_size	32	バッチごとに埋め込むテキスト数
[embedding]	timeout_secs	30	埋め込み処理のタイムアウト（0 = タイムアウトなし）
[search]	max_results	50	すべての検索結果に適用される上限
[search.reranker]	model	fastembed:jina-reranker-v2-base-multilingual	クロスエンコーダーモデル
[search.reranker]	top_k_candidates	50	再ランキング前に取得する候補数
[search.hyde]	top_k	3	重心の算出に使用する近傍数
[search.hyde]	alpha	0.5	元のクエリ埋め込みに対するブレンド比率
[memory]	max_search_results	50	上限が指定されていない場合のデフォルトのページサイズ
[memory]	sleep_consolidation_enabled	true	マネージャーの初期化時に遅延スリープ統合を行います
[memory]	sleep_consolidation_interval_hours	24	スリープ統合の実行間隔（時間）
[knowledge]	outdating_days	15	インデックス済みコンテンツが検索時に再インデックスされるまでの日数
[knowledge]	max_results	5	ナレッジ検索で返す結果数

埋め込みプロバイダー

[embedding]
# Local models (no API key, runs on CPU, model auto-downloaded on first use)
model = "fastembed:Qdrant/all-MiniLM-L6-v2-onnx"                       # Default: 384-dim quantized, ~125MB resident
model = "fastembed:nomic-ai/nomic-embed-text-v1.5"                      # 768-dim, 8192-ctx, ~550MB weights, highest quality
model = "fastembed:BAAI/bge-small-en-v1.5"                              # 384-dim, ~62 MTEB, fast + good quality
model = "fastembed:sentence-transformers/all-MiniLM-L6-v2-quantized"  # Smallest (~22MB), fastest
model = "fastembed:BAAI/bge-base-en-v1.5"                              # Larger (~440MB), higher quality
model = "fastembed:intfloat/multilingual-e5-small"                     # Multilingual

# Cloud providers (require API keys, generally higher quality)
model = "voyage:voyage-3.5-lite"          # VOYAGE_API_KEY
model = "openai:text-embedding-3-small"   # OPENAI_API_KEY
model = "google:text-embedding-004"       # GOOGLE_API_KEY
model = "jina:jina-embeddings-v3"         # JINA_API_KEY

設定の全項目

利用可能なすべてのオプションと説明については、config-templates/default.toml を参照してください。

メモリの種類

フィルタリングを改善するため、カテゴリ別にメモリを整理します。

種類	用途
code	コードパターン、解決策、実装
architecture	システム設計、決定事項、パターン
bug_fix	バグ修正、トラブルシューティング、解決策
feature	機能仕様、実装
documentation	ドキュメント、説明、ナレッジ
user_preference	設定、好み、ワークフロー
decision	プロジェクトの決定事項、トレードオフ
learning	チュートリアル、メモ、学習
configuration	セットアップ、設定、デプロイ
testing	テスト戦略、QA の知見
performance	最適化、ベンチマーク
security	脆弱性、修正、考慮事項
validation	アイデア／製品の検証、仮説テスト
research	技術／市場調査、分析
workflow	SOP、プレイブック、プロセスの説明
requirement	ビジネス要件、仕様、制約
design	UI／UX の決定事項、ワイヤーフレーム、システム設計
integration	API 統合、サードパーティーサービス
communication	ステークホルダーへの状況報告、チームの決定事項
process	デプロイ手順、ランブック、運用
insight	一般的な知見、ヒント
goal	統合ワークフロー用のタスク／意図のアンカー

MCP 統合

Claude Desktop のセットアップ

Claude Desktop の設定（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "octobrain": {
      "command": "/path/to/octobrain",
      "args": ["mcp"]
    }
  }
}

Claude Desktop を再起動してください。Octobrain のツールが会話で利用できるようになります。

HTTP トランスポート

ウェブベースの統合の場合：

octobrain mcp --bind 0.0.0.0:12345

サーバーは MCP プロトコル通信のために /mcp エンドポイントを公開します。

ストレージの保存場所

データはプラットフォーム固有のディレクトリに保存されます。

プラットフォーム	保存場所
macOS	~/.local/share/octobrain/
Linux	~/.local/share/octobrain/ または $XDG_DATA_HOME/octobrain/
Windows	%APPDATA%\octobrain\

プロジェクト固有のメモリーは、正規化された Git リモート URL（例：github.com/org/repo）ごとに分離されます。

コントリビューション

コントリビューションを歓迎します！以下の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. cargo fmt --all を実行してコードをフォーマットします
4. cargo clippy を実行し、すべての警告を修正します
5. cargo test --no-default-features を実行します
6. プルリクエストを送信します

開発環境のセットアップ

# Clone and build
git clone https://github.com/muvon/octobrain.git
cd octobrain
cargo build --no-default-features

# Run tests
cargo test --no-default-features

# Run clippy
cargo clippy --no-default-features

ライセンス

Apache-2.0 — 詳細は LICENSE をご覧ください。

クレジット

Muvon Un Limited が開発しました。