feat: integrate external Brain memory bridge

Adds optional external Brain CLI/MCP integration, installed project bridge tooling, the Brain seed skill, v0.18.0 release docs/version text, and regression coverage.

Author: codejunkie99

.agent/AGENTS.md

@@ -78,6 +78,8 @@ Daily driver, highest-leverage first:
   protocol for patterns the dream cycle has staged.
 - `retract_lesson.py <lesson_id> --rationale "..."` — stop an accepted lesson
   from being injected into future recall/context while preserving audit history.
+- `brain_bridge.py ask|note|status` — optional bridge to the external Brain
+  CLI for git-backed long-term memory shared across harnesses.
 - `memory_reflect.py <skill> <action> <outcome>` — log a significant event.
 
 ## Rules

.agent/skills/_index.md

@@ -45,6 +45,14 @@ Triggers: "data flywheel", "trace to train", "training traces",
 Constraints: local-only by default; human-approved runs only; redaction required
 before trainable; does not train models.
 
+## brain
+Connects agentic-stack projects to the external Brain CLI and MCP server for
+git-backed long-term memory shared across harnesses.
+Triggers: "brain", "long-term memory", "shared memory", "cross-agent memory",
+"mcp memory", "remember across tools", "git-backed memory"
+Constraints: Brain is external; check availability before use, do not store
+secrets, and use `brain_bridge.py ask` before saving new durable notes.
+
 ## design-md
 Uses a root `DESIGN.md` as the portable visual system contract for
 Google Stitch workflows. Loads only when `DESIGN.md` exists at the

.agent/skills/_manifest.jsonl

@@ -5,5 +5,6 @@
 {"name":"deploy-checklist","version":"2026-01-01","triggers":["deploy","ship","release","go live"],"tools":["bash"],"preconditions":[],"constraints":["all tests passing","no unresolved TODOs in diff","requires human approval for production"],"category":"operations"}
 {"name":"data-layer","version":"2026-04-26","triggers":["data layer","dashboard","show me the dashboard","what did my agents do","agent analytics","agent status","resource usage","usage report","cron monitoring","daily report","tokens","terminal dashboard","TUI"],"tools":["bash","git"],"preconditions":[".agent exists"],"constraints":["local-only by default","no screenshot delivery without explicit user approval","do not commit private .agent/data-layer exports"],"category":"operations"}
 {"name":"data-flywheel","version":"2026-04-25","triggers":["data flywheel","trace to train","training traces","context cards","eval cases","approved runs","vertical intelligence"],"tools":["bash","git"],"preconditions":[".agent exists"],"constraints":["local-only by default","human-approved runs only","redaction required before trainable","do not train models"],"category":"operations"}
+{"name":"brain","version":"2026-05-10","triggers":["brain","long-term memory","shared memory","cross-agent memory","mcp memory","remember across tools","git-backed memory"],"tools":["bash"],"preconditions":[".agent exists"],"constraints":["Brain is external; do not assume the brain binary is installed","do not store secrets in Brain","use ask before note when checking prior context"],"category":"memory"}
 {"name":"design-md","version":"2026-04-26","triggers":["DESIGN.md","design.md","Google Stitch","Stitch","design tokens","design system","visual design"],"tools":["bash","memory_reflect"],"preconditions":["DESIGN.md exists at project root"],"constraints":["prefer DESIGN.md tokens over invented values","do not modify DESIGN.md unless the user explicitly asks","preserve unknown sections when an edit IS authorised","validate when tooling is available"],"category":"design"}
 {"name":"tldraw","version":"2026-04-21","triggers":["draw","diagram","sketch","wireframe","flowchart","mind-map","mind map","visualize","lay out","architecture diagram","whiteboard"],"tools":["mcp.tldraw.create_shape","mcp.tldraw.update_shape","mcp.tldraw.delete_shape","mcp.tldraw.get_canvas"],"preconditions":["tldraw MCP server reachable","user has http://localhost:3030 open"],"constraints":["call get_canvas before update_shape or delete_shape","at most 200 shapes per create_shape call","coordinates within 0..1600 x 0..900 unless told otherwise"],"category":"visualization","feature_flag":"tldraw"}

.agent/skills/brain/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: brain
+version: 2026-05-10
+triggers: ["brain", "long-term memory", "shared memory", "cross-agent memory", "mcp memory", "remember across tools", "git-backed memory"]
+tools: [bash]
+preconditions: [".agent exists"]
+constraints: ["Brain is external; do not assume the brain binary is installed", "do not store secrets in Brain", "use ask before note when checking prior context"]
+category: memory
+---
+
+# Brain Integration
+
+Use this skill when the task needs durable memory shared across coding-agent
+harnesses through the external `brain` CLI and MCP server.
+
+## Check Availability
+
+```bash
+python3 .agent/tools/brain_bridge.py status
+```
+
+If Brain is missing, tell the user to install it:
+
+```bash
+brew install codejunkie99/tap/brain
+```
+
+## Recall
+
+Before non-trivial work that could depend on prior cross-tool decisions:
+
+```bash
+python3 .agent/tools/brain_bridge.py ask "<intent or topic>"
+```
+
+Use returned notes as context, but keep project-local `.agent/memory/semantic`
+as the source for agentic-stack lessons until the user explicitly asks to
+promote or migrate them.
+
+## Save
+
+Save one concise observation when the user gives a durable preference,
+cross-project convention, or decision that should survive across harnesses:
+
+```bash
+python3 .agent/tools/brain_bridge.py note "<one durable observation>"
+```
+
+Do not save secrets, credentials, or ephemeral task details.
+
+## MCP
+
+To wire Brain as an MCP stdio server, inspect:
+
+```bash
+python3 .agent/tools/brain_bridge.py mcp-command
+```
+
+The expected command is `brain serve --mcp`.

.agent/tools/brain_bridge.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Host-agent bridge to the external Brain CLI.
+
+This script is copied into installed projects by `agentic-stack upgrade`. It
+keeps agent instructions stable even though Brain itself is a separate Rust
+binary and release stream.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+INSTALL_HINT = """brain CLI not found.
+
+Install Brain:
+  brew install codejunkie99/tap/brain
+
+Or set:
+  AGENTIC_STACK_BRAIN_BIN=/path/to/brain
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Bridge .agent workflows to Brain.")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("status")
+    sub.add_parser("log")
+    doctor = sub.add_parser("doctor")
+    doctor.add_argument("--deep", action="store_true")
+    ask = sub.add_parser("ask")
+    ask.add_argument("query", nargs=argparse.REMAINDER)
+    note = sub.add_parser("note")
+    note.add_argument("text", nargs=argparse.REMAINDER)
+    sub.add_parser("mcp-command")
+
+    args = parser.parse_args(argv)
+    brain = _brain_bin()
+    if brain is None:
+        print(INSTALL_HINT.rstrip(), file=sys.stderr)
+        return 2
+
+    if args.command == "status":
+        print(f"brain={brain}")
+        return _call([brain, "doctor"])
+    if args.command == "mcp-command":
+        print(f"{brain} serve --mcp")
+        return 0
+    if args.command == "doctor":
+        cmd = [brain, "doctor"]
+        if args.deep:
+            cmd.append("--deep")
+        return _call(cmd)
+    if args.command in {"ask", "note"}:
+        text = " ".join(getattr(args, "query", None) or getattr(args, "text", [])).strip()
+        if not text:
+            print(f"error: brain_bridge.py {args.command} requires text", file=sys.stderr)
+            return 2
+        return _call([brain, args.command, text])
+    if args.command == "log":
+        return _call([brain, "log"])
+    return 2
+
+
+def _brain_bin() -> str | None:
+    configured = os.environ.get("AGENTIC_STACK_BRAIN_BIN")
+    if configured:
+        return configured
+    return shutil.which("brain")
+
+
+def _call(cmd: list[str]) -> int:
+    try:
+        return subprocess.run(cmd, cwd=Path.cwd(), check=False).returncode
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.18.0] — 2026-05-10
+
+Minor release. Adds first-class integration with the external Brain CLI/MCP
+memory system while keeping agentic-stack's project-local `.agent/` runtime
+independent and optional.
+
+### Added
+- **Brain integration.** Adds `agentic-stack brain ...` and
+  `.agent/tools/brain_bridge.py` so projects can use the external
+  `codejunkie99/brain` CLI/MCP server as a git-backed long-term memory layer
+  without vendoring the Rust workspace into agentic-stack.
+- **Brain seed skill.** Adds a `brain` skill that teaches host agents when to
+  query or write Brain memory and how to avoid storing secrets.
+
 ## [0.17.0] — 2026-05-10
 
 Minor release. Clears the open PR queue and ships new harness adapters, the

README.md

@@ -25,27 +25,30 @@ metrics without training a model or sending telemetry.
   <img src="docs/diagram.svg" alt="agentic-stack architecture" width="880"/>
 </p>
 
-### New in v0.17.0 — adapters, Mission Control, and lesson retraction
+### New in v0.18.0 — external Brain memory integration
+
+Minor release. Adds an optional bridge to
+[`codejunkie99/brain`](https://github.com/codejunkie99/brain), the external
+git-backed long-term memory CLI/TUI/MCP server, without vendoring Brain's Rust
+workspace into agentic-stack.
+
+- **`agentic-stack brain ...`.** Check Brain status, onboard a project, search
+  global memory, write durable notes, run Brain doctor/TUI, or print the MCP
+  stdio command from the normal agentic-stack CLI.
+- **Project bridge.** Installed `.agent/` projects now include
+  `.agent/tools/brain_bridge.py`, so host agents can call Brain explicitly when
+  a task needs cross-project recall.
+- **Brain seed skill.** A new `brain` skill teaches agents when to query or
+  write Brain memory, and keeps secret handling explicit.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full list.
+
+### v0.17.0 — adapters, Mission Control, and lesson retraction
 
 Minor release. Clears the open PR queue and ships the combined production
 surface from Copilot CLI, Gemini, Mission Control, and semantic lesson
 retraction work.
 
-- **New adapters.** GitHub Copilot CLI installs `AGENTS.md`,
-  `.github/instructions/`, `.github/hooks/`, and `.github/skills/`; Google
-  Gemini CLI installs `gemini.md` and a `.gemini/skills/` mirror.
-- **Mission Control beta.** Run `agentic-stack mission-control --port 8787`
-  for a local web dashboard, or use `--snapshot` to render a static HTML
-  report without opening a browser.
-- **Lesson retraction.** Run `.agent/tools/retract_lesson.py <lesson_id> --rationale "..."`
-  to stop obsolete accepted lessons from guiding future recall while preserving
-  append-only audit history.
-- **Test layout cleanup.** The validation suite now lives under `tests/` with
-  pytest configuration, covering adapters, upgrades, Mission Control, and
-  semantic retraction.
-
-See [CHANGELOG.md](CHANGELOG.md) for the full list.
-
 ### v0.16.1 — getting-started refresh
 
 Patch release. Ships the production-ready getting-started guide from PR #49
@@ -175,6 +178,7 @@ verb-style subcommands (works with both `install.sh` and `install.ps1`):
 ```bash
 ./install.sh dashboard           # TUI dashboard: health, verify, memory, team, skills, instances
 ./install.sh mission-control     # beta local web dashboard; Ctrl-C turns it off
+./install.sh brain status        # optional external Brain CLI integration
 ./install.sh add cursor          # add a second adapter (Claude Code + Cursor in same repo)
 ./install.sh status              # one-screen view: which adapters, brain stats
 ./install.sh doctor              # read-only audit; green / yellow / red per adapter
@@ -188,6 +192,32 @@ verb-style subcommands (works with both `install.sh` and `install.ps1`):
 
 PowerShell uses the same verbs, for example `.\install.ps1 dashboard`.
 
+### Optional: external Brain integration
+
+[`codejunkie99/brain`](https://github.com/codejunkie99/brain) is the
+git-backed long-term memory binary and MCP server. agentic-stack now treats it
+as an optional external memory layer instead of vendoring its Rust workspace.
+
+Install Brain first:
+
+```bash
+brew install codejunkie99/tap/brain
+```
+
+Then check or wire it from a project:
+
+```bash
+agentic-stack brain status
+agentic-stack brain onboard --agents codex,cursor --yes
+agentic-stack brain ask "auth decisions"
+agentic-stack brain note "Use PKCE for local OAuth flows."
+agentic-stack brain mcp-command
+```
+
+Installed `.agent/` projects also get `python3 .agent/tools/brain_bridge.py`
+and a `brain` seed skill so host agents can query or write Brain memory when a
+task needs cross-harness long-term recall.
+
 Bare `./install.sh` (no arguments) opens a **multi-select wizard** on
 a fresh project — check every harness you actually use, hit enter,
 each one gets installed. The wizard auto-detects harnesses already on
@@ -389,6 +419,7 @@ The index is stored at `.agent/memory/.index/` and gitignored.
     ├── show.py                 # colorful brain-state dashboard
     ├── data_layer_export.py    # local cross-harness dashboard/data export
     ├── data_flywheel_export.py # approved runs -> traces/cards/evals/JSONL
+    ├── brain_bridge.py         # bridge to external Brain CLI/MCP memory
     ├── list_candidates.py
     ├── graduate.py
     ├── reject.py
@@ -417,6 +448,7 @@ harness_manager/                # v0.9.0 manifest-driven Python backend
 ├── remove.py                   # safe uninstall with shared-file detection + ownership handoff
 ├── dashboard_tui.py            # project dashboard for health/verify/memory/team/skills/instances
 ├── mission_control.py          # beta local web dashboard entrypoint
+├── brain.py                    # optional external Brain CLI integration
 ├── mission_control_collectors.py
 ├── mission_control_render.py
 ├── mission_control_server.py

docs/getting-started.md

@@ -81,6 +81,7 @@ the project root:
 ```bash
 agentic-stack dashboard           # TUI dashboard: health, verify, memory, team, skills
 agentic-stack mission-control     # beta local web dashboard; Ctrl-C turns it off
+agentic-stack brain status        # optional external Brain CLI integration
 agentic-stack status              # one-screen view: which adapters, brain stats
 agentic-stack doctor              # read-only audit; green / yellow / red per adapter
 agentic-stack upgrade --dry-run   # preview safe .agent infrastructure refresh
@@ -93,6 +94,7 @@ Source checkout users can run the same verbs through the clone:
 ```bash
 ./install.sh dashboard /path/to/your-project
 ./install.sh mission-control /path/to/your-project
+./install.sh brain status
 ./install.sh status /path/to/your-project
 ./install.sh doctor /path/to/your-project
 ./install.sh upgrade /path/to/your-project --dry-run

harness_manager/__init__.py

@@ -2,8 +2,8 @@
 
 This package is the implementation backend for `./install.sh` and `./install.ps1`.
 The user-facing surface is plain verbs: install, add, remove, doctor, status,
-dashboard, mission-control, manage, transfer, upgrade, and sync-manifest.
+dashboard, mission-control, brain, manage, transfer, upgrade, and sync-manifest.
 The "harness_manager" name is internal only and never appears in CLI help, docs,
 or error messages users see.
 """
-__version__ = "0.17.0"
+__version__ = "0.18.0"