Multi-Agent Shared Memory

Architecture Overview

Three layers, each building on the previous:

Layer 1: Shared Fact Log      — append-only discoveries, real-time sync
Layer 2: Yjs CRDT Scratchpad  — collaborative working document
Layer 3: Reconciliation       — LLM-powered canonical fact extraction

All layers scope by session_id (coordination session). Only agents in the same session share memory.

Layer 1: Shared Fact Log

Append-only table of agent discoveries. No CRDT, no merge — pure append.

CREATE TABLE shared_facts (
  id TEXT PRIMARY KEY,
  session_id TEXT NOT NULL,
  agent_id TEXT NOT NULL,
  content TEXT NOT NULL,
  fact_type TEXT NOT NULL CHECK (fact_type IN (
    'discovery', 'bug', 'decision', 'warning', 'question', 'answer'
  )),
  confidence REAL NOT NULL DEFAULT 1.0,
  tags JSONB NOT NULL DEFAULT '[]',
  source_ref JSONB,
  superseded_by TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Write path: agent publishes via REST API -> DB insert -> Electric syncs to subscribers.

// Publishing a fact
await fetch('/api/sync/shared-facts', {
  method: 'POST',
  body: JSON.stringify({
    session_id: 'coord-abc123',
    agent_id: 'claude-1',
    content: 'auth module has race condition in session refresh',
    fact_type: 'bug',
    confidence: 0.9,
    tags: ['auth', 'concurrency'],
    source_ref: { file: 'src/auth/session.ts', line: 42 },
  }),
});

Read path (React): subscribe via Electric shape.

function useSharedFacts(sessionId: string) {
  const { data, isLoading } = useShape({
    url: `${proxyBaseUrl}/api/shapes/shared-facts`,
    params: { session_id: sessionId },
  });
  return { facts: data, isLoading };
}

Read path (CLI agents): poll via daemon RPC or direct API call.

Layer 2: Yjs CRDT Scratchpad

Multiple agents concurrently edit a shared document. Browser agents use WebSocket Yjs collab. CLI agents submit structured patches applied server-side.

Patch Types

Structured Patch (CLI Agents)

await fetch('/api/sync/yjs-document-patches', {
  method: 'POST',
  body: JSON.stringify({
    document_id: 'scratchpad-task-42',
    agent_id: 'claude-2',
    patch_type: 'append_item',
    path: 'findings',
    content: 'Database index missing on user_id column',
  }),
});

Server-side: loads Y.Doc state, applies patch, saves updated state. Electric fans out.

Server-Side Patch Application

import * as Y from 'yjs';

function applyPatch(doc: Y.Doc, patchType: string, path: string, content: string) {
  const root = doc.getMap('root');
  switch (patchType) {
    case 'set_key':
      root.set(path, content);
      break;
    case 'append_section': {
      let section = root.get(path);
      if (!(section instanceof Y.Text)) {
        section = new Y.Text();
        root.set(path, section);
      }
      section.insert(section.length, content);
      break;
    }
    case 'append_item': {
      let arr = root.get(path);
      if (!(arr instanceof Y.Array)) {
        arr = new Y.Array();
        root.set(path, arr);
      }
      arr.push([content]);
      break;
    }
    case 'replace_section': {
      const text = new Y.Text();
      text.insert(0, content);
      root.set(path, text);
      break;
    }
  }
}

Layer 3: Reconciliation

Periodic or on-demand LLM pass that reads the fact log, resolves contradictions, deduplicates, and produces canonical memories.

Extending Existing Memory Tables

ALTER TABLE agent_memories ADD COLUMN scope TEXT DEFAULT 'private';
-- Values: 'private' (single agent), 'shared' (session-wide), 'reconciled' (LLM-verified)
ALTER TABLE agent_memories ADD COLUMN session_scope TEXT;
ALTER TABLE agent_memories ADD COLUMN source_facts JSONB DEFAULT '[]';
ALTER TABLE agent_memories ADD COLUMN reconciled_at TIMESTAMPTZ;

Reconciliation Process

1. Query unreconciled facts (where superseded_by IS NULL)
2. Group related facts by tags, source references, semantic similarity
3. LLM prompt: determine canonical truths, contradictions, duplicates
4. Create scope = 'reconciled' memories with source_facts references
5. Mark source facts as superseded_by the new reconciled memory

Heuristic Fallback (No LLM)

Normalize content, deduplicate by exact match, keep highest confidence per group.

CLI vs Browser Agent Paths

Session Scoping

All memory is scoped by coordination session ID. When agents start a shared task:

1. Generate or reuse a session ID (e.g., coord-{taskId})
2. All fact publications include this session ID
3. Shape subscriptions filter by session ID
4. Reconciliation processes one session at a time

Session order

Same shape as the control layer. A session names the native store first, then the vendor.

1. Knowledge graph (revealui.memory.v1) is the durable product memory.
2. The vendor adapter is a pointer. Grok [memory], Claude ~/.claude memory files, and any other vendor home do not become a second durable store.
3. revealui-harnesses session adapter <vendor> prints that order and does not query the graph.
4. An operator who wants the read passes --memory. That calls queryDurableMemory and continues if the graph is down. Session hooks do not pass --memory.

Durable vs working vs session facts

Keep these names distinct. Do not proxy memory_publish_fact into kg_add_episode (that ingest is a later graph phase, not this skill).