@knowledgine/cli 0.4.1 → 0.6.0

package/dist/templates/skills/knowledgine-memory/skill-md.ja.js

@@ -0,0 +1,169 @@
+export const SKILL_MD = `---
+name: knowledgine-memory
+version: "1.0.0"
+lang: ja
+description: >
+  タスクの状態、コンテキスト、学習したパターンのセッション横断メモリを管理する。
+  永続的な知識ではなく、現在のタスク進捗、セッションコンテキスト、作業中に
+  学習した手順的パターンなど、セッションをまたいで情報を保持する必要がある場合に呼び出す。
+  永続的・精選された知識を保存する knowledgine-capture とは異なる。
+---
+# knowledgine-memory
+
+## 目的
+
+メモリレイヤーシステムを使用して、セッションスコープおよびセッション横断の状態を管理する。
+メモリエントリは、作業内容、中断した箇所、繰り返し発生する問題の解決方法を追跡する—
+一時的なコンテキストで永続的なナレッジベースを汚染しない。
+
+## 使用するタイミング
+
+以下のいずれかに該当する場合はメモリツールを使用する:
+
+1. **タスク進捗の追跡** — 複数ステップのタスクの途中で、次のセッションで再開したい
+2. **セッションコンテキストの永続化** — コンテキスト（未解決の疑問、現在の仮説、ブロッキングな問題）を引き継ぎたい
+3. **手順的パターンの学習** — 再利用する価値のある繰り返し可能なワークフローやデバッグ戦略を発見した
+4. **ユーザー設定と作業状態** — 作業中に学習した設定、エイリアス、ワークスペース構成
+5. **有効期限付きの一時的なメモ** — 自動的に期限切れになる短期的なリマインダーや進行中の状態（TTL を使用）
+
+## 使用しないタイミング
+
+- **永続的な知識** → \`knowledgine-capture\` を使用（バグ修正、設計上の決定、再利用可能なパターン）
+- **プロジェクトドキュメントやソースファイル** → \`knowledgine-ingest\` を使用
+- **セッション終了時のサマリー** → \`knowledgine-debrief\` を使用（内部で store_memory を呼び出す場合あり）
+- チーム全体で共有したい事実や解決策 → \`knowledgine-capture\` を使用
+
+## メモリレイヤー
+
+情報の期待される有効期間に合ったレイヤーを選択する:
+
+| レイヤー | 有効期間 | 答える問い | 推奨 TTL |
+|-------|----------|---------------------|-----------------|
+| \`episodic\` | 数時間〜数日 | 「今、何をしているか？」 | 3600〜86400秒 |
+| \`semantic\` | 数日〜数週間 | 「今週、何を学んだか？」 | 604800秒 または なし |
+| \`procedural\` | 数週間〜永続的 | 「この種の問題をどう解決するか？」 | なし |
+
+- **episodic** — 短期的なセッションコンテキスト。TTL を設定して古い状態を自動的に期限切れにする。例: 現在のタスクの説明、進行中のデバッグコンテキスト、セッションの目標。
+- **semantic** — 進行中のプロジェクトフェーズに関連する中期的な事実と決定。例: チームの決定、プロジェクトの制約、コードベースのセクションについて学習した事実。
+- **procedural** — 長期的なパターンと再利用可能なスキル。複数のセッションにわたってパターンが安定したと証明されたら semantic から昇格させる。例: デバッグワークフロー、コードレビューチェックリスト、デプロイ手順。
+
+昇格ワークフローとレイヤーごとのタグ戦略は \`layer-guide.md\` を参照。
+
+## 使用方法（MCP ツール）
+
+### store_memory
+
+新しいメモリエントリを保存する。
+
+\`\`\`
+store_memory(
+  content: string,                         // メモリコンテンツ（必須、空でない）
+  layer?: "episodic" | "semantic" | "procedural",  // デフォルト: episodic
+  tags?: string[],                         // リコールフィルタリング用の分類タグ
+  metadata?: {
+    source?: string,                       // 起源（ファイル、URL、ツール名）
+    project?: string,                      // プロジェクトスコープ
+    sessionId?: string,                    // セッション識別子
+    confidence?: number,                   // 0〜1 の信頼度スコア
+  },
+  ttl?: number,                            // 生存期間（秒）（オプション）
+)
+\`\`\`
+
+### recall_memory
+
+クエリ、フィルター、または最新順でメモリエントリを取得する。
+
+\`\`\`
+recall_memory(
+  query?: string,                          // 全文検索（最新エントリの場合は省略）
+  filter?: {
+    layer?: "episodic" | "semantic" | "procedural",
+    tags?: string[],                       // AND フィルター — すべてのタグが一致する必要あり
+    createdAfter?: string,                 // ISO 8601 下限
+    createdBefore?: string,               // ISO 8601 上限
+    memoryIds?: string[],                  // ID で特定のエントリを取得
+  },
+  limit?: number,                          // デフォルト: 10、最大: 100
+  includeVersionHistory?: boolean,         // デフォルト: false
+  asOf?: string,                           // ISO 8601 時点クエリ
+)
+\`\`\`
+
+### update_memory
+
+既存エントリのコンテンツ、タグ、メタデータを更新する。デフォルトでバージョンスナップショットを作成する。
+
+\`\`\`
+update_memory(
+  id: string,                              // メモリエントリ ID（必須）
+  content?: string,                        // 置換コンテンツ
+  summary?: string,                        // 置換サマリー
+  tags?: string[],                         // 置換タグ（マージではなく完全置換）
+  metadata?: {                             // メタデータの部分マージ
+    source?: string,
+    project?: string,
+    sessionId?: string,
+    confidence?: number,
+  },
+  createVersion?: boolean,                 // デフォルト: true（不変バージョンが作成される）
+)
+\`\`\`
+
+### forget_memory
+
+メモリエントリを削除する。デフォルトはソフト削除（復元可能）；ハード削除はデータを完全に削除する。
+
+\`\`\`
+forget_memory(
+  id: string,                              // メモリエントリ ID（必須）
+  reason?: string,                         // 削除理由（監査ログに書き込まれる）
+  hard?: boolean,                          // デフォルト: false（ソフト削除）
+)
+\`\`\`
+
+## 手順
+
+### メモリの保存
+
+1. **レイヤーを選択する** — 現在のタスク状態は episodic、事実と決定は semantic、繰り返し可能なパターンは procedural
+2. **明確なコンテンツを書く** — 再調査なしに将来のセッションで行動できるよう、十分なコンテキストを含める
+3. **episodic エントリに TTL を設定する** — 期待される関連期間に応じて 3600（1 時間）、86400（1 日）、604800（1 週間）
+4. **タグを追加する** — 効率的なリコールフィルタリングのため 2〜4 個のタグを使用する（例: \`["auth", "in-progress", "session-2024-01"]\`）
+5. **store_memory を呼び出す** — content、layer、tags、オプションで metadata/ttl を渡す
+6. **返された ID を記録する** — このエントリを後で更新または削除する必要がある場合に保存する
+
+### セッション開始時にメモリを呼び出す
+
+1. 引数なしで \`recall_memory\` を呼び出して最新エントリを取得する（デフォルト上限: 10）
+2. オプションでレイヤー（\`episodic\`）でフィルタリングして現在のタスク状態に集中する
+3. 特定のタスクを再開する場合は、タグまたはプロジェクトメタデータで検索する
+4. エントリを確認し、期限切れまたは不要なものを \`forget_memory\` で削除する
+
+### メモリの更新
+
+1. 前回の \`store_memory\` 結果または \`recall_memory\` からエントリ ID を取得する
+2. ID と変更フィールドを指定して \`update_memory\` を呼び出す
+3. 重要な更新には \`createVersion: true\`（デフォルト）のまま — 履歴が保持される
+4. \`createVersion: false\` は軽微な修正（タイポ、フォーマット）のみに使用する
+
+### クリーンアップ
+
+1. タスクが完了したらエントリ ID を指定して \`forget_memory\` を呼び出す
+2. 監査の明確さのために \`reason\` を指定する（例: \`"Task completed — captured in knowledgine-capture"\`）
+3. 物理的に削除する必要があるデータを含む場合を除き、ソフト削除（デフォルト）を優先する
+
+## ベストプラクティス
+
+- **episodic メモリには TTL を使用する** — セッション内メモには 3600（1 時間）、翌日継続には 86400（1 日）、進行中のタスクには 604800（1 週間）
+- **リコール効率のためにタグ付けする** — タグは AND フィルタリングされる；コンテキストを一意に識別する具体的なタグを使用する（プロジェクト名、タスクエリア、ステータス）
+- **重要な更新にはバージョンを作成する** — デフォルトの \`createVersion: true\` は不変の監査証跡を作成する；重要なコンテンツ変更では無効にしない
+- **ソフト削除を優先する** — \`hard: false\`（デフォルト）はエントリを復元可能に保ち監査ログを維持する；データを物理的にパージする必要がある場合のみ \`hard: true\` を使用する
+- **意図的にレイヤー間を昇格させる** — episodic メモリが複数のセッションで有用と証明されたら semantic として再保存する；semantic パターンが安定したスキルになったら procedural に昇格させる
+
+## 参照ファイル
+
+- 各レイヤーの詳細ガイダンス（例、TTL の推奨値、レイヤー昇格ワークフロー）は \`layer-guide.md\` を参照
+- メモリツールと knowledgine-capture の比較判断マトリクスは \`memory-vs-knowledge.md\` を参照
+`;
+//# sourceMappingURL=skill-md.ja.js.map

package/dist/templates/skills/knowledgine-memory/skill-md.ja.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-md.ja.js","sourceRoot":"","sources":["../../../../src/templates/skills/knowledgine-memory/skill-md.ja.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuKvB,CAAC"}

package/dist/templates/skills/knowledgine-memory/skill-md.js

@@ -0,0 +1,169 @@
+export const SKILL_MD = `---
+name: knowledgine-memory
+version: "1.0.0"
+lang: en
+description: >
+  Manage cross-session memory for task state, context, and learned patterns. Invoke when
+  you need to persist information across sessions that is not permanent knowledge — such
+  as current task progress, session context, or procedural patterns learned during work.
+  Distinct from knowledgine-capture which stores permanent, curated knowledge.
+---
+# knowledgine-memory
+
+## Purpose
+
+Manage session-scoped and cross-session state using the memory layer system. Memory entries
+track what you are doing, where you left off, and how you solve recurring problems — without
+polluting the permanent knowledge base with ephemeral context.
+
+## When to Use
+
+Use memory tools when any of the following apply:
+
+1. **Task progress tracking** — You are mid-way through a multi-step task and want to resume in a future session
+2. **Session context persistence** — You need to carry forward context (open questions, current hypotheses, blocking issues)
+3. **Procedural pattern learning** — You discovered a repeatable workflow or debugging strategy worth reusing
+4. **User preferences and working state** — Preferences, aliases, or workspace configuration learned during work
+5. **Temporary notes with expiration** — Short-lived reminders or in-progress state that should expire automatically (use TTL)
+
+## When NOT to Use
+
+- **Permanent knowledge** → use \`knowledgine-capture\` (bug fixes, design decisions, reusable patterns)
+- **Project documentation or source files** → use \`knowledgine-ingest\`
+- **End-of-session summary** → use \`knowledgine-debrief\` (which may call store_memory internally)
+- Facts or solutions you want to share team-wide → use \`knowledgine-capture\`
+
+## Memory Layers
+
+Choose the layer that matches the expected lifespan of the information:
+
+| Layer | Lifespan | Question it answers | Recommended TTL |
+|-------|----------|---------------------|-----------------|
+| \`episodic\` | Hours to days | "What am I doing right now?" | 3600–86400s |
+| \`semantic\` | Days to weeks | "What did I learn this week?" | 604800s or none |
+| \`procedural\` | Weeks to permanent | "How do I solve this type of problem?" | None |
+
+- **episodic** — Short-term session context. Use TTL to expire stale state automatically. Examples: current task description, in-progress debugging context, session goals.
+- **semantic** — Mid-term facts and decisions relevant to an ongoing project phase. Examples: team decisions, project constraints, learned facts about a codebase section.
+- **procedural** — Long-term patterns and repeatable skills. Promote from semantic when a pattern proves stable across multiple sessions. Examples: debugging workflows, code review checklists, deployment procedures.
+
+See \`layer-guide.md\` for promotion workflow and per-layer tagging strategy.
+
+## How to Use (MCP Tools)
+
+### store_memory
+
+Store a new memory entry.
+
+\`\`\`
+store_memory(
+  content: string,                         // Memory content (required, non-empty)
+  layer?: "episodic" | "semantic" | "procedural",  // Default: episodic
+  tags?: string[],                         // Classification tags for recall filtering
+  metadata?: {
+    source?: string,                       // Origin (file, URL, tool name)
+    project?: string,                      // Project scope
+    sessionId?: string,                    // Session identifier
+    confidence?: number,                   // 0–1 confidence score
+  },
+  ttl?: number,                            // Time-to-live in seconds (optional)
+)
+\`\`\`
+
+### recall_memory
+
+Retrieve memory entries by query, filter, or recency.
+
+\`\`\`
+recall_memory(
+  query?: string,                          // Full-text search (omit for recent entries)
+  filter?: {
+    layer?: "episodic" | "semantic" | "procedural",
+    tags?: string[],                       // AND filter — all tags must match
+    createdAfter?: string,                 // ISO 8601 lower bound
+    createdBefore?: string,               // ISO 8601 upper bound
+    memoryIds?: string[],                  // Retrieve specific entries by ID
+  },
+  limit?: number,                          // Default: 10, max: 100
+  includeVersionHistory?: boolean,         // Default: false
+  asOf?: string,                           // ISO 8601 point-in-time query
+)
+\`\`\`
+
+### update_memory
+
+Update content, tags, or metadata of an existing entry. Creates a version snapshot by default.
+
+\`\`\`
+update_memory(
+  id: string,                              // Memory entry ID (required)
+  content?: string,                        // Replacement content
+  summary?: string,                        // Replacement summary
+  tags?: string[],                         // Replacement tags (full replace, not merge)
+  metadata?: {                             // Partial metadata merge
+    source?: string,
+    project?: string,
+    sessionId?: string,
+    confidence?: number,
+  },
+  createVersion?: boolean,                 // Default: true (immutable version created)
+)
+\`\`\`
+
+### forget_memory
+
+Delete a memory entry. Soft delete by default (recoverable); hard delete removes data permanently.
+
+\`\`\`
+forget_memory(
+  id: string,                              // Memory entry ID (required)
+  reason?: string,                         // Deletion reason (written to audit log)
+  hard?: boolean,                          // Default: false (soft delete)
+)
+\`\`\`
+
+## Step-by-Step Instructions
+
+### Storing a memory
+
+1. **Choose the layer** — episodic for current task state, semantic for facts and decisions, procedural for repeatable patterns
+2. **Write clear content** — Include enough context for you (or the agent) to act on the memory in a future session without re-investigation
+3. **Set TTL for episodic entries** — 3600 (1 hour), 86400 (1 day), or 604800 (1 week) depending on expected relevance window
+4. **Add tags** — Use 2–4 tags to enable efficient recall filtering (e.g., \`["auth", "in-progress", "session-2024-01"]\`)
+5. **Call store_memory** — Pass content, layer, tags, and optional metadata/ttl
+6. **Note the returned ID** — Store it if you will need to update or delete this entry later
+
+### Recalling memories at session start
+
+1. Call \`recall_memory\` with no arguments to get recent entries (default limit: 10)
+2. Optionally filter by layer (\`episodic\`) to focus on current task state
+3. If resuming a specific task, search by tags or project metadata
+4. Review entries and discard expired or irrelevant ones with \`forget_memory\`
+
+### Updating a memory
+
+1. Retrieve the entry ID from a prior \`store_memory\` result or \`recall_memory\`
+2. Call \`update_memory\` with the ID and changed fields
+3. Leave \`createVersion: true\` (default) for important updates — this preserves the history
+4. Use \`createVersion: false\` only for minor corrections (typos, formatting)
+
+### Cleaning up
+
+1. Call \`forget_memory\` with the entry ID when a task is complete
+2. Provide a \`reason\` for audit clarity (e.g., \`"Task completed — captured in knowledgine-capture"\`)
+3. Prefer soft delete (default) unless the entry contains data that must be physically removed
+
+## Best Practices
+
+- **Use TTL for episodic memories** — 3600 (1 hr) for within-session notes, 86400 (1 day) for next-day continuation, 604800 (1 week) for ongoing tasks
+- **Tag for recall efficiency** — Tags are AND-filtered; use specific tags that uniquely identify the context (project name, task area, status)
+- **Create versions for important updates** — The default \`createVersion: true\` creates an immutable audit trail; do not disable it for significant content changes
+- **Prefer soft delete** — \`hard: false\` (default) keeps entries recoverable and maintains the audit log; use \`hard: true\` only when data must be physically purged
+- **Promote across layers deliberately** — When an episodic memory proves useful across multiple sessions, re-store it as semantic; when a semantic pattern becomes a stable skill, promote to procedural
+
+## Reference Files
+
+- See \`layer-guide.md\` for detailed guidance on each layer with examples, TTL recommendations, and the layer promotion workflow
+- See \`memory-vs-knowledge.md\` for a decision matrix comparing memory tools with knowledgine-capture
+`;
+//# sourceMappingURL=skill-md.js.map

package/dist/templates/skills/{knowledgine-recall → knowledgine-memory}/skill-md.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-md.js","sourceRoot":"","sources":["../../../../src/templates/skills/knowledgine-recall/skill-md.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoFvB,CAAC"}
+{"version":3,"file":"skill-md.js","sourceRoot":"","sources":["../../../../src/templates/skills/knowledgine-memory/skill-md.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuKvB,CAAC"}

package/dist/templates/skills/knowledgine-search/references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../../../../src/templates/skills/knowledgine-search/references.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAuT7C,CAAC"}

package/dist/templates/skills/knowledgine-search/references.ja.d.ts

@@ -0,0 +1,2 @@
+export declare const REFERENCES: Record<string, string>;
+//# sourceMappingURL=references.ja.d.ts.map

package/dist/templates/skills/knowledgine-search/references.ja.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.ja.d.ts","sourceRoot":"","sources":["../../../../src/templates/skills/knowledgine-search/references.ja.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAwT7C,CAAC"}

package/dist/templates/skills/knowledgine-search/references.ja.js

@@ -0,0 +1,313 @@
+export const REFERENCES = {
+    "search-strategy.md": `# 検索戦略
+
+適切な検索モードの選択方法、コンテキストシグナルの抽出方法、
+クエリ検索・コンテキストベースのサジェスト・グラフ走査を組み合わせた
+効果的な検索ワークフローの構築方法。
+
+---
+
+## モードの選択
+
+### キーワードモード
+
+SQLite FTS5 全文検索を使用します。正確な単語を含むドキュメントに一致します。
+
+**最適な用途**:
+- 正確なエラーメッセージ（例: \`"SQLITE_ERROR: no such module: vec0"\`）
+- 関数名や変数名（例: \`"capture_knowledge"\`, \`"KnowledgeRepository"\`）
+- ファイルパス（例: \`"packages/core/src"\`）
+- バージョン文字列や識別子
+
+**制限事項**:
+- 同義語には一致しない（"fix" は "resolve" に一致しない）
+- 大文字小文字は区別しないが、単語境界には敏感
+- 複数語のクエリではフレーズの順序が重要
+
+**例**:
+\`\`\`
+search_knowledge(query: "ENOENT no such file or directory", mode: "keyword")
+\`\`\`
+
+### セマンティックモード
+
+ベクトル埋め込みを使用して意味によって一致します。共通の単語がなくても関連するコンテンツを見つけます。
+
+**最適な用途**:
+- 概念的なクエリ（例: "認証エラーの処理方法"）
+- 何を求めているかはわかるが正確な語句が不明な場合
+- 特定のエラーメッセージなしにトピックを探索する場合
+- 言語をまたいだ、または言い換えによる一致
+
+**要件**:
+- ナレッジベースが \`--semantic\` フラグで初期化されている必要がある
+- 埋め込みが利用できない場合はキーワード検索にフォールバック
+
+**例**:
+\`\`\`
+search_knowledge(query: "user authentication token expiry", mode: "semantic")
+\`\`\`
+
+### ハイブリッドモード
+
+キーワードとセマンティックのスコアを組み合わせます。両モードの最良の結果を返します。
+
+**最適な用途**:
+- ファイルパス、タスクの説明、機能領域から導出されたコンテキストベースのクエリ
+- 最も汎用的な探索
+- どちらのモードが良いかわからない場合
+- 正確な語句と概念を混在させた複雑なクエリ
+
+**例**:
+\`\`\`
+search_knowledge(query: "TypeScript null safety database repository", mode: "hybrid")
+\`\`\`
+
+---
+
+## コンテキストシグナルの抽出
+
+特定の検索クエリがない場合は、現在の作業コンテキストからシグナルを抽出します。
+
+### シグナルの種類
+
+| シグナルの種類 | 入力例 | 抽出されるクエリ |
+|----------------|--------|-----------------|
+| ファイルパス | \`src/commands/setup.ts\` | \`"setup command configuration"\` |
+| ファイルパス | \`packages/core/src/config/config-loader.ts\` | \`"config loader configuration"\` |
+| ファイルパス | \`packages/ingest/src/plugins/github.ts\` | \`"github ingest plugin"\` |
+| コンポーネント名 | \`SetupCommand\`, \`KnowledgeRepository\` | キーワードクエリとして直接使用 |
+| タスクの説明 | "セットアップコマンドに TOML 設定ファイルのサポートを追加" | \`"TOML configuration setup"\` |
+| タスクの説明 | "空のドキュメントに対するエンティティ抽出パイプラインを修正" | \`"entity extraction empty document"\` |
+| エラーメッセージ | "SQLITE_ERROR: table entities has no column 'confidence'" | \`"SQLITE_ERROR entities column"\` |
+| 機能領域 | MCP 設定 | \`"MCP server configuration"\` |
+| 機能領域 | 検索 | \`"search_knowledge FTS5 semantic"\` |
+
+### マルチシグナルクエリ
+
+より絞り込んだ結果を得るために 2〜3 個のシグナルを組み合わせます:
+
+\`\`\`
+// ファイル + タスク
+query: "config-loader TOML parsing"
+
+// コンポーネント + 問題の種類
+query: "KnowledgeRepository null safety"
+
+// 技術 + パターン
+query: "sqlite migration schema change"
+\`\`\`
+
+---
+
+## ワークフローパターン
+
+### パターン 1: セッション開始
+
+既知の領域で作業を始めるとき:
+
+1. 主要なファイルまたは機能領域からコンテキストを抽出する
+2. 組み合わせたコンテキストクエリでハイブリッド検索を実行する
+3. 上位 3〜5 件の結果を確認し、警告や過去の決定を記録する
+4. 現在のファイルパスで \`find_related\` を使用して接続されたノートを発見する
+5. 特定の問題が発生したら対象を絞ったキーワードクエリで進む
+
+\`\`\`
+// Step 1: コンテキストベースの検索
+search_knowledge(query: "setup command MCP configuration", mode: "hybrid", limit: 10)
+
+// Step 2: グラフの走査
+find_related(filePath: "src/commands/setup.ts", limit: 5)
+\`\`\`
+
+### パターン 2: エラー発生時
+
+エラーや例外が発生したとき:
+
+1. 正確なエラーメッセージをコピーする
+2. エラーメッセージでキーワード検索を実行する
+3. 結果がなければ、エラーのキーとなる名詞を抽出して再試行する
+4. それでも結果がなければ、症状の説明でセマンティック検索を試みる
+
+\`\`\`
+Error: "Cannot find module '@knowledgine/core'"
+→ keyword: "Cannot find module @knowledgine/core"
+→ keyword: "module resolution"
+→ semantic: "TypeScript module not found build error"
+\`\`\`
+
+### パターン 3: 慣れないコードの探索
+
+慣れないコンポーネントやモジュールに取り組むとき:
+
+1. ファイルパスで検索: \`keyword: "src/commands/setup.ts"\`
+2. コンポーネント名で検索: \`keyword: "setupCommand"\`
+3. トピックで検索: \`semantic: "MCP configuration setup"\`
+4. 関連する結果からグラフを走査: \`find_related(noteId: <id>, maxHops: 2)\`
+
+### パターン 4: 変更を加える前に
+
+アーキテクチャ上の決定や重要な変更を行う前に:
+
+1. 過去の決定を検索: \`keyword: "design-decision <topic>"\`
+2. 関連するパターンを検索: \`semantic: "<concept> pattern implementation"\`
+3. 関連する noteId で \`find_related\` を使用して接続された決定を見つける
+
+---
+
+## 結果の解釈
+
+### キーワードモード（BM25 スコア）
+
+結果は BM25 関連性スコアで並べられています。高いほど良い；固定スケールはありません。
+包括的なコンテキストを構築する場合以外は、上位 3〜5 件の結果に注目してください。
+
+### セマンティックモード（コサイン類似度）
+
+| スコア | 意味 |
+|--------|------|
+| > 0.9 | 非常に強い一致 — 関連性が高い可能性が高い |
+| 0.7〜0.9 | 良い一致 — 適用可能性を確認 |
+| 0.5〜0.7 | 弱い一致 — 関連する場合と関連しない場合がある |
+| < 0.5 | 周辺的 — より良い結果がなければ通常スキップ |
+
+### ハイブリッドモード
+
+スコアは BM25 とコサイン類似度を組み合わせています。絶対値よりも相対的な順序を
+複合シグナルとして扱ってください。
+
+---
+
+## find_related によるグラフ走査
+
+最初の関連ノートを見つけた後、\`find_related\` を使って接続されたノートを発見します:
+
+\`\`\`
+// 検索結果から数値のノート ID を使用
+find_related(noteId: 42, limit: 5, maxHops: 1)
+
+// または現在のファイルパスで直接検索
+find_related(filePath: "packages/core/src/config/config-loader.ts", limit: 5)
+\`\`\`
+
+**重要**: \`noteId\` は文字列ではなく数値（整数）でなければなりません。
+\`search_knowledge\` の結果の \`id\` フィールドをそのまま使用してください。
+
+**maxHops のガイダンス**:
+
+| maxHops | 効果 |
+|---------|------|
+| 1 | 直接の参照のみ — 高速で焦点が絞られている（デフォルト） |
+| 2 | 1 度の分離 — 探索に適している |
+| 3 | より広いグラフ — オープンエンドな探索に使用 |
+`,
+    "query-tips.md": `# クエリのヒント
+
+様々な状況に対応した効果的な検索クエリの作成方法、テンプレート、
+フォールバック戦略、上限のガイダンス。
+
+---
+
+## 一般的な原則
+
+1. **具体性が勝る** — 具体的なクエリは曖昧なクエリより優れている
+   - 悪い例: \`"error"\`
+   - 良い例: \`"TypeError cannot read properties of undefined"\`
+
+2. **名詞と識別子を使用する** — 動詞や形容詞はノイズを増やす
+   - 悪い例: \`"null のときに壊れたものをどう修正するか"\`
+   - 良い例: \`"null check repository getById"\`
+
+3. **エラーメッセージは宝の山** — キーワードモードではそのまま貼り付ける
+
+4. **概念には自然言語を使う** — セマンティックモードでは状況を説明する
+   - \`"what approach did we use for caching database results"\`
+
+---
+
+## 状況別クエリテンプレート
+
+### エラーメッセージ
+\`\`\`
+// 正確なエラーメッセージをそのまま貼り付ける
+keyword: "<exact error text>"
+
+// 長すぎる場合は固有の部分を使用
+keyword: "SQLITE_CONSTRAINT UNIQUE"
+\`\`\`
+
+### ファイルまたはコンポーネント
+\`\`\`
+keyword: "<拡張子なしのファイル名>"
+keyword: "<ClassName> OR <functionName>"
+\`\`\`
+
+### 設計トピック
+\`\`\`
+semantic: "<component> architecture decision"
+keyword: "design-decision <topic>"
+\`\`\`
+
+### 過去の問題
+\`\`\`
+semantic: "<症状の説明（平易な言葉で）>"
+hybrid: "<technology> <problem noun>"
+\`\`\`
+
+### パターン検索
+\`\`\`
+keyword: "pattern <concept>"
+semantic: "reusable pattern for <problem type>"
+\`\`\`
+
+### コンテキストベース（セッション開始またはファイルを開いたとき）
+\`\`\`
+// ファイル領域 + タスクを組み合わせる
+hybrid: "<module-name> <task-noun>"
+
+// 機能領域
+hybrid: "<feature area> <technology>"
+\`\`\`
+
+---
+
+## 最初のクエリで結果が得られなかったとき
+
+以下のフォールバック戦略を順番に試みてください:
+
+1. **クエリを広げる** — 具体的な識別子を削除し、名詞だけを残す
+   - \`"SQLITE_ERROR: table notes has no column 'embedding'"\`
+   - → \`"sqlite migration column"\`
+
+2. **モードを切り替える** — キーワードが失敗したらセマンティックまたはハイブリッドを試み、
+   セマンティックが失敗したらキーワードを試みる
+
+3. **同義語クエリ** — 関連する語句を使用する
+   - \`"authentication"\` → \`"auth session token login"\`
+
+4. **タグベースのクエリ** — タグカテゴリで検索する
+   - \`"bug-fix typescript"\`
+   - \`"design-decision database"\`
+
+5. **結果なしを受け入れる** — すべての問題が事前に記録されているわけではありません。
+   解決した後、knowledgine-capture を使って解決策を記録してください。
+
+---
+
+## 上限のガイダンス
+
+| 状況 | 推奨上限 |
+|------|---------|
+| クイックルックアップ（既知のトピック） | 3〜5 |
+| 一般的な探索 | 10 |
+| セッション開始時の完全なコンテキスト構築 | 15〜20 |
+| レアなエントリを見つける | 20（デフォルト） |
+
+\`search_knowledge\` のデフォルト上限は **20** です。クエリが正確な場合は
+ノイズを避けるために低い上限を使用してください。\`find_related\` のデフォルト上限は
+**5** です — これはほとんどのグラフ走査操作に適切です。
+
+上限を大きくすると検索が若干遅くなります；クエリが正確な場合は低い上限を優先してください。
+`,
+};
+//# sourceMappingURL=references.ja.js.map

package/dist/templates/skills/knowledgine-search/references.ja.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.ja.js","sourceRoot":"","sources":["../../../../src/templates/skills/knowledgine-search/references.ja.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAA2B;IAChD,oBAAoB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyMvB;IAEC,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2GlB;CACA,CAAC"}