{
  "id": "2026-04-23-brain-architecture-94c50b47a8",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-04-23-brain-architecture.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.661Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Brain Architecture",
  "summary": "Brain Architecture Date: 2026 04 23 Status: Design Related: docs/specs/2026 04 23 semantic intent layer.md, docs/specs/2026 04 22 atlas agent memory design.md Overview Three distinct knowledge layers with clear ownership, access boundaries, and promotion paths. Each layer serves a different purpose and has different access rules. Personal Brain What it is: P...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Brain Architecture",
      "level": 1,
      "body": "**Date:** 2026-04-23  \n**Status:** Design  \n**Related:** `docs/specs/2026-04-23-semantic-intent-layer.md`, `docs/specs/2026-04-22-atlas-agent-memory-design.md`\n\n---"
    },
    {
      "title": "Overview",
      "level": 2,
      "body": "Three distinct knowledge layers with clear ownership, access boundaries, and promotion paths. Each layer serves a different purpose and has different access rules.\n\n```\nPersonal Brain     — per person, private, never reaches agents\nBezelBrain         — company intelligence, shared, agents read it\nAgent Brain        — platform learning, agents write it, powers self-healing\n```\n\n---"
    },
    {
      "title": "Personal Brain",
      "level": 2,
      "body": "**What it is:** Private thought capture per operator. Justin's thoughts stay Justin's. Richard's stay Richard's. Nothing in Personal Brain is ever surfaced to agents or to other people.\n\n**Storage:** `brain_memory` WHERE `scope = 'personal'` AND `user_id = '<person>'`\n\n**Access:** Exclusively via `brain-mcp` with the correct per-user key. No other path exists to this data.\n\n**Use:** Think out loud, capture observations, park half-formed ideas. The only action that moves data out of Personal Brain is an explicit promote.\n\n---"
    },
    {
      "title": "BezelBrain",
      "level": 2,
      "body": "**What it is:** BezelIQ's organizational intelligence hub. Shared across all team members. Captures thoughts, ideas, knowledge, and external intelligence. Ideas promote into RedKey projects. As the company grows, this is the onboarding corpus — everything the company knows lives here.\n\n**Storage:** `brain_memory` WHERE `scope = 'corporate'`\n\n**Access:**\n- Write: via `brain-mcp` (direct capture or promoted from Personal Brain)\n- Read by humans: via `brain-mcp` search tools\n- Read by agents: via `atlas-context.js` only — not open MCP access. No agent MCP config includes `brain-mcp`.\n\n**Categories:**\n- `thought` — observation, note, reaction\n- `idea` — something worth doing, not yet a project\n- `knowledge` — established fact, decision, principle the company holds\n- `external` — competitive signal, research, API discovery, sentinel output\n- `agent_insight` — surfaced from Agent Brain, worth human attention\n\n**Promotion paths:**\n1. Personal → BezelBrain: `contribute(thought_id)` in brain-mcp — scope becomes `corporate`\n2. BezelBrain idea → RedKey project: `contribute_to_project(thought_id, context?)` — brain-mcp posts to coordinator topic, Claire picks up, Priya specs it, workflow created\n3. Agent Brain → BezelBrain: agents write `category = 'agent_insight'` when they identify something worth human attention (e.g. \"HubSpot schema changed again — third time this quarter\")\n\n**Visibility field:** `visibility = 'team' | 'public'` — default `team`. Added now so future contractor/external scoping doesn't require a migration.\n\n---"
    },
    {
      "title": "Agent Brain",
      "level": 2,
      "body": "**What it is:** What the platform learns through execution. Written by agents, not humans. This is the memory that powers self-healing — API behavior patterns, resolution history, what worked when something broke.\n\n**Storage:** Existing `agent_memory` table in RedKey Supabase.\n\n**Written by:**\n- `teach_agent` MCP tool (Atlas injecting learnings into specific agents)\n- Self-healing loop (resolution patterns when APIs break and get fixed)\n- Agents proactively via `teach_agent` when they identify a durable learning\n\n**Read by:**\n- `atlas-context.js` (relevant memories injected into Atlas sessions)\n- Intent layer (queried during resolution and self-healing)\n\n**Upward flow to BezelBrain:** When an agent identifies an insight worth human attention, it writes to `brain_memory` with `scope = 'corporate'`, `category = 'agent_insight'`, `source = 'agent'`. This surfaces in Atlas context for human review.\n\n---"
    },
    {
      "title": "brain_memory",
      "level": 3,
      "body": "```sql\nCREATE TABLE brain_memory (\n  id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),\n  content         text NOT NULL,\n  embedding       vector(1536),\n  user_id         text,                        -- 'justin' | 'richard' | null (for corporate-direct)\n  scope           text NOT NULL DEFAULT 'personal', -- 'personal' | 'corporate'\n  category        text,                        -- 'thought' | 'idea' | 'knowledge' | 'external' | 'agent_insight'\n  contributed_by  text,                        -- who originally created it (preserved through promotion)\n  visibility      text NOT NULL DEFAULT 'team', -- 'team' | 'public'\n  tags            text[],\n  source          text,                        -- 'brain-mcp' | 'sentinel' | 'api-scout' | 'agent'\n  workflow_context jsonb,                      -- active workflow/step at capture time (auto-tagged)\n  metadata        jsonb,\n  created_at      timestamptz DEFAULT now(),\n  updated_at      timestamptz DEFAULT now()\n);\n\nCREATE INDEX brain_memory_embedding_idx ON brain_memory\n  USING hnsw (embedding vector_cosine_ops);\n\nCREATE INDEX brain_memory_scope_idx ON brain_memory (scope);\nCREATE INDEX brain_memory_user_scope_idx ON brain_memory (user_id, scope);\n```\n\n---"
    },
    {
      "title": "brain-mcp Edge Function",
      "level": 2,
      "body": "**Hosted on:** RedKey Supabase (`tseqkbyqyrctrkihllss`)  \n**Auth:** `x-brain-key` header or `?key=` query param → resolves to `user_id`  \n**Secrets:** `BRAIN_KEY_JUSTIN`, `BRAIN_KEY_RICHARD` (one per operator)"
    },
    {
      "title": "Tools",
      "level": 3,
      "body": "**capture_thought**\n```\ncontent: string\nscope?: 'personal' | 'corporate'  — default 'personal'\ncategory?: string\ntags?: string[]\n```\nSaves to `brain_memory`. Auto-tags `workflow_context` by querying RedKey for active workflows at capture time.\n\n**search_thoughts**\n```\nquery: string\nscope?: 'personal' | 'corporate' | 'both'  — default: personal for user's own, corporate for both\nlimit?: number  — default 10\nthreshold?: number  — default 0.5\n```\nSemantic search via pgvector. Personal searches are user-scoped. Corporate searches see all corporate entries regardless of contributor.\n\n**list_thoughts**\n```\nscope?: string\ncategory?: string\nlimit?: number\ndays?: number\n```\n\n**contribute**\n```\nthought_id: string\n```\nPromotes a personal thought to corporate. Preserves `contributed_by`. Scope becomes `corporate`.\n\n**contribute_to_project**\n```\nthought_id: string\ncontext?: string  — additional framing for Claire/Priya\n```\nPromotes idea to BezelBrain as `scope = 'corporate'`, then posts to `roles.coordinator` HCS topic to trigger a RedKey workflow. Claire picks it up, Priya specs it.\n\n**thought_stats**\nSummary: total by scope, category distribution, top tags, top contributors."
    },
    {
      "title": "System awareness",
      "level": 3,
      "body": "`brain-mcp` has read access to RedKey Supabase (`workflow_instances`, `cluster_events`) to:\n- Auto-tag captures with current workflow context\n- Enrich search results with system state relevance\n- Proactively surface relevant thoughts when context changes\n\n---"
    },
    {
      "title": "atlas-context.js Integration",
      "level": 2,
      "body": "Corporate brain is injected into every Atlas session before recent memories:\n\n```js\n// Query corporate brain — recent + semantically relevant\nconst corporate = await supabase\n  .from('brain_memory')\n  .select('content, category, contributed_by, created_at, tags')\n  .eq('scope', 'corporate')\n  .order('created_at', { ascending: false })\n  .limit(15);\n\n// If topic provided, also run semantic search on corporate brain\nif (topic) {\n  const relevant = await semanticSearch('brain_memory', topic, { scope: 'corporate', limit: 10 });\n}\n```\n\nAppears as `## BezelBrain` section in Atlas context, above recent memories.\n\n---"
    },
    {
      "title": "Access Summary",
      "level": 2,
      "body": "| Layer | brain-mcp (personal key) | atlas-context.js | Agent MCP | Intent layer |\n|---|---|---|---|---|\n| Personal Brain | ✅ own only | ✗ | ✗ | ✗ |\n| BezelBrain | ✅ read/write | ✅ read | ✗ | ✅ read |\n| Agent Brain | ✗ | ✅ read | ✅ write via teach_agent | ✅ read/write |\n\n---"
    },
    {
      "title": "What This Replaces",
      "level": 2,
      "body": "- `open-brain-mcp` in the `ccos` repo — retired\n- `capture_thought` tool in `ccos2-gateway` — retired\n- `park_idea` tool in `ccos2-gateway` — retired\n- Thought data migration from both sources → `brain_memory` (follow-on task)"
    }
  ],
  "html_path": "artifacts/2026-04-23-brain-architecture-94c50b47a8.html",
  "json_path": "artifacts/2026-04-23-brain-architecture-94c50b47a8.json"
}