@cairnvibe/sdk 0.2.13 → 0.3.0

package/dist/key-rotator.d.ts

@@ -1,7 +1,35 @@
 export declare class KeyRotator {
     private keys;
     private next;
+    private deadKeys;
     constructor(keys: string[]);
     static fromEnvList(value: string | undefined): KeyRotator | null;
+    /**
+     * Round-robins across whichever keys haven't been confirmed dead yet.
+     * If EVERY configured key has been marked dead (a real, if unlikely,
+     * total outage or a fully-expired key set), falls back to rotating
+     * across the full original list anyway — a bounded retry loop still
+     * needs something real to try, and refusing to ever retry again would
+     * turn "every key happens to be dead right now" into "permanently
+     * broken for the rest of this process," which is strictly worse.
+     */
     take(): string;
+    /**
+     * Marks a key as confirmed invalid (a real 401 from the provider, not a
+     * rate limit) — excluded from `take()`'s rotation for the rest of this
+     * process's life. Logs once per key the first time it's marked, naming
+     * only its last 4 characters (never the real secret) and how many
+     * configured keys still remain live, so a real deployment's own logs
+     * show exactly what happened instead of a silent, confusing drop in
+     * capacity.
+     */
+    markDead(key: string): void;
+    /** How many distinct keys are configured — callers use this to bound a
+     * rate-limit retry loop (no point trying more times than there are
+     * actual keys to fall back to). */
+    get size(): number;
+    /** How many configured keys have NOT been marked dead — narrower than
+     * `size` once markDead has actually excluded something; used to bound a
+     * retry loop against only the keys genuinely worth trying right now. */
+    get liveSize(): number;
 }

package/dist/key-rotator.js

@@ -1,13 +1,28 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyRotator = void 0;
 // Round-robins across a comma-separated list of API keys (e.g. `GROQ_API_KEYS`)
 // so runtime verb calls spread across several free-tier rate limits instead
 // of hammering a single key. Mirrors packages/indexer/src/key-rotator.ts —
 // small enough that duplicating it beats adding a shared package for it.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeyRotator = void 0;
+//
+// Real, live-found gap this closes: a key that's genuinely invalid/expired
+// (a real 401, confirmed directly against Groq's own API — not a transient
+// rate limit) used to just keep getting handed out by `take()` on every
+// pass through the rotation, forever, for the life of the process — a
+// configured-but-dead key wasn't just wasted capacity, it actively
+// sabotaged roughly (dead keys / total keys) of every real request, since
+// GroqVerbLLM's own retry-on-a-different-key logic only ever triggered on
+// a 429 (rate limit), never a 401 (dead key) — see server.ts's own
+// isInvalidKeyError. `markDead` is the fix: once a caller confirms a key
+// is genuinely invalid (not just rate-limited), it's excluded from
+// rotation for the rest of THIS process's life — a session-scoped
+// blocklist, not a persisted one, since a key's validity is checked fresh
+// every time this module is loaded (no stale cross-process assumptions).
 class KeyRotator {
     keys;
     next = 0;
+    deadKeys = new Set();
     constructor(keys) {
         if (keys.length === 0)
             throw new Error("KeyRotator: at least one key is required");
@@ -22,10 +37,49 @@ class KeyRotator {
             .filter(Boolean);
         return keys.length > 0 ? new KeyRotator(keys) : null;
     }
+    /**
+     * Round-robins across whichever keys haven't been confirmed dead yet.
+     * If EVERY configured key has been marked dead (a real, if unlikely,
+     * total outage or a fully-expired key set), falls back to rotating
+     * across the full original list anyway — a bounded retry loop still
+     * needs something real to try, and refusing to ever retry again would
+     * turn "every key happens to be dead right now" into "permanently
+     * broken for the rest of this process," which is strictly worse.
+     */
     take() {
-        const key = this.keys[this.next % this.keys.length];
+        const liveKeys = this.keys.filter((k) => !this.deadKeys.has(k));
+        const pool = liveKeys.length > 0 ? liveKeys : this.keys;
+        const key = pool[this.next % pool.length];
         this.next += 1;
         return key;
     }
+    /**
+     * Marks a key as confirmed invalid (a real 401 from the provider, not a
+     * rate limit) — excluded from `take()`'s rotation for the rest of this
+     * process's life. Logs once per key the first time it's marked, naming
+     * only its last 4 characters (never the real secret) and how many
+     * configured keys still remain live, so a real deployment's own logs
+     * show exactly what happened instead of a silent, confusing drop in
+     * capacity.
+     */
+    markDead(key) {
+        if (this.deadKeys.has(key))
+            return;
+        this.deadKeys.add(key);
+        const remaining = this.keys.length - this.deadKeys.size;
+        console.warn(`[cairn] API key ending in "${key.slice(-4)}" is invalid (confirmed via a real 401) — excluded from rotation for the rest of this session. ${remaining} of ${this.keys.length} configured key(s) remain.`);
+    }
+    /** How many distinct keys are configured — callers use this to bound a
+     * rate-limit retry loop (no point trying more times than there are
+     * actual keys to fall back to). */
+    get size() {
+        return this.keys.length;
+    }
+    /** How many configured keys have NOT been marked dead — narrower than
+     * `size` once markDead has actually excluded something; used to bound a
+     * retry loop against only the keys genuinely worth trying right now. */
+    get liveSize() {
+        return this.keys.length - this.deadKeys.size;
+    }
 }
 exports.KeyRotator = KeyRotator;

package/dist/memory-sqlite.d.ts

@@ -0,0 +1,86 @@
+import Database from "better-sqlite3";
+import type { HistoryTurn } from "@cairnvibe/core";
+export interface MemoryTurnRecord {
+    role: "user" | "assistant";
+    content: string;
+    createdAt: string;
+}
+export interface MemoryStore {
+    /** Core tier — explicit remember, upsert by (scopeId, key), same as
+     * Track B's own "remember" being an explicit act, never automatic.
+     * Kept small on purpose (MAX_CORE_FACTS_PER_SCOPE): once a scope's Core
+     * facts exceed the cap, the least-recently-updated ones are moved to
+     * the Archive tier below (see this file's own doc comment) rather than
+     * deleted outright — "the piece that lets memory scale" the plan calls
+     * for, not a data-loss cliff. */
+    rememberFact(scopeId: string, key: string, value: string): void;
+    recallFact(scopeId: string, key: string): string | null;
+    /** Every CORE fact for this scope, key -> value — never includes Archive tier facts (see recallArchivedFacts for those). */
+    recallFacts(scopeId: string): Record<string, string>;
+    /** Recall tier — append-only, one row per turn, both roles. */
+    recordTurn(scopeId: string, role: "user" | "assistant", content: string): void;
+    /** Recall tier — recency-ordered, oldest-first (ready to feed straight into a HistoryTurn[] array). */
+    recentTurns(scopeId: string, limit?: number): MemoryTurnRecord[];
+    /**
+     * Architecture Pillar 5 — the Recall tier's own real search: a keyword
+     * match against past turn content, not just a recency LIMIT. Lets a
+     * later question reach back further than `recentTurns`' own window
+     * without loading the ENTIRE history every time. Recency-ordered
+     * (newest match first) — no relevance ranking beyond "matched at all,"
+     * a deliberately simple v1.
+     */
+    searchTurns(scopeId: string, query: string, limit?: number): MemoryTurnRecord[];
+    /**
+     * Architecture Pillar 5 — the Archive tier. Long-term facts pulled in
+     * only when a real query actually relates to them, never always-
+     * injected the way Core facts are (that's the whole point — this is
+     * what lets memory scale past Core's small cap without either losing
+     * old facts or paying to inject all of them on every single turn).
+     * Populated automatically when `rememberFact` evicts an over-cap Core
+     * fact; a caller may also archive something directly if it never
+     * belonged in the small, always-injected Core set to begin with.
+     */
+    archiveFact(scopeId: string, key: string, value: string): void;
+    /** Keyword match against BOTH key and value, recency-ordered. Empty object for no match — never guesses at relevance. */
+    recallArchivedFacts(scopeId: string, query: string, limit?: number): Record<string, string>;
+}
+/**
+ * @param target Either a file path (opened/created, parent dir made if
+ * needed) or an already-open better-sqlite3 `Database` — pass an open
+ * connection to share it with your own tables instead of opening a second file.
+ */
+export declare function createSqliteMemoryStore(target: string | Database.Database): MemoryStore;
+/**
+ * Phase 5 step 4 — pure, standalone, directly testable (no closures, no
+ * DB, no WebSocket), storage-agnostic (works from a `MemoryStore`
+ * however it's actually backed) — shared by BOTH transports (the
+ * realtime relay, which seeds this once per connection, and the typed/
+ * HTTP handler, which seeds it once per genuinely fresh session — see
+ * server.ts's own use). Prior turns go FIRST (oldest overall), any
+ * already-accumulated history stays after them, then the whole thing is
+ * capped to `maxTurns` — same cap `history` itself already uses
+ * everywhere else, just applied once more here so a scope with a long
+ * real memory can't blow past it the moment a session starts.
+ */
+export declare function seedHistoryFromMemory(existingHistory: readonly HistoryTurn[], priorTurns: readonly MemoryTurnRecord[], maxTurns: number): HistoryTurn[];
+/**
+ * Phase 5 step 3 — closes the loop step 2 opened: a fact the model
+ * explicitly remembered was being written but never read back into a
+ * LATER turn's context, only `recentTurns`' raw conversation text
+ * (unstructured, unreliable) had any chance of mentioning it. Pure and
+ * standalone for the same reason as `seedHistoryFromMemory` — directly
+ * testable with a plain object, no store, no connection. Returns null
+ * for an empty fact set (nothing to say) rather than an empty string,
+ * so a caller can cleanly skip adding a turn at all.
+ */
+export declare function formatRememberedFacts(facts: Readonly<Record<string, string>>): string | null;
+/**
+ * Architecture Pillar 5 — the Archive tier's own version of
+ * formatRememberedFacts, worded to make the tier distinction legible to
+ * the model instead of silently blending long-since-archived facts in
+ * with the small, always-injected Core set (the two ARE genuinely
+ * different: Core is curated and small; this only ever shows up because
+ * this exact turn's own question happened to relate to it). Same null-
+ * for-empty discipline as its Core counterpart.
+ */
+export declare function formatArchivedFacts(facts: Readonly<Record<string, string>>): string | null;

package/dist/memory-sqlite.js

@@ -0,0 +1,230 @@
+"use strict";
+// Phase 5 — real cross-session memory, backed by SQLite. Shape-inspired
+// by (not copied from) Track B's services/graph/src/cairn_graph/memory.py
+// (facts: an explicit upsert keyed by (scope, key); turns: append-only,
+// recency-ordered recall, no search) — reimplemented here because Track
+// B's version has no real tenant/scope isolation and wasn't built for
+// Track A's actual runtime. Mirrors dashboard-sqlite.ts's own shape
+// (file-or-shared-Database, a namespaced table, plain better-sqlite3) —
+// the same real, already-shipped pattern, not a new one.
+//
+// `scopeId` is deliberately opaque and caller-supplied, never invented
+// here: Track A has no existing identity concept anywhere (no userId/
+// sessionId/tenantId in this SDK today — confirmed before writing this).
+// A caller passes whatever it already has — a Cairn customer's own
+// end-user id if they have login, or any other stable string they
+// choose — and gets exactly the isolation that string implies. This
+// store makes no claim about WHO a scope actually is.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSqliteMemoryStore = createSqliteMemoryStore;
+exports.seedHistoryFromMemory = seedHistoryFromMemory;
+exports.formatRememberedFacts = formatRememberedFacts;
+exports.formatArchivedFacts = formatArchivedFacts;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const FACTS_TABLE = "cairn_memory_facts";
+const TURNS_TABLE = "cairn_memory_turns";
+const ARCHIVE_TABLE = "cairn_memory_archive";
+const DEFAULT_RECENT_TURNS = 20;
+const DEFAULT_SEARCH_LIMIT = 5;
+// Architecture Pillar 5 — MemGPT-shaped tiered memory. A REAL, measured
+// finding motivates this, not a hunch: swapping a tiered-memory agent for
+// a flat/long-context-only one dropped multi-session task completion from
+// ~80% to ~45% (MemoryArena, arxiv 2603.07670). Core is deliberately kept
+// SMALL — "durable, curated facts, always injected" only means something
+// if the set actually stays small; a scope that just accumulates facts
+// forever isn't curated, it's a second, worse-organized turn log. Chosen
+// as a real, testable number (not tuned against production data, which
+// doesn't exist yet for this) — see this file's own tests for the exact
+// eviction behavior at the boundary.
+const MAX_CORE_FACTS_PER_SCOPE = 20;
+/** Real, significant (4+ letter) words, lowercased — the same crude but
+ * dependency-free keyword-matching approach server.ts's Skill retrieval
+ * (matchSkillByGoal) already established, reused here for the same
+ * "cheap, deterministic, no new dependency" reasoning: no FTS5 extension
+ * required, no semantic embedding call, just real substring matching
+ * against words a human would actually recognize as meaningful. */
+function significantWords(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((w) => w.length >= 4);
+}
+/**
+ * @param target Either a file path (opened/created, parent dir made if
+ * needed) or an already-open better-sqlite3 `Database` — pass an open
+ * connection to share it with your own tables instead of opening a second file.
+ */
+function createSqliteMemoryStore(target) {
+    const db = typeof target === "string" ? openFile(target) : target;
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS ${FACTS_TABLE} (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      scope_id TEXT NOT NULL,
+      key TEXT NOT NULL,
+      value TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      UNIQUE(scope_id, key)
+    )
+  `);
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS ${TURNS_TABLE} (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      scope_id TEXT NOT NULL,
+      role TEXT NOT NULL,
+      content TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    )
+  `);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_${TURNS_TABLE}_scope ON ${TURNS_TABLE}(scope_id, id)`);
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS ${ARCHIVE_TABLE} (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      scope_id TEXT NOT NULL,
+      key TEXT NOT NULL,
+      value TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      UNIQUE(scope_id, key)
+    )
+  `);
+    const upsertFact = db.prepare(`
+    INSERT INTO ${FACTS_TABLE} (scope_id, key, value, updated_at) VALUES (?, ?, ?, ?)
+    ON CONFLICT(scope_id, key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+  `);
+    const selectFact = db.prepare(`SELECT value FROM ${FACTS_TABLE} WHERE scope_id = ? AND key = ?`);
+    const selectAllFacts = db.prepare(`SELECT key, value FROM ${FACTS_TABLE} WHERE scope_id = ?`);
+    const countFacts = db.prepare(`SELECT COUNT(*) as count FROM ${FACTS_TABLE} WHERE scope_id = ?`);
+    // ORDER BY updated_at, then id — a real tiebreaker: several facts
+    // written in the same millisecond (easily happens in a tight loop, or
+    // any two facts genuinely remembered together) would otherwise leave
+    // "least-recently-updated" ambiguous, since SQLite makes no ordering
+    // guarantee among rows with an equal ORDER BY key. Falling back to
+    // insertion order (id) is the correct default when two facts are
+    // equally "old" by their real timestamp.
+    const selectOldestFacts = db.prepare(`SELECT key, value, updated_at FROM ${FACTS_TABLE} WHERE scope_id = ? ORDER BY updated_at ASC, id ASC LIMIT ?`);
+    const deleteFact = db.prepare(`DELETE FROM ${FACTS_TABLE} WHERE scope_id = ? AND key = ?`);
+    const insertTurn = db.prepare(`INSERT INTO ${TURNS_TABLE} (scope_id, role, content, created_at) VALUES (?, ?, ?, ?)`);
+    const selectRecentTurns = db.prepare(`SELECT role, content, created_at FROM ${TURNS_TABLE} WHERE scope_id = ? ORDER BY id DESC LIMIT ?`);
+    const upsertArchiveFact = db.prepare(`
+    INSERT INTO ${ARCHIVE_TABLE} (scope_id, key, value, updated_at) VALUES (?, ?, ?, ?)
+    ON CONFLICT(scope_id, key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+  `);
+    function archiveFactImpl(scopeId, key, value, updatedAt) {
+        upsertArchiveFact.run(scopeId, key, value, updatedAt);
+    }
+    /** Enforces MAX_CORE_FACTS_PER_SCOPE after a real write — moves the
+     * least-recently-updated Core facts (oldest `updated_at` first) to
+     * Archive instead of deleting them, until back at the cap. Never
+     * evicts the fact that was just written (it's always the most
+     * recently updated, so ORDER BY updated_at ASC naturally excludes it
+     * as long as the cap is >= 1). */
+    function enforceCoreCap(scopeId) {
+        const { count } = countFacts.get(scopeId);
+        const overflow = count - MAX_CORE_FACTS_PER_SCOPE;
+        if (overflow <= 0)
+            return;
+        const toEvict = selectOldestFacts.all(scopeId, overflow);
+        for (const row of toEvict) {
+            archiveFactImpl(scopeId, row.key, row.value, row.updated_at);
+            deleteFact.run(scopeId, row.key);
+        }
+    }
+    return {
+        rememberFact(scopeId, key, value) {
+            upsertFact.run(scopeId, key, value, new Date().toISOString());
+            enforceCoreCap(scopeId);
+        },
+        recallFact(scopeId, key) {
+            const row = selectFact.get(scopeId, key);
+            return row?.value ?? null;
+        },
+        recallFacts(scopeId) {
+            const rows = selectAllFacts.all(scopeId);
+            return Object.fromEntries(rows.map((r) => [r.key, r.value]));
+        },
+        recordTurn(scopeId, role, content) {
+            insertTurn.run(scopeId, role, content, new Date().toISOString());
+        },
+        recentTurns(scopeId, limit = DEFAULT_RECENT_TURNS) {
+            const rows = selectRecentTurns.all(scopeId, limit);
+            // DESC + LIMIT gets the N most recent, then reversed to oldest-first — ready to feed straight into a HistoryTurn[]-shaped array, same convention that array already uses.
+            return rows.reverse().map((r) => ({ role: r.role, content: r.content, createdAt: r.created_at }));
+        },
+        searchTurns(scopeId, query, limit = DEFAULT_SEARCH_LIMIT) {
+            const words = significantWords(query);
+            if (words.length === 0)
+                return [];
+            const clause = words.map(() => "content LIKE ?").join(" OR ");
+            const params = words.map((w) => `%${w}%`);
+            const rows = db.prepare(`SELECT role, content, created_at FROM ${TURNS_TABLE} WHERE scope_id = ? AND (${clause}) ORDER BY id DESC LIMIT ?`).all(scopeId, ...params, limit);
+            return rows.reverse().map((r) => ({ role: r.role, content: r.content, createdAt: r.created_at }));
+        },
+        archiveFact(scopeId, key, value) {
+            archiveFactImpl(scopeId, key, value, new Date().toISOString());
+        },
+        recallArchivedFacts(scopeId, query, limit = DEFAULT_SEARCH_LIMIT) {
+            const words = significantWords(query);
+            if (words.length === 0)
+                return {};
+            const clause = words.map(() => "(key LIKE ? OR value LIKE ?)").join(" OR ");
+            const params = words.flatMap((w) => [`%${w}%`, `%${w}%`]);
+            const rows = db.prepare(`SELECT key, value FROM ${ARCHIVE_TABLE} WHERE scope_id = ? AND (${clause}) ORDER BY updated_at DESC LIMIT ?`).all(scopeId, ...params, limit);
+            return Object.fromEntries(rows.map((r) => [r.key, r.value]));
+        },
+    };
+}
+function openFile(filePath) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
+    return new better_sqlite3_1.default(filePath);
+}
+/**
+ * Phase 5 step 4 — pure, standalone, directly testable (no closures, no
+ * DB, no WebSocket), storage-agnostic (works from a `MemoryStore`
+ * however it's actually backed) — shared by BOTH transports (the
+ * realtime relay, which seeds this once per connection, and the typed/
+ * HTTP handler, which seeds it once per genuinely fresh session — see
+ * server.ts's own use). Prior turns go FIRST (oldest overall), any
+ * already-accumulated history stays after them, then the whole thing is
+ * capped to `maxTurns` — same cap `history` itself already uses
+ * everywhere else, just applied once more here so a scope with a long
+ * real memory can't blow past it the moment a session starts.
+ */
+function seedHistoryFromMemory(existingHistory, priorTurns, maxTurns) {
+    const combined = [...priorTurns.map((t) => ({ role: t.role, text: t.content })), ...existingHistory];
+    return combined.slice(Math.max(0, combined.length - maxTurns));
+}
+/**
+ * Phase 5 step 3 — closes the loop step 2 opened: a fact the model
+ * explicitly remembered was being written but never read back into a
+ * LATER turn's context, only `recentTurns`' raw conversation text
+ * (unstructured, unreliable) had any chance of mentioning it. Pure and
+ * standalone for the same reason as `seedHistoryFromMemory` — directly
+ * testable with a plain object, no store, no connection. Returns null
+ * for an empty fact set (nothing to say) rather than an empty string,
+ * so a caller can cleanly skip adding a turn at all.
+ */
+function formatRememberedFacts(facts) {
+    const entries = Object.entries(facts);
+    if (entries.length === 0)
+        return null;
+    return `Remembered from a previous conversation with this user: ${entries.map(([key, value]) => `${key} — ${value}`).join("; ")}.`;
+}
+/**
+ * Architecture Pillar 5 — the Archive tier's own version of
+ * formatRememberedFacts, worded to make the tier distinction legible to
+ * the model instead of silently blending long-since-archived facts in
+ * with the small, always-injected Core set (the two ARE genuinely
+ * different: Core is curated and small; this only ever shows up because
+ * this exact turn's own question happened to relate to it). Same null-
+ * for-empty discipline as its Core counterpart.
+ */
+function formatArchivedFacts(facts) {
+    const entries = Object.entries(facts);
+    if (entries.length === 0)
+        return null;
+    return `Also found in older, archived memory (relevant to this question): ${entries.map(([key, value]) => `${key} — ${value}`).join("; ")}.`;
+}

package/dist/realtime-cli.js

@@ -22,6 +22,8 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const core_1 = require("@cairnvibe/core");
 const realtime_server_1 = require("./realtime-server");
+const memory_sqlite_1 = require("./memory-sqlite");
+const skill_store_1 = require("./skill-store");
 function parseCapability(raw) {
     if (raw === "explain" || raw === "guide" || raw === "act")
         return raw;
@@ -124,7 +126,26 @@ function main() {
     const port = parsePortFlag(process.argv.slice(2)) ?? Number(process.env.CAIRN_REALTIME_PORT ?? 3010);
     const capability = parseCapability(process.env.CAIRN_CAPABILITY);
     const persona = process.env.CAIRN_PERSONA || undefined;
-    const server = (0, realtime_server_1.createRealtimeServer)({ manifest, provider, deepgramApiKey, registeredActions, capability, persona });
+    // Phase 5 / Architecture Pillar 5 — real cross-session memory, opt-in
+    // via a real file path. Closes the gap DEVELOPMENT.md's own Pillar 5
+    // entry flagged: MemoryStore was wired into createCopilotHandler and
+    // ConnectionDeps from the start, but never actually reachable from
+    // this CLI — a real deployment had no zero-code way to turn it on for
+    // the realtime relay. Absent env var means exactly today's behavior:
+    // no memory, zero overhead.
+    const memoryDbPath = process.env.CAIRN_MEMORY_DB_PATH;
+    const memory = memoryDbPath ? (0, memory_sqlite_1.createSqliteMemoryStore)(node_path_1.default.resolve(process.cwd(), memoryDbPath)) : undefined;
+    // Architecture Pillar 3 (Skill half) — same real, previously-missing
+    // wiring for self-authored Skills. Deliberately a SEPARATE file/scope
+    // from memory (see skill-store.ts's own doc comment: Skills are
+    // per-deployment, memory is per-user) — sharing the same underlying
+    // sqlite file is still fine if a deployment points both env vars at
+    // the same path, since each store creates its own distinctly-named
+    // tables.
+    const skillsDbPath = process.env.CAIRN_SKILLS_DB_PATH;
+    const skills = skillsDbPath ? (0, skill_store_1.createSqliteSkillStore)(node_path_1.default.resolve(process.cwd(), skillsDbPath)) : undefined;
+    const skillsScopeId = process.env.CAIRN_SKILLS_SCOPE_ID || undefined;
+    const server = (0, realtime_server_1.createRealtimeServer)({ manifest, provider, deepgramApiKey, registeredActions, capability, persona, memory, skills, skillsScopeId });
     server.listen(port, () => {
         console.error(`cairn-realtime: listening on ws://localhost:${port} (provider: ${provider})`);
         if (withCommand)

package/dist/realtime-server.d.ts

@@ -1,23 +1,74 @@
 import http from "node:http";
 import { WebSocket } from "ws";
 import { type HistoryTurn, type LiveElement, type Manifest, type WebMcpTool } from "@cairnvibe/core";
-import { createVerbLLM, type CapabilityTier, type CreateCopilotHandlerOptions } from "./server";
+import { createCriticLLM, createPlanLLM, createVerbLLM, type CapabilityTier, type CreateCopilotHandlerOptions } from "./server";
+import { formatRememberedFacts, seedHistoryFromMemory, type MemoryStore } from "./memory-sqlite";
+import type { SkillStore } from "./skill-store";
 export interface CreateRealtimeServerOptions extends CreateCopilotHandlerOptions {
     manifest: Manifest;
     deepgramApiKey: string;
     sttModel?: string;
     ttsVoice?: string;
+    /** Phase 5 — real cross-session memory (packages/sdk/src/memory-sqlite.ts,
+     * or any store implementing the same interface). Optional — omitting it
+     * keeps every connection exactly as memory-less as before this existed.
+     * Scoped by whatever `scopeId` string a connection's own client sends in
+     * its "context" message (see ConnectionDeps' own doc comment) — this SDK
+     * invents no identity of its own. */
+    memory?: MemoryStore;
+    /** Architecture Pillar 3 (Skill half) — see ConnectionDeps' own doc
+     * comment. Optional; omitting it keeps every connection exactly as it
+     * was before this existed. */
+    skills?: SkillStore;
+    /** See ConnectionDeps' own doc comment. Defaults to "default" when `skills` is set but this is omitted. */
+    skillsScopeId?: string;
 }
+export { seedHistoryFromMemory, formatRememberedFacts };
 export declare function createRealtimeServer(options: CreateRealtimeServerOptions): http.Server;
 export interface ConnectionDeps {
     deepgramApiKey: string;
     sttModel: string;
     ttsVoice: string;
     llm: ReturnType<typeof createVerbLLM>;
+    /** Phase 3 step 2 — a separately-configured Planner LLM, called on the
+     * first continuing step of a turn (see finalizeTurn). Optional so
+     * existing ConnectionDeps construction (and every existing test) keeps
+     * working unchanged; absent means no Planner call happens at all. */
+    planLLM?: ReturnType<typeof createPlanLLM>;
+    /** Phase 3 step 3 — a separately-configured Critic LLM. Only engages
+     * (task-advancement/replan/give-up actually driving the loop, not just
+     * logging) when BOTH this and planLLM are present — the Critic needs a
+     * real Plan's current task to check against. Optional for the same
+     * backward-compatibility reason as planLLM. */
+    criticLLM?: ReturnType<typeof createCriticLLM>;
     systemPrompt: string;
     manifest: Manifest;
     registeredActions: string[];
+    /** Phase 4 step 4 — real descriptions for registeredActions ids, same
+     * shape/purpose as CreateCopilotHandlerOptions.actionDescriptions.
+     * Optional, defaults to {} — an existing ConnectionDeps construction
+     * (own or a test's) keeps working with every action rendered bare. */
+    actionDescriptions?: Record<string, string>;
     capability: CapabilityTier;
+    /** Phase 5 — see CreateRealtimeServerOptions' own doc comment. Optional,
+     * same backward-compatibility reason as every other addition here:
+     * absent means no memory read/write happens for any connection, ever
+     * — today's exact behavior. */
+    memory?: MemoryStore;
+    /**
+     * Architecture Pillar 3 (Skill half) — real, persistent storage for
+     * self-authored Skills (skill-store.ts). A DIFFERENT axis of scope than
+     * `memory` above: Skills are meant to be shared across every user who
+     * talks to this deployment (the same scope `ui-manifest.json` itself
+     * already has), never per-user — see skill-store.ts's own doc comment.
+     * Optional; absent means no Skill retrieval/saving happens at all, zero
+     * overhead, today's exact behavior.
+     */
+    skills?: SkillStore;
+    /** The deployment-wide scope Skills are stored/looked up under when
+     * `skills` is configured. Defaults to "default" — a single-deployment
+     * setup, today's only real usage — when omitted. */
+    skillsScopeId?: string;
 }
 export declare function handleDeepgramMessage(raw: string, client: WebSocket, deps: ConnectionDeps, getContext: () => {
     route: string;
@@ -26,4 +77,34 @@ export declare function handleDeepgramMessage(raw: string, client: WebSocket, de
     webMcpTools: WebMcpTool[];
 }, speakStreamed: (text: string) => Promise<void>, history: HistoryTurn[], turnState: {
     buffer: string;
-}, getGeneration: () => number, waitForToolResult: () => Promise<string>): Promise<void>;
+}, getGeneration: () => number, waitForToolResult: () => Promise<string>, 
+/** Phase 5 — called with each real (role, text) turn as it's finalized,
+ * right alongside the same-shaped `history.push`. Optional and a no-op
+ * by default so every existing call site keeps working unchanged. The
+ * realtime connection's own recordMemoryTurn writes it to durable
+ * storage when memory + a scopeId are both configured for this
+ * connection — see ConnectionDeps.memory's own doc comment. */
+recordMemoryTurn?: (role: "user" | "assistant", text: string) => void, 
+/** Phase 5 step 2 — see finalizeTurn's own doc comment. Threaded
+ * through here purely to reach finalizeTurn's two call sites below. */
+getScopeId?: () => string | null, 
+/** Real, live-found gap this closes: `generation` (getGeneration/
+ * triggerServerBargeIn) previously only ever bumped on an EXPLICIT
+ * barge-in — two ordinary, sequential turns with no interruption
+ * between them shared the exact same generation number. That was
+ * fine for what `generation` was originally built for (dropping
+ * audio/verbs abandoned mid-turn by a real interruption), but it
+ * left the CLIENT's own generation-based staleness check (added for
+ * that same reason, in index.tsx) with no way to tell a merely SLOW
+ * turn's late-arriving reply apart from the current one — nothing
+ * had bumped, so the late reply's generation still matched. Found
+ * live: a "hello" reply that took long enough to arrive AFTER the
+ * next question's own "final" had already fired, landing on the
+ * wrong caption because both were tagged the same generation.
+ * Called once per genuinely NEW turn (both call sites below), so
+ * every real "final" gets its own fresh generation — a turn is now
+ * "superseded" the instant a newer one starts, not only when an
+ * explicit interruption says so. Optional and a no-op by default so
+ * every existing call site (own or a test's) that doesn't pass this
+ * keeps behaving exactly as before. */
+bumpGeneration?: () => void): Promise<void>;