From b6ceccca26d806f2cbc7ef915762e46dd13e429c Mon Sep 17 00:00:00 2001 From: Mathias Date: Sat, 22 Aug 2026 06:10:06 +0000 Subject: [PATCH] docs: name brain-mcp and say where its code lives (#94) (#99) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A forge search for "brain-mcp" returned nothing for this repo: the description mentioned neither the brain nor brain-mcp, and the README never used the string or the hostname. Both appeared only in the generated CLAUDE.md/AGENTS.md. Since #91 part 2 decided the code stays in ingestion, discoverability is answered by naming. Adds a "Where brain-mcp lives" section: the ingress, the package, a table mapping what-you-are-looking-for to where-it-is (including that the brain content is a separate repo), and why it is not standalone, with a pointer to the ADR. Also repoints the README's three forge links from the decommissioned gitea.d-ma.be alias to git.d-ma.be. Dated files under docs/superpowers are left alone — they record what was true when written. Repo description and topics were set through the forge API, and NPM's default-site was changed from congratulations to 404 so a retired hostname reads as absent rather than as a moved repo. Closes #94. Co-authored-by: Mathias --- README.md | 38 +++++++++++++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b168937..ebb6265 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,11 @@ Instead of letting Claude Code do whatever it wants, hyperguild enforces structu workflows (TDD red/green/refactor), logs every session, and accumulates learnings into a searchable brain. +**This repo is also where `brain-mcp` lives** — the MCP server at +`brain-mcp.d-ma.be` that `brain_query`, `brain_write`, `brain_read`, `brain_edit` +and `capture` are served from. It is not a separate deployable; see +[Where brain-mcp lives](#where-brain-mcp-lives). + ## Hypothesis > We believe routing skill tasks through local models, backed by brain context, @@ -20,7 +25,7 @@ usage, the fast-model routing path should be reconsidered. **hyperguild = Claude Code + MCP.** This is a supervisor for Claude Code sessions specifically. For multi-agent orchestration (OpenCode + LiteLLM, executor/reviewer pipelines), see -[agentsquad](http://gitea.d-ma.be/mathias/agentsquad) — a separate harness for a different +[agentsquad](https://git.d-ma.be/mathias/agentsquad) — a separate harness for a different orchestration model. Skills (mathias/skills) are shared between both. ## How it works @@ -44,6 +49,33 @@ brain/ └── knowledge/ — legacy flat notes (migration pending: hyperguild#22) ``` +## Where brain-mcp lives + +`brain-mcp` is served from **`ingestion/internal/mcp`** in this repo, at +**`brain-mcp.d-ma.be`**. It is a component *inside* the `ingestion` service, not +a standalone deployable — one pod in the `supervisor` namespace serves the MCP +endpoint, the REST API, and the claudewatcher together. + +| You are looking for | It is here | +|---|---| +| The MCP tool surface (`brain_query`, `brain_write`, `brain_read`, `brain_edit`, `capture`, …) | `ingestion/internal/mcp` | +| The HTTP/REST API (`/query`, `/write`, `/ingest`) | `ingestion/internal/api` | +| Session ingestion from Claude Code transcripts | `ingestion/internal/claudewatcher` | +| The brain *content* (notes, wings, halls) | [`mathias/brain`](https://git.d-ma.be/mathias/brain) — a separate repo | +| Deployment manifests | `config/supervisor` | + +### Why it is not its own repo + +Asked and decided in [#91](https://git.d-ma.be/mathias/hyperguild/issues/91) +(part 2). `internal/mcp` imports 17 of ingestion's other internal packages and +has exactly one importer — it is the MCP facade over the service's own +internals, so "move it out" resolves to renaming `ingestion`, publishing 17 +packages as a shared library, or maintaining a shim. The discoverability problem +that prompted the question is answered by naming it here instead. + +Full reasoning, including the reversal trigger: brain +`wiki/hyperguild/decisions/brain-mcp-stays-in-ingestion-fix-discoverability-by-name`. + ## Phase 1 tools (available now) | Tool | What it does | @@ -58,7 +90,7 @@ brain/ | `tier` | Returns the current connectivity tier (1=cloud, 2=LAN, 3=offline) | > **Note:** `tdd_red/green/refactor` and `spec` were retired in Plan 7 (2026-05-12). -> They are now SKILL.md files in [mathias/skills](http://gitea.d-ma.be/mathias/skills). +> They are now SKILL.md files in [mathias/skills](https://git.d-ma.be/mathias/skills). ## Connect a project @@ -147,7 +179,7 @@ The routing pod selects models per skill call based on historical pass rate: ## Open issues -See [issues](http://gitea.d-ma.be/mathias/hyperguild/issues) — key open items: +See [issues](https://git.d-ma.be/mathias/hyperguild/issues) — key open items: - **#25** — skills platform overhaul (audit first, then lazy loading + brain feedback loop) - **#24** — reduce context burn from skill listing