agent-knowledge

AIコーディングアシスタント向けのセッション横断メモリとリコール -- Claude Code、Cursor、OpenCode、Cline、Continue.dev、Aiderでそのまま動作します。Git同期ナレッジベース、ハイブリッドセマンティック+TF-IDF検索、シークレットスクラビング付き自動蒸留。

ベンチマーク: longmemeval_s で R@5 = 97.2%（スパース）/ 98.8%（ハイブリッド）、より難しい longmemeval_m 分割で 86.0%（スパース）/ 88.4%（ハイブリッド） — 公開のLongMemEval学術ベンチマーク（Wu et al. 2024, ICLR 2025）、各分割で全500問、LLM不要、APIキー不要、完全オフラインで実行。論文の公式 flat-bm25 ベースラインに対して、同一条件の再現でR@5が+8.6pp〜+13.2pp向上。カテゴリ別の完全な表、再現手順、論文比較の詳細は bench/README.md を参照。

なぜ必要か

AIコーディングセッションは一時的なものです。セッションが終わると、そこで学んだすべて（アーキテクチャ決定、デバッグの洞察、プロジェクトコンテキスト）は失われます。次のセッションはゼロから始まります。

agent-knowledge は、2つの補完的なシステムでこれを解決します：

1. ナレッジベース -- 構造化エントリ（決定、ワークフロー、プロジェクトコンテキスト）のGit同期マークダウンボールトで、セッションやマシンを超えて永続化されます。

2. セッション検索 -- すべてのコーディングツールのセッショントランスクリプトに対するTF-IDFランキングの全文検索で、エージェントが以前の出来事を思い出せるようにします。どのツールが使われたかに関係なく。

Related MCP server: Doclea MCP

対応ツール

主要なAIコーディングアシスタントのセッションは自動検出されます。ツールがインストールされていれば、そのセッションが自動的に表示されます。

設定は不要です。追加のセッションルートは、AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS 環境変数（カンマ区切りのパス）で追加できます。

機能

• ホスト非依存のセッション検索 -- 主要なAIコーディングアシスタント（Claude Code、Cursor、Codex CLI、Aider、Continue.dev、Cline、OpenCode）全体での統合検索。設定にホスト名は組み込まれておらず、アダプタレジストリが起動時にインストール済みホストルートをプローブします。

• ハイブリッド検索 -- セマンティックベクトル類似度とTF-IDFキーワードランキングをブレンド

• Git同期ナレッジベース -- YAMLフロントマター付きマークダウンボールト、書き込み時に自動コミットとプッシュ

• 自動陳腐化検出 -- knowledge_analyze(action: "stale_by_code_activity") は、各エントリ本文で言及されているファイルパスを、最近のセッションサマリーの filesModified と相互参照します。シンボル存在の精度レイヤーと組み合わせて：エントリが引用する識別子（インラインバッククォート+フェンスブロック）がタッチされたファイルでチェックされ、まだ存在する場合は信頼度が×0.3にダウンウェイトされます。evergreen: true のエントリは免除されます。

• 検索ギャップ追跡 -- knowledge_analyze(action: "search_gaps") は、過去 since_days のゼロ結果クエリをトークンJaccard類似度でグループ化して表示します。「次にどのエントリを書くべきか」の最も明確なシグナルです。

• セクション優先コンテキストパッカー -- knowledge(action: "wakeup") は、トークン予算（デフォルト800、token_budget または AGENT_KNOWLEDGE_WAKEUP_BUDGET で上書き可能）内でマルチセクションバンドル（identity → active_tasks → recent_decisions → known_gotchas → last_session_summary → top_weighted → semantic_fallback）を組み立てます。未使用のセクション予算は後のセクションに再配分されます。

• スコア付き+ゲート付きプロモーター -- セッションインサイトは、6シグナルの重み付きスコアラーと3つの独立したゲート（minScore、minRecallCount、minUniqueQueries）でプロモートされます。バックグラウンドで自動実行、knowledge_admin(action: "promote") でオンデマンド実行、または npm run bench:promote でオフラインでベンチマーク可能。実行ごとに監査可能な .dreams/YYYY-MM-DD.md ダイアリーを出力します。

• プラグ可能なアダプタシステム -- SessionAdapter インターフェースを実装することで新しいツールのサポートを追加

• 埋め込み -- ローカル（Hugging Face）、OpenAI、Claude/Voyage、またはGeminiプロバイダー

• ファジーマッチング -- Levenshtein距離によるタイポ耐性検索

• 6つの検索スコープ -- エラー、プラン、設定、ツール、ファイル、決定

• 6つのMCPツール -- 統合されたアクションベースのインターフェース（knowledge、knowledge_search、knowledge_session、knowledge_graph、knowledge_analyze、knowledge_admin）

• エバーグリーンエントリ -- フロントマターの evergreen: true は、ランキングでの減衰からエントリを免除し、プロモーション下で追加専用にします。ダッシュボードはこれらのカードにピン留めバッジを表示します。

• 著者帰属 -- オプションの author: <string> フロントマターは、各カードに控えめなチップとして表示されます。

• コードグラフ解決 -- コード構造のための calls、imports、inherits エッジタイプ。有向BFSトラバーサル（outbound/inbound/both）。効率的な取り込みのための bulk_link。再取り込み前に古いコードエッジをクリアするための unlink_by_origin。code: プレフィックス付きノードIDはコードとナレッジを区別します。

• 時間的ナレッジグラフ -- エッジは valid_from / valid_to の有効期間ウィンドウをサポート。as_of クエリは特定時点のスナップショットを返します。invalidate アクションは事実を削除せずに終了としてマークします。

• ハイブリッドスコアリングブースト -- 固有名詞と時間的近接性のブーストをTF-IDF+セマンティックブレンドに追加し、+66.7%で上限、シグナルがない場合はショートサーキット。

• カテゴリをフィルタではなくブーストとして -- category_mode: "boost" をオプトインすると、カテゴリの推測が間違っていても正しい答えを破棄せずにランクを下げるだけになります。

• 逐語セッションインデックス -- メッセージごとのチャンク（30文字以上）をベクトルストアに埋め込み、生の会話を検索可能にします。AGENT_KNOWLEDGE_INDEX_VERBATIM=false で切り替え。

• 設定可能なGit URL -- ランタイムセットアップ用の knowledge_admin(action: "config")。XDG/AppDataの場所に永続化。

• クロスマシン永続化 -- ナレッジはgitで同期され、セッションは各ツールのローカルストレージから読み取られます。

• リアルタイムダッシュボード -- localhost:3423 で閲覧、検索、管理。

• シークレットスクラビング -- APIキー、トークン、パスワード、秘密鍵はgitプッシュ前に自動的に編集されます。

• ナレッジグラフ -- エントリ間の関係エッジ（related_to、supersedes、depends_on、contradicts、specializes、part_of、alternative_to、builds_on）とBFSトラバーサル。

• 信頼度/減衰スコアリング -- エントリはアクセス頻度と新しさでスコアリングされ、候補から確立、実証済みへ自動プロモーション。

• メモリ統合 -- 書き込み時のTF-IDF重複検出（類似エントリの警告）に加え、knowledge_analyze(action: "consolidate") によるバッチ重複スキャン。

• リフレクションサイクル -- knowledge_analyze(action: "reflect") は接続されていないエントリを表面化し、エージェントが新しいグラフ接続を特定するための構造化プロンプトを生成します。

• 書き込み時の自動リンク -- 新しいエントリは、コサイン類似度が0.7を超える場合、上位3件の類似既存エントリに自動的にリンクされます。

• 信頼度メタデータ — エントリは extracted（ユーザー作成）または inferred（自動蒸留、検索ランク乗数0.85×）とタグ付けされ、confidence_score フィールドはモデルの確信度0-1を保持します。

• ナレッジ分析 — knowledge_analyze アクション god_nodes（最も接続されたエントリ）、bridges（カテゴリ間コネクタ）、gaps（孤立エントリ）。

• ナレッジブリーフ — knowledge_analyze(action: "brief") は、セッション開始時のオリエンテーション用にキャッシュされた約200トークンのサマリー（コアコンセプト、アクティブプロジェクト、最近の決定、陳腐化とギャップの数）を返します。

• エッジの来歴 — グラフエッジは origin（manual、auto-link、distill、reflect）を追跡し、分析がユーザーの判断と自動ヒューリスティックを区別できるようにします。

• 蒸留における決定的事前抽出 — セッションサマリーには、bash/ツール出力から正規表現で抽出されたgitコミット、エラーパターン、アクセスしたURL、変更されたパッケージが含まれます（LLMコストなし）。

• すべての検索ヒットに鮮度メタデータ — すべてのナレッジ結果には freshness: { body_age_days, last_accessed, access_count, verified_at, verification_age_days, evergreen } が付属します。エージェントは信頼シグナルを読み取って判断します。ポリシーによる降格は課しません。

• カテゴリ別減衰ウィンドウ — 「未使用」フィルタとタイプ別チャートは、カテゴリ別のしきい値（プロジェクト180日、人365日、決定90日、ワークフロー60日、ノート30日）を尊重するため、アイデンティティ型のコンテンツが毎週再読されないだけで古く見えることはありません。

• ライフサイクルフック — SessionStart 自動ウェイクアップ+取り込み鮮度チェック、UserPromptSubmit 最初のプロンプトへのターゲット注入、PreCompact メモリフラッシュの促し+蒸留、SessionEnd 蒸留。合計6つのフックスクリプト、すべてフェイルオープン、各 AGENT_KNOWLEDGE_* 環境変数で切り替え可能。詳細は docs/HOOKS.md を参照。

• ホスト自動メモリの置き換え — セッションごとのメモリシステムを持つホスト（Claude Codeの ~/.claude/projects/*/memory/、他のIDEでも同様）では、永続的なユーザー事実とフィードバックをagent-knowledgeにルーティングします。自動メモリはマシンローカルで他のマシンから見えません。agent-knowledgeはgit同期、クロスマシン、検索可能で、ウェイクアップに表示されます。Claude Code統合の注意点は docs/USER-MANUAL.md を参照。

コードベース取り込み

knowledge-ingest スキルは、コードベースディレクトリからナレッジベースを入力または更新します。tree-sitterを使用してゼロトークンの構造抽出（クラス、関数、インポート、コールグラフ、根拠コメント）を行い、その後ファイルをサブシステムにクラスタリングし、既存のMCPツールを介してナレッジエントリ+グラフエッジを作成します。以降の実行は増分的で、変更されたファイルのみが再処理されます。

/knowledge-ingest ./my-project

Agent Skills標準を使用 — Claude Code、OpenCode、Cursor、Codex CLI、Gemini CLIで動作します。詳細は取り込みガイドを参照。

対応言語: TypeScript、JavaScript、Python、Go、Rust、Java、C、C++。

クイックスタート

npmからインストール

npm install -g agent-knowledge

またはソースからクローン

git clone https://github.com/keshrath/agent-knowledge.git
cd agent-knowledge
npm install && npm run build

オプション1: MCPサーバー（AIエージェント向け）

MCPクライアント設定（Claude Code、Clineなど）に追加：

{
  "mcpServers": {
    "agent-knowledge": {
      "command": "npx",
      "args": ["agent-knowledge"]
    }
  }
}

ダッシュボードは最初のMCP接続時に http://localhost:3423 で自動起動します。

クライアント固有の手順（Claude Code、Cursor、Windsurf、OpenCode）はセットアップガイドを参照。

オプション2: スタンドアロンサーバー（REST/WebSocketクライアント向け）

node dist/server.js --port 3423

MCPツール（6）

ナレッジベース

検索

レスポンス形式: {mode: "general" | "scoped", sessions, knowledge}。スコープモードでは設計上 knowledge: [] を返します。

スコープ: errors, plans, configs, tools, files, decisions, all。

検索ノブ:

• mmr: true はMaximal Marginal Relevance（最大限界関連性）による再ランキングを適用します（top-K内のほぼ重複クラスタを排除）。mmr_lambda は0〜1、デフォルトは0.7。

• category_mode: "boost"（デフォルト）は、カテゴリが一致するエントリに1.25倍のスコア乗数を適用し、非一致を除外しません。ハードフィルタ動作には "filter" を指定します。

• explain: true はすべてのナレッジヒットに score_components: {bm25, decay, maturity, confidence, category_boost, mmr_penalty} を付加します。

セッション

ナレッジグラフ

ナレッジタイプ: related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on コード構造タイプ: calls, imports, inherits

トラバース方向: outbound（source→target）、inbound（target→source）、both（デフォルト、無向）

分析

管理

スコアリング付きプロモーター

プロジェクトレベルの各候補は6つのシグナル（関連性0.30、頻度0.24、クエリ多様性0.15、新しさ0.15、統合性0.10、概念豊富さ0.06）でスコアリングされ、minScore ≥ 0.5、minRecallCount ≥ 2、minUniqueQueries ≥ 2 のゲートで制御されます。3つのゲートすべてを通過する必要があります。バックグラウンドでの自動プロモーションは同じ auto_distill 設定フラグで制御されます。オンデマンドで knowledge_admin(action: "promote") を呼び出します。

• promote_mode: "explain"（デフォルト）— 候補のスコアリング + ゲート判定、日記の書き込み、KBには一切触れません。

• promote_mode: "apply" — ゲートを通過した候補をプロモートし、日記を書き、gitコミットします。

• 実行のたびに ~/agent-knowledge/.dreams/YYYY-MM-DD.md に候補ごとのシグナル内訳とゲート結果を出力します。. で始まるディレクトリはgit追跡されますが、一覧・検索からは除外されます。

• 根拠に基づく再水和: ソースセッションファイルがディスク上に存在しない候補はスキップされます（削除されたコンテンツのプロモートを防止）。

• evergreen: true フロントマターを持つエントリは、プロモーションによって上書きされることはありません — アクティビティは追記されます。

書き込みベンチハーネス: npm run bench:promote — 「後続セッションで参照された」による自動ラベリング付きオフラインリプレイ。ゲート付きプロモーターをナイーブな「すべて出荷」ベースラインと比較し、precision / recall / F1 を報告します。シグナル重みや閾値の変更をロールアウトする前に、これを使って検証してください。

REST API

アーキテクチャ

graph LR
    subgraph Storage
        KB[(Knowledge Base<br/>~/agent-knowledge<br/>Git Repository)]
    end

    subgraph Session Sources
        CC[(Claude Code<br/>JSONL)]
        CU[(Cursor<br/>JSONL)]
        OC[(OpenCode<br/>SQLite)]
        CL[(Cline<br/>JSON)]
        CD[(Continue.dev<br/>JSON)]
        AI[(Aider<br/>MD / JSONL)]
    end

    subgraph agent-knowledge
        KM[Knowledge Module<br/>store / search / git]
        AD[Session Adapters<br/>auto-discovery]
        SE[Search Engine<br/>TF-IDF + Fuzzy]
        DS[Dashboard<br/>:3423]
        MCP[MCP Server<br/>stdio]
    end

    subgraph Clients
        AG[Agent Sessions]
        WB[Web Browser]
    end

    KB <-->|git pull/push| KM
    CC --> AD
    CU --> AD
    OC --> AD
    CL --> AD
    CD --> AD
    AI --> AD
    AD --> SE
    KM --> MCP
    SE --> MCP
    KM --> DS
    SE --> DS
    MCP --> AG
    DS --> WB

ナレッジグラフ

エントリとコードシンボルは、専用の edges SQLiteテーブルに保存された型付き・重み付きエッジを介して接続できます。11種類のリレーションシップタイプがサポートされています — ナレッジエッジ用に8種類、コード構造用に3種類です:

ナレッジ: related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on コード構造: calls, imports, inherits

• knowledge_graph(action: "link") はエッジを作成・更新します（オプションで強度0〜1を指定可能）

• knowledge_graph(action: "unlink") はエッジを削除します（タイプでフィルタリング可能）

• knowledge_graph(action: "list") はエントリまたはリレーションシップタイプのエッジを一覧表示します

• knowledge_graph(action: "traverse") は開始エントリから有向BFSトラバーサルを実行します。direction（outbound、inbound、both）と rel_type フィルターをサポートします

• knowledge_graph(action: "bulk_link") は単一トランザクションでエッジを一括作成します（コードグラフ取り込み用）

• knowledge_graph(action: "unlink_by_origin") は特定のオリジンを持つすべてのエッジを削除します（再取り込み前に古いコードエッジをクリアするため）

コードグラフ

コード構造エッジは、コードベース取り込み中に knowledge-ingest スキルによって作成されます。code: プレフィックス付きのノードIDを使用します:

code:src/auth/middleware.ts                    # file node
code:src/auth/middleware.ts::validateToken      # symbol node

クエリ例:

# Who calls validateToken?
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", direction: "inbound", rel_type: "calls", depth: 3 })

# What breaks if I change this function?
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", direction: "inbound", rel_type: "calls", depth: 5 })

# Combined: callers + knowledge context (decisions, design rationale)
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", depth: 2 })

自動リンク

knowledge の action: "write" がエントリを作成・更新すると、コサイン類似度によって既存エントリの上位3件の類似エントリを自動的に検索し、0.7を超えるスコアのペアに対して related_to エッジを作成します。

信頼度 & 減衰スコアリング

各ナレッジエントリには、entry_scores SQLiteテーブルで追跡される信頼度スコアがあります。検索結果は以下を使用してランキングされます:

finalScore = baseRelevance * 0.5^(daysSinceLastAccess / 90) * maturityMultiplier

エントリはアクセス数に基づいて自動的に成熟します:

頻繁にアクセスされるエントリは検索ランキングで上位に表示され、古いエントリは時間の経過とともに減衰します。

検索機能

TF-IDFランキング -- 結果はTF-IDF（Term Frequency-Inverse Document Frequency）でスコアリングされます。希少な用語ほど関連性が高まります。グローバルインデックスは60秒間キャッシュされます。

ファジーマッチング -- スライディングウィンドウ方式のレーベンシュタイン編集距離。しきい値は設定可能（デフォルト0.7）。

スコープ指定検索 -- knowledge_search の scope パラメータによる絞り込み:

統合

REST書き込みエンドポイント

POST /api/knowledge は { category, filename, content } を受け付け、完全な書き込みパイプライン（git pull → ファイル書き込み → 埋め込みインデックス → 自動リンク → git push → 重複チェック）を実行します。ステータス201で { path, autoLinks?, duplicateWarnings?, git } を返します。

これにより、MCP接続なしで他のサービスからHTTPベースの書き込みが可能になります。

agent-tasks KnowledgeBridge

agent-tasks には組み込みの KnowledgeBridge があり、タスク完了時に learning および decision アーティファクトを agent-knowledge に自動プッシュします。エントリはフロントマタータグ（agent-tasks、プロジェクト名、アーティファクトタイプ）付きで decisions/ に配置され、埋め込みで自動インデックス化され、類似エントリに自動リンクされます。設定は不要です。agent-knowledge が localhost:3423 で実行されていれば動作します。

テスト

npm test              # 563 tests across 35 files
npm run test:watch    # Watch mode
npm run lint          # ESLint on src/ and tests/
npm run typecheck     # tsc --noEmit
npm run check         # typecheck + lint + format + test

環境変数

すべての環境変数は AGENT_KNOWLEDGE_* プレフィックスの下にあります。ホスト名はハードコードされておらず、アダプタレジストリがインストール済みのAIコーディングホスト（.claude、.cursor、.codex、.aider、.continue、OpenCode）を設定なしで自動検出します。

コア

埋め込み

APIキー

プロジェクトスコープの上書きは標準キーより優先されます。どちらかを設定してください。スコープ付きの形式を使用すると、環境の他の部分とは異なるキーで agent-knowledge を実行できます。

フック

外部ツールの上書き

ドキュメント

• セットアップガイド — インストール、クライアント設定（Claude Code、OpenCode、Cursor、Windsurf）、フック、スキル

• 取り込みガイド — コードベース取り込みスキル、tree-sitter抽出、増分更新

• アーキテクチャ — ソース構造、設計原則、データベーススキーマ

• ダッシュボード — Web UIのビューと機能

• 変更履歴

ライセンス

MIT