brain-memory-bank

Brain Memory Bank

GSD-inspired persistent context pattern for brain-mcp multi-agent workflows.

Use when: Using brain-mcp to coordinate multiple subagents that need shared context across tasks.

What it solves: Subagents have no memory between tasks. This makes the orchestrator the memory bank using a single STATE.md file.

---

Pattern

Orchestrator
│
│  MAINTAINS: ~/.hermes/.brain/STATE.md
│
│  PER TASK:
│    1. brain_set("task_context", $SLICE_OF_STATE)
│    2. brain_wake(agent, goal + context)
│
│  AFTER RESULTS:
│    1. brain_read() — collect agent posts
│    2. Update STATE.md — "What Was Done", "Agent Context"
│    3. brain_set next wave or end
│
└── Subagents: read brain_get("task_context"), do work, brain_post() results

---

Orchestrator Workflow

1. Initialize Session

BRAIN_STATE="$HOME/.hermes/.brain/STATE.md"
mkdir -p "$(dirname "$BRAIN_STATE")"

cat > "$BRAIN_STATE" <<'EOF'
# Brain MCP — Session State

## Session

Project: [project-name]
Session ID: [session-id]
Started: [YYYY-MM-DD HH:MM]
Status: active

## Current Phase

Phase: init
Updated: [YYYY-MM-DD HH:MM]

## Orchestrator Memory

### What Was Done
- (empty — fill after first wave)

### Active Decisions
- (empty)

### Blockers
- (none)

### Pending Results
- (none)

## Agent Context

## Files Under Work

## Session Log
EOF

2. Per-Wave: Inject Context Slices

Before brain_wake, extract relevant slice from STATE.md:

# Extract context relevant to this task
get_context_slice() {
  local phase="$1"  # e.g., "auth", "api", "frontend"
  local state="$HOME/.hermes/.brain/STATE.md"

  # Get orchestrator memory (always relevant)
  echo "## Orchestrator Memory"
  grep -A 20 "## Orchestrator Memory" "$state" 2>/dev/null || echo "(no memory yet)"

  # Get relevant files under work
  echo ""
  echo "## Files Under Work (relevant to: $phase)"
  grep -A 10 "## Files Under Work" "$state" 2>/dev/null | grep -i "$phase" || echo "(none)"

  # Get agent context for relevant agents
  echo ""
  echo "## Agent Context"
  grep -A 8 "### agent-" "$state" 2>/dev/null | grep -A 8 "$phase" || echo "(none)"
}