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

---

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 — per person, private, never reaches agents BezelBrain — company intelligence, shared, agents read it Agent Brain — platform learning, agents write it, powers self-healing ``

---

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.

Storage: brain_memory WHERE scope = 'personal' AND user_id = '<person>'

Access: Exclusively via brain-mcp with the correct per-user key. No other path exists to this data.

Use: Think out loud, capture observations, park half-formed ideas. The only action that moves data out of Personal Brain is an explicit promote.

---

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.

Storage: brain_memory WHERE scope = 'corporate'

• Write: via brain-mcp (direct capture or promoted from Personal Brain)
• Read by humans: via brain-mcp search tools
• Read by agents: via atlas-context.js only — not open MCP access. No agent MCP config includes brain-mcp.

• thought — observation, note, reaction
• idea — something worth doing, not yet a project
• knowledge — established fact, decision, principle the company holds
• external — competitive signal, research, API discovery, sentinel output
• agent_insight — surfaced from Agent Brain, worth human attention

Promotion paths: 1. Personal → BezelBrain: contribute(thought_id) in brain-mcp — scope becomes corporate 2. BezelBrain idea → RedKey project: contribute_to_project(thought_id, context?) — brain-mcp posts to coordinator topic, Claire picks up, Priya specs it, workflow created 3. 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")

Visibility field: visibility = 'team' | 'public' — default team. Added now so future contractor/external scoping doesn't require a migration.

---

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.

Storage: Existing agent_memory table in RedKey Supabase.

• teach_agent MCP tool (Atlas injecting learnings into specific agents)
• Self-healing loop (resolution patterns when APIs break and get fixed)
• Agents proactively via teach_agent when they identify a durable learning

• atlas-context.js (relevant memories injected into Atlas sessions)
• Intent layer (queried during resolution and self-healing)

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.

---

```sql CREATE TABLE brain_memory ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), content text NOT NULL, embedding vector(1536), user_id text, -- 'justin' | 'richard' | null (for corporate-direct) scope text NOT NULL DEFAULT 'personal', -- 'personal' | 'corporate' category text, -- 'thought' | 'idea' | 'knowledge' | 'external' | 'agent_insight' contributed_by text, -- who originally created it (preserved through promotion) visibility text NOT NULL DEFAULT 'team', -- 'team' | 'public' tags text[], source text, -- 'brain-mcp' | 'sentinel' | 'api-scout' | 'agent' workflow_context jsonb, -- active workflow/step at capture time (auto-tagged) metadata jsonb, created_at timestamptz DEFAULT now(), updated_at timestamptz DEFAULT now() );

CREATE INDEX brain_memory_embedding_idx ON brain_memory USING hnsw (embedding vector_cosine_ops);

CREATE INDEX brain_memory_scope_idx ON brain_memory (scope); CREATE INDEX brain_memory_user_scope_idx ON brain_memory (user_id, scope); ```

---

Hosted on: RedKey Supabase (tseqkbyqyrctrkihllss) Auth: x-brain-key header or ?key= query param → resolves to user_id Secrets: BRAIN_KEY_JUSTIN, BRAIN_KEY_RICHARD (one per operator)

capture_thought `` content: string scope?: 'personal' | 'corporate' — default 'personal' category?: string tags?: string[] ` Saves to brain_memory. Auto-tags workflow_context` by querying RedKey for active workflows at capture time.

search_thoughts `` query: string scope?: 'personal' | 'corporate' | 'both' — default: personal for user's own, corporate for both limit?: number — default 10 threshold?: number — default 0.5 `` Semantic search via pgvector. Personal searches are user-scoped. Corporate searches see all corporate entries regardless of contributor.

list_thoughts `` scope?: string category?: string limit?: number days?: number ``

contribute `` thought_id: string ` Promotes a personal thought to corporate. Preserves contributed_by. Scope becomes corporate`.

contribute_to_project `` thought_id: string context?: string — additional framing for Claire/Priya ` Promotes 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.

thought_stats Summary: total by scope, category distribution, top tags, top contributors.

• Auto-tag captures with current workflow context
• Enrich search results with system state relevance
• Proactively surface relevant thoughts when context changes

---

Corporate brain is injected into every Atlas session before recent memories:

```js // Query corporate brain — recent + semantically relevant const corporate = await supabase .from('brain_memory') .select('content, category, contributed_by, created_at, tags') .eq('scope', 'corporate') .order('created_at', { ascending: false }) .limit(15);

// If topic provided, also run semantic search on corporate brain if (topic) { const relevant = await semanticSearch('brain_memory', topic, { scope: 'corporate', limit: 10 }); } ```

Appears as ## BezelBrain section in Atlas context, above recent memories.

---

| Layer | brain-mcp (personal key) | atlas-context.js | Agent MCP | Intent layer | |---|---|---|---|---| | Personal Brain | ✅ own only | ✗ | ✗ | ✗ | | BezelBrain | ✅ read/write | ✅ read | ✗ | ✅ read | | Agent Brain | ✗ | ✅ read | ✅ write via teach_agent | ✅ read/write |

---

• open-brain-mcp in the ccos repo — retired
• capture_thought tool in ccos2-gateway — retired
• park_idea tool in ccos2-gateway — retired
• Thought data migration from both sources → brain_memory (follow-on task)