briefd

Your agents, briefed. Not flooded.
A self-hosted context compiler for AI coding teams: git-backed knowledge, served to coding agents
as token-budgeted context bundles over MCP.

▶ Watch the 90-second explainer · How it works · Quickstart

Teams that build many projects in one domain keep the same knowledge in their heads and in
scattered CLAUDE.md / AGENTS.md files: terminology, business rules, architecture decisions,
conventions. Loading all of it into every session burns thousands of tokens on every turn, and
whatever doesn't fit gets left out.

briefd inverts the model: context on demand, not up front. Your knowledge lives as Markdown
in a git repository. briefd indexes it and answers one question from your coding agent —
"what do I need to know for this task?" — with a compiled, deduplicated bundle that never
exceeds the token budget you set.

Why

On the sample knowledge repo in this repository (44 documents, 47 realistic developer tasks),
compile_bundle spends 86% fewer tokens per task than pasting everything into CLAUDE.md
while still containing the section that answers the task 96% of the time. The realistic
middle ground — a hand-curated CLAUDE.md with just conventions and the glossary — costs
2.8× more than a bundle and has the answer less than half the time.

Reproduce it with make bench; the method is in internal/eval/bench.go.

That is what the tokenizer says. Inside real Claude Code sessions
(eval/session/, Sonnet, 10 tasks, same prompts) briefd cut the context
carried per turn by 35% and the cost per task by 40% with identical answers — at the price of
3–4 extra tool-call round trips per task. The saving grows with the size of your knowledge repo;
a static CLAUDE.md cannot.

How it works

• Git is the source of truth. The index is a disposable cache rebuilt from a clone.
• Agents never write to the index. propose_update opens a reviewable branch/PR; what
  briefd serves changes only when a human merges.
• Hybrid retrieval, no external services. SQLite FTS5 (BM25) + multilingual embeddings
  (multilingual-e5-small, 100+ languages) computed by a pure-Go encoder, fused with
  reciprocal rank fusion. No Postgres, no vector database, no ONNX runtime, no CGO.
• Hard token budgets. Every API that returns context takes max_tokens and never exceeds it.

Quickstart

# 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"

Open http://localhost:7788/ for the dashboard, then ask Claude Code something the sample
corpus knows — "what's our retry policy for acquirer calls?" or "ters ibraz nedir?" — and
watch search_context / compile_bundle show up in the request log.

Any MCP client that speaks streamable HTTP works. For a project-level .mcp.json:

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

Tools

The same operations are available over REST (/api/search, POST /api/bundle, /api/docs/{path},
/api/scopes, POST /api/proposals, POST /api/usage, /api/gaps, /api/health, /api/stats)
behind the same bearer token.

Your knowledge repo

briefd expects a git repository (or directory) of Markdown with three kinds of folders
(briefd init <dir> scaffolds it with example documents):

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/

Documents are split on ##/### headings into sections of roughly 200–800 tokens with stable
ids, so a section can be quoted on its own. Optional front matter adds metadata:

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

testdata/knowledge/ is a complete example (a fictional payments
platform) and doubles as the evaluation corpus.

Running it for real

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 clones the repository, follows the branch with fetch + hard reset every sync.interval
(default 60 s), or immediately when your forge calls POST /webhook/git with a GitHub-style
HMAC signature. Only changed files are re-parsed and re-embedded.

Languages. The default embedding model, multilingual-e5-small, covers 100+ languages,
so a Turkish, German or Japanese knowledge repo — or English docs queried in another language —
works out of the box. English-only teams can set embeddings.model: all-MiniLM-L6-v2 (87 MB,
~2.5× faster indexing). briefd model pull pre-fetches a model for offline or image-build use;
--embeddings none gives BM25-only mode; Ollama and OpenAI-compatible services are alternative
providers.

Docker

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

The image is distroless and pure Go (~34 MB, linux/amd64 + arm64). Database, checkout and model
live in the briefd-data volume. Mount a directory and set BRIEFD_SOURCE=/knowledge to serve
local files instead.

Deployment guide: deploy/README.md covers Compose and systemd
setups, git forges (GitHub, GitLab, Azure DevOps, Bitbucket, SSH), installing the embedding model
offline, proxies and private CAs, exposure/security, upgrades and monitoring. For a laptop-only
setup see deploy/local/.

Configuration — briefd.yaml (see deploy/briefd.example.yaml)
or BRIEFD_* environment variables; flags override both. The ones you will actually touch:

briefd model pull pre-fetches the embedding model for offline or image-build use.

Dashboard and metrics

GET / is a read-only status page embedded in the binary: requests and tokens served, p50/p95
latency per tool, budget pressure, bundle cache hit rate, index size per scope, the oldest
documents, sync state, the last 100 requests, and a search box for manual inspection. GET /metrics exposes the same
counters in Prometheus text format; GET /api/stats as JSON.

Knowledge gaps. Every search_context / compile_bundle call is logged with its retrieval
confidence (query_log, 30-day retention). The dashboard lists the questions of the last seven
days that the knowledge base did not answer — nothing matched, or the agent's report_usage said
no section helped — grouped by question and ranked by how often they were asked, plus the answered
questions whose top result barely stood out from the rest. That list is the backlog for whoever
maintains the repository; GET /api/gaps?days=7&limit=20 returns it as JSON.

Document age. Every section in a bundle carries the date its document last changed
(## path — heading (updated 2026-03-04), from git history, or the file mtime for a plain
directory), so an agent can weigh a rule by its age. The dashboard lists the documents that
changed longest ago — the ones to re-read first.

Behind the code. Give a document refs: ["services/payment/**"] in its front matter and
list the code repositories in code.repos; briefd follows their history (bare clones, never the
files) and counts the commits that touched a governed path after the document last changed.
The attribution line then reads (updated 2026-03-01; code changed since: 3 commits, last 2026-06-01), the dashboard lists the documents most behind, and briefd_documents_behind_code
is exported. The agent reading a stale rule is often the right one to fix it with
propose_update. Design in ADR-0007.

Retrieval quality

Retrieval is measured, not assumed. make eval scores 47 English golden queries (keyword,
paraphrase, typo, mixed-language) over the sample corpus and 30 Turkish queries over a
Turkish corpus; CI fails if hybrid retrieval drops below eval/thresholds.yaml
or eval/thresholds-tr.yaml:

On public BEIR datasets briefd's vector-only mode reproduces the published quality of both
embedding models and hybrid mode beats BM25 and vector-only on each — SciFact nDCG@10 0.714
vs 0.665 for the BEIR BM25 baseline; see eval/beir/ to reproduce.

Every change to chunking, embeddings or fusion ships with before/after numbers
(ADR-0004 is an example).

CLI

briefd init       # scaffold a knowledge repo (domain/, conventions/, projects/)
briefd serve      # MCP + REST + dashboard
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

Status and roadmap

v0.1 is feature-complete; expect rough edges before 1.0. Planned next:

• usage-driven relevance tuning from report_usage
• contradiction detection for proposals
• a light Turkish stemmer for the BM25 side and glossary-alias query expansion
• multiple knowledge repositories per instance

Read docs/ARCHITECTURE.md for a guided tour with diagrams. The full
specification is in SPEC.md; decisions are recorded in docs/adr/.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md for the
development setup, testing rules and conventions. Security issues: SECURITY.md.

License

Apache-2.0