From 25b9b6683e451b158b316cff035aa8e792803bb3 Mon Sep 17 00:00:00 2001 From: Mathias Date: Thu, 20 Aug 2026 17:32:20 +0200 Subject: [PATCH 1/2] docs: name brain-mcp and say where its code lives (#94) 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 mentions neither the brain nor brain-mcp, and the README said "accumulates learnings into a searchable brain" without ever using the string `brain-mcp` or its hostname. Both appeared only in CLAUDE.md and AGENTS.md — generated agent-context files, not the human front door. That is precisely the experience that generated infra#265. Since #91 part 2 decided the code stays in ingestion, discoverability has to be 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 different repo), and why it is not standalone, with a pointer to the ADR for the full reasoning and the reversal trigger. Docs only. Repo description and topics are set through the forge API, not in this diff. Refs #94, #91. --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index b168937..d7bf8d2 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, @@ -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 | -- 2.54.0 From ecbef33637b6f1d746efd396c447f2486d7d7363 Mon Sep 17 00:00:00 2001 From: Mathias Date: Thu, 20 Aug 2026 17:37:05 +0200 Subject: [PATCH 2/2] docs: point the README's forge links at git.d-ma.be (#94) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The three forge links in README.md used http://gitea.d-ma.be, an alias whose ingress was removed by infra#126. Verified rather than assumed: DNS still resolves the name to the same IP, but a public repo returns 404 there and 200 on git.d-ma.be, with no redirect — so the links are broken, not merely old. Scope is README.md only. The dated files under docs/superpowers/plans and specs are records of what was done in April/May 2026, when that hostname was correct; rewriting them would falsify the record rather than fix a link. Note the agentsquad link still 404s unauthenticated — that repo is private, which is expected and not a URL problem. Refs #94, infra#126. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d7bf8d2..ebb6265 100644 --- a/README.md +++ b/README.md @@ -25,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 @@ -90,7 +90,7 @@ Full reasoning, including the reversal trigger: 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 @@ -179,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 -- 2.54.0