Your organisation already solved this problem. BricoWerx captures that work as versioned pieces — code, prompts, skills, evals, pipelines — and serves it to your team through a CLI and to your AI assistants through MCP.
brico — from bricolage /bʁi.kɔ.laʒ/, French: to build with what you already have in your hands. werx — where it gets made.
Extract → capture → add → doctor. The full lifecycle, shipping today.
tokens to answer “do we have JWT auth?” — against tens of thousands for a repo-indexing assistant.
code · prompt · skill · eval · dataset · pipeline — one manifest field, zero engine changes.
Brico — from the French bricolage: building with what you already have in your hands. Werx — the workshop where it happens.
The auth module your team perfected two projects ago is entangled with that project's dependencies, invisible to search, and unversioned as an asset in its own right. The same is now true of prompts, evals and agent skills — valuable, untested, trapped.
Teams answer “how do we build this?” over and over, when the real question should be “do we already have a piece for this?” Prompts live in Notion, eval scripts rot in scratch folders, agent configs are copy-pasted between repos and silently drift apart.
Assistants index whole repositories and stuff context windows to answer what the organisation already answered. Regenerating an auth module costs more than tokens: review time, subtle bugs, and a fourth slightly different implementation.
Context efficiency became a first-class engineering concern — teams track token spend like cloud spend. And MCP standardised how assistants consume external knowledge. Both point at a curated, versioned store of an organisation's best work.
A piece is a versioned engineering asset: source files, a manifest describing its behaviour, and a set of derived knowledge representations. Everything else follows.
Knowledge systems die when the cost of contributing exceeds the value of retrieving — the fate of every abandoned internal wiki. Every representation beyond the raw files is derived and optional: generated at capture time or backfilled later, never demanded from the contributor.
Anything that looks like a database is a rebuildable projection of the Vault. That single rule buys database power — vector, full-text, graph — with none of the database liabilities: no migrations-as-truth, no sync conflicts, no server between a developer and their knowledge.
Every piece carries a ladder of representations, each derived at capture time and stored as plain files in its version directory. Consumers climb only as far as the task requires.
// card — the whole thing { "name": "auth", "kind": "code", "description": "JWT auth with Passport & bcrypt", "tags": ["security", "jwt"], "framework": "nest", "latest": "0.2.0" }
Name, description, tags, kind, compatibility. Enough to answer existence questions across an entire Vault for the price of a sentence.
// surface — signatures, no bodies (from the AST) export class AuthService { signIn(dto: SignInDto): Promise<Session> verify(token: string): Promise<Claims> } env JWT_SECRET, JWT_EXPIRES_IN wire add AuthModule to AppModule imports
Exported types, function signatures, env vars and wiring steps — extracted from the AST, bodies omitted. Everything needed to call the piece correctly.
# summary.md — generated at capture ## Why it works this way Refresh tokens are rotated on every use and stored hashed, so a leaked token is single-use. ## Trade-offs Stateful refresh store (Redis) was accepted to gain revocation; a pure-JWT design cannot revoke.
Design decisions, trade-offs, architecture notes — the reasoning a senior engineer would otherwise have to be interrupted for.
// the files themselves
auth.service.ts auth.module.ts
auth.controller.ts jwt.strategy.ts
refresh-token.store.ts lego.manifest.json
The top rung is rarely needed. And the largest saving isn't on this ladder at all: not generating code in the first place. brico add installs a verified, versioned piece for zero generation tokens, zero review of novel code, zero new bugs.
The same question, answered two ways. Multiplied across every retrieval an assistant makes in a working day, this is the difference between AI that grazes the whole codebase and AI that asks a librarian.
brico mcp exposes the Vault over the Model Context
Protocol, making every MCP-capable assistant — Claude, IDE agents, internal copilots — a
consumer of your organisation's proven work. A thin protocol layer over the same engine and
index the CLI already uses.
search_pieces(query, kind?)Semantic + keyword search over the Vault; returns cards.get_piece(name, level)Returns the requested rung: card, surface, summary, or source.plan_reuse(task)Given a task description, returns candidate pieces with fit rationale.get_relations(name, kind?)Graph neighbourhood: dependencies, dependents, replacements, similar pieces.All tools serve ladder representations — never raw repository scans.
We do not build ML infrastructure — we version AI engineering assets. Model registries
and experiment tracking are owned territory; the unowned gap sits next to it: the day-to-day
assets teams scatter across wikis, gists and repos. The extension is a single
kind field and new adapters. The engine core does not change.
Files, dependencies, env vars and framework wiring steps — captured, versioned, snappable.
Template file, input variables, target models, and attached evaluation cases.
Instructions plus scripts, in the emerging industry format.
Cases, scoring criteria, harness configuration — standalone and reusable.
URI, content hash, schema, license — identity and provenance without the payload.
RAG and agent configurations that reference other pieces by name and version.
Files in git are the source of truth.
Every database is a derived, rebuildable projection.
Each version directory holds the piece's files, its manifest, and derived knowledge:
summary.md, surface.json, and embeddings as raw float32 vectors with a
sidecar recording the embedding model — because vectors from different models are not comparable.
A single database at ~/.brico/index.db, compiled into the binary — still one static
binary, still zero runtime dependencies. It replaces index.json and provides every query capability
the first draft wanted five separate systems for.
pgvector, full-text, recursive CTEs. One well-understood database instead of five, entered only when team Vaults demand it. Because of the source-of-truth rule it stays a projection: if the hosted database dies, it is rebuilt from the repositories.
sqlite-vec — brute-force cosine is already single-digit milliseconds at 10k vectors.
“Something like rate limiting for our stack”
FTS5 full-text index with ranking.
“stripe”, “jwt”, tag and description matches
Relational tables plus recursive CTEs — a few lines of SQL.
“What breaks if redis is replaced?”
Any index can be deleted and rebuilt with one command — brico reindex —
the same philosophy as today's self-healing index.json, scaled up. Embedding generation is the only place a
network touches the pipeline, so it is fenced: always skippable, and
brico reindex --embed backfills later. Offline-first stays a hard
guarantee, not an asterisk.
Relationships are declared where everything else about a piece is declared: in the manifest. The local index aggregates them into queryable tables — no graph database, no new mental model for contributors.
depends_onWhat breaks if we replace the cache piece?replacesWhat superseded the old mailer, and why?similar_toIs there anything close to this already?inspired_byWhere did this design come from?used_byWhich pipelines are downstream of this prompt?Because pipeline pieces reference their components by name and version, the graph naturally spans code and AI assets — impact analysis works identically whether the changed piece is a Redis client or a chunking prompt.
Each phase preserves the one-binary, git-first identity. Everything heavier waits for the demand that justifies it.
brico mcp with four core toolskind field in the manifestbrico eval harnessbrico stats token accountingbrico graphDeliberately absent: “autonomous assembly of systems from verified pieces.” It remains the long-range north star — the natural consequence of a Vault an AI can query, trust, and wire — but it is a research direction, not a committed phase.
BricoWerx is an Engineering Knowledge Operating System — it structures, versions, relates, and preserves engineering craftsmanship, serving it to humans through a CLI and cockpit, and to AI through MCP.
| Category | Representatives | Our differentiation |
|---|---|---|
| Repo-indexing AI assistants | Sourcegraph/Cody, GitHub indexing, internal RAG | They retrieve from everything ever written; we retrieve from a curated Vault of proven pieces at ladder fidelity. Recall of the best, not of the most. |
| Prompt management SaaS | LangSmith, PromptLayer, Humanloop | SaaS-first and heavyweight. Our wedge: offline, git-native, one binary — prompts versioned next to the code pieces they serve, which none of them do. |
| ML infrastructure | MLflow, Weights & Biases, Hugging Face | Not competed with. We version AI engineering assets around their artifacts; dataset pieces point to them rather than replacing them. |
| Package registries | npm, PyPI, internal registries | Registries distribute libraries; the Vault captures your modules with wiring, environment, decisions and evals attached — knowledge a package cannot carry. |
The through-line in every row: our moat is not a model or an index — it is the discipline of the Vault and the trust it earns. Models will churn; a decade of versioned organisational craftsmanship only appreciates.
Time from download to first captured piece stays under five minutes; weekly active Vaults grow phase over phase.
brico add events per Vault per month — the direct measure of “reuse beats regeneration” happening.
brico stats shows measured tokens served vs. full-file baseline; target 1–2 orders of magnitude.
Share of prompt pieces carrying eval cases; eval pass-rate history visible across versions.
Pieces reused by someone other than their author — the truest signal that organisational memory is being built.
A new engineer joins, connects their assistant to the team Vault, and ships production-quality work on day one using pieces they did not write and decisions they did not have to re-make. When that story is routine, the Engineering Knowledge Operating System exists.
| Command | Status | What it does |
|---|---|---|
brico extract | working | X-rays a NestJS or Next.js project, surfaces reusable candidates ranked by confidence |
brico capture | working | Snapshots a module into an immutable, semver'd piece with a manifest |
brico add | working | Resolves a version, copies files, merges env vars, prints wiring steps |
brico list / search | working | Finds any piece by name, tag, or description via a self-healing index |
brico doctor | working | Validates engine, adapters, Vault, and project |
brico ui | working | Full-screen terminal cockpit over the Vault |
brico publish | working | Pushes the Vault or a single piece to a GitHub repo |
brico mcp | phase A | Exposes the Vault as a Model Context Protocol server |
brico eval | phase B | Runs versioned evaluation cases for prompt pieces |
brico stats | phase C | Local, opt-in token-savings accounting |
brico graph | phase C | Queries the relationship graph — depends_on, replaces, similar_to |
The main repo is asked for once and saved to your global config — override with
--repo/-l or the
LEGO_PUBLISH_REPO environment variable. Pushes use your ambient git credentials.
Days of work, not months — a thin protocol layer over the same engine and index the CLI already uses.
Your next answer is already sitting in your last project. Reuse beats regeneration — enforced by making reuse the cheapest path.