local-knowledge

ローカルナレッジの検索

開発者の個人メモ、ドキュメント、またはローカルナレッジベースから、特定のコンテキストに関する情報を検索する必要がある場合に、このスキルを使用します。

概要

Terraphim では、ロールベースのヘイスタックを通じて AI コーディングエージェントがローカルナレッジを検索できます。ロールごとにアクセスできるナレッジ領域が異なります。

ロール	ナレッジ領域	ヘイスタック
Terraphim Engineer	アーキテクチャ、システム設計	ローカルドキュメント + ナレッジグラフ
Rust Engineer	Rust のパターン、非同期処理、WASM	ローカルメモ + Query.rs API
Frontend Engineer	JavaScript、TypeScript、React	GrepApp（GitHub のコード検索）

このスキルを使用する場合

ユーザーが次のような内容を求めた場合は、ローカルナレッジを検索します。

• 個人メモにあるトピックについて質問する（「自分のメモにある」「自分のドキュメント」など）
• 以前に記録した、特定の分野に関するパターンを必要としている
• 「普段 X はどうやっていますか」や「Y にはどんなパターンを使っていますか」と質問する
• 過去の解決策やブックマークしたリソースに言及する

トリガーフレーズ：

• 「自分のメモで……を確認して」
• 「自分のドキュメントから……を検索して」
• 「……について何か持っていますか」
• 「……に関するメモを探して」
• 分野固有の質問（Rust の非同期処理、フロントエンドのパターンなど）

アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code Agent                         │
│  Uses /search and /role commands via terraphim-agent REPL   │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    terraphim-agent REPL                      │
│  /search "query" --role rust-engineer --limit 10            │
└───────────────────────────┬─────────────────────────────────┘
                            │
          ┌─────────────────┼─────────────────┐
          ▼                 ▼                 ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Terraphim Eng   │ │ Rust Engineer   │ │ Frontend Eng    │
│                 │ │                 │ │                 │
│ • Local docs    │ │ • Rust notes    │ │ • GrepApp JS    │
│ • expanded_docs │ │ • Query.rs      │ │ • GrepApp TS    │
│ • Knowledge KG  │ │ • Auto-gen KG   │ │                 │
└─────────────────┘ └─────────────────┘ └─────────────────┘

人間向け

クイックスタート

# Build terraphim-agent with REPL features
cd /path/to/terraphim-ai
cargo build -p terraphim_agent --features repl-full --release

# Start the REPL
./target/release/terraphim-agent

# In REPL: List available roles
/role list

# Switch to Rust Engineer role
/role select rust-engineer

# Search your notes
/search "async iterator patterns" --limit 5

ロールの設定

ロールは terraphim_server/default/ にある JSON 設定ファイルで定義されています。

{
  "roles": {
    "Rust Engineer": {
      "relevance_function": "title-scorer",
      "haystacks": [
        {
          "location": "/path/to/your/notes",
          "service": "Ripgrep",
          "extra_parameters": { "glob": "*rust*.md" }
        }
      ]
    }
  }
}

独自のメモを追加する

1. メモ用のディレクトリを作成します（例：~/notes/rust/）
2. ナレッジを記載した Markdown ファイルを追加します
3. ロール設定を更新し、そのディレクトリを Ripgrep ヘイスタックとして追加します
4. 必要に応じて、意味的な用語の拡張に使うナレッジグラフを作成します

AI エージェント向け

Terraphim の機能を確認する

terraphim-agent が利用可能か確認します。

# Find the agent binary
if command -v terraphim-agent >/dev/null 2>&1; then
    AGENT="terraphim-agent"
elif [ -x "./target/release/terraphim-agent" ]; then
    AGENT="./target/release/terraphim-agent"
elif [ -x "$HOME/projects/terraphim/terraphim-ai/target/release/terraphim-agent" ]; then
    AGENT="$HOME/projects/terraphim/terraphim-ai/target/release/terraphim-agent"
fi

REPL コマンドリファレンス

検索コマンド：

# Basic search (uses current role)
/search "query string"

# Search with specific role
/search "async patterns" --role rust-engineer

# Limit results
/search "error handling" --limit 5

# Semantic search (uses knowledge graph)
/search "error handling" --semantic

# Concept-based search
/search "error handling" --concepts

ロールコマンド：

# List available roles
/role list

# Select a role
/role select rust-engineer

# Show current role
/role current

グラフコマンド：

# Show knowledge graph terms
/graph

# Show top K terms
/graph --top-k 20

AI エージェント向けの検索パターン

パターン 1：分野固有の検索

ユーザーが特定の分野について質問した場合は、まず適切なロールを選択します。

# User asks about Rust async
/role select rust-engineer
/search "async iterator" --limit 5

パターン 2：幅広いナレッジの検索

一般的な質問には、expanded_docs を指定して Terraphim Engineer ロールを使用します。

/role select terraphim-engineer
/search "atomic data server configuration"

パターン 3：コード例

フロントエンドのコード例には、GrepApp との連携を使用します。

/role select frontend-engineer
/search "useState useEffect pattern"

検索結果の解釈

検索結果には次の項目が含まれます。

• title：ドキュメント／メモのタイトル
• url：ファイルパスまたはソース URL
• body：コンテンツの抜粋
• description：要約（LLM による要約が有効な場合）
• rank：関連度スコア

出力例：

Results for "async iterator":

1. [rust-matching-iterators.md]
   Path: /Users/alex/notes/rust-matching-iterators.md
   Async iterator over AWS S3 pagination using State enum...

2. [rust-python-extension.md]
   Path: /Users/alex/notes/rust-python-extension.md
   PyO3/Maturin async patterns for Python extensions...

エラー処理

terraphim-agent が利用できない、または失敗した場合：

1. 段階的な縮退：ローカル検索を使わずに続行します
2. ユーザーへの通知：「ローカルナレッジ検索を利用できないため、一般的なナレッジを使用します」
3. 代替手段：ウェブ検索または組み込みナレッジを使用します

# Check if search succeeded
if ! /search "query" 2>/dev/null; then
    echo "Local search unavailable, falling back to general knowledge"
fi

ナレッジグラフの形式

ナレッジグラフファイルを使うと、意味的な用語の拡張ができます。

# term_name

Optional description of the term.

synonyms:: synonym1, synonym2, synonym3

例 — Rust の非同期処理に関する用語：

# async_iterator

Async iterators in Rust using Stream trait and async/await.

synonyms:: Stream, AsyncIterator, futures::Stream, tokio::stream

設定例

ローカルメモを使用する Rust Engineer

{
  "Rust Engineer": {
    "shortname": "rust-engineer",
    "relevance_function": "terraphim-graph",
    "kg": {
      "knowledge_graph_local": {
        "input_type": "markdown",
        "path": "docs/src/kg/rust_notes_kg"
      }
    },
    "haystacks": [
      {
        "location": "/Users/alex/synced/expanded_docs",
        "service": "Ripgrep",
        "extra_parameters": { "glob": "*rust*.md" }
      },
      {
        "location": "https://query.rs",
        "service": "QueryRs"
      }
    ]
  }
}

GrepApp を使用する Frontend Engineer

{
  "Frontend Engineer": {
    "shortname": "frontend-engineer",
    "relevance_function": "title-scorer",
    "haystacks": [
      {
        "location": "https://grep.app",
        "service": "GrepApp",
        "extra_parameters": { "language": "JavaScript" }
      },
      {
        "location": "https://grep.app",
        "service": "GrepApp",
        "extra_parameters": { "language": "TypeScript" }
      }
    ]
  }
}

トラブルシューティング

問題	解決策
結果が返されない	ヘイスタックのパスが存在し、.md ファイルが含まれていることを確認します
有効なロールが違う	/role select <name> を使って切り替えます
検索が遅すぎる	--limit を小さくするか、より具体的なクエリを使用します
KG が読み込まれない	設定内のパスと Markdown 形式を確認します
エージェントが見つからない	cargo build -p terraphim_agent --features repl-full --release でビルドします

関連スキル

• terraphim-hooks - ナレッジグラフを使ったテキスト置換
• session-search - AI コーディングセッションの履歴検索
• rust-development - Rust 固有のパターン