Atlas + Agent Memory — Design Spec

Date: 2026-04-22 Status: Draft — pending implementation plan Author: Justin King + Claude (brainstorming session)

---

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.

Without 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.

With 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.

This is the investor story: *our agents don't just respond — they build institutional knowledge. The longer they run, the better they get.*

---

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.

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.

Atlas has two capabilities no other agent has:

1. Cross-client visibility — he sees memory and patterns across all deployments (CCOS2, RedKey, new co, and future clients) with no client scoping 2. Memory curation — he can inject learnings directly into other agents' memories, improving the fleet without persona changes or redeployment

Atlas 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.

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.

---

Different agents need different memory. The design is unified (same tables, same retrieval pattern) but scoped per agent type.

| Agent | Personal memory | Project memory | Cross-client? | |---|---|---|---| | Atlas | All platform design history, decisions, architectural patterns | All workflow instances across the portfolio | Yes — that's his job | | Claire | Classification patterns, workflow template selection history | Prior projects for this client | No | | Priya | What specs have worked, what got rejected, successful brief patterns | All prior steps of the current workflow | No | | Vikram | Recurring violations, stack patterns, PR review history | Full project thread — spec, exec approval, Quinn's build | No | | Quinn | How he's solved similar problems, tech debt he's noticed | Spec + exec approval + prior output | No | | Engine | None — deterministic state machine | Already held in workflow_instances | No |

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.

---

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.

```sql -- Enable pgvector create extension if not exists vector;

-- Semantic memory — embedded insights, decisions, patterns, learnings -- NOTE: vector(1536) matches OpenAI text-embedding-3-small / ada-002. -- The embedding model must be chosen before the table is created — the dimension -- is fixed at creation time and cannot be altered without dropping and rebuilding -- the index. Implementation must commit to a model and document it. create table agent_memory ( id uuid primary key default gen_random_uuid(), client_id text not null, agent_id text not null, session_id uuid, content text not null, embedding vector(1536), tags text[], -- e.g. ['pr-review', 'workflow:uuid', 'decision'] created_at timestamptz default now() ); create index on agent_memory using ivfflat (embedding vector_cosine_ops); create index on agent_memory (client_id, agent_id, created_at desc);

-- Sessions — one row per conversation or worker run create table agent_sessions ( id uuid primary key default gen_random_uuid(), client_id text not null, agent_id text not null, summary text, started_at timestamptz default now(), ended_at timestamptz, last_checkpoint timestamptz, metadata jsonb default '{}' ); create index on agent_sessions (client_id, agent_id, started_at desc);

-- Messages — full conversation log (Atlas) or task log (workers) create table agent_messages ( id uuid primary key default gen_random_uuid(), session_id uuid references agent_sessions(id), client_id text not null, agent_id text not null, role text not null, -- 'user' | 'assistant' content text not null, created_at timestamptz default now() ); create index on agent_messages (session_id, created_at); ```

RLS: Worker agents enforce WHERE client_id = ? at the policy level. Atlas uses service-role — no client restriction.

---

Before Claude launches, the context script runs:

1. Embed the opening topic or seed phrase 2. Semantic search: retrieve top-K relevant memories for this agent (+ cross-client for Atlas) 3. Pull last 3 session summaries for recency context 4. If recovering from a crash (session with no ended_at): load raw message log as additional context 5. Assemble context block → write to temp file → pass via --append-system-prompt-file

The agent walks in oriented. No manual loading step. No skill to invoke.

Memory is written continuously, not only at the end:

• 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.
• Every 5–10 turns: checkpoint triggered automatically — extract insights from recent turns, embed, write to agent_memory. last_checkpoint updated on session row.
• 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.

1. Summarize the full session (1 paragraph) → stored in agent_sessions.summary 2. Extract 3–10 discrete insights ("we decided X", "pattern Y recurring on CCOS2", "Atlas flagged Z as technical debt") 3. Embed each insight → insert into agent_memory with tags 4. ended_at written on session row

---

```bash #!/usr/bin/env bash

topic="${1:-}" node scripts/atlas-context.js "$topic" > /tmp/atlas-context.md exec claude \ --append-system-prompt-file definitions/agents/atlas-persona.md \ --append-system-prompt-file /tmp/atlas-context.md \ --add-dir . ```

Shell alias for seamless invocation from anywhere:

``bash alias atlas="~/downloads/cc/projects/redkey/run-architect.sh" ``

atlas → context assembles from Supabase → session opens with full orientation.

---

Agents improve through two mechanisms:

A skill that writes directly to agent_memory for any agent, from any session:

`` /teach vikram "Always verify async error handling coverage before PR approval — Quinn consistently misses this" /teach quinn "Prefer explicit error types over generic catch blocks — Vikram flags this on every review" /teach priya "Specs must include explicit output contracts for every step — Claire needs these to create workflow instances" ``

The 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.

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.