agent-knowledge

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.6ポイントから13.2ポイント上回りました。カテゴリ別の完全な表、再現手順、論文との比較の詳細は bench/README.md をご覧ください。

カテゴリで絞り込めるナレッジベース	TF-IDFで順位付けしたセッション検索

特長

AIコーディングセッションは一時的なものです。セッションが終了すると、アーキテクチャ上の決定、デバッグで得た知見、プロジェクトのコンテキストなど、そこで学んだことはすべて失われます。次のセッションは何もない状態から始まります。

agent-knowledgeは、相互に補完する2つのシステムでこの問題を解決します。

1. ナレッジベース -- 意思決定、ワークフロー、プロジェクトのコンテキストなどを構造化したエントリーを保存する、Git同期対応のMarkdown保管庫です。セッションやマシンをまたいで情報を保持します。
2. セッション検索 -- お使いのすべてのコーディングツールのセッショントランスクリプトを対象とした、TF-IDFで順位付けする全文検索です。どのツールが使われたかにかかわらず、エージェントが過去の出来事を想起できます。

対応ツール

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

ツール	形式	自動検出されるパス
Claude Code	JSONL	~/.claude/projects/
Cursor	JSONL	~/.cursor/projects/*/agent-transcripts/
Codex CLI	JSONL	~/.codex/projects/
Aider	Markdown/JSONL	プロジェクトディレクトリ内の .aider.chat.history.md / .aider.llm.history
Continue.dev	JSON	~/.continue/projects/
Cline	JSON	VS Code の globalStorage saoudrizwan.claude-dev/tasks/
OpenCode	SQLite	~/.local/share/opencode/opencode.db（または $OPENCODE_DATA_DIR）

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

機能

• ホストに依存しないセッション検索 -- 主要な AI コーディングアシスタント（Claude Code、Cursor、Codex CLI、Aider、Continue.dev、Cline、OpenCode）すべてを横断して統合検索します。設定にホスト名は組み込まれていません。アダプターレジストリが起動時に、インストール済みホストのルートを検出します。
• ハイブリッド検索 -- セマンティックなベクトル類似度と TF-IDF キーワードランキングを組み合わせます。
• Git 同期ナレッジベース -- YAML フロントマターを備えた Markdown 保管庫で、書き込み時に自動でコミットおよびプッシュします。
• 自動陳腐化検出 -- knowledge_analyze(action: "stale_by_code_activity") は、各エントリー本文に記載されたファイルパスと、最近のセッションサマリーにある filesModified を照合します。シンボルの存在を確認する精度レイヤーも組み合わせています。エントリー内で引用されている識別子（インラインのバッククォートとフェンスコードブロック）を変更対象ファイル内で確認し、まだ存在する場合は信頼度を ×0.3 に下げます。evergreen: true のエントリーは対象外です。
• 検索ギャップの追跡 -- knowledge_analyze(action: "search_gaps") は、直近 since_days 日間に検索結果が 0 件だったクエリを、トークンの 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 のプロバイダーを利用できます。
• あいまい一致 -- レーベンシュタイン距離を使用した、タイプミスに対応する検索です。
• 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 で閲覧、検索、管理できます。
• シークレットの除去 -- Git へのプッシュ前に、API キー、トークン、パスワード、秘密鍵を自動で伏せ字にします。
• ナレッジグラフ -- エントリー間の関係エッジ（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 } が含まれます。エージェントが信頼性のシグナルを読み取り、判断します。こちらでポリシーに基づく降格を強制することはありません。
• カテゴリごとに設定可能な減衰期間 — 「未使用」フィルターとタイプ別グラフは、カテゴリごとのしきい値（projects は 180d、people は 365d、decisions は 90d、workflows は 60d、notes は 30d）を使用するため、毎週読み返されないだけで、個人の基本情報に関する内容が陳腐化したように見えることはありません。
• ライフサイクルフック — SessionStart で自動ウェイクアップと取り込み鮮度チェック、UserPromptSubmit で最初のプロンプトに応じた対象を絞った注入、PreCompact でメモリのフラッシュを促してから蒸留、SessionEnd で蒸留を実行します。フックスクリプトは全部で 6 つあり、すべてフェイルオープンで、各スクリプトを AGENT_KNOWLEDGE_* 環境変数で個別に切り替えられます。docs/HOOKS.md を参照してください。
• ホストの自動メモリを置き換え -- セッションごとのメモリシステムを備えるホスト（Claude Code の ~/.claude/projects/*/memory/ や、他の IDE にある同様の機能）では、長期保存するユーザー情報やフィードバックを代わりに agent-knowledge に記録します。自動メモリはマシンごとに保存され、他のマシンからは見えません。agent-knowledge は Git で同期され、マシン間で共有でき、検索可能で、ウェイクアップ時にも表示されます。docs/USER-MANUAL.md の Claude Code 統合に関する注記を参照してください。

コードベースの取り込み

knowledge-ingest スキルは、コードベースのディレクトリからナレッジベースにデータを登録または更新します。tree-sitter を使用して、トークンを消費せずに構造を抽出します（クラス、関数、インポート、呼び出しグラフ、意図を説明するコメント）。その後、ファイルをサブシステムごとにクラスタリングし、既存の MCP ツールを使ってナレッジエントリとグラフエッジを作成します。以降の実行は増分処理となり、変更されたファイルのみが再処理されます。

/knowledge-ingest ./my-project

Agent Skills standard を使用しており、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）

ナレッジベース

ツール	アクション	説明	パラメーター
knowledge	list	カテゴリやタグでエントリを一覧表示	category?, tag?
	read	特定のエントリを読み取る	path（必須）
	write	エントリを作成／更新する（git 同期を自動実行）	category, filename, content（すべて必須）
	delete	エントリを削除する（git 同期を自動実行）	path（必須）
	sync	git のプルとプッシュを手動で実行	--
	wakeup	L0 の ID と、重み付け上位の L1 エントリを返す（トークン予算を考慮）	token_budget?, category?

検索

ツール	説明	パラメーター
knowledge_search	汎用ハイブリッド TF-IDF + セマンティック検索（scope なし）	query, project?, role?, max_results?, ranked?, semantic?, category?, category_mode?, mmr?, mmr_lambda?, explain?
	スコープを指定したセッション限定の想起（scope を設定した場合）	query, scope, project?, max_results?

レスポンス形式：{mode: "general" | "scoped", sessions, knowledge}。スコープモードでは、仕様上 knowledge: [] が返されます。

スコープ：errors、plans、configs、tools、files、decisions、all。

検索パラメーター：

• mmr: true を指定すると、Maximal Marginal Relevance による再ランキングを適用します（上位 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} が付加されます。

セッション

ツール	アクション	説明	パラメーター
knowledge_session	list	メタデータ付きでセッションを一覧表示します	project?
	get	セッションの会話全体を取得します	session_id, project?, include_tools?, tail?
	summary	セッションの概要（トピック、ツール、ファイル）	session_id, project?

ナレッジグラフ

ツール	アクション	説明	パラメーター
knowledge_graph	link	エントリー間のエッジを作成／更新します	source, target, rel_type, strength?
	unlink	エントリー間のエッジを削除します	source, target, rel_type?
	invalidate	エッジを期限切れとしてマークします（valid_toを設定）	source, target, rel_type?, valid_to?
	list	エッジを一覧表示します	entry?, rel_type?, as_of?
	traverse	エントリーから有向BFS探索を実行します	entry, depth?, direction?, rel_type?, as_of?
	bulk_link	エッジを一括作成します（コードグラフの取り込み）	edges (source、target、rel_type、strength?、origin?を含む配列)
	unlink_by_origin	originに基づいてすべてのエッジを削除します	origin

ナレッジの種類：related_to、supersedes、depends_on、contradicts、specializes、part_of、alternative_to、builds_on コード構造の種類：calls、imports、inherits

探索方向：outbound（source→target）、inbound（target→source）、both（デフォルト、無向）

分析

ツール	アクション	説明	パラメーター
knowledge_analyze	consolidate	ほぼ重複するエントリーを検出します	category?, threshold?
	reflect	リンクすべき未接続のエントリーを検出します	category?, max_entries?
	god_nodes	最も多く接続されたエントリー（次数中心性）	top_n?
	bridges	カテゴリーを横断してつなぐエントリー（媒介中心性）	top_n?
	gaps	成熟度別の孤立したエントリー（エッジ数0～1）	max_entries?
	brief	キャッシュされた約200トークンのナレッジベース概要	--

管理

ツール	アクション	説明	パラメーター
knowledge_admin	status	ベクトルストアの統計情報	--
	config	設定の表示または更新	git_url?, memory_dir?, auto_distill?
	rebuild_embeddings	すべてのナレッジエントリーを再度ベクトル化します（プロバイダーの切り替え時に便利です）	--
	prune_orphans	ディスク上に存在しなくなったセッションの埋め込みを削除します	vacuum?, force_vacuum?
	vacuum	ベクトルストアの空きページを再利用します	--
	promote	スコアリングとゲートによるプロモーション	promote_mode?（apply|explain）、min_score?、min_recall_count?、min_unique_queries?

スコアリングによるプロモーター

プロジェクトレベルの各候補は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"（デフォルト）— 候補をスコアリングしてゲート判定し、日誌に記録します。ナレッジベースには手を加えません。
• promote_mode: "apply" — 条件を満たした候補をプロモーションし、日誌に記録して、Git にコミットします。
• 実行のたびに ~/agent-knowledge/.dreams/YYYY-MM-DD.md が作成され、候補ごとのシグナルの内訳とゲート判定結果が記録されます。. で始まるディレクトリは Git で追跡されますが、一覧表示や検索からは除外されます。
• 根拠に基づく再取り込み：ソースセッションファイルがディスク上に存在しなくなった候補はスキップされます（削除されたコンテンツのプロモーションを防ぎます）。
• evergreen: true のフロントマターを持つエントリーは、プロモーションによって上書きされることはありません。活動内容は追記されます。

書き込みベンチハーネス：npm run bench:promote — 「後続のセッションで参照されたかどうか」による自動ラベル付けを行うオフライン再生です。ゲート付きプロモーターと単純な「すべて反映」ベースラインを比較し、適合率／再現率／F1 をレポートします。シグナルの重みやしきい値の変更を展開する前に、その評価に使用してください。

REST API

Method	Endpoint	Description
GET	/api/knowledge	ナレッジ項目の一覧表示
GET	/api/knowledge/search?q=	ナレッジベースを検索
GET	/api/knowledge/:path	特定の項目を読み込む
GET	/api/knowledge/god-nodes?top_n=	最も多く接続された項目
GET	/api/knowledge/bridges?top_n=	カテゴリー間をつなぐ項目
GET	/api/knowledge/gaps?max_entries=	孤立した項目
GET	/api/knowledge/brief	ナレッジベースの概要
GET	/api/sessions	セッションの一覧表示
GET	/api/sessions/search?q=&role=&ranked=	セッションを検索（TF-IDF）
GET	/api/sessions/recall?scope=&q=	範囲を指定して想起
GET	/api/sessions/:id	セッションを読み込む
GET	/api/sessions/:id/summary	セッションの概要
POST	/api/knowledge	項目を書き込む（HTTP クライアント）
GET	/health	ヘルスチェック

アーキテクチャ

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") 1 回のトランザクションでエッジを一括作成します（コードグラフの取り込み用）。
• knowledge_graph(action: "unlink_by_origin") 特定の origin を持つエッジをすべて削除します（再取り込み前に古いコードエッジを消去するため）。

コードグラフ

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

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

アクセス数に応じて、項目は自動的に成熟します。

Stage	Accesses	Multiplier
candidate	5 未満	0.5x
established	5〜19	1.0x
proven	20 以上	1.5x

頻繁にアクセスされる項目は検索順位が上がり、古くなった項目は時間とともに減衰します。

検索機能

TF-IDF ランキング -- 結果は、単語の出現頻度と逆文書頻度によってスコア付けされます。希少な語ほど関連性が高まります。グローバルインデックスは 60 秒間キャッシュされます。

あいまい検索 -- スライディングウィンドウを使用したレーベンシュタイン編集距離です。しきい値を設定できます（デフォルトは 0.7）。

scope パラメーターを指定した knowledge_search による範囲指定検索：

範囲	対象
errors	スタックトレース、例外、失敗したコマンド
plans	アーキテクチャ、TODO、実装手順
configs	設定、環境変数、構成ファイル
tools	MCP ツール呼び出し、CLI コマンド
files	ファイルパス、変更内容
decisions	トレードオフ、根拠、選択

インテグレーション

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

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

これにより、MCP 接続なしで他のサービスから HTTP 経由で書き込めます。

agent-tasks KnowledgeBridge

agent-tasks には、タスク完了時に learning および decision アーティファクトを agent-knowledge に自動プッシュする KnowledgeBridge が組み込まれています。エントリーはフロントマターのタグ（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）を設定なしで自動検出します。

コア

変数	デフォルト	説明
AGENT_KNOWLEDGE_MEMORY_DIR	~/agent-knowledge	Git 同期されるナレッジベースのディレクトリ
AGENT_KNOWLEDGE_GIT_URL	--	Git リモート URL（ディレクトリがない場合は自動的にクローン）
AGENT_KNOWLEDGE_AUTO_DISTILL	true	セッションの知見をナレッジベースに自動抽出
AGENT_KNOWLEDGE_INDEX_VERBATIM	true	セッションの生メッセージチャンクをベクトルストアにインデックス化し、後で会話を検索できるようにします。大規模運用でディスク容量を節約するには false に設定します。
AGENT_KNOWLEDGE_DATA_DIR	(platform config)	プライマリーホストのデータルートを上書きします。一般的なケースでは未設定のままにしてください。アダプターは ~/ 配下の既知のホストルートをすべて自動検出します。
AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS	--	追加のセッションディレクトリをカンマ区切りで指定します。自動検出されたディレクトリに追加されます。
AGENT_KNOWLEDGE_PORT	3423	ダッシュボードの HTTP/WebSocket ポート
AGENT_KNOWLEDGE_HOST	127.0.0.1	ダッシュボードのバインドアドレス（0.0.0.0 にするとネットワークに公開されます）

埋め込み

変数	デフォルト	説明
AGENT_KNOWLEDGE_EMBEDDING_PROVIDER	local	local | openai | claude | gemini
AGENT_KNOWLEDGE_EMBEDDING_ALPHA	0.3	TF-IDF とセマンティックのブレンド比率（0 = セマンティックのみ、1 = TF-IDF のみ）
AGENT_KNOWLEDGE_EMBEDDING_MODEL	--	プロバイダーのデフォルトモデルを上書きします
AGENT_KNOWLEDGE_EMBEDDING_IDLE_TIMEOUT	60	ローカルモデルをアンロードするまでの秒数（0 = 読み込み状態を維持）
AGENT_KNOWLEDGE_EMBEDDING_THREADS	(auto)	ローカルプロバイダーの ONNX / OMP スレッド数

API キー

プロジェクト固有の上書き設定は、標準のキーより優先されます。いずれかを設定してください。プロジェクト固有の形式を使うと、環境内のほかのものとは異なるキーで agent-knowledge を実行できます。

変数	フォールバック	説明
AGENT_KNOWLEDGE_OPENAI_API_KEY	OPENAI_API_KEY	OpenAI の埋め込み
AGENT_KNOWLEDGE_ANTHROPIC_API_KEY	ANTHROPIC_API_KEY	Claude / Voyage の埋め込み
AGENT_KNOWLEDGE_GEMINI_API_KEY	GEMINI_API_KEY	Gemini の埋め込み

フック

変数	デフォルト	説明
AGENT_KNOWLEDGE_AUTOWAKE	1	SessionStart に knowledge(action: wakeup) バンドルを自動挿入します。無効にするには 0 を設定します。
AGENT_KNOWLEDGE_WAKEUP_BUDGET	800	wakeup バンドルに使用するトークン数
AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT	1	最初のユーザープロンプトで対象を絞った knowledge_search を実行し、上位の結果を挿入します。無効にするには 0 / false / off を設定します。
AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET	600	最初のプロンプトへの挿入に使用するトークン数（上限・下限 [100, 8000]）
AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS	4	最初のプロンプトに付加するナレッジの最大件数（上限・下限 [1, 20]）
AGENT_KNOWLEDGE_PRECOMPACT_NUDGE	1	プリコンパクションの前に、knowledge(action: write) でコンテキストを保存するようエージェントに促します。0 にすると通知を無効にし、off にすると通知とディスクへのダンプの両方を抑制します。

外部ツールの上書き設定

変数	デフォルト	説明
OPENCODE_DATA_DIR	~/.local/share/opencode	OpenCode のセッション DB の保存場所を上書きします（OpenCode 独自の環境変数で、アダプターに適用されます）

ドキュメント

• セットアップガイド — インストール、クライアントのセットアップ（Claude Code、OpenCode、Cursor、Windsurf）、フック、スキル
• 取り込みガイド — コードベース取り込みスキル、tree-sitter による抽出、増分更新
• アーキテクチャ — ソース構成、設計原則、データベーススキーマ
• ダッシュボード — Web UI のビューと機能
• 変更履歴

ライセンス

MIT