briefd

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 98% 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.

Related MCP server: flaiwheel

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/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.

On your own machine (private knowledge, company network): see deploy/local/ for a localhost-only config, a launchd service, and the .mcp.json / CLAUDE.md templates for your projects.

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, 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.

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:

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

• staleness scoring via refs globs (knowledge that lags the code it governs)

• 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