gnosys 5.4.3 → 5.6.0

package/README.md

@@ -52,7 +52,7 @@ Gnosys takes a different approach: the central brain is a single SQLite database
 - **Reflection API** — `gnosys.reflect(outcome)` updates confidence and consolidates memories based on real-world outcomes.
 - **Bulk import** — CSV, JSON, JSONL. Import entire datasets in seconds.
 - **Obsidian-native** — `gnosys export` generates a full vault with YAML frontmatter, `[[wikilinks]]`, summaries, and graph data.
-- **Multi-machine sync (v5.3.0)** — share your `gnosys.db` across machines via NAS or shared drive. Local cache for speed, remote source of truth for consistency. Built-in conflict detection with skip-and-flag resolution. Run `gnosys remote configure` to set up.
+- **Multi-machine sync** — share your `gnosys.db` across machines via NAS or shared drive. Remote NAS is the canonical source of truth; local DB is an offline-resilience cache. Built-in conflict detection with skip-and-flag resolution. Run `gnosys setup remote` to set up.
 - **MCP-compatible** — also runs as a full MCP server that drops into Cursor, Claude Desktop (Chat / Cowork / Code), Claude Code, Codex, Gemini CLI, Antigravity, or any MCP client.
 - **Zero infrastructure** — no external databases, no Docker (unless you want it), no cloud services. Just `npm install`.
 
@@ -96,6 +96,50 @@ The helper auto-starts the sandbox if it's not running. No MCP required.
 
 ---
 
+## Interactive Chat (TUI)
+
+`gnosys chat` opens a memory-aware terminal chat. Every prompt triggers federated recall against the central brain; the LLM sees relevant memories in context and cites them in its answers.
+
+```bash
+gnosys chat                    # new session
+gnosys chat --resume <id>      # continue an earlier session
+gnosys chat --list             # see all sessions
+gnosys chat --search <query>   # full-text search across session logs
+```
+
+**Free-text or slash commands.** "remember that flag default is OFF" works the same as `/remember flag default is OFF`. The TUI also recognizes "what did we decide about ULIDs?" → `/recall`, "thanks, that's all" → `/quit`. Destructive intents always confirm; non-destructive ones auto-accept after 5 confirmations of the same pattern.
+
+**24 slash commands** across reading, recall, writing, focus, and polish — type `/help` inside the TUI for the full list. Highlights:
+
+- `/pin <id>`, `/scope`, `/threshold`, `/recall <q>` — tune what shows up in context
+- `/remember <text>`, `/save-turn`, `/attach <file>` — promote chat content to gnosys memory (PDFs, images, audio all auto-pin to the session)
+- `/focus <topic>`, `/branch`, `/resume-focus` — replace the "new chat" model with cheap focus boundaries; one continuous session log, instant pivot
+- `/export <file.md>`, `/search-chats <q>`, `/dream-here` — round-trip the session, find old chats, or trigger a focused dream cycle
+
+**Multiple choice.** When the model needs you to pick from a small set, it emits a fenced `gnosys-choose` block. The TUI parses it and shows an arrow-key selectable list — provider-agnostic, no tool-use API required.
+
+Sessions live as append-only JSONL at `~/.gnosys/chat-sessions/`; promoted memories carry `session:<id>`, `from-chat:true`, and `source:remember|save-turn|auto|attach` provenance tags so you can find them later via federated search.
+
+---
+
+## Per-Project Bundles
+
+Move a single project's memories between machines without dragging the whole central DB.
+
+```bash
+gnosys export project --to ./gnosys-public.json.gz       # auto-detects current project
+gnosys export project <projectId> --to <bundle>          # explicit
+gnosys import project <bundle> --strategy merge          # default — skip existing
+gnosys import project <bundle> --strategy replace        # wipe target project first
+gnosys import project <bundle> --strategy new-id         # remap to a fresh project ID
+```
+
+Bundles are gzipped JSON containing the project row, memories (with embeddings inline), relationships, and audit log. Lossless round-trip with the same DB schema; partially compatible across versions via the bundle manifest.
+
+For an Obsidian-compatible markdown vault, use `gnosys export vault --to <dir>` (the v5.5.x form `gnosys export --to <dir>` keeps working).
+
+---
+
 ## Web Knowledge Base
 
 Turn any website into a searchable knowledge base for AI chatbots. No database required. Works on Vercel, Netlify, Cloudflare Pages, or any platform that can serve files.
@@ -461,19 +505,19 @@ All memories live in a single `~/.gnosys/gnosys.db` with `project_id` and `scope
 
 ### Multi-Machine Sync
 
-Gnosys v5.3.0 supports running across multiple machines with a shared database on a NAS or network share.
+Gnosys supports running across multiple machines with a shared database on a NAS or network share.
 
 **How it works:**
-- Local DB at `~/.gnosys/gnosys.db` is your fast working cache
 - Remote DB on a network share (e.g. `/Volumes/nas/gnosys/`) is the canonical source of truth
-- Reads always hit local for speed
-- Writes go to local first, then sync to remote
-- Per-memory `modified` timestamps detect conflicts
+- Local DB at `~/.gnosys/gnosys.db` is an offline-resilience cache, not a performance optimization
+- Reads hit remote when reachable; fall back to local cache when remote is offline
+- Writes go to remote first; queue locally and auto-flush when offline
+- Per-memory `modified` timestamps detect conflicts; ULID memory IDs prevent collisions across concurrent writers
 - Skip-and-flag is the safe default; `--newer-wins` for unattended sync
 
 **Setup:**
 ```bash
-gnosys remote configure
+gnosys setup remote
 # interactive: validates path, tests SQLite locking, checks latency
 ```
 
@@ -616,7 +660,7 @@ All commands support `--json` for programmatic output. See the [User Guide](http
 
 **Web knowledge base:** `web init`, `web ingest`, `web build-index`, `web build`, `web add`, `web remove`, `web status`
 
-**Multi-machine sync:** `remote configure`, `remote status`, `remote sync`, `remote push`, `remote pull`, `remote resolve`
+**Multi-machine sync:** `remote status`, `remote sync`, `remote push`, `remote pull`, `remote resolve` (configure via `gnosys setup remote`)
 
 **Server:** `serve`, `serve --with-maintenance`
 

package/dist/cli.js

@@ -108,6 +108,32 @@ function maybePrintUpgradeNudge() {
     }
 }
 maybePrintUpgradeNudge();
+/**
+ * v5.6.0 back-compat shim: rewrite `gnosys export --to <dir>` →
+ * `gnosys export vault --to <dir>` before commander parses argv. The v5.6.0
+ * restructure made `export` a parent command with `vault` and `project`
+ * subcommands; without this shim, the bare `--to` form prints usage instead
+ * of running the vault export.
+ *
+ * Pattern: argv[2]==="export" AND argv[3] is not a known subcommand AND any
+ * of the v5.5.x flags appear (`--to`, `--all`, `--overwrite`, etc.).
+ */
+function rewriteLegacyExport() {
+    if (process.argv[2] !== "export")
+        return;
+    const next = process.argv[3];
+    if (next === "vault" || next === "project" || next === "--help" || next === "-h")
+        return;
+    // Any v5.5.x-style flag → assume legacy vault invocation
+    const looksLegacy = process.argv.slice(3).some((a) => a === "--to" || a.startsWith("--to=") ||
+        a === "--all" || a === "--overwrite" ||
+        a === "--no-summaries" || a === "--no-reviews" || a === "--no-graph" ||
+        a === "--json");
+    if (looksLegacy) {
+        process.argv.splice(3, 0, "vault");
+    }
+}
+rewriteLegacyExport();
 async function getResolver() {
     const resolver = new GnosysResolver();
     await resolver.resolve();
@@ -1218,6 +1244,45 @@ program
         centralDb?.close();
     }
 });
+// ─── gnosys chat (TUI) ───────────────────────────────────────────────────
+program
+    .command("chat")
+    .description("Interactive memory-aware terminal chat (TUI)")
+    .option("--resume <sessionId>", "Resume an existing chat session")
+    .option("--list", "List recent chat sessions and exit")
+    .option("--search <query>", "Full-text search across session logs")
+    .option("--provider <name>", "Override LLM provider (anthropic, openai, groq, ollama, …)")
+    .option("--model <name>", "Override LLM model name")
+    .option("--limit <n>", "Limit for --list / --search (default 20)", "20")
+    .action(async (opts) => {
+    const limit = parseInt(opts.limit, 10) || 20;
+    const chat = await import("./lib/chat/index.js");
+    if (opts.list) {
+        chat.printSessionList(limit);
+        return;
+    }
+    if (opts.search) {
+        chat.printSearchResults(opts.search, limit);
+        return;
+    }
+    // Interactive chat
+    const resolver = await getResolver();
+    const stores = resolver.getStores();
+    const storePath = stores[0]?.path ?? process.cwd();
+    let cliConfig;
+    try {
+        cliConfig = await loadConfig(storePath);
+    }
+    catch {
+        cliConfig = (await import("./lib/config.js")).DEFAULT_CONFIG;
+    }
+    await chat.startChat({
+        config: cliConfig,
+        resume: opts.resume,
+        providerName: opts.provider,
+        modelName: opts.model,
+    });
+});
 // ─── gnosys ingest <file> ─────────────────────────────────────────────────
 program
     .command("ingest <fileOrGlob>")
@@ -1876,12 +1941,13 @@ program
         }
     }
 });
-// ─── gnosys import <file> ────────────────────────────────────────────────
-program
-    .command("import <fileOrUrl>")
-    .description("Bulk import structured data (CSV, JSON, JSONL) into Gnosys memories")
-    .requiredOption("--format <format>", "Data format: csv, json, jsonl")
-    .requiredOption("--mapping <json>", 'Field mapping as JSON: \'{"source_field":"gnosys_field"}\'. Valid targets: title, category, content, tags, relevance')
+// ─── gnosys import (parent + subcommands) ───────────────────────────────
+const importCmd = program
+    .command("import [fileOrUrl]")
+    .enablePositionalOptions()
+    .description("Import data into Gnosys (bulk CSV/JSON/JSONL — see also: 'gnosys import project <bundle>')")
+    .option("--format <format>", "Data format: csv, json, jsonl (required for bulk import)")
+    .option("--mapping <json>", 'Field mapping as JSON: \'{"source_field":"gnosys_field"}\'. Valid targets: title, category, content, tags, relevance')
     .option("--mode <mode>", "Processing mode: llm or structured", "structured")
     .option("--limit <n>", "Max records to import", parseInt)
     .option("--offset <n>", "Skip first N records", parseInt)
@@ -1892,6 +1958,17 @@ program
     .option("--dry-run", "Preview without writing")
     .option("--store <store>", "Target store: project, personal, global", "project")
     .action(async (fileOrUrl, opts) => {
+    if (!fileOrUrl) {
+        console.error("Usage:");
+        console.error("  gnosys import <file> --format csv|json|jsonl --mapping '{...}'   (bulk)");
+        console.error("  gnosys import project <bundle.json.gz>                            (project bundle)");
+        process.exit(1);
+    }
+    if (!opts.format || !opts.mapping) {
+        console.error("Error: --format and --mapping are required for bulk imports.");
+        console.error("       For project bundles, use 'gnosys import project <bundle>'.");
+        process.exit(1);
+    }
     // Parse mapping JSON
     let mapping;
     try {
@@ -1966,6 +2043,51 @@ program
         process.exit(1);
     }
 });
+// `gnosys import project <bundle>` — restore a portable .json.gz bundle
+importCmd
+    .command("project <bundlePath>")
+    .description("Import a project bundle (.json.gz) created by 'gnosys export project'")
+    .option("--strategy <strategy>", "Conflict handling: merge (default), replace, new-id", "merge")
+    .option("--working-directory <dir>", "Override the bundle's working_directory (e.g. when restoring on a different machine)")
+    .option("--json", "Output the result as JSON")
+    .action(async (bundlePath, opts) => {
+    const validStrategies = ["merge", "replace", "new-id"];
+    if (!validStrategies.includes(opts.strategy)) {
+        console.error(`Invalid strategy: ${opts.strategy}. Use one of: ${validStrategies.join(", ")}`);
+        process.exit(1);
+    }
+    const { GnosysDB: DbClass } = await import("./lib/db.js");
+    const { importProject } = await import("./lib/importProject.js");
+    const centralDb = DbClass.openCentral();
+    if (!centralDb.isAvailable()) {
+        console.error("Central DB unavailable.");
+        process.exit(1);
+    }
+    try {
+        const result = importProject(centralDb, {
+            bundlePath: path.resolve(bundlePath),
+            strategy: opts.strategy,
+            workingDirectoryOverride: opts.workingDirectory,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(`Imported project ${result.projectName} (${result.projectId})`);
+            console.log(`  Strategy:        ${result.strategy}`);
+            console.log(`  Memories:        ${result.memoriesInserted} inserted, ${result.memoriesSkipped} skipped, ${result.memoriesReplaced} replaced`);
+            console.log(`  Relationships:   ${result.relationshipsInserted}`);
+            console.log(`  Audit entries:   ${result.auditEntriesInserted}`);
+        }
+    }
+    catch (err) {
+        console.error(`Import failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        centralDb.close();
+    }
+});
 // ─── gnosys reindex ──────────────────────────────────────────────────────
 program
     .command("reindex")
@@ -3347,14 +3469,7 @@ program
 const dreamCmd = program
     .command("dream")
     .description("Dream Mode — idle-time consolidation (run a cycle, view log)");
-// Bare `gnosys dream` runs a cycle now (preserves v5.4.1 behavior).
-dreamCmd
-    .option("--max-runtime <minutes>", "Max runtime in minutes (default: 30)")
-    .option("--no-critique", "Skip self-critique phase")
-    .option("--no-summaries", "Skip summary generation")
-    .option("--no-relationships", "Skip relationship discovery")
-    .option("--json", "Output raw JSON report")
-    .action(async (opts) => {
+async function runDreamCycle(opts) {
     const resolver = new GnosysResolver();
     await resolver.resolve();
     const stores = resolver.getStores();
@@ -3364,6 +3479,7 @@ dreamCmd
     }
     const { GnosysDB: DbClass } = await import("./lib/db.js");
     const { GnosysDreamEngine, formatDreamReport } = await import("./lib/dream.js");
+    const { getMachineId } = await import("./lib/remote.js");
     const storePath = stores[0].path;
     const cfg = await loadConfig(storePath);
     const db = new DbClass(storePath);
@@ -3371,6 +3487,24 @@ dreamCmd
         console.error("Dream Mode requires gnosys.db (v2.0). Run 'gnosys migrate' first.");
         process.exit(1);
     }
+    // Designation gate — warn (and exit unless --force) if this isn't the
+    // designated dream machine. Manual runs from non-designated machines are
+    // useful for testing but shouldn't happen by accident on shared brains.
+    const centralDb = GnosysDB.openCentral();
+    if (centralDb.isAvailable()) {
+        const designated = centralDb.getDreamMachineId();
+        if (designated) {
+            const localId = getMachineId(centralDb);
+            if (designated !== localId && !opts.force) {
+                console.error(`Dream is designated to machine ${designated}, but this is ${localId}.\n` +
+                    `Pass --force to run anyway, or run 'gnosys setup dream' to redesignate.`);
+                centralDb.close();
+                db.close();
+                process.exit(1);
+            }
+        }
+        centralDb.close();
+    }
     const dreamConfig = {
         enabled: true,
         idleMinutes: 0,
@@ -3394,7 +3528,28 @@ dreamCmd
         console.log(formatDreamReport(report));
     }
     db.close();
-});
+}
+// Bare `gnosys dream` runs a cycle (preserves v5.4.1 behavior).
+dreamCmd
+    .option("--max-runtime <minutes>", "Max runtime in minutes (default: 30)")
+    .option("--no-critique", "Skip self-critique phase")
+    .option("--no-summaries", "Skip summary generation")
+    .option("--no-relationships", "Skip relationship discovery")
+    .option("--force", "Run even if this machine is not the designated dream node")
+    .option("--json", "Output raw JSON report")
+    .action(runDreamCycle);
+// `gnosys dream run` — explicit alias matching the `gnosys dream log|run`
+// pattern. Same options + behavior as the bare command.
+dreamCmd
+    .command("run")
+    .description("Force a dream cycle now (manual trigger)")
+    .option("--max-runtime <minutes>", "Max runtime in minutes (default: 30)")
+    .option("--no-critique", "Skip self-critique phase")
+    .option("--no-summaries", "Skip summary generation")
+    .option("--no-relationships", "Skip relationship discovery")
+    .option("--force", "Run even if this machine is not the designated dream node")
+    .option("--json", "Output raw JSON report")
+    .action(runDreamCycle);
 // `gnosys dream log` — view recent dream runs from audit_log
 dreamCmd
     .command("log")
@@ -3462,18 +3617,7 @@ dreamCmd
         centralDb?.close();
     }
 });
-// ─── gnosys export ───────────────────────────────────────────────────────
-program
-    .command("export")
-    .description("Export gnosys.db to Obsidian-compatible vault (one-way)")
-    .requiredOption("--to <dir>", "Target directory for export")
-    .option("--all", "Export all memories (active + archived)")
-    .option("--overwrite", "Overwrite existing files")
-    .option("--no-summaries", "Skip category summaries")
-    .option("--no-reviews", "Skip review suggestions")
-    .option("--no-graph", "Skip relationship graph")
-    .option("--json", "Output raw JSON report")
-    .action(async (opts) => {
+async function runVaultExport(opts) {
     const resolver = new GnosysResolver();
     await resolver.resolve();
     const stores = resolver.getStores();
@@ -3512,6 +3656,81 @@ program
         console.log(formatExportReport(report));
     }
     db.close();
+}
+const exportCmd = program
+    .command("export")
+    .description("Export memory to a vault (markdown) or a project bundle (.json.gz)")
+    .enablePositionalOptions();
+// Bare `gnosys export` shows the canonical subcommand forms. Back-compat for
+// the v5.5.x form `gnosys export --to <dir>` is handled in a pre-parse shim
+// at the top of the file (rewrites argv to insert "vault" before "--to").
+exportCmd.action(() => {
+    console.error("Usage: gnosys export vault --to <dir>             # Obsidian vault export");
+    console.error("       gnosys export project [id] --to <bundle>   # portable .json.gz bundle");
+    process.exit(1);
+});
+// `gnosys export vault` — explicit alias for the default behavior
+exportCmd
+    .command("vault")
+    .description("Export gnosys.db to an Obsidian-compatible vault (one-way)")
+    .requiredOption("--to <dir>", "Target directory for export")
+    .option("--all", "Export all memories (active + archived)")
+    .option("--overwrite", "Overwrite existing files")
+    .option("--no-summaries", "Skip category summaries")
+    .option("--no-reviews", "Skip review suggestions")
+    .option("--no-graph", "Skip relationship graph")
+    .option("--json", "Output raw JSON report")
+    .action(runVaultExport);
+// `gnosys export project [id]` — bundle a single project for portability
+exportCmd
+    .command("project [projectId]")
+    .description("Export a single project to a portable .json.gz bundle (round-trips with 'gnosys import project')")
+    .requiredOption("--to <file>", "Output bundle file path (e.g. ./gnosys-public.gnosys.json.gz)")
+    .option("--include-archived", "Include archived and superseded memories (default: active only)")
+    .option("--no-audit", "Skip the audit log")
+    .option("--json", "Output the result as JSON")
+    .action(async (projectIdArg, opts) => {
+    const { GnosysDB: DbClass } = await import("./lib/db.js");
+    const { exportProject } = await import("./lib/exportProject.js");
+    const centralDb = DbClass.openCentral();
+    if (!centralDb.isAvailable()) {
+        console.error("Central DB unavailable.");
+        process.exit(1);
+    }
+    let projectId = projectIdArg;
+    if (!projectId) {
+        // Auto-detect from cwd
+        const proj = centralDb.getProjectByDirectory(process.cwd());
+        if (!proj) {
+            console.error("No project ID given and current directory is not a registered project.");
+            console.error("Usage: gnosys export project <projectId> --to <file>");
+            process.exit(1);
+        }
+        projectId = proj.id;
+    }
+    try {
+        const result = exportProject(centralDb, {
+            projectId,
+            outputPath: path.resolve(opts.to),
+            includeArchived: !!opts.includeArchived,
+            includeAudit: opts.audit !== false,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            const ratio = (result.compressedBytes / result.uncompressedBytes * 100).toFixed(1);
+            console.log(`Exported project ${projectId}`);
+            console.log(`  Memories:      ${result.memoryCount}`);
+            console.log(`  Relationships: ${result.relationshipCount}`);
+            console.log(`  Audit entries: ${result.auditEntryCount}`);
+            console.log(`  Bundle:        ${result.outputPath}`);
+            console.log(`  Size:          ${(result.compressedBytes / 1024).toFixed(1)} KB compressed (${ratio}% of ${(result.uncompressedBytes / 1024).toFixed(1)} KB)`);
+        }
+    }
+    finally {
+        centralDb.close();
+    }
 });
 // ─── gnosys serve ────────────────────────────────────────────────────────
 program