{
  "id": "2026-05-06-backboard-openrouter-memory-strategy-7b68dbe4ff",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-05-06-backboard-openrouter-memory-strategy.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.718Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Backboard, OpenRouter, and RedKey Memory Strategy",
  "summary": "Backboard, OpenRouter, and RedKey Memory Strategy Date: 2026 05 06 Purpose RedKey currently uses several model providers and memory paths directly: Codex, Claude, Gemini, OpenAI embeddings, Supabase agent memory, and tool specific API keys. That works, but it makes model routing, memory continuity, cost control, and agent handoffs harder than they need to be...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Backboard, OpenRouter, and RedKey Memory Strategy",
      "level": 1,
      "body": "Date: 2026-05-06"
    },
    {
      "title": "Purpose",
      "level": 2,
      "body": "RedKey currently uses several model providers and memory paths directly: Codex, Claude, Gemini, OpenAI embeddings, Supabase `agent_memory`, and tool-specific API keys. That works, but it makes model routing, memory continuity, cost control, and agent handoffs harder than they need to be.\n\nThe Backboard founder conversation suggests a stronger architecture:\n\n- Backboard may become the memory and state layer.\n- OpenRouter may become the default model routing layer.\n- Supabase and Hedera should remain the control, registry, and audit layer.\n- Direct provider keys should remain available, but should no longer be the default path for general model calls.\n\nThis document captures the relevant insights, target architecture, and first implementation spike."
    },
    {
      "title": "Memory Is Data",
      "level": 3,
      "body": "Backboard frames memory as data with explicit weighting, not as a vague human-brain metaphor. That fits RedKey better than treating memory as opaque conversational history.\n\nRelevant weighting dimensions from the conversation:\n\n- recency: how recently memory was created or accessed\n- frequency: how often a memory is used\n- adjacency: related topics can affect a memory even when the exact memory is not directly touched\n- temporal resonance: time and relative time affect whether a memory is relevant\n- world-context change: external events can change the relevance or importance of a memory\n\nThis is more advanced than RedKey's current basic vector/recency retrieval model."
    },
    {
      "title": "Assistants As Memory Scopes",
      "level": 3,
      "body": "Backboard's \"assistant\" abstraction is effectively an isolated memory collection. That maps cleanly to RedKey memory slicing:\n\n- one assistant per RedKey agent\n- one assistant per role\n- one assistant per client\n- one assistant per project\n- one assistant per expert/persona\n- one assistant per marketplace expert product\n\nThe key property is isolation. A CPO memory scope should not pollute a dad memory scope; likewise, a Brooke sales memory scope should not pollute a developer-worker memory scope."
    },
    {
      "title": "Memory Modes",
      "level": 3,
      "body": "Backboard supports memory modes that map directly to RedKey execution needs:\n\n- `off`: no memory used; good for isolated worker tasks and deterministic verification\n- `readonly`: retrieve memory without writing new memory; good for controlled agents and review tasks\n- `auto`: read and write memory; good for long-lived agents and expert personas\n\nThis aligns with existing RedKey patterns:\n\n- some agents need full project context\n- some agents need full company context\n- some agents should have no memory beyond the task brief\n- `/teach` should be a controlled write path\n- reflection should produce candidate learnings, not uncontrolled memory sprawl"
    },
    {
      "title": "Stateful OpenRouter",
      "level": 3,
      "body": "OpenRouter routes model calls, but it does not by itself provide durable memory. Each model call is essentially stateless unless the caller includes the right context.\n\nBackboard can sit in front of OpenRouter:\n\n```text\nRedKey agent -> Backboard state/context -> OpenRouter -> chosen model\n```\n\nThat changes the model:\n\n```text\nWithout Backboard:\nClaude has one thread, Kimi has none, DeepSeek has none, Gemini has another.\nEach model switch requires RedKey to rebuild and repack context.\n\nWith Backboard:\nBackboard holds the working state.\nOpenRouter chooses the model.\nThe selected model receives the relevant context for the task.\n```\n\nFor RedKey, this matters because the cluster should be able to use cheaper or specialized models without losing continuity."
    },
    {
      "title": "Adaptive Context Management",
      "level": 3,
      "body": "Backboard claims it can move state across different context windows using indexing and summarization, then reinflate when returning to larger contexts.\n\nThis maps directly to RedKey's biggest pain points:\n\n- long projects\n- headless workers\n- task handoffs\n- context compaction\n- model switching\n- small-context cheap models\n- summarizing without losing important state\n\nThis needs a spike before we trust it, but the capability is strategically relevant."
    },
    {
      "title": "Retrospectives, Skills, And `/teach`",
      "level": 3,
      "body": "Backboard's internal process uses retrospectives to update skill files, version those changes, and inspect regressions when a retrospective worsens behavior.\n\nThis validates RedKey's existing direction:\n\n- reflection stages after large modules\n- `/teach` for controlled memory insertion\n- skill files as durable operating instructions\n- versioned changes to agent behavior\n- review when memory or skill updates cause regressions\n\nThe important distinction is that not every reflection should become durable memory. Reflection should generate candidate learnings. `/teach` or a governed memory write should decide what persists."
    },
    {
      "title": "Data Ownership And Anonymization",
      "level": 3,
      "body": "The founder stated that customer data/memories are segregated and owned by the customer, with anonymization available before context reaches model providers.\n\nThis is highly relevant, but should not be treated as enough for production-sensitive data until confirmed in writing.\n\nRequired due diligence:\n\n- export rights\n- deletion behavior\n- tenant isolation\n- model-provider data exposure\n- anonymization controls\n- retention controls\n- auditability\n- pricing and limits"
    },
    {
      "title": "Expert Marketplace Fit",
      "level": 3,
      "body": "The conversation strongly validated the expert marketplace and \"rent knowledge\" direction.\n\nRelevant patterns:\n\n- digital expert/persona as isolated memory scope\n- vertical expert corpus\n- retired experts contributing tacit knowledge\n- voice/video capture for trades and tacit domain knowledge\n- payment by quality, not only by time\n- expert judges validating knowledge quality\n- marketplace trust through provenance and usage audit\n\nBackboard can potentially provide the memory/RAG substrate. RedKey/Hedera can provide provenance, usage tracking, attribution, and compensation."
    },
    {
      "title": "Current Problem",
      "level": 2,
      "body": "RedKey currently uses provider APIs too directly.\n\nExamples:\n\n- direct OpenAI calls\n- direct Anthropic calls\n- direct Gemini calls\n- direct provider-specific scripts\n- Supabase `agent_memory` direct embedding/retrieval\n- Codex/Claude/Gemini sessions with separate state assumptions\n\nThis creates several problems:\n\n- no consistent task-based model routing\n- no central cost policy\n- no easy model fallback\n- no systematic model benchmarking\n- repeated context packing logic\n- provider-specific drift across scripts\n- hard-to-control memory writes\n- weak model arbitrage\n\nThe issue is not that direct provider keys are bad. The issue is that they should be escape hatches, not the default integration pattern."
    },
    {
      "title": "Target Architecture",
      "level": 2,
      "body": "```text\nRedKey task or agent\n  -> RedKey model gateway\n    -> memory/context policy\n      -> Backboard for stateful memory-aware calls\n        -> OpenRouter for model routing\n      -> direct provider API only for special cases\n    -> Supabase for registry, task state, audit metadata\n    -> Hedera for externalized proof, usage, provenance, and compensation events\n```"
    },
    {
      "title": "Responsibilities",
      "level": 3,
      "body": "RedKey model gateway:\n\n- accepts task class, input, memory mode, client/project/agent scope, cost constraints, and reliability constraints\n- chooses whether the call should use Backboard, direct provider API, or local runtime\n- records model, provider, cost, latency, failure mode, and output metadata\n\nBackboard:\n\n- holds assistant-scoped memory\n- manages readonly/auto/off memory behavior\n- provides stateful conversations over OpenRouter\n- provides document/RAG support if the spike validates it\n- potentially handles adaptive context management\n\nOpenRouter:\n\n- routes model calls\n- enables cheaper model experiments\n- provides model switching without rewriting app code\n- supports fallback and model arbitrage\n\nSupabase:\n\n- remains RedKey's source of truth for tasks, projects, agents, artifacts, and memory/audit metadata\n- stores mappings from RedKey scopes to Backboard assistant IDs\n- stores eval results and routing configuration\n\nHedera:\n\n- remains the external proof layer\n- records provenance, usage, marketplace events, and compensation-relevant events\n\nDirect provider APIs:\n\n- remain available for provider-specific features\n- remain available for local tools like Codex/Claude runtimes\n- remain available if OpenRouter or Backboard is not suitable for a specific use case"
    },
    {
      "title": "Model Routing Policy",
      "level": 2,
      "body": "RedKey should route by task class instead of provider name.\n\nInitial task classes:\n\n- `architecture_review`\n- `code_generation`\n- `code_review`\n- `test_repair`\n- `cheap_extraction`\n- `summarization`\n- `long_context_analysis`\n- `classification`\n- `embedding`\n- `memory_retrieval`\n- `reflection`\n- `teach_candidate_generation`\n\nExample configuration shape:\n\n```yaml\nmodel_routes:\n  architecture_review:\n    memory_mode: readonly\n    primary: anthropic/claude-sonnet-4.5\n    fallback: openai/gpt-5.4\n    max_cost_usd: 5.00\n\n  cheap_extraction:\n    memory_mode: off\n    primary: deepseek/deepseek-chat\n    fallback: qwen/qwen-plus\n    max_cost_usd: 0.25\n\n  code_worker:\n    memory_mode: readonly\n    primary: moonshotai/kimi-k2\n    fallback: openai/gpt-5.3-codex\n    max_cost_usd: 2.00\n\n  expert_persona_chat:\n    memory_mode: auto\n    primary: openrouter/auto\n    state_provider: backboard\n```\n\nSpecific model names should be verified at implementation time because OpenRouter availability changes. The stable design is the route abstraction, not the initial model roster."
    },
    {
      "title": "Memory Scope Model",
      "level": 2,
      "body": "Backboard assistant IDs should be mapped from RedKey scopes.\n\nSuggested scope keys:\n\n```text\nclient:{client_id}\nproject:{project_id}\nagent:{agent_id}\nrole:{role_id}\nexpert:{expert_id}\nworkflow:{workflow_instance_id}\ntask:{task_id}\n```\n\nNot all scopes need Backboard memory.\n\nDefault policy:\n\n- short-lived worker task: memory `off` or `readonly`\n- reviewer: memory `readonly`\n- architect/Atlas: memory `readonly` by default, controlled writes through `/teach`\n- long-running expert persona: memory `auto`\n- marketplace expert: memory `auto` inside that expert's isolated assistant scope\n- regulated/sensitive data: memory `off` until Backboard controls are confirmed"
    },
    {
      "title": "Backboard Spike",
      "level": 2,
      "body": "The next build should not be the Backboard docs MCP. The next build should be a memory/state spike."
    },
    {
      "title": "Spike Goals",
      "level": 3,
      "body": "Validate whether Backboard can serve as RedKey's memory/context layer."
    },
    {
      "title": "Spike Tasks",
      "level": 3,
      "body": "1. Add Doppler secrets:\n   - `BACKBOARD_API_KEY` already exists in `bezel/prd`.\n   - Add OpenRouter key if not already present.\n\n2. Create a small Backboard client:\n   - authenticate with `X-API-Key`\n   - create or identify assistant\n   - send message with memory `off`, `readonly`, and `auto`\n   - add/list/search/delete memories\n   - inspect retrieved memories when available\n\n3. Create a RedKey provider interface:\n   - `MemoryProvider`\n   - `ModelProvider`\n   - `BackboardMemoryProvider`\n   - `OpenRouterModelProvider`\n\n4. Run controlled evals:\n   - memory write and retrieval\n   - memory isolation between assistants\n   - readonly mode does not write\n   - off mode does not retrieve or write\n   - OpenRouter model switch preserves useful state through Backboard\n   - small-context model receives sufficient context\n   - latency and cost are acceptable\n\n5. Compare against current Supabase `agent_memory`:\n   - retrieval relevance\n   - inspectability\n   - write control\n   - deletion/export\n   - latency\n   - cost\n   - operational complexity"
    }
  ],
  "html_path": "artifacts/2026-05-06-backboard-openrouter-memory-strategy-7b68dbe4ff.html",
  "json_path": "artifacts/2026-05-06-backboard-openrouter-memory-strategy-7b68dbe4ff.json"
}