gnosys 5.11.4 → 5.12.0

package/dist/lib/configCommand.js

@@ -0,0 +1,321 @@
+import path from "path";
+import fs from "fs/promises";
+import { fileURLToPath } from "url";
+import { loadConfig, writeConfig, resolveTaskModel, generateConfigTemplate, ALL_PROVIDERS, } from "./config.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+async function packageVersion() {
+    const pkgPath = path.resolve(__dirname, "..", "..", "package.json");
+    const pkg = JSON.parse(await fs.readFile(pkgPath, "utf-8"));
+    return pkg.version;
+}
+function providerModel(cfg, p) {
+    switch (p) {
+        case "anthropic": return cfg.llm.anthropic.model;
+        case "ollama": return cfg.llm.ollama.model;
+        case "groq": return cfg.llm.groq.model;
+        case "openai": return cfg.llm.openai.model;
+        case "lmstudio": return cfg.llm.lmstudio.model;
+        case "xai": return cfg.llm.xai.model;
+        case "mistral": return cfg.llm.mistral.model;
+        case "openrouter": return cfg.llm.openrouter.model;
+        case "custom": return cfg.llm.custom?.model;
+    }
+}
+export async function runConfigShowCommand(getResolver, opts) {
+    const resolver = await getResolver();
+    const stores = resolver.getStores();
+    if (stores.length === 0) {
+        console.error("No stores found. Run gnosys init first.");
+        process.exit(1);
+    }
+    const cfg = await loadConfig(stores[0].path);
+    if (opts.json) {
+        // v5.9.3 (design §12): --json keeps the old machine-readable
+        // dump for scripts. Default output is the human-friendly view.
+        process.stdout.write(`${JSON.stringify(cfg, null, 2)}\n`);
+        return;
+    }
+    console.log("System of Cognition (SOC) — LLM Configuration:");
+    console.log(`  Default provider: ${cfg.llm.defaultProvider}`);
+    console.log("");
+    console.log("  Providers:");
+    console.log(`    Anthropic:  model=${cfg.llm.anthropic.model}, apiKey=${cfg.llm.anthropic.apiKey ? "config" : (process.env.ANTHROPIC_API_KEY ? "env" : "—")}`);
+    console.log(`    Ollama:     model=${cfg.llm.ollama.model}, url=${cfg.llm.ollama.baseUrl}`);
+    console.log(`    Groq:       model=${cfg.llm.groq.model}, apiKey=${cfg.llm.groq.apiKey ? "config" : (process.env.GROQ_API_KEY ? "env" : "—")}`);
+    console.log(`    OpenAI:     model=${cfg.llm.openai.model}, apiKey=${cfg.llm.openai.apiKey ? "config" : (process.env.OPENAI_API_KEY ? "env" : "—")}, url=${cfg.llm.openai.baseUrl}`);
+    console.log(`    LM Studio:  model=${cfg.llm.lmstudio.model}, url=${cfg.llm.lmstudio.baseUrl}`);
+    console.log(`    xAI:        model=${cfg.llm.xai.model}, apiKey=${cfg.llm.xai.apiKey ? "config" : (process.env.XAI_API_KEY ? "env" : "—")}`);
+    console.log(`    Mistral:    model=${cfg.llm.mistral.model}, apiKey=${cfg.llm.mistral.apiKey ? "config" : (process.env.MISTRAL_API_KEY ? "env" : "—")}`);
+    console.log(`    OpenRouter: model=${cfg.llm.openrouter.model}, apiKey=${cfg.llm.openrouter.apiKey ? "config" : (process.env.OPENROUTER_API_KEY ? "env" : "—")}, url=${cfg.llm.openrouter.baseUrl}`);
+    if (cfg.llm.custom) {
+        console.log(`    Custom:     model=${cfg.llm.custom.model}, url=${cfg.llm.custom.baseUrl}, apiKey=${cfg.llm.custom.apiKey ? "config" : (process.env.GNOSYS_LLM_API_KEY ? "env" : "—")}`);
+    }
+    console.log("");
+    const structuring = resolveTaskModel(cfg, "structuring");
+    const synthesis = resolveTaskModel(cfg, "synthesis");
+    console.log("  Task Routing:");
+    console.log(`    Structuring: ${structuring.provider}/${structuring.model}${cfg.taskModels?.structuring ? " (override)" : " (default)"}`);
+    console.log(`    Synthesis:   ${synthesis.provider}/${synthesis.model}${cfg.taskModels?.synthesis ? " (override)" : " (default)"}`);
+}
+export async function runConfigSetCommand(getResolver, key, value, extra) {
+    // v5.9.3 Screen 13 — schema-validate the top-level key against the
+    // known set BEFORE any work, render a `did you mean X?` hint on
+    // typo. The diff + store-source label fire after the switch.
+    const { suggestConfigKey, classifyStore, KNOWN_CONFIG_KEYS } = await import("./setup/configSetRender.js");
+    const { Header } = await import("./setup/ui/header.js");
+    const { printStatus } = await import("./setup/ui/status.js");
+    const { printDiff } = await import("./setup/ui/diff.js");
+    if (!KNOWN_CONFIG_KEYS.includes(key)) {
+        const suggestion = suggestConfigKey(key);
+        const meta = suggestion ? `did you mean \`${suggestion}\` ?` : undefined;
+        printStatus("fail", `unknown config key   ${key}`, meta);
+        process.exit(1);
+    }
+    const resolver = await getResolver();
+    const writeTarget = resolver.getWriteTarget();
+    if (!writeTarget) {
+        printStatus("fail", "no writable store found");
+        process.exit(1);
+    }
+    const storePath = writeTarget.store.getStorePath();
+    const cfg = await loadConfig(storePath);
+    const validProviders = ALL_PROVIDERS.join(", ");
+    const homeDir = process.env.HOME || process.env.USERPROFILE || "/";
+    const storeLabel = classifyStore(storePath, homeDir);
+    // Each branch populates this row so the trailing Diff print picks up
+    // a single before/after summary. Recall has three sub-fields and
+    // sets the row inside its own switch.
+    let diffRow = null;
+    switch (key) {
+        case "provider":
+            if (!ALL_PROVIDERS.includes(value)) {
+                printStatus("fail", `invalid provider \`${value}\``, `supported: ${validProviders}`);
+                process.exit(1);
+            }
+            diffRow = { label: "provider", from: cfg.llm.defaultProvider, to: value };
+            cfg.llm.defaultProvider = value;
+            break;
+        case "model": {
+            // Set model for current default provider
+            const p = cfg.llm.defaultProvider;
+            const fromModel = providerModel(cfg, p) ?? "(unset)";
+            if (p === "anthropic")
+                cfg.llm.anthropic.model = value;
+            else if (p === "ollama")
+                cfg.llm.ollama.model = value;
+            else if (p === "groq")
+                cfg.llm.groq.model = value;
+            else if (p === "openai")
+                cfg.llm.openai.model = value;
+            else if (p === "lmstudio")
+                cfg.llm.lmstudio.model = value;
+            else if (p === "xai")
+                cfg.llm.xai.model = value;
+            else if (p === "mistral")
+                cfg.llm.mistral.model = value;
+            else if (p === "openrouter")
+                cfg.llm.openrouter.model = value;
+            else if (p === "custom") {
+                if (!cfg.llm.custom)
+                    cfg.llm.custom = { model: value, baseUrl: "" };
+                else
+                    cfg.llm.custom.model = value;
+            }
+            diffRow = { label: `${p}.model`, from: fromModel, to: value };
+            break;
+        }
+        case "task": {
+            // gnosys config set task <taskName> <provider> <model>
+            const taskName = value;
+            const taskProvider = extra[0];
+            const taskModel = extra[1];
+            if (!taskName || !taskProvider || !taskModel) {
+                printStatus("fail", "usage", "gnosys config set task <structuring|synthesis> <provider> <model>");
+                process.exit(1);
+            }
+            if (taskName !== "structuring" && taskName !== "synthesis") {
+                printStatus("fail", `invalid task \`${taskName}\``, "valid: structuring, synthesis");
+                process.exit(1);
+            }
+            if (!ALL_PROVIDERS.includes(taskProvider)) {
+                printStatus("fail", `invalid provider \`${taskProvider}\``, `supported: ${validProviders}`);
+                process.exit(1);
+            }
+            if (!cfg.taskModels)
+                cfg.taskModels = {};
+            const taskMap = cfg.taskModels;
+            const prev = taskMap[taskName];
+            const fromStr = prev ? `${prev.provider}/${prev.model}` : "(unset)";
+            taskMap[taskName] = { provider: taskProvider, model: taskModel };
+            diffRow = { label: `task.${taskName}`, from: fromStr, to: `${taskProvider}/${taskModel}` };
+            break;
+        }
+        case "ollama-url":
+            diffRow = { label: "ollama.baseUrl", from: cfg.llm.ollama.baseUrl ?? "(unset)", to: value };
+            cfg.llm.ollama.baseUrl = value;
+            break;
+        case "ollama-model":
+            diffRow = { label: "ollama.model", from: cfg.llm.ollama.model ?? "(unset)", to: value };
+            cfg.llm.ollama.model = value;
+            break;
+        case "anthropic-model":
+            diffRow = { label: "anthropic.model", from: cfg.llm.anthropic.model ?? "(unset)", to: value };
+            cfg.llm.anthropic.model = value;
+            break;
+        case "groq-model":
+            diffRow = { label: "groq.model", from: cfg.llm.groq.model ?? "(unset)", to: value };
+            cfg.llm.groq.model = value;
+            break;
+        case "openai-model":
+            diffRow = { label: "openai.model", from: cfg.llm.openai.model ?? "(unset)", to: value };
+            cfg.llm.openai.model = value;
+            break;
+        case "openai-url":
+            diffRow = { label: "openai.baseUrl", from: cfg.llm.openai.baseUrl ?? "(unset)", to: value };
+            cfg.llm.openai.baseUrl = value;
+            break;
+        case "lmstudio-url":
+            diffRow = { label: "lmstudio.baseUrl", from: cfg.llm.lmstudio.baseUrl ?? "(unset)", to: value };
+            cfg.llm.lmstudio.baseUrl = value;
+            break;
+        case "lmstudio-model":
+            diffRow = { label: "lmstudio.model", from: cfg.llm.lmstudio.model ?? "(unset)", to: value };
+            cfg.llm.lmstudio.model = value;
+            break;
+        case "xai-model":
+            diffRow = { label: "xai.model", from: cfg.llm.xai.model ?? "(unset)", to: value };
+            cfg.llm.xai.model = value;
+            break;
+        case "mistral-model":
+            diffRow = { label: "mistral.model", from: cfg.llm.mistral.model ?? "(unset)", to: value };
+            cfg.llm.mistral.model = value;
+            break;
+        case "openrouter-model":
+            diffRow = { label: "openrouter.model", from: cfg.llm.openrouter.model ?? "(unset)", to: value };
+            cfg.llm.openrouter.model = value;
+            break;
+        case "openrouter-key":
+            diffRow = { label: "openrouter.apiKey", from: cfg.llm.openrouter.apiKey ? "(set)" : "(unset)", to: "(set)" };
+            cfg.llm.openrouter.apiKey = value;
+            break;
+        case "custom-url":
+            diffRow = { label: "custom.baseUrl", from: cfg.llm.custom?.baseUrl ?? "(unset)", to: value };
+            if (!cfg.llm.custom)
+                cfg.llm.custom = { model: "", baseUrl: value };
+            else
+                cfg.llm.custom.baseUrl = value;
+            break;
+        case "custom-model":
+            diffRow = { label: "custom.model", from: cfg.llm.custom?.model ?? "(unset)", to: value };
+            if (!cfg.llm.custom)
+                cfg.llm.custom = { model: value, baseUrl: "" };
+            else
+                cfg.llm.custom.model = value;
+            break;
+        case "custom-key":
+            // Sensitive — don't echo the key in the diff, just mark as redacted.
+            diffRow = { label: "custom.apiKey", from: cfg.llm.custom?.apiKey ? "(set)" : "(unset)", to: "(set)" };
+            if (!cfg.llm.custom)
+                cfg.llm.custom = { model: "", baseUrl: "", apiKey: value };
+            else
+                cfg.llm.custom.apiKey = value;
+            break;
+        case "recall": {
+            // gnosys config set recall <field> <value>
+            // Supported: recall aggressive true/false, recall maxMemories <n>, recall minRelevance <n>
+            const recallField = value;
+            const recallValue = extra[0];
+            if (!recallField || !recallValue) {
+                printStatus("fail", "usage", "gnosys config set recall <aggressive|maxMemories|minRelevance> <value>");
+                process.exit(1);
+            }
+            if (!cfg.recall)
+                cfg.recall = { aggressive: true, maxMemories: 8, minRelevance: 0.4 };
+            switch (recallField) {
+                case "aggressive":
+                    if (recallValue !== "true" && recallValue !== "false") {
+                        printStatus("fail", `invalid value \`${recallValue}\``, "use `true` or `false`");
+                        process.exit(1);
+                    }
+                    diffRow = { label: "recall.aggressive", from: String(cfg.recall.aggressive), to: recallValue };
+                    cfg.recall.aggressive = recallValue === "true";
+                    break;
+                case "maxMemories": {
+                    const n = parseInt(recallValue, 10);
+                    if (isNaN(n) || n < 1 || n > 20) {
+                        printStatus("fail", "maxMemories must be between 1 and 20");
+                        process.exit(1);
+                    }
+                    diffRow = { label: "recall.maxMemories", from: String(cfg.recall.maxMemories), to: String(n) };
+                    cfg.recall.maxMemories = n;
+                    break;
+                }
+                case "minRelevance": {
+                    const f = parseFloat(recallValue);
+                    if (isNaN(f) || f < 0 || f > 1) {
+                        printStatus("fail", "minRelevance must be between 0 and 1");
+                        process.exit(1);
+                    }
+                    diffRow = { label: "recall.minRelevance", from: String(cfg.recall.minRelevance), to: String(f) };
+                    cfg.recall.minRelevance = f;
+                    break;
+                }
+                default:
+                    printStatus("fail", `unknown recall field \`${recallField}\``, "valid: aggressive, maxMemories, minRelevance");
+                    process.exit(1);
+            }
+            break;
+        }
+    }
+    await writeConfig(storePath, cfg);
+    // v5.9.3 Screen 13 — print Header + Diff + ✓ saved with store label.
+    console.log("");
+    console.log(Header(["gnosys", "config", "set"]));
+    console.log("");
+    if (diffRow) {
+        // Append store source to the `to` column so the diff line says
+        // both the new value and where it landed (project vs global).
+        printDiff([{ ...diffRow, to: `${diffRow.to}    (${storeLabel})` }]);
+    }
+    printStatus("ok", `saved · ${path.join(storePath, "gnosys.json")}`, `(${storeLabel})`);
+}
+export async function runConfigInitCommand(getResolver, opts) {
+    // v5.9.3 (design handoff §14, deci-050): `config init` is being
+    // folded into `gnosys setup`. Without --force we print a warning
+    // pointing to `gnosys setup` and exit. With --force we write the
+    // (now-blank-provider) template anyway for muscle-memory use.
+    if (!opts.force) {
+        const { Header } = await import("./setup/ui/header.js");
+        const { Status } = await import("./setup/ui/status.js");
+        const { Footer } = await import("./setup/ui/footer.js");
+        console.log("");
+        console.log(Header(["gnosys", "config", "init"], { version: `v${(await packageVersion())}` }));
+        console.log("");
+        console.log(Status("warn", "writing a blank template means the next run of `gnosys setup`"));
+        console.log(Status("warn", "will walk you through the same choices anyway"));
+        console.log("");
+        console.log("   try   gnosys setup        interactive walkthrough (recommended)");
+        console.log("");
+        console.log(Footer("re-run with --force to write the template anyway"));
+        process.exit(0);
+    }
+    const resolver = await getResolver();
+    const writeTarget = resolver.getWriteTarget();
+    if (!writeTarget) {
+        console.error("No writable store found.");
+        process.exit(1);
+    }
+    const storePath = writeTarget.store.getStorePath();
+    const configPath = path.join(storePath, "gnosys.json");
+    try {
+        await fs.access(configPath);
+        console.error("gnosys.json already exists. Use 'gnosys config set' to modify.");
+        process.exit(1);
+    }
+    catch {
+        // File doesn't exist — good
+    }
+    await fs.writeFile(configPath, generateConfigTemplate() + "\n", "utf-8");
+    console.log(`Created ${configPath}`);
+}

package/dist/lib/connectCommand.d.ts

@@ -0,0 +1,8 @@
+export type ConnectCommandOptions = {
+    url: string;
+    token?: string;
+    ide?: string;
+    dir?: string;
+    print?: boolean;
+};
+export declare function runConnectCommand(opts: ConnectCommandOptions): Promise<void>;

package/dist/lib/connectCommand.js

@@ -0,0 +1,19 @@
+import { remoteMcpEntry, writeRemoteClientConfig } from "./mcpClientConfig.js";
+export async function runConnectCommand(opts) {
+    const remote = { url: opts.url, token: opts.token };
+    if (opts.print) {
+        console.log(JSON.stringify({ mcpServers: { gnosys: remoteMcpEntry(remote) } }, null, 2));
+        return;
+    }
+    const ide = opts.ide === "claude-desktop" ? "claude-desktop" : "cursor";
+    try {
+        const file = await writeRemoteClientConfig(ide, opts.dir || process.cwd(), remote);
+        console.log(`✓ Pointed ${ide} at ${opts.url}`);
+        console.log(`  wrote: ${file}${opts.token ? "  (bearer token included)" : ""}`);
+        console.log("  Restart the IDE / MCP servers to pick it up.");
+    }
+    catch (e) {
+        console.error(`connect failed: ${e instanceof Error ? e.message : e}`);
+        process.exitCode = 1;
+    }
+}

package/dist/lib/db.d.ts

@@ -374,6 +374,58 @@ export declare class GnosysDB {
         remote_snapshot: string | null;
     }>;
     resolveConflict(memoryId: string): void;
+    recordStagingLedgerEntry(entry: {
+        stagingKey: string;
+        machineId: string;
+        memoryUlid?: string | null;
+        firstSeenAt: string;
+        ingestEpoch?: number | null;
+        status?: string;
+    }): void;
+    isUlidProcessed(ulid: string): boolean;
+    markUlidProcessed(ulid: string, ingestEpoch?: number | null): void;
+    countPendingStagingLedger(): number;
+    getStagingLedgerFirstSeenAt(stagingKey: string): string | null;
+    insertPendingAdd(row: {
+        id: string;
+        title: string;
+        category: string;
+        content: string;
+        tags?: string;
+        project_id?: string | null;
+        scope?: string;
+        created: string;
+    }): void;
+    listActivePendingAdds(): Array<{
+        id: string;
+        title: string;
+        category: string;
+        content: string;
+        tags: string;
+        project_id: string | null;
+        scope: string;
+        created: string;
+    }>;
+    clearPendingAdd(id: string): void;
+    getSnapshotManifest(): {
+        epoch: number;
+        seq: number;
+        snapshot_path: string;
+        published_at: string;
+        checksum: string | null;
+        size_bytes: number | null;
+        heartbeat_at: string | null;
+    } | null;
+    publishSnapshotManifest(manifest: {
+        epoch: number;
+        seq: number;
+        snapshotPath: string;
+        publishedAt: string;
+        checksum?: string | null;
+        sizeBytes?: number | null;
+        heartbeatAt?: string | null;
+    }): void;
+    touchSnapshotHeartbeat(at: string): void;
     close(): void;
     isMigrated(): boolean;
     getSchemaVersion(): number;

package/dist/lib/db.js

@@ -24,7 +24,7 @@ import { readMachineConfig } from "./machineConfig.js";
 import { logError } from "./log.js";
 import { ulid } from "ulidx";
 // ─── Schema ─────────────────────────────────────────────────────────────
-const SCHEMA_VERSION = 4;
+const SCHEMA_VERSION = 5;
 const SCHEMA_SQL = `
 CREATE TABLE IF NOT EXISTS memories (
   id                  TEXT PRIMARY KEY,
@@ -171,6 +171,51 @@ CREATE TABLE IF NOT EXISTS sync_conflicts (
 );
 
 CREATE INDEX IF NOT EXISTS idx_sync_conflicts_status ON sync_conflicts(status);
+
+-- v13 multi-machine sync (master DB)
+
+CREATE TABLE IF NOT EXISTS sync_staging_ledger (
+  staging_key       TEXT PRIMARY KEY,
+  machine_id        TEXT NOT NULL,
+  memory_ulid       TEXT,
+  first_seen_at     TEXT NOT NULL,
+  ingest_epoch      INTEGER,
+  status            TEXT NOT NULL DEFAULT 'pending'
+);
+
+CREATE INDEX IF NOT EXISTS idx_sync_staging_status ON sync_staging_ledger(status);
+CREATE INDEX IF NOT EXISTS idx_sync_staging_first_seen ON sync_staging_ledger(first_seen_at);
+
+CREATE TABLE IF NOT EXISTS sync_processed_ulids (
+  ulid              TEXT PRIMARY KEY,
+  ingested_at       TEXT NOT NULL,
+  ingest_epoch      INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS sync_pending_adds (
+  id                TEXT PRIMARY KEY,
+  title             TEXT NOT NULL,
+  category          TEXT NOT NULL,
+  content           TEXT NOT NULL,
+  tags              TEXT DEFAULT '',
+  project_id        TEXT,
+  scope             TEXT DEFAULT 'project',
+  created           TEXT NOT NULL,
+  cleared_at        TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_sync_pending_adds_cleared ON sync_pending_adds(cleared_at);
+
+CREATE TABLE IF NOT EXISTS sync_snapshot_manifest (
+  singleton_id      INTEGER PRIMARY KEY CHECK (singleton_id = 1),
+  epoch             INTEGER NOT NULL,
+  seq               INTEGER NOT NULL,
+  snapshot_path     TEXT NOT NULL,
+  published_at      TEXT NOT NULL,
+  checksum          TEXT,
+  size_bytes        INTEGER,
+  heartbeat_at      TEXT
+);
 `;
 // FTS5 sync triggers — created separately (can't use IF NOT EXISTS on triggers)
 const FTS_TRIGGERS_SQL = `
@@ -641,6 +686,55 @@ export class GnosysDB {
                 // Table may already exist
             }
         }
+        if (fromVersion < 5) {
+            try {
+                this.db.exec(`
+        CREATE TABLE IF NOT EXISTS sync_staging_ledger (
+          staging_key       TEXT PRIMARY KEY,
+          machine_id        TEXT NOT NULL,
+          memory_ulid       TEXT,
+          first_seen_at     TEXT NOT NULL,
+          ingest_epoch      INTEGER,
+          status            TEXT NOT NULL DEFAULT 'pending'
+        );
+        CREATE INDEX IF NOT EXISTS idx_sync_staging_status ON sync_staging_ledger(status);
+        CREATE INDEX IF NOT EXISTS idx_sync_staging_first_seen ON sync_staging_ledger(first_seen_at);
+
+        CREATE TABLE IF NOT EXISTS sync_processed_ulids (
+          ulid              TEXT PRIMARY KEY,
+          ingested_at       TEXT NOT NULL,
+          ingest_epoch      INTEGER
+        );
+
+        CREATE TABLE IF NOT EXISTS sync_pending_adds (
+          id                TEXT PRIMARY KEY,
+          title             TEXT NOT NULL,
+          category          TEXT NOT NULL,
+          content           TEXT NOT NULL,
+          tags              TEXT DEFAULT '',
+          project_id        TEXT,
+          scope             TEXT DEFAULT 'project',
+          created           TEXT NOT NULL,
+          cleared_at        TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_sync_pending_adds_cleared ON sync_pending_adds(cleared_at);
+
+        CREATE TABLE IF NOT EXISTS sync_snapshot_manifest (
+          singleton_id      INTEGER PRIMARY KEY CHECK (singleton_id = 1),
+          epoch             INTEGER NOT NULL,
+          seq               INTEGER NOT NULL,
+          snapshot_path     TEXT NOT NULL,
+          published_at      TEXT NOT NULL,
+          checksum          TEXT,
+          size_bytes        INTEGER,
+          heartbeat_at      TEXT
+        );
+      `);
+            }
+            catch {
+                // Sync tables/indexes may already exist — fine
+            }
+        }
         this.db.pragma(`user_version = ${SCHEMA_VERSION}`);
     }
     isAvailable() {
@@ -1233,6 +1327,80 @@ export class GnosysDB {
     resolveConflict(memoryId) {
         this.db.prepare("UPDATE sync_conflicts SET status = 'resolved' WHERE memory_id = ?").run(memoryId);
     }
+    // ─── v13 multi-machine sync (master + client local overlay) ───────────
+    recordStagingLedgerEntry(entry) {
+        if (entry.status === undefined) {
+            this.db.prepare(`
+        INSERT INTO sync_staging_ledger (staging_key, machine_id, memory_ulid, first_seen_at, ingest_epoch, status)
+        VALUES (?, ?, ?, ?, ?, 'pending')
+        ON CONFLICT(staging_key) DO UPDATE SET
+          memory_ulid = COALESCE(excluded.memory_ulid, sync_staging_ledger.memory_ulid),
+          ingest_epoch = COALESCE(excluded.ingest_epoch, sync_staging_ledger.ingest_epoch)
+      `).run(entry.stagingKey, entry.machineId, entry.memoryUlid ?? null, entry.firstSeenAt, entry.ingestEpoch ?? null);
+            return;
+        }
+        this.db.prepare(`
+      INSERT INTO sync_staging_ledger (staging_key, machine_id, memory_ulid, first_seen_at, ingest_epoch, status)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(staging_key) DO UPDATE SET
+        memory_ulid = COALESCE(excluded.memory_ulid, sync_staging_ledger.memory_ulid),
+        ingest_epoch = COALESCE(excluded.ingest_epoch, sync_staging_ledger.ingest_epoch),
+        status = excluded.status
+    `).run(entry.stagingKey, entry.machineId, entry.memoryUlid ?? null, entry.firstSeenAt, entry.ingestEpoch ?? null, entry.status);
+    }
+    isUlidProcessed(ulid) {
+        const row = this.db.prepare("SELECT 1 FROM sync_processed_ulids WHERE ulid = ?").get(ulid);
+        return Boolean(row);
+    }
+    markUlidProcessed(ulid, ingestEpoch) {
+        this.db.prepare(`
+      INSERT OR IGNORE INTO sync_processed_ulids (ulid, ingested_at, ingest_epoch)
+      VALUES (?, ?, ?)
+    `).run(ulid, new Date().toISOString(), ingestEpoch ?? null);
+    }
+    countPendingStagingLedger() {
+        const row = this.db.prepare("SELECT COUNT(*) as cnt FROM sync_staging_ledger WHERE status = 'pending'").get();
+        return row.cnt;
+    }
+    getStagingLedgerFirstSeenAt(stagingKey) {
+        const row = this.db.prepare("SELECT first_seen_at FROM sync_staging_ledger WHERE staging_key = ?").get(stagingKey);
+        return row?.first_seen_at ?? null;
+    }
+    insertPendingAdd(row) {
+        this.db.prepare(`
+      INSERT OR REPLACE INTO sync_pending_adds
+        (id, title, category, content, tags, project_id, scope, created, cleared_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL)
+    `).run(row.id, row.title, row.category, row.content, row.tags ?? "", row.project_id ?? null, row.scope ?? "project", row.created);
+    }
+    listActivePendingAdds() {
+        return this.db.prepare("SELECT id, title, category, content, tags, project_id, scope, created FROM sync_pending_adds WHERE cleared_at IS NULL ORDER BY created ASC").all();
+    }
+    clearPendingAdd(id) {
+        this.db.prepare("UPDATE sync_pending_adds SET cleared_at = ? WHERE id = ? AND cleared_at IS NULL").run(new Date().toISOString(), id);
+    }
+    getSnapshotManifest() {
+        const row = this.db.prepare("SELECT epoch, seq, snapshot_path, published_at, checksum, size_bytes, heartbeat_at FROM sync_snapshot_manifest WHERE singleton_id = 1").get();
+        return row ?? null;
+    }
+    publishSnapshotManifest(manifest) {
+        this.db.prepare(`
+      INSERT INTO sync_snapshot_manifest
+        (singleton_id, epoch, seq, snapshot_path, published_at, checksum, size_bytes, heartbeat_at)
+      VALUES (1, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(singleton_id) DO UPDATE SET
+        epoch = excluded.epoch,
+        seq = excluded.seq,
+        snapshot_path = excluded.snapshot_path,
+        published_at = excluded.published_at,
+        checksum = excluded.checksum,
+        size_bytes = excluded.size_bytes,
+        heartbeat_at = excluded.heartbeat_at
+    `).run(manifest.epoch, manifest.seq, manifest.snapshotPath, manifest.publishedAt, manifest.checksum ?? null, manifest.sizeBytes ?? null, manifest.heartbeatAt ?? null);
+    }
+    touchSnapshotHeartbeat(at) {
+        this.db.prepare("UPDATE sync_snapshot_manifest SET heartbeat_at = ? WHERE singleton_id = 1").run(at);
+    }
     // ─── Lifecycle ──────────────────────────────────────────────────────
     close() {
         this.db?.close();

package/dist/lib/dearchiveCommand.d.ts

@@ -0,0 +1,7 @@
+import type { GnosysResolver } from "./resolver.js";
+type GetResolver = () => Promise<GnosysResolver>;
+export type DearchiveCommandOptions = {
+    limit: string;
+};
+export declare function runDearchiveCommand(getResolver: GetResolver, query: string, opts: DearchiveCommandOptions): Promise<void>;
+export {};

package/dist/lib/dearchiveCommand.js

@@ -0,0 +1,41 @@
+export async function runDearchiveCommand(getResolver, query, opts) {
+    let archive;
+    try {
+        const { GnosysArchive } = await import("./archive.js");
+        const resolver = await getResolver();
+        const stores = resolver.getStores();
+        if (stores.length === 0) {
+            console.error("No Gnosys stores found. Run gnosys init first.");
+            process.exit(1);
+        }
+        const writeTarget = resolver.getWriteTarget();
+        if (!writeTarget) {
+            console.error("No writable store found.");
+            process.exit(1);
+        }
+        archive = new GnosysArchive(writeTarget.path);
+        if (!archive.isAvailable()) {
+            console.error("Archive not available. Install it with: npm install better-sqlite3");
+            process.exit(1);
+        }
+        const results = archive.searchArchive(query, parseInt(opts.limit));
+        if (results.length === 0) {
+            console.log(`No archived memories found matching "${query}".`);
+            return;
+        }
+        console.log(`Found ${results.length} archived memories matching "${query}":\n`);
+        for (const r of results) {
+            console.log(`  • ${r.title} (${r.id})`);
+        }
+        console.log("");
+        const ids = results.map((r) => r.id);
+        const restored = await archive.dearchiveBatch(ids, writeTarget.store);
+        console.log(`Dearchived ${restored.length} memories back to active:`);
+        for (const rp of restored) {
+            console.log(`  → ${rp}`);
+        }
+    }
+    finally {
+        archive?.close();
+    }
+}

package/dist/lib/discoverCommand.d.ts

@@ -0,0 +1,9 @@
+export type DiscoverCommandOptions = {
+    limit: string;
+    json?: boolean;
+    federated?: boolean;
+    scope?: string;
+    directory?: string;
+    idFormat?: string;
+};
+export declare function runDiscoverCommand(query: string, opts: DiscoverCommandOptions): Promise<void>;