ctx0 — Persistent Memory

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│   Full vault:     Agent → ctx0_remember → DB write → curator agent →       │
│                   vault tree → embedding queue → DB read → vector search   │
│                   → agent                                                  │
│                   (6 hops, 2 subagents, network I/O, DB costs)             │
│                                                                             │
│   This system:    Agent → db.insert() → done                               │
│                   Session start → load summary (~300 tokens)               │
│                   Need details? → FTS5 search (<1ms)                       │
│                   (2 tools, 0 subagents, local disk only)                  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                       PERSISTENT MEMORY SYSTEM                              │
│                                                                             │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │                        MAIN AGENT                                    │   │
│   │   bot0 daemon │ Claude Code │ Cursor │ any agent                    │   │
│   │                                                                      │   │
│   │   Tools:                                                             │   │
│   │   ├── memory_save(content, tags?, pin?)                             │   │
│   │   └── memory_search(query, tags?, project?)                         │   │
│   │                                                                      │   │
│   │   Auto-injected at session start:                                    │   │
│   │   └── <memory> block in system prompt (summary + pinned entries)    │   │
│   │                                                                      │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                         │                       │                           │
│            Local disk   │                       │  Haiku (background)       │
│                         ▼                       ▼                           │
│   ┌──────────────────────────┐   ┌──────────────────────────────────┐     │
│   │  LOCAL SQLITE STORAGE     │   │  AI SUMMARIZATION (async)        │     │
│   │                           │   │                                  │     │
│   │  ~/.bot0/memory.db        │   │  Triggered by:                   │     │
│   │                           │   │  • Entry count threshold (20+)   │     │
│   │  ┌─────────────────────┐ │   │  • Session end                   │     │
│   │  │ memories             │ │   │  • Session start (catch-up)      │     │
│   │  │ memories_fts (FTS5)  │ │   │  • Periodic interval (5 min)     │     │
│   │  │ memory_summaries     │ │   │  • Daily compaction cron         │     │
│   │  │ sync_meta            │ │   │  • Auto-save hooks (bus event)   │     │
│   │  └─────────────────────┘ │   │  Cost: ~$0.0001/summary (Haiku)  │     │
│   │                           │   │  Fallback: load raw if fails     │     │
│   │  WAL mode, <1ms r/w      │   └──────────────────────────────────┘     │
│   └────────────┬─────────────┘                                             │
│                │                                                            │
│                │  Cloud sync (fire-and-forget push, session-start pull)     │
│                ▼                                                            │
│   ┌──────────────────────────────────────────────────────────────────┐     │
│   │  SUPABASE: ctx0_memories (optional, multi-daemon sync)            │     │
│   │                                                                    │     │
│   │  Daemon A (laptop) ──push──▶ ctx0_memories ◀──push── Daemon B    │     │
│   │  Daemon A ◀──pull (session start)──▶ Daemon B                    │     │
│   │                                                                    │     │
│   │  • Row-level sync (append-only, nanoid PKs = no conflicts)       │     │
│   │  • Memories sync bidirectionally; summaries stay local-only       │     │
│   │  • Graceful degradation: unauthenticated → local-only mode       │     │
│   └──────────────────────────────────────────────────────────────────┘     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

CREATE TABLE memories (
  id TEXT PRIMARY KEY,                        -- nanoid (e.g., "m_a1b2c3")
  content TEXT NOT NULL,                      -- The memory itself (natural language)
  tags TEXT NOT NULL DEFAULT '[]',            -- JSON array of strings
  source TEXT NOT NULL DEFAULT 'agent',       -- 'user' | 'agent' | 'auto'
  project TEXT,                               -- Project context (null = global)
  pinned INTEGER NOT NULL DEFAULT 0,          -- 1 = always load into context
  superseded_by TEXT,                         -- ID of newer version (soft-update)
  summarized INTEGER NOT NULL DEFAULT 0,      -- 1 = included in a summary
  created_at TEXT NOT NULL DEFAULT (datetime('now'))  -- ISO 8601
);

-- Loading: pinned memories (always loaded first)
CREATE INDEX idx_memories_pinned ON memories(pinned, created_at DESC)
  WHERE pinned = 1 AND superseded_by IS NULL;

-- Loading: recent active memories
CREATE INDEX idx_memories_active ON memories(created_at DESC)
  WHERE superseded_by IS NULL;

-- Loading: project-specific memories
CREATE INDEX idx_memories_project ON memories(project, created_at DESC)
  WHERE project IS NOT NULL AND superseded_by IS NULL;

-- Summarization: unsummarized entries
CREATE INDEX idx_memories_unsummarized ON memories(created_at ASC)
  WHERE summarized = 0 AND superseded_by IS NULL;

-- Search: by source
CREATE INDEX idx_memories_source ON memories(source);

-- FTS5 virtual table for content search
CREATE VIRTUAL TABLE memories_fts USING fts5(
  content,
  content=memories,
  content_rowid=rowid
);

-- Keep FTS in sync with triggers
CREATE TRIGGER memories_ai AFTER INSERT ON memories BEGIN
  INSERT INTO memories_fts(rowid, content) VALUES (new.rowid, new.content);
END;

CREATE TRIGGER memories_ad AFTER DELETE ON memories BEGIN
  INSERT INTO memories_fts(memories_fts, rowid, content)
    VALUES ('delete', old.rowid, old.content);
END;

CREATE TRIGGER memories_au AFTER UPDATE ON memories BEGIN
  INSERT INTO memories_fts(memories_fts, rowid, content)
    VALUES ('delete', old.rowid, old.content);
  INSERT INTO memories_fts(rowid, content) VALUES (new.rowid, new.content);
END;

CREATE TABLE memory_summaries (
  id TEXT PRIMARY KEY,                        -- nanoid (e.g., "ms_x7y8z9")
  type TEXT NOT NULL DEFAULT 'incremental',   -- 'incremental' | 'compacted'
  summary TEXT NOT NULL,                      -- AI-generated summary text
  entry_count INTEGER NOT NULL,               -- How many entries/summaries were summarized
  entry_ids TEXT NOT NULL DEFAULT '[]',        -- JSON array of memory IDs included
  period_start TEXT NOT NULL,                  -- Earliest entry timestamp
  period_end TEXT NOT NULL,                    -- Latest entry timestamp
  created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE INDEX idx_summaries_type ON memory_summaries(type, created_at DESC);
CREATE INDEX idx_summaries_period ON memory_summaries(period_end DESC);

CREATE TABLE sync_meta (
  key TEXT PRIMARY KEY,                          -- 'last_sync_ts', 'device_id'
  value TEXT NOT NULL
);

import Database from 'better-sqlite3';
import { join } from 'path';
import { homedir } from 'os';

const DB_PATH = join(homedir(), '.bot0', 'memory.db');

function initMemoryDb(): Database.Database {
  const db = new Database(DB_PATH);

  // WAL mode for better concurrent read/write performance
  db.pragma('journal_mode = WAL');

  // Run schema creation (idempotent)
  db.exec(`
    CREATE TABLE IF NOT EXISTS memories (
      id TEXT PRIMARY KEY,
      content TEXT NOT NULL,
      tags TEXT NOT NULL DEFAULT '[]',
      source TEXT NOT NULL DEFAULT 'agent',
      project TEXT,
      pinned INTEGER NOT NULL DEFAULT 0,
      superseded_by TEXT,
      summarized INTEGER NOT NULL DEFAULT 0,
      created_at TEXT NOT NULL DEFAULT (datetime('now'))
    );

    CREATE INDEX IF NOT EXISTS idx_memories_pinned ON memories(pinned, created_at DESC)
      WHERE pinned = 1 AND superseded_by IS NULL;
    CREATE INDEX IF NOT EXISTS idx_memories_active ON memories(created_at DESC)
      WHERE superseded_by IS NULL;
    CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project, created_at DESC)
      WHERE project IS NOT NULL AND superseded_by IS NULL;
    CREATE INDEX IF NOT EXISTS idx_memories_unsummarized ON memories(created_at ASC)
      WHERE summarized = 0 AND superseded_by IS NULL;
    CREATE INDEX IF NOT EXISTS idx_memories_source ON memories(source);

    CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
      content, content=memories, content_rowid=rowid
    );

    CREATE TABLE IF NOT EXISTS memory_summaries (
      id TEXT PRIMARY KEY,
      type TEXT NOT NULL DEFAULT 'incremental',
      summary TEXT NOT NULL,
      entry_count INTEGER NOT NULL,
      entry_ids TEXT NOT NULL DEFAULT '[]',
      period_start TEXT NOT NULL,
      period_end TEXT NOT NULL,
      created_at TEXT NOT NULL DEFAULT (datetime('now'))
    );
    CREATE INDEX IF NOT EXISTS idx_summaries_type
      ON memory_summaries(type, created_at DESC);
    CREATE INDEX IF NOT EXISTS idx_summaries_period
      ON memory_summaries(period_end DESC);

    CREATE TABLE IF NOT EXISTS sync_meta (
      key TEXT PRIMARY KEY,
      value TEXT NOT NULL
    );
  `);

  return db;
}

~/.bot0/
├── config.json       # Existing daemon config
└── memory.db         # SQLite database (single file)

User: "Remember that the deploy key for staging is in 1Password under 'staging-deploy'"
Agent: [calls memory_save]
→ INSERT into memories: { content: "...", source: "user", tags: ["infra", "credentials"] }

Agent: [reading code, discovers unconventional pattern]
Agent: [calls memory_save]
→ INSERT: { content: "bot0 wraps Drizzle in OrmClient (packages/db/orm.ts)...",
            source: "agent", tags: ["codebase", "pattern"] }

LOAD_MEMORY_CONTEXT(project):

  blocks = []

  ── Phase 1: Pinned memories (always loaded, raw content) ──────────

  pinned = SELECT id, content, tags, created_at
           FROM memories
           WHERE pinned = 1
             AND superseded_by IS NULL
           ORDER BY created_at DESC

  for entry in pinned:
    blocks.push({ section: "pinned", content: entry.content })

  ── Phase 2: Latest compacted summary (big picture) ────────────────

  compacted = SELECT summary FROM memory_summaries
              WHERE type = 'compacted'
              ORDER BY created_at DESC
              LIMIT 1

  if compacted:
    blocks.push({ section: "context", content: compacted.summary })

  ── Phase 3: Incremental summaries since last compaction ───────────

  incrementals = SELECT summary FROM memory_summaries
                 WHERE type = 'incremental'
                   AND created_at > COALESCE(
                     (SELECT MAX(created_at) FROM memory_summaries WHERE type = 'compacted'),
                     '1970-01-01'
                   )
                 ORDER BY created_at DESC

  for s in incrementals:
    blocks.push({ section: "recent", content: s.summary })

  ── Phase 4: Unsummarized entries (newest, not yet in any summary) ─

  unsummarized = SELECT id, content, created_at
                 FROM memories
                 WHERE summarized = 0
                   AND superseded_by IS NULL
                   AND pinned = 0
                 ORDER BY created_at DESC
                 LIMIT 10

  if unsummarized.length > 0:
    blocks.push({ section: "latest", content: format_entries(unsummarized) })

  RETURN format_memory_block(blocks)

<memory>
You have persistent memory from previous sessions.

## Pinned
- Deploy key for staging is in 1Password under 'staging-deploy' [2026-01-15]
- User prefers Bun over Node for new TypeScript projects [2026-01-20]

## Context
The user works on bot0, a local-first AI agent system using pnpm workspaces with
Turborepo. The daemon is the core component. Authentication uses hardware-bound
device keys via Secure Enclave/TPM 2.0. The project uses Drizzle ORM for database
schema management with Supabase PostgreSQL. The user prefers TypeScript strict mode
and monospace terminal aesthetics.

## Recent
Last few sessions focused on designing a persistent memory system for the daemon.
Evaluated flat memory log vs git-like context controller approaches. Decided on a
hybrid: flat log simplicity with AI summary priming. SQLite with FTS5 for search.

## Latest (not yet summarized)
- ctx0-persistent-memory.md spec finalized with hybrid approach [2026-02-26]
- Summarization triggers: entry threshold, session end, session start catch-up,
  periodic interval, daily compaction cron [2026-02-26]
</memory>

if no summaries exist:
  load pinned (up to 1000 tokens)
  load recent entries (up to 2000 tokens)
  load project entries (up to 500 tokens)
  total: up to ~3500 tokens (one-time cost until first summarization runs)

interface MemorySaveTool {
  name: 'memory_save';
  description: 'Save information to your persistent memory. Use when you learn something worth remembering across sessions: user preferences, project patterns, environmental facts, surprising discoveries, or anything the user explicitly asks you to remember.';
  parameters: {
    /** The memory content. Clear, concise, standalone. Max 2000 chars. */
    content: string;
    /** Tags for categorization: "preference", "codebase", "contact", "infra", "decision", "pattern", "debug" */
    tags?: string[];
    /** Pin to always load into context. Use sparingly — pinned entries consume budget every session. */
    pin?: boolean;
  };
}

import { nanoid } from 'nanoid';

const insertStmt = db.prepare(`
  INSERT INTO memories (id, content, tags, source, project, pinned, created_at)
  VALUES (?, ?, ?, ?, ?, ?, datetime('now'))
`);

function memorySave(params: {
  content: string;
  tags?: string[];
  pin?: boolean;
}, context: { source: 'user' | 'agent' | 'auto'; project?: string }): string {
  const { content, tags = [], pin = false } = params;

  // Enforce max content length (~500 tokens ≈ ~2000 chars)
  if (content.length > 2000) {
    return 'Memory too long. Keep under ~500 tokens (2000 chars). Be more concise.';
  }

  const id = `m_${nanoid(6)}`;

  insertStmt.run(
    id,
    content.trim(),
    JSON.stringify(tags),
    context.source,
    context.project ?? null,
    pin ? 1 : 0,
  );

  // Check if summarization should trigger (entry count threshold)
  checkSummarizationTrigger();

  return `Saved${pin ? ' (pinned)' : ''}: "${content.slice(0, 60)}..."`;
}

interface MemorySearchTool {
  name: 'memory_search';
  description: 'Search your memory for specific information. Use when the summary in your context doesn\'t contain what you need — this searches raw entries for exact details.';
  parameters: {
    /** Search query — natural language or keywords */
    query: string;
    /** Filter by tags */
    tags?: string[];
    /** Filter by project */
    project?: string;
    /** Maximum results (default 10) */
    limit?: number;
  };
}

const ftsSearchStmt = db.prepare(`
  SELECT m.id, m.content, m.tags, m.created_at
  FROM memories m
  JOIN memories_fts fts ON m.rowid = fts.rowid
  WHERE memories_fts MATCH ?
    AND m.superseded_by IS NULL
  ORDER BY rank
  LIMIT ?
`);

const keywordSearchStmt = db.prepare(`
  SELECT id, content, tags, created_at
  FROM memories
  WHERE content LIKE ?
    AND superseded_by IS NULL
  ORDER BY created_at DESC
  LIMIT ?
`);

function memorySearch(params: {
  query: string;
  tags?: string[];
  project?: string;
  limit?: number;
}): string {
  const { query, tags, project, limit = 10 } = params;

  // Try FTS5 first (handles phrases, boolean operators, ranking)
  let results: MemoryRow[];
  try {
    results = ftsSearchStmt.all(query, limit);
  } catch {
    // FTS5 syntax error (e.g., unbalanced quotes) — fallback to LIKE
    results = keywordSearchStmt.all(`%${query}%`, limit);
  }

  // Post-filter by tags and project (small result set, fast in JS)
  if (tags?.length) {
    results = results.filter(r => {
      const entryTags: string[] = JSON.parse(r.tags);
      return tags.some(t => entryTags.includes(t));
    });
  }
  if (project) {
    results = results.filter(r => r.project === project);
  }

  if (results.length === 0) {
    return 'No memories found matching your search.';
  }

  return results.map(r => {
    const entryTags: string[] = JSON.parse(r.tags);
    return `- ${r.content} [${entryTags.join(', ')}] (${r.created_at.slice(0, 10)})`;
  }).join('\n');
}

┌─────────────────────────────────────────────────────────────────┐
│                    MEMORY WRITE PATH                              │
│                                                                   │
│   Any save trigger                                               │
│   → Build MemoryEntry object                                     │
│   → db.prepare(INSERT).run(...)              (<1ms, local)       │
│   → FTS5 trigger auto-updates search index   (<1ms, local)       │
│   → Check summarization trigger              (entry count check)  │
│   → Push to cloud (fire-and-forget)          (non-blocking)      │
│   → Done. <1ms locally. Cloud push is async.                     │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    MEMORY READ PATH                               │
│                                                                   │
│   New conversation starts                                        │
│   → Pull new memories from cloud (other daemons' writes)        │
│     (INSERT OR IGNORE into local SQLite, ~50-150ms)             │
│   → Check for unsummarized entries from crashed sessions         │
│     (self-healing catch-up — summarize if needed)                │
│   → Load pinned entries (raw content)                            │
│   → Load latest compacted summary                                │
│   → Load incremental summaries since last compaction             │
│   → Load any unsummarized entries (raw, newest)                  │
│   → Format into <memory> block string                            │
│   → Inject into system prompt                                    │
│   → Done. ~300-500 tokens.                                       │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

const supersedeTx = db.transaction((oldId: string, newContent: string, project?: string) => {
  const old = db.prepare('SELECT * FROM memories WHERE id = ?').get(oldId);
  if (!old) return;

  const newId = `m_${nanoid(6)}`;

  // Insert replacement
  insertStmt.run(newId, newContent, old.tags, 'agent', project ?? old.project, old.pinned);

  // Mark old as superseded
  db.prepare('UPDATE memories SET superseded_by = ? WHERE id = ?').run(newId, oldId);
});

const SUMMARIZE_THRESHOLD = 20;

function checkSummarizationTrigger(): void {
  const { count } = db.prepare(`
    SELECT COUNT(*) as count FROM memories
    WHERE summarized = 0 AND superseded_by IS NULL
  `).get() as { count: number };

  if (count >= SUMMARIZE_THRESHOLD) {
    // Run async — don't block the conversation
    summarizeEntries().catch(err =>
      console.error('[memory] Summarization failed:', err)
    );
  }
}

async function onSessionEnd(sessionId: string): Promise<void> {
  try {
    const { count } = db.prepare(`
      SELECT COUNT(*) as count FROM memories
      WHERE summarized = 0 AND superseded_by IS NULL
    `).get() as { count: number };

    if (count > 0) {
      await summarizeEntries();
      console.log(`[memory] Summarized ${count} entries at session end`);
    }
  } catch (err) {
    // Non-fatal — log but don't break session cleanup
    console.error('[memory] Session-end summarization failed:', err);
  }
}

async function onSessionStart(): Promise<void> {
  const { count } = db.prepare(`
    SELECT COUNT(*) as count FROM memories
    WHERE summarized = 0 AND superseded_by IS NULL
  `).get() as { count: number };

  // If there are unsummarized entries older than the latest summary,
  // a previous session likely crashed before summarizing
  if (count > SUMMARIZE_THRESHOLD) {
    console.log(`[memory] Catch-up: ${count} unsummarized entries from previous session`);
    await summarizeEntries();
  }
}

const SUMMARIZE_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes

let summarizeTimer: NodeJS.Timeout | null = null;

function startPeriodicSummarization(): void {
  summarizeTimer = setInterval(async () => {
    const { count } = db.prepare(`
      SELECT COUNT(*) as count FROM memories
      WHERE summarized = 0 AND superseded_by IS NULL
    `).get() as { count: number };

    if (count > 0) {
      await summarizeEntries();
    }
  }, SUMMARIZE_INTERVAL_MS);
}

function stopPeriodicSummarization(): void {
  if (summarizeTimer) {
    clearInterval(summarizeTimer);
    summarizeTimer = null;
  }
}

async function dailyCompaction(): Promise<void> {
  // Get all incremental summaries older than 24 hours
  const incrementals = db.prepare(`
    SELECT id, summary, entry_count, period_start, period_end
    FROM memory_summaries
    WHERE type = 'incremental'
      AND created_at < datetime('now', '-1 day')
    ORDER BY created_at ASC
  `).all() as SummaryRow[];

  if (incrementals.length < 2) return; // Nothing to compact

  // AI-summarize the incremental summaries into one compacted summary
  const compactedText = await generateCompactionSummary(
    incrementals.map(s => s.summary)
  );

  const totalEntries = incrementals.reduce((sum, s) => sum + s.entry_count, 0);
  const periodStart = incrementals[0].period_start;
  const periodEnd = incrementals[incrementals.length - 1].period_end;

  // Atomic: insert compacted + delete old incrementals
  const compactTx = db.transaction(() => {
    db.prepare(`
      INSERT INTO memory_summaries (id, type, summary, entry_count, entry_ids, period_start, period_end)
      VALUES (?, 'compacted', ?, ?, '[]', ?, ?)
    `).run(`ms_${nanoid(6)}`, compactedText, totalEntries, periodStart, periodEnd);

    const ids = incrementals.map(s => s.id);
    db.prepare(`
      DELETE FROM memory_summaries WHERE id IN (${ids.map(() => '?').join(',')})
    `).run(...ids);
  });

  compactTx();
  console.log(`[memory] Compacted ${incrementals.length} summaries into 1`);
}

async function generateIncrementalSummary(
  entries: Array<{ content: string; tags: string[]; source: string }>
): Promise<string> {
  const entryText = entries
    .map((e, i) => `${i + 1}. ${e.content}`)
    .join('\n');

  const response = await haiku.messages.create({
    model: 'claude-haiku-4-5-20251001',
    max_tokens: 300,
    messages: [{
      role: 'user',
      content: `Summarize these memories into a concise paragraph (2-5 sentences). Preserve key facts, decisions, and preferences. Drop redundancies. Write in third person present tense ("The user prefers...", "The project uses...").

Memories:
${entryText}

Summary:`,
    }],
  });

  return response.content[0].text.trim();
}

async function generateCompactionSummary(
  summaries: string[]
): Promise<string> {
  const summaryText = summaries
    .map((s, i) => `${i + 1}. ${s}`)
    .join('\n\n');

  const response = await haiku.messages.create({
    model: 'claude-haiku-4-5-20251001',
    max_tokens: 500,
    messages: [{
      role: 'user',
      content: `Merge these incremental memory summaries into a single comprehensive summary. Preserve all key facts, preferences, and decisions. Remove duplicates. Resolve any contradictions (prefer more recent information). Write in third person present tense. Keep it concise but complete.

Summaries to merge:
${summaryText}

Merged summary:`,
    }],
  });

  return response.content[0].text.trim();
}

async function summarizeEntries(): Promise<void> {
  // Get unsummarized entries
  const entries = db.prepare(`
    SELECT id, content, tags, source, created_at
    FROM memories
    WHERE summarized = 0 AND superseded_by IS NULL
    ORDER BY created_at ASC
  `).all() as MemoryRow[];

  if (entries.length === 0) return;

  // Generate AI summary
  const summary = await generateIncrementalSummary(
    entries.map(e => ({
      content: e.content,
      tags: JSON.parse(e.tags),
      source: e.source,
    }))
  );

  const entryIds = entries.map(e => e.id);
  const periodStart = entries[0].created_at;
  const periodEnd = entries[entries.length - 1].created_at;

  // Atomic: insert summary + mark entries as summarized
  const summarizeTx = db.transaction(() => {
    db.prepare(`
      INSERT INTO memory_summaries (id, type, summary, entry_count, entry_ids, period_start, period_end)
      VALUES (?, 'incremental', ?, ?, ?, ?, ?)
    `).run(`ms_${nanoid(6)}`, summary, entries.length, JSON.stringify(entryIds), periodStart, periodEnd);

    db.prepare(`
      UPDATE memories SET summarized = 1
      WHERE id IN (${entryIds.map(() => '?').join(',')})
    `).run(...entryIds);
  });

  summarizeTx();
  console.log(`[memory] Summarized ${entries.length} entries`);
}

SESSION START
│
├─ Pull new memories from cloud (other daemons' writes)
│  → SELECT WHERE synced_at > last_sync_ts
│  → INSERT OR IGNORE into local SQLite
│  → Trigger summarization catch-up if new entries arrived
│
├─ SQLite query: load summaries + pinned entries
│  → inject ~300-500 tokens into <memory> system prompt
│  → agent starts with "big picture" context (includes other daemons' knowledge)
│
MID-CONVERSATION (on demand)
│
├─ Agent calls memory_save("user wants dark mode in all UIs")
│  → SQLite INSERT into memories (<1ms)
│  → FTS5 index auto-updated (SQLite trigger)
│  → Check entry count threshold → maybe trigger summarization
│  → Push to cloud (fire-and-forget, non-blocking)
│
├─ Agent calls memory_search("dark mode preference")
│  → FTS5 MATCH query → returns ranked raw entries (<1ms)
│  → Agent sees actual content, high fidelity
│
BACKGROUND (async, non-blocking)
│
├─ Summarization triggers (entry threshold / timer / session end)
│  → Read unsummarized entries from SQLite
│  → Send to Haiku for summary generation (~500-2000ms)
│  → INSERT summary + mark entries as summarized (atomic transaction)
│
SESSION END
│
├─ Final summarization of remaining unsummarized entries
│  → Next session loads fresh summary
│
DAILY (cron)
│
├─ Compaction: roll up incremental summaries into one compacted summary
│  → Keeps context loading bounded regardless of history length

## Memory

You have persistent memory stored locally on this machine. A summary of what you've learned is shown in the <memory> block above.

### When to save memories

Save a memory when you encounter:
- **User requests**: "Remember that...", "Save this for later", "Don't forget..."
- **User preferences**: Implicit or explicit (coding style, tools, communication)
- **Surprising facts**: Information that contradicts assumptions or is non-obvious
- **Project patterns**: Codebase conventions, architecture decisions, deploy configs
- **People info**: Names, roles, preferences, relationships
- **Resolutions**: How a tricky problem was solved (error + fix)
- **Environment**: API endpoints, config locations, access patterns

### When NOT to save
- Transient information (temp debugging steps, one-off commands)
- Information already in the codebase (README content, code comments)
- Obvious facts any LLM would know
- Duplicate of something already in your <memory>

### How to write good memories
- Clear, standalone sentences — useful without the original conversation
- Specific: "User prefers Bun over Node for new TS projects" not "User likes Bun"
- Include the 'why' when relevant: "Chose Supabase over Firebase for pgvector support"
- Tag appropriately: preference, codebase, contact, infra, decision, pattern, debug

### Using your memories
- Check <memory> before asking the user things you might already know
- If the summary doesn't have what you need, use memory_search for exact details
- When you notice a memory is outdated, save a corrected version

Session completes → SessionStateChanged event (bus)
                          │
                    hooks.ts subscriber
                          │
              ┌───────────┼───────────┐
              │           │           │
              ▼           ▼           ▼
        Task Summary  Correction  Error Resolution
         (Haiku)      (Haiku)     (heuristic+Haiku)
              │           │           │
              ▼           ▼           ▼
           insertMemory(source: 'auto')
              │
              ▼
        checkSummarizationTrigger()

export interface AutoSaveHookDeps {
  getSessionManager: () => SessionManager | null;
  getSigningProvider: () => SigningProvider | null;
  getConfig: () => DaemonConfig;
}

initAutoSaveHooks({
  getSessionManager: () => this.getOrCreateSessionManager(),
  getSigningProvider: () => this.signingProvider,
  getConfig: () => loadConfig(),
});

┌──────────────────────────────────────────────────────────────────────────┐
│                        MULTI-DAEMON CLOUD SYNC                            │
│                                                                           │
│   DAEMON A (laptop)                    DAEMON B (desktop)                │
│   ~/.bot0/memory.db                    ~/.bot0/memory.db                 │
│                                                                           │
│   memory_save("user prefers Bun")      memory_save("deploy key in 1PW")  │
│        │                                       │                         │
│        │ 1. INSERT locally (<1ms)              │ 1. INSERT locally       │
│        │ 2. Push to cloud (fire & forget)      │ 2. Push to cloud        │
│        ▼                                       ▼                         │
│   ┌──────────────────────────────────────────────────────┐               │
│   │           Supabase: ctx0_memories                     │               │
│   │                                                       │               │
│   │  id       │ content                    │ synced_at    │               │
│   │  m_a1b2c3 │ "user prefers Bun"         │ 2026-02-27   │               │
│   │  m_x7y8z9 │ "deploy key in 1PW"        │ 2026-02-27   │               │
│   │                                                       │               │
│   │  Proxy auto-injects user_id on all queries           │               │
│   └──────────────────────────────────────────────────────┘               │
│        │                                       │                         │
│        │ 3. Pull on session start              │ 3. Pull on session start│
│        │    (WHERE synced_at > last_sync_ts)   │                         │
│        ▼                                       ▼                         │
│   memory.db now has both memories      memory.db now has both memories   │
│   → local summarization catches up     → local summarization catches up  │
│                                                                           │
└──────────────────────────────────────────────────────────────────────────┘

export const ctx0Memories = pgTable('ctx0_memories', {
  id: text('id').notNull(),
  userId: uuid('user_id').notNull().references(() => ctx0Users.id),
  content: text('content').notNull(),
  tags: jsonb('tags').notNull().default([]),
  source: text('source').notNull().default('agent'),
  project: text('project'),
  pinned: boolean('pinned').notNull().default(false),
  supersededBy: text('superseded_by'),
  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
  syncedAt: timestamp('synced_at', { withTimezone: true }).notNull().defaultNow(),
}, (table) => ({
  pk: primaryKey({ columns: [table.id, table.userId] }),
  userSyncIdx: index('idx_ctx0_memories_user').on(table.userId, table.syncedAt),
}));

CREATE TABLE ctx0_memories (
  id TEXT NOT NULL,
  user_id UUID NOT NULL REFERENCES auth.users(id),
  content TEXT NOT NULL,
  tags JSONB NOT NULL DEFAULT '[]'::jsonb,
  source TEXT NOT NULL DEFAULT 'agent',
  project TEXT,
  pinned BOOLEAN NOT NULL DEFAULT false,
  superseded_by TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  synced_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  PRIMARY KEY (id, user_id)
);

CREATE INDEX idx_ctx0_memories_user ON ctx0_memories(user_id, synced_at DESC);

interface MemoryToolDeps {
  getDb: () => ProxiedSupabaseClient | null;
}

let _deps: MemoryToolDeps | null = null;

export function setMemoryToolDeps(deps: MemoryToolDeps): void {
  _deps = deps;
}

async function syncMemoryToCloud(memory: {
  id: string;
  content: string;
  tags: string[];
  source: string;
  project: string | null;
  pinned: boolean;
}): Promise<void> {
  const db = _deps?.getDb();
  if (!db) return; // Not authenticated — skip silently

  try {
    await db.from('ctx0_memories').upsert({
      id: memory.id,
      content: memory.content,
      tags: memory.tags,
      source: memory.source,
      project: memory.project,
      pinned: memory.pinned,
      synced_at: new Date().toISOString(),
    }, { onConflict: 'id,user_id' });
  } catch (err) {
    console.error('[memory] Cloud push failed:', err);
    // Non-fatal — local SQLite is the source of truth during execution
  }
}

function memorySave(params: { content: string; tags?: string[]; pin?: boolean }, context) {
  // ... existing local INSERT ...

  // Fire-and-forget cloud push
  syncMemoryToCloud({ id, content, tags, source: context.source, project, pinned: pin })
    .catch(() => {});

  return `Saved: "${content.slice(0, 60)}..."`;
}

async function syncSupersedeToCloud(oldId: string, newId: string): Promise<void> {
  const db = _deps?.getDb();
  if (!db) return;

  try {
    await db.from('ctx0_memories')
      .update({ superseded_by: newId, synced_at: new Date().toISOString() })
      .eq('id', oldId);
  } catch (err) {
    console.error('[memory] Cloud supersede sync failed:', err);
  }
}

async function pullMemoriesFromCloud(): Promise<number> {
  const db = _deps?.getDb();
  if (!db) return 0;

  try {
    // Read last sync timestamp
    const meta = localDb.prepare(
      'SELECT value FROM sync_meta WHERE key = ?'
    ).get('last_sync_ts') as { value: string } | undefined;

    const lastSyncTs = meta?.value ?? '1970-01-01T00:00:00Z';

    // Fetch new/updated memories from cloud
    const result = await db.from('ctx0_memories')
      .select('id,content,tags,source,project,pinned,superseded_by,created_at,synced_at')
      .gt('synced_at', lastSyncTs)
      .order('synced_at', { ascending: true })
      .limit(1000);

    if (!result.data || result.data.length === 0) return 0;

    const rows = result.data as CloudMemoryRow[];

    // INSERT OR IGNORE new memories into local SQLite
    const insertOrIgnore = localDb.prepare(`
      INSERT OR IGNORE INTO memories (id, content, tags, source, project, pinned, superseded_by, created_at)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
    `);

    // UPDATE superseded_by for existing memories (if cloud has a newer supersede)
    const updateSupersede = localDb.prepare(`
      UPDATE memories SET superseded_by = ?
      WHERE id = ? AND superseded_by IS NULL AND ? IS NOT NULL
    `);

    let newCount = 0;

    const pullTx = localDb.transaction(() => {
      for (const row of rows) {
        const changes = insertOrIgnore.run(
          row.id,
          row.content,
          JSON.stringify(row.tags),
          row.source,
          row.project,
          row.pinned ? 1 : 0,
          row.superseded_by,
          row.created_at,
        ).changes;

        if (changes > 0) newCount++;

        // Apply supersede if it exists on cloud but not locally
        if (row.superseded_by) {
          updateSupersede.run(row.superseded_by, row.id, row.superseded_by);
        }
      }

      // Update watermark
      const latestSyncedAt = rows[rows.length - 1].synced_at;
      localDb.prepare(
        'INSERT OR REPLACE INTO sync_meta (key, value) VALUES (?, ?)'
      ).run('last_sync_ts', latestSyncedAt);
    });

    pullTx();

    if (newCount > 0) {
      console.log(`[memory] Pulled ${newCount} new memories from cloud`);
      // Trigger summarization catch-up for new entries
      checkSummarizationTrigger();
    }

    return newCount;
  } catch (err) {
    console.error('[memory] Cloud pull failed:', err);
    return 0; // Non-fatal — continue with local state
  }
}

async function bootstrapFromCloud(): Promise<boolean> {
  const db = _deps?.getDb();
  if (!db) return false;

  try {
    // Pull ALL memories for this user (paginated for large sets)
    let offset = 0;
    const pageSize = 500;
    let totalPulled = 0;

    while (true) {
      const result = await db.from('ctx0_memories')
        .select('id,content,tags,source,project,pinned,superseded_by,created_at,synced_at')
        .order('created_at', { ascending: true })
        .range(offset, offset + pageSize - 1);

      if (!result.data || result.data.length === 0) break;

      const rows = result.data as CloudMemoryRow[];

      const insertStmt = localDb.prepare(`
        INSERT OR IGNORE INTO memories (id, content, tags, source, project, pinned, superseded_by, created_at)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
      `);

      const insertTx = localDb.transaction(() => {
        for (const row of rows) {
          insertStmt.run(
            row.id, row.content, JSON.stringify(row.tags), row.source,
            row.project, row.pinned ? 1 : 0, row.superseded_by, row.created_at,
          );
        }
      });

      insertTx();
      totalPulled += rows.length;
      offset += pageSize;

      if (rows.length < pageSize) break; // Last page
    }

    if (totalPulled > 0) {
      console.log(`[memory] Bootstrapped ${totalPulled} memories from cloud`);

      // Set sync watermark
      localDb.prepare(
        'INSERT OR REPLACE INTO sync_meta (key, value) VALUES (?, ?)'
      ).run('last_sync_ts', new Date().toISOString());

      // Generate summaries for bootstrapped entries
      await summarizeEntries();
    }

    return totalPulled > 0;
  } catch (err) {
    console.error('[memory] Cloud bootstrap failed:', err);
    return false;
  }
}

// In session start (packages/daemon/src/session/manager.ts or memory init)
async function initMemoryWithSync(): Promise<void> {
  const isNewDb = !existsSync(DB_PATH);

  // Initialize local SQLite (creates tables if needed)
  initMemoryDb();

  if (isNewDb) {
    // New device — try bootstrapping from cloud
    await bootstrapFromCloud();
  } else {
    // Existing device — pull new memories from other daemons
    await pullMemoriesFromCloud();
  }

  // Existing session start logic: catch-up summarization, etc.
  await onSessionStart();
}

# List recent memories
bot0 memory list --limit 20

# Search
bot0 memory search "deploy key"

# Export
bot0 memory export --format json > backup.json
bot0 memory export --format md > readable.md

# Import
bot0 memory import backup.json

# Stats
bot0 memory stats
# → 342 memories, 8 summaries, 156 KB, oldest: 2025-12-01