briefd

briefd

エージェントに、要点を。洪水ではなく。
AI コーディングチームのためのセルフホスト可能なコンテキストコンパイラー: git で管理されたナレッジを、コーディングエージェントへ
MCP 経由でトークン予算に収めたコンテキストバンドルとして提供します。

---

▶ 90 秒の解説動画を見る · 仕組み · クイックスタート

1 つのドメインで多くのプロジェクトを構築するチームは、同じナレッジを頭の中と、散在する CLAUDE.md / AGENTS.md ファイルに保持し続けています。用語、ビジネスルール、アーキテクチャ上の決定、 規約などです。そのすべてを毎セッションに読み込むと、毎ターン何千ものトークンを消費し、 収まりきらなかったものは省かれてしまいます。

briefd はこのモデルを逆転させます。事前にではなく、オンデマンドでコンテキストを。 ナレッジは git リポジトリ内の Markdown として存在します。briefd はそれをインデックス化し、コーディングエージェントからの 1 つの問い — 「このタスクには何を知っておく必要があるか?」 — に対して、設定したトークン予算を 決して超えない、コンパイル済みで重複排除されたバンドルで答えます。

なぜ

このリポジトリにあるサンプルのナレッジリポジトリ（44 ドキュメント、47 の現実的な開発者向けタスク）において、 compile_bundle は すべてを CLAUDE.md に貼り付ける場合に比べてタスクあたり 86% 少ないトークンで済みながら、 タスクに答えるセクションを 96% の確率で含んでいます（98% は英語のみの all-MiniLM-L6-v2 モデルを使用した場合で、 解説動画が引用している数値です）。現実的な中間策 — 規約と用語集だけを手作業で厳選した CLAUDE.md — は バンドルの 2.8 倍のコストがかかり、回答を含む確率は半分未満です。

make bench で再現できます。手法は internal/eval/bench.go にあります。

これはトークナイザーが示す数値です。実際の Claude Code セッション （eval/session/、Sonnet、10 タスク、同じプロンプト）では、briefd は ターンごとに持ち運ぶコンテキストを 35%、タスクあたりのコストを 40% 削減し、回答は同一でした — その代償としてタスクあたり 3〜4 回の 追加ツール呼び出しラウンドトリップが発生します。削減効果はナレッジリポジトリの規模が大きくなるほど増大します。 静的な CLAUDE.md ではそれは実現できません。

もう一つのエージェントメモリではありません

メモリツール（agentmemory、Mem0、claude-mem）は エージェントがセッションで観察したことを、ユーザーごとに自動的に記録します。briefd は チームが決定したことを、人間が書き、コードと同様にレビューして提供します。両者は異なる問いに 答え、並行して運用されます。

	エージェントメモリ	briefd
信頼できる情報源	エージェントが書き込むデータベース	git リポジトリ内の Markdown
書き込む人	エージェントが自動的に	人間。エージェントはプルリクエストを作成
スコープ	1 つのエージェント / 1 人のユーザー	チーム全体、ドメイン内のすべてのプロジェクト
レビュー	なし	すべての変更に差分、レビュアー、名前がある
陳腐化	不明	すべてのセクションに日付。対象コードとのドリフト
答えられないこと	黙って存在しない	ダッシュボードにバックログとして一覧表示
フットプリント	ランタイム + エンジン + 複数のポート	単一の静的バイナリ、1 つの SQLite ファイル、1 つのポート（または stdio）
ツールサーフェス	数十のツール、セッションあたり数千トークン	7 つのツール、セッションあたり約 2.8k トークン

メモリツールは、エージェントが先週試したことを覚えておくために使ってください。briefd は、チームのすべてのエージェントが 同じルールを適用するために — そしてルールがコードに遅れをとったときに誰かが気づくために使ってください。

仕組み

• git が信頼できる情報源です。 インデックスはクローンから再構築される使い捨てのキャッシュです。
• エージェントは決してインデックスに書き込みません。 propose_update はレビュー可能なブランチ/PR を作成します。 briefd が提供する内容は、人間がマージしたときにのみ変化します。
• ハイブリッド検索、外部サービス不要。 SQLite FTS5（BM25）+ 多言語埋め込み （multilingual-e5-small、100 以上の言語）を純粋な Go エンコーダーで計算し、順位の逆数融合で統合します。 Postgres もベクトルデータベースも ONNX ランタイムも CGO も不要です。
• 厳格なトークン予算。 コンテキストを返すすべての API は max_tokens を受け取り、それを超えることはありません。

クイックスタート

30 秒で試せます — リポジトリは不要です:

briefd demo      # serves the built-in sample knowledge base on http://127.0.0.1:7788

その後、ダッシュボードを開くか、エージェントから接続します: claude mcp add --transport http briefd http://127.0.0.1:7788/mcp。 初回実行時は埋め込みモデル (約 470 MB) をダウンロードします。briefd demo --embeddings none でスキップできます。

自分のナレッジを使う場合:

# 1. build (Go >= 1.26) or grab a binary from the releases page
git clone https://github.com/ismailperim/briefd && cd briefd && make build

# 2. serve the sample knowledge repo (downloads the 470 MB multilingual embedding model once)
./bin/briefd serve --source testdata/knowledge --db /tmp/briefd.db --token dev-token

# 3. connect Claude Code
claude mcp add --transport http briefd http://localhost:7788/mcp \
  --header "Authorization: Bearer dev-token"

ダッシュボードは http://localhost:7788/ を開き、次に Claude Code にサンプルコーパスが知っていることを尋ねてください — 「アクワイアラ呼び出しのリトライポリシーは?」 や 「ters ibraz nedir?」 — そして search_context / compile_bundle がリクエストログに表示されるのを確認してください。

ストリーミング可能な HTTP を話す MCP クライアントであればどれでも動作します。プロジェクトレベルの .mcp.json の場合は:

{
  "mcpServers": {
    "briefd": {
      "type": "http",
      "url": "http://localhost:7788/mcp",
      "headers": { "Authorization": "Bearer dev-token" }
    }
  }
}

エージェントにインストールさせます。 コーディングエージェントに 1 つの指示を渡すだけです:

次の URL にある手順を取得して実行してください: https://raw.githubusercontent.com/ismailperim/briefd/main/INSTALL_FOR_AGENTS.md

エージェントにいつ尋ねるべきかを教えます。 エージェントが呼び出さないツールは何も保存しません。 skills/briefd スキルは、Claude Code (および SKILL.md を読むあらゆるエージェント) に、いつバンドルをコンパイルするか、古くなったセクションをどう扱うか、いつ更新を提案するかを伝えます。同じガイダンスを CLAUDE.md の段落としてまとめたものが deploy/local/CLAUDE.md にあります。

npx skills add ismailperim/briefd

シングルユーザーで、サーバー不要ですか? briefd mcp は stdio 経由で MCP を話します — 同じツール、同じインデックス、ポートもトークンも不要です。Claude Desktop、Cursor の stdio 設定、MCP ディレクトリのインスペクターはこれを直接起動します:

{
  "mcpServers": {
    "briefd": {
      "command": "briefd",
      "args": ["mcp", "--source", "/path/to/knowledge", "--db", "~/.briefd/knowledge.db"]
    }
  }
}

チームで 1 つのインスタンスを共有する場合 (ダッシュボード、メトリクス、webhook、REST) は serve を使ってください。エージェントがチェックアウトを保持するマシン上で動作する場合は mcp を使ってください。

ツール

ツール	機能
compile_bundle(task_description, max_tokens?, scopes?, paths?)	予算内に収まる、重複排除された 1 つのコンテキストブロックを、ドメイン → 規約 → プロジェクトの順に並べ、セクションごとの出典行と bundle_id を付けます。決定的でキャッシュされます。
search_context(query, max_tokens?, scopes?, top_k?, paths?)	予算に収まるランク付けされたセクションを、確認用に返します。paths (編集中のコードパス) は、その refs が該当するドキュメントを先頭に引き上げます。
get_document(doc_path, scopes?)	1 つのドキュメント全体を取得します。
list_scopes()	ドキュメント/セクション数の付いたスコープです。
propose_update(doc_path, change_description, new_content)	ブランチ briefd/proposal-<id> を作成します (設定されている場合はプルリクエストも)。インデックスには一切触れません。
report_usage(bundle_id, useful_chunk_ids)	任意のフィードバック: どのセクションが役立ったか。空のリストは、その質問をナレッジギャップとしてマークします。
suggest_links(doc_path?, limit?)	ナレッジベースに欠けているリンク (あるドキュメントが別のドキュメントを名指ししているのにリンクしていない) と壊れたリンク — propose_update でナレッジベースを整理するエージェント向けです。

同じ操作は REST (/api/search、POST /api/bundle、/api/docs/{path}、 /api/scopes、POST /api/proposals、POST /api/usage、/api/gaps、/api/health、/api/stats) からも、同じベアラートークンの背後で利用できます。

ナレッジリポジトリ

briefd は、3 種類のフォルダーを持つ Markdown の git リポジトリ (またはディレクトリ) を想定しています (briefd init <dir> でサンプルドキュメント付きの雛形を生成します):

knowledge-repo/
├── domain/          # shared: terminology, business rules, ADRs
├── conventions/     # shared: coding standards, infra patterns
└── projects/
    ├── ledger-service/   # visible only when scope "projects/ledger-service" is requested
    └── merchant-portal/

ドキュメントは ##/### 見出しで、おおよそ 200〜800 トークンの安定した ID を持つセクションに分割されるため、セクション単位で引用できます。任意のフロントマターでメタデータを追加できます:

---
title: Retry policy            # defaults to the first H1
tags: [payments, resilience]
refs: ["services/payment/**"]  # code paths this doc governs
---

testdata/knowledge/ は完全な例 (架空の決済プラットフォーム) で、評価コーパスも兼ねています。

Obsidian Vault とリンク

ナレッジリポジトリは Obsidian Vault にできます。briefd は本文中および related: などのフロントマタープロパティ内の [[wikilinks]]（[[note|alias]] や [[note#heading]] を含む）と相対 Markdown リンクを読み取り、Obsidian と同じ方法（パスによる解決、またはリポジトリ内の任意の場所のファイル名による解決）で解決し、リンクグラフを構築します。ダッシュボードがそれを描画し、get_document は各ドキュメントのリンクとバックリンクを返すので、エージェントはそれらをたどることができます。また、孤立ノード（どこからもリンクされていない）と壊れたリンク（リンク先が存在しない）は、ギャップやカバレッジと並んでメンテナンスシグナルとして一覧表示されます。フォルダスコープ（domain/、conventions/、projects/<name>/）は引き続き適用されるため、Vault の最上位レベルはその形に保ってください。

実際に動かす

export BRIEFD_GIT_TOKEN=ghp_...     # only for private HTTPS remotes
./bin/briefd serve --source https://github.com/your-org/knowledge.git --token "$(openssl rand -hex 16)"

briefd はリポジトリをクローンし、sync.interval（デフォルト 60 秒）ごとに fetch + hard reset でブランチを追従します。または、フォージが GitHub 形式の HMAC 署名を付けて POST /webhook/git を呼び出したときに即座に追従します。変更されたファイルのみが再パースおよび再埋め込みされます。

言語。 デフォルトの埋め込みモデル multilingual-e5-small は 100 以上の言語をカバーしているため、トルコ語、ドイツ語、日本語のナレッジリポジトリでも、あるいは英語のドキュメントを別の言語でクエリする場合でも、そのまま動作します。英語のみのチームは embeddings.model: all-MiniLM-L6-v2（87 MB、インデックス作成が約 2.5 倍高速）を設定できます。briefd model pull はオフラインまたはイメージビルドでの使用に向けてモデルを事前取得します。--embeddings none は BM25 のみのモードになります。Ollama および OpenAI 互換サービスは代替プロバイダーです。

Docker

cd deploy
BRIEFD_SOURCE=https://github.com/your-org/knowledge.git BRIEFD_API_TOKEN=... docker compose up

イメージは distroless かつ pure Go（約 34 MB、linux/amd64 + arm64）です。データベース、チェックアウト、モデルは briefd-data ボリュームに置かれます。ディレクトリをマウントして BRIEFD_SOURCE=/knowledge を設定すると、代わりにローカルファイルを提供できます。

デプロイガイド: deploy/README.md では、Compose と systemd のセットアップ、Git フォージ（GitHub、GitLab、Azure DevOps、Bitbucket、SSH）、埋め込みモデルのオフラインインストール、プロキシとプライベート CA、公開／セキュリティ、アップグレードとモニタリングについて説明しています。ノート PC のみのセットアップについては deploy/local/ を参照してください。

設定 — briefd.yaml（deploy/briefd.example.yaml を参照）または BRIEFD_* 環境変数。フラグはどちらよりも優先されます。実際によく触ることになるものは次のとおりです。

設定	環境変数	デフォルト	備考
source	BRIEFD_SOURCE	—	git URL またはディレクトリ
api_token	BRIEFD_API_TOKEN	(なし)	空 = 認証なし（信頼できるネットワーク上のみ）
listen	BRIEFD_LISTEN	:7788
sync.interval	BRIEFD_SYNC_INTERVAL	60s	0 でポーリングを無効化
sync.webhook_secret	BRIEFD_SYNC_WEBHOOK_SECRET	—	POST /webhook/git を有効化
git.token	BRIEFD_GIT_TOKEN	—	HTTPS リモート用。SSH には git.ssh_key
forge.type、forge.token	BRIEFD_FORGE_*	—	github または gitlab: 各提案に対して pull / merge request を作成
embeddings.provider	BRIEFD_EMBEDDINGS_PROVIDER	local	ollama、openai、または BM25 のみにする場合は none
embeddings.model	BRIEFD_EMBEDDINGS_MODEL	multilingual-e5-small	または all-MiniLM-L6-v2（英語、高速）
search.default_max_tokens	BRIEFD_DEFAULT_MAX_TOKENS	2000
query_log.retention_days	BRIEFD_QUERY_LOG_RETENTION_DAYS	30	ナレッジギャップレポートに使用。query_log.enabled: false で無効化
code.repos	—	(なし)	ドリフト検出のためにドキュメントの refs と比較されるコードリポジトリ（URL またはパス）

briefd model pull はオフラインまたはイメージビルドでの使用に向けて埋め込みモデルを事前取得します。

ダッシュボードとメトリクス

GET / はバイナリに埋め込まれたダッシュボードです（ビルド手順も外部アセットも不要）：

• Overview — リクエスト、提供・節約されたトークン、インデックスと同期。過去 24 時間にエージェントへ提供されたドキュメントが刻印されたナレッジグラフ。循環リスト。そして Needs attention（メンテナンスシグナルごとに 1 行、深刻なものから順に）。
• Graph — すべてのドキュメントとリンク、ズームとパン（マウスまたはキーボード）、スコープフィルター、検索。ドキュメントを選択すると、そのリンク、バックリンク、提供された頻度を確認できます（#graph=<doc path> で直接リンクできます）。
• Maintenance — レビュー待ちの提案、ナレッジギャップ、コードより遅れているドキュメント、最も古いドキュメント、修正すべきリンク、コードカバレッジ。
• Activity — ツールごとのレイテンシーとボリューム、スコープ別のインデックス、リクエストログ。カウンターは再起動後も保持され、リセットできます。
• Instance — 実行中の設定（シークレットは設定済み/未設定としてのみ表示）、Sync now と Rebuild index 付き。

GET /metrics はカウンターを Prometheus テキスト形式で公開します。GET /api/stats は JSON で公開します。

ナレッジギャップ。 すべての search_context / compile_bundle 呼び出しは、その検索信頼度とともに記録されます（query_log、30 日間保持）。ダッシュボードには、ナレッジベースが答えられなかった過去 7 日間の質問 — 何も一致しなかった、またはエージェントの report_usage がどのセクションも役に立たなかったと報告したもの — が、質問ごとにグループ化され、尋ねられた頻度順に並べられて表示されます。さらに、回答済みの質問のうち、最上位の結果が他とほとんど差がなかったものも表示されます。このリストはリポジトリを保守する人にとってのバックログです。GET /api/gaps?days=7&limit=20 はこれを JSON で返します。

ドキュメントの古さ。 バンドル内のすべてのセクションは、そのドキュメントが最後に変更された日付を持ちます（## path — heading (updated 2026-03-04)、git 履歴から、またはプレーンなディレクトリの場合はファイルの mtime から）。これにより、エージェントはルールをその古さで重み付けできます。ダッシュボードには、最も長く前に変更されたドキュメント — 最初に読み直すべきもの — が一覧表示されます。

コードより遅れている。 ドキュメントのフロントマターに refs: ["services/payment/**"] を指定し、code.repos にコードリポジトリを列挙すると、briefd はその履歴を追跡し（ベアクローン、ファイルは決して追わない）、ドキュメントが最後に変更された後に管理対象パスに触れたコミットを数えます。すると帰属情報の行は (updated 2026-03-01; code changed since: 3 commits, last 2026-06-01) となり、ダッシュボードには最も遅れているドキュメントが一覧表示され、briefd_documents_behind_code がエクスポートされます。古いルールを読んでいるエージェントが、propose_update でそれを修正するのにふさわしいことがよくあります。設計は ADR-0007 にあります。

同じ refs は逆方向にも機能します。compile_bundle に paths（タスクが触れるファイル）を渡すと、それらを管理するルールがバンドルの先頭に来ます。また、ダッシュボードの Coverage パネルには、どのドキュメントも主張していない各コードリポジトリのディレクトリ — ナレッジベースの盲点 — が一覧表示されます（ADR-0008）。briefd 自体はコードをインデックスしません。あなたのエージェントの grep と LSP のほうがそれを得意とします。

検索品質

検索は想定ではなく、測定されます。make eval は 47 件の英語ゴールデンクエリ（キーワード、言い換え、タイポ、混在言語）をサンプルコーパス上で、30 件のトルコ語クエリをトルコ語コーパス上で採点します。ハイブリッド検索が eval/thresholds.yaml または eval/thresholds-tr.yaml を下回ると CI が失敗します。

モード	英語 R@5	英語 R@10	英語 MRR	トルコ語 R@5	トルコ語 R@10	トルコ語 MRR
BM25 のみ	0.681	0.755	0.591	0.733	0.767	0.602
ベクトルのみ	0.830	0.936	0.771	0.950	1.000	0.832
ハイブリッド（デフォルト）	0.830	0.926	0.746	0.933	1.000	0.847

公開 BEIR データセットにおいて、briefd のベクトルのみのモードは両方の埋め込みモデルの公開品質を再現し、ハイブリッドモードはそれぞれで BM25 とベクトルのみを上回ります — SciFact nDCG@10 は 0.714 で、BEIR BM25 ベースラインの 0.665 に対して優位です。再現するには eval/beir/ を参照してください。

チャンキング、埋め込み、融合に対するすべての変更は、変更前後の数値とともに提供されます（ADR-0004 がその一例です）。

CLI

briefd demo       # serve the built-in sample knowledge base — try it in 30 seconds
briefd init       # scaffold a knowledge repo (domain/, conventions/, projects/)
briefd serve      # MCP over HTTP + REST + dashboard, for a shared instance
briefd mcp        # MCP over stdio, for one agent on this machine (Claude Desktop, Cursor)
briefd index      # index a directory into the database (--rebuild to start over)
briefd search     # query like search_context does (--mode bm25|vector|hybrid, --json)
briefd model list # local embedding models and whether they are downloaded
briefd model pull # download a model (--model all-MiniLM-L6-v2 for the English one)
briefd eval       # retrieval quality against the golden set
briefd bench      # tokens per task: static CLAUDE.md vs compile_bundle

ステータスとロードマップ

v0.1 は機能が完了していますが、1.0 までには荒削りな部分が想定されます。次に予定されているもの:

• report_usage による利用状況に基づく関連性チューニング
• 提案に対する矛盾検出
• BM25 側のための軽量なトルコ語ステマーと用語集エイリアスによるクエリ拡張
• インスタンスごとに複数のナレッジリポジトリ

図付きのガイド付きツアーについては docs/ARCHITECTURE.md をお読みください。完全な仕様は SPEC.md にあり、決定事項は docs/adr/ に記録されています。

コントリビューション

Issue とプルリクエストを歓迎します — 開発環境のセットアップ、テスト規則、規約については CONTRIBUTING.md を参照してください。セキュリティ問題: SECURITY.md。

ライセンス

Apache-2.0