{
  "id": "2026-04-22-atlas-agent-memory-design-cb2806df3c",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-04-22-atlas-agent-memory-design.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.659Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Atlas + Agent Memory — Design Spec",
  "summary": "Atlas + Agent Memory — Design Spec Date: 2026 04 22 Status: Draft — pending implementation plan Author: Justin King + Claude (brainstorming session) Why We Are Building This RedKey's differentiator is not that it runs agents — every platform does that. The differentiator is that RedKey agents learn . Every session, every task, every review leaves a trace. Th...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Atlas + Agent Memory — Design Spec",
      "level": 1,
      "body": "**Date:** 2026-04-22  \n**Status:** Draft — pending implementation plan  \n**Author:** Justin King + Claude (brainstorming session)\n\n---"
    },
    {
      "title": "Why We Are Building This",
      "level": 2,
      "body": "RedKey's differentiator is not that it runs agents — every platform does that. The differentiator is that **RedKey agents learn**. Every session, every task, every review leaves a trace. The longer the platform runs, the smarter every agent becomes. This is institutional knowledge as infrastructure.\n\nWithout this, agents reset every session. Quinn solves the same problem twice. Vikram flags the same issue on the twentieth PR that he flagged on the first. Priya writes specs that repeat historical mistakes. The platform is stateless, which means it doesn't compound.\n\nWith Supabase-backed semantic memory, the platform compounds. Insights are embedded, indexed, and retrieved when relevant. A pattern noticed on CCOS2 improves behavior on a new client deployment. A decision made six months ago surfaces automatically when the same question arises again.\n\nThis is the investor story: *our agents don't just respond — they build institutional knowledge. The longer they run, the better they get.*\n\n---"
    },
    {
      "title": "Atlas",
      "level": 2,
      "body": "Atlas is the platform-level strategic architect for RedKey. He is not a workflow worker. He does not process tasks on a timer. He is Justin's thinking partner for designing and improving the RedKey platform itself — how to make agents smarter, workflows better, the architecture stronger.\n\n**Atlas is distinct from Vikram.** Vikram is the dev architect: he reviews specs and PRs, enforces the stack, gates merges. Atlas operates upstream — he helps design the system before anything reaches Vikram.\n\nAtlas has two capabilities no other agent has:\n\n1. **Cross-client visibility** — he sees memory and patterns across all deployments (CCOS2, RedKey, new co, and future clients) with no client scoping\n2. **Memory curation** — he can inject learnings directly into other agents' memories, improving the fleet without persona changes or redeployment\n\nAtlas runs as an **interactive Claude Code session**, not a headless daemon. You launch him via a script, have a design conversation, and he walks in oriented every time — pre-loaded with relevant past decisions, recent session summaries, and cross-client patterns.\n\n**Agent definition:** Atlas is registered as a RedKey employee — an `agent_definition` on HCS with `roles.architect`. He does not run on a timer. His \"deployment\" is the launch script.\n\n---"
    },
    {
      "title": "Memory Taxonomy — Who Needs What",
      "level": 2,
      "body": "Different agents need different memory. The design is unified (same tables, same retrieval pattern) but scoped per agent type.\n\n| Agent | Personal memory | Project memory | Cross-client? |\n|---|---|---|---|\n| **Atlas** | All platform design history, decisions, architectural patterns | All workflow instances across the portfolio | Yes — that's his job |\n| **Claire** | Classification patterns, workflow template selection history | Prior projects for this client | No |\n| **Priya** | What specs have worked, what got rejected, successful brief patterns | All prior steps of the current workflow | No |\n| **Vikram** | Recurring violations, stack patterns, PR review history | Full project thread — spec, exec approval, Quinn's build | No |\n| **Quinn** | How he's solved similar problems, tech debt he's noticed | Spec + exec approval + prior output | No |\n| **Engine** | None — deterministic state machine | Already held in `workflow_instances` | No |\n\n**Project memory is not a separate concept.** It is `agent_memory` rows tagged with `workflow_instance_id`. Any agent on a workflow queries their personal memory plus the project thread using the same table and the same retrieval mechanism — just different tag filters.\n\n---"
    },
    {
      "title": "Schema",
      "level": 2,
      "body": "Three tables. All client-scoped. Identical whether stored in one Supabase (Option A, current) or per-client Supabase instances (Option B, future). Atlas queries without client scope.\n\n```sql\n-- Enable pgvector\ncreate extension if not exists vector;\n\n-- Semantic memory — embedded insights, decisions, patterns, learnings\n-- NOTE: vector(1536) matches OpenAI text-embedding-3-small / ada-002.\n-- The embedding model must be chosen before the table is created — the dimension\n-- is fixed at creation time and cannot be altered without dropping and rebuilding\n-- the index. Implementation must commit to a model and document it.\ncreate table agent_memory (\n  id          uuid primary key default gen_random_uuid(),\n  client_id   text not null,\n  agent_id    text not null,\n  session_id  uuid,\n  content     text not null,\n  embedding   vector(1536),\n  tags        text[],           -- e.g. ['pr-review', 'workflow:uuid', 'decision']\n  created_at  timestamptz default now()\n);\ncreate index on agent_memory using ivfflat (embedding vector_cosine_ops);\ncreate index on agent_memory (client_id, agent_id, created_at desc);\n\n-- Sessions — one row per conversation or worker run\ncreate table agent_sessions (\n  id              uuid primary key default gen_random_uuid(),\n  client_id       text not null,\n  agent_id        text not null,\n  summary         text,\n  started_at      timestamptz default now(),\n  ended_at        timestamptz,\n  last_checkpoint timestamptz,\n  metadata        jsonb default '{}'\n);\ncreate index on agent_sessions (client_id, agent_id, started_at desc);\n\n-- Messages — full conversation log (Atlas) or task log (workers)\ncreate table agent_messages (\n  id          uuid primary key default gen_random_uuid(),\n  session_id  uuid references agent_sessions(id),\n  client_id   text not null,\n  agent_id    text not null,\n  role        text not null,   -- 'user' | 'assistant'\n  content     text not null,\n  created_at  timestamptz default now()\n);\ncreate index on agent_messages (session_id, created_at);\n```\n\n**RLS:** Worker agents enforce `WHERE client_id = ?` at the policy level. Atlas uses service-role — no client restriction.\n\n---"
    },
    {
      "title": "Session Start — Context Assembly",
      "level": 3,
      "body": "Before Claude launches, the context script runs:\n\n1. Embed the opening topic or seed phrase\n2. Semantic search: retrieve top-K relevant memories for this agent (+ cross-client for Atlas)\n3. Pull last 3 session summaries for recency context\n4. If recovering from a crash (session with no `ended_at`): load raw message log as additional context\n5. Assemble context block → write to temp file → pass via `--append-system-prompt-file`\n\nThe agent walks in oriented. No manual loading step. No skill to invoke."
    },
    {
      "title": "Mid-Session — Durable Capture",
      "level": 3,
      "body": "Memory is written continuously, not only at the end:\n\n- **Every turn:** message written to `agent_messages` via Claude Code post-turn hook (Atlas) or MCP tool (worker agents). Session is durable from the first exchange.\n- **Every 5–10 turns:** checkpoint triggered automatically — extract insights from recent turns, embed, write to `agent_memory`. `last_checkpoint` updated on session row.\n- **Manual force:** `/log` skill — triggers immediate checkpoint on demand. Use when you've just made an important decision and want it locked in before the conversation moves on."
    },
    {
      "title": "Session End — Memory Consolidation",
      "level": 3,
      "body": "1. Summarize the full session (1 paragraph) → stored in `agent_sessions.summary`\n2. Extract 3–10 discrete insights (\"we decided X\", \"pattern Y recurring on CCOS2\", \"Atlas flagged Z as technical debt\")\n3. Embed each insight → insert into `agent_memory` with tags\n4. `ended_at` written on session row\n\n---"
    },
    {
      "title": "Atlas Launch Script",
      "level": 2,
      "body": "```bash\n#!/usr/bin/env bash"
    },
    {
      "title": "run-architect.sh — assemble Supabase context, launch interactive Atlas session",
      "level": 1,
      "body": "topic=\"${1:-}\"\nnode scripts/atlas-context.js \"$topic\" > /tmp/atlas-context.md\nexec claude \\\n  --append-system-prompt-file definitions/agents/atlas-persona.md \\\n  --append-system-prompt-file /tmp/atlas-context.md \\\n  --add-dir .\n```\n\nShell alias for seamless invocation from anywhere:\n\n```bash\nalias atlas=\"~/downloads/cc/projects/redkey/run-architect.sh\"\n```\n\n`atlas` → context assembles from Supabase → session opens with full orientation.\n\n---"
    },
    {
      "title": "Forcing Improvements Into Agent Memory",
      "level": 2,
      "body": "Agents improve through two mechanisms:"
    },
    {
      "title": "Manual — `/teach` Skill",
      "level": 3,
      "body": "A skill that writes directly to `agent_memory` for any agent, from any session:\n\n```\n/teach vikram \"Always verify async error handling coverage before PR approval — Quinn consistently misses this\"\n/teach quinn \"Prefer explicit error types over generic catch blocks — Vikram flags this on every review\"\n/teach priya \"Specs must include explicit output contracts for every step — Claire needs these to create workflow instances\"\n```\n\nThe learning is embedded and written immediately. It surfaces for the target agent whenever semantically relevant work triggers it. No persona update. No redeployment. No retraining.\n\n**Dependency:** `/teach` calls the same embedding API used by the memory system to generate the vector before writing. The embedding model must be consistent across all writes to `agent_memory` — mixing models produces incomparable vectors and breaks similarity search."
    },
    {
      "title": "Autonomous — Atlas as Memory Curator",
      "level": 3,
      "body": "Atlas has cross-client, cross-agent visibility. As part of his role, he identifies patterns no single agent can see:\n\n- Quinn on CCOS2 and Quinn on new co are both missing the same thing\n- Vikram has flagged the same stack violation twelve times across three clients\n- Priya's specs for a particular workflow type consistently underspecify async contracts\n\nWhen Atlas identifies a pattern, he pushes the learning into the relevant agent's memory directly — the same write path as `/teach`, but initiated by Atlas. The agent fleet improves without any human intervention.\n\n**This is the compound flywheel:** Atlas observes patterns, injects learnings, agents improve, Atlas observes the improvement, the cycle repeats. The platform gets smarter with every deployment.\n\n---"
    },
    {
      "title": "What This Replaces",
      "level": 2,
      "body": "| Current | Replacement |\n|---|---|\n| `/cockpit` skill — manual context load at session start | Atlas launch script — automatic Supabase context assembly |\n| `/session-close` skill — manual summary and commit | Session end hook — automatic summarisation and memory persistence |\n| `/log` skill — manual mid-session write to file | `/log` skill updated — writes to `agent_memory` + `agent_sessions` in Supabase |\n\n`/log` is retained as the manual force-checkpoint. The rest are retired.\n\n---"
    },
    {
      "title": "Migration Path — Option A to Option B",
      "level": 2,
      "body": "**Option A (current):** All agent memory in the central RedKey Supabase (`tseqkbyqyrctrkihllss`), `client_id` on every row.\n\n**Option B (future):** Per-client Supabase instances. Each deployment holds its own memory. Atlas queries multiple instances.\n\n**Why the schema is migration-ready:**\n- Schema is identical in both options — no redesign required\n- Memory access is abstracted behind a `MemoryRepository` that resolves `client_id → Supabase URL`\n- Option A: all client_ids → same URL\n- Option B: lookup table maps `client_id → client Supabase URL`\n- Migration = data move (dump rows by client_id, restore to client-specific instance) + resolver config update\n- Zero schema change. Zero agent code change.\n\n---"
    },
    {
      "title": "Summary",
      "level": 2,
      "body": "| Concept | What it is |\n|---|---|\n| `agent_memory` | Embedded insights, decisions, learnings — retrieved semantically at session start |\n| `agent_sessions` | One row per conversation or worker run — holds summary, timestamps, checkpoint state |\n| `agent_messages` | Full message log — durable mid-session, used for crash recovery and audit |\n| Atlas | Strategic platform architect — cross-client, interactive, memory curator for the fleet |\n| `/teach` | Manual memory injection — push a learning into any agent from any session |\n| Atlas curation | Autonomous memory injection — Atlas identifies cross-client patterns, improves agents proactively |\n| Project memory | `agent_memory` rows tagged with `workflow_instance_id` — same table, different filter |\n| Option A → B | Config change in resolver — zero schema or agent code change |"
    }
  ],
  "html_path": "artifacts/2026-04-22-atlas-agent-memory-design-cb2806df3c.html",
  "json_path": "artifacts/2026-04-22-atlas-agent-memory-design-cb2806df3c.json"
}