briefd

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 (98% with the English-only all-MiniLM-L6-v2 model, the figure the explainer video quotes). 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.

Not another agent memory

Memory tools (agentmemory, Mem0, claude-mem) record what *an agent* observed in its sessions, automatically, per user. briefd serves what *the team* decided, written by people and reviewed like code. They answer different questions and run side by side.

Use a memory tool so your agent remembers what it tried last week. Use briefd so every agent on the team applies the same rules — and so someone notices when a rule falls behind the code.

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

Try it in 30 seconds — no repository needed:

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

Then open the dashboard, or point an agent at it: claude mcp add --transport http briefd http://127.0.0.1:7788/mcp. The first run downloads the embedding model (about 470 MB); briefd demo --embeddings none skips it.

With your own knowledge:

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

Let the agent install it. Hand your coding agent one instruction:

Retrieve and follow the instructions at: https://raw.githubusercontent.com/ismailperim/briefd/main/INSTALL_FOR_AGENTS.md

Teach the agent when to ask. Tools an agent does not call save nothing. The skills/briefd skill tells Claude Code (and any agent that reads SKILL.md) when to compile a bundle, how to treat a stale section and when to propose an update; the same guidance as a CLAUDE.md paragraph is in deploy/local/CLAUDE.md.

npx skills add ismailperim/briefd

Single-user, no server? briefd mcp speaks MCP over stdio — the same tools, the same index, no port and no token. Claude Desktop, Cursor's stdio config and MCP directory inspectors launch it directly:

{

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

Use serve when a team shares one instance (dashboard, metrics, webhook, REST); use mcp when the agent runs on the machine that holds the checkout.

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

Obsidian vaults and links

A knowledge repository can be an Obsidian vault. briefd reads [[wikilinks]] in the text and in front-matter properties such as related: (including [[note|alias]] and [[note#heading]]) and relative Markdown links, resolves them the way Obsidian does (by path, or by file name anywhere in the repository), and builds a link graph: the dashboard draws it, get_document returns each document's links and backlinks so an agent can follow them, and orphans (nothing links here) and broken links (the target does not exist) are listed as maintenance signals next to gaps and coverage. Folder scopes still apply — domain/, conventions/, projects/ / — so keep the vault's top level in that shape.

Running it for real