@kisev/memomatic 1.0.0-dev.69.gd644a007a7ee → 1.0.0-dev.71.gee4e37a5bb61

package/README.md

@@ -15,7 +15,7 @@ npm install --global @kisev/memomatic
 
 The corpus lives under `$XDG_STATE_HOME/memomatic/` (`MEMORY.md`, `USER.md`,
 daily notes, `DREAMS.md`); rules live in `$XDG_CONFIG_HOME/memomatic/MEMORY_RULES.md`.
-Requires Node.js 22+. Connect `memomatic mcp-serve` as a local stdio MCP server
+Requires Node.js 22.13+. Connect `memomatic mcp-serve` as a local stdio MCP server
 in OpenCode, Kilo, MiMo, or another MCP host and restart that host. No plugin or
 automatic context injection is used. For background processing, run the CLI:
 
@@ -31,6 +31,15 @@ Configure `dream.model` and an OpenCode provider before expecting session
 extraction; without a model, the session watermark is preserved. Follow the
 [setup, first-entry, and scheduling guide](../../docs/how-to/memomatic.md).
 
+## CLI and Dream
+
+See [CLI conventions](../../docs/reference/cli.md) and
+[Dream controls](../../docs/how-to/memomatic.md#observe-limit-and-resume-dream).
+`dream --plan` inspects pending work without a model; `dream --dry-run` may call
+models. Normal Dream drains the eligible snapshot with per-fragment checkpoints,
+reusing one OpenCode server and unchanged embeddings. The first legacy-cursor
+migration checks prior history once without discarding existing memory.
+
 ## Inbox
 
 All writes are asynchronous. Skills, agents, and the `memory_write` tool

package/README.ru.md

@@ -15,7 +15,7 @@ npm install --global @kisev/memomatic
 
 Корпус живёт в `$XDG_STATE_HOME/memomatic/` (`MEMORY.md`, `USER.md`, ежедневные
 записи, `DREAMS.md`); правила — в `$XDG_CONFIG_HOME/memomatic/MEMORY_RULES.md`.
-Нужен Node.js 22+. Подключите `memomatic mcp-serve` как локальный MCP-сервер stdio
+Нужен Node.js 22.13+. Подключите `memomatic mcp-serve` как локальный MCP-сервер stdio
 в OpenCode, Kilo, MiMo или другом MCP-хосте и перезапустите хост. Плагин и
 автоматическая подстановка контекста не используются. Фоновая обработка доступна через CLI:
 
@@ -31,6 +31,15 @@ memomatic dream      # полный проход: inbox + сессии + кон
 без модели отметка обработанных сессий сохраняется. См.
 [настройку, первую запись и расписание](../../docs/ru/how-to/memomatic.md).
 
+## CLI и Dream
+
+См. [соглашения CLI](../../docs/ru/reference/cli.md) и
+[управление Dream](../../docs/ru/how-to/memomatic.md#наблюдение-ограничения-и-продолжение-dream).
+`dream --plan` читает очередь без модели; `dream --dry-run` может вызывать модели.
+Обычный Dream обрабатывает весь подходящий снимок с контрольными точками фрагментов,
+переиспользуя один сервер OpenCode и неизменённые эмбеддинги. Первая миграция старого
+курсора перепроверяет историю один раз, сохраняя накопленную память.
+
 ## Inbox
 
 Все записи асинхронны. Скиллы, агенты и инструмент `memory_write` кладут

package/dist/cli.js

@@ -1,108 +1,217 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
 import { openMemomatic, rebuildIndex, searchMemory } from "./service.js";
 import { runDream } from "./dream.js";
 import { processInbox, withRunLock } from "./inbox.js";
 import { OpenCodeExecutor } from "./executor.js";
-import { handleMcpRequest } from "./mcp.js";
-const USAGE = `usage: memomatic <command> [args]
-
-commands:
-  process [--dry-run]      validate the inbox and move accepted entries into the corpus
-  dream [--dry-run]        run the consolidation sweep (scheduled by memomatic-dream.timer)
-  search <query>           search memory from the command line
-  status                   report corpus and index status
-  index                    rebuild the search index
-  mcp-serve                run the MCP stdio server`;
-function parseArguments(argv) {
-    const [command, ...rest] = argv;
-    if (!command || command === "help" || command === "--help") {
-        process.stderr.write(`${USAGE}\nSearch options: --explain, --project NAME\n`);
-        process.exitCode = command ? 0 : 2;
-        return { command: "", rest };
+import { normalizeSettings } from "./settings.js";
+import { planIngestion } from "./ingestion.js";
+import { opencodeDatabasePath } from "./ingest.js";
+import { memomaticPaths } from "./paths.js";
+import { program, common, Option, configFile, applyConfig, reporter, cancellation, duration, integer, fail, } from "./generated/cli.js";
+const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const cli = common(program("memomatic", "Explicit memory retrieval and observable background processing", version), "MEMOMATIC").addOption(new Option("--state-dir <path>", "absolute private memory directory").env("MEMOMATIC_HOME"));
+const add = (name, description) => cli.command(name).description(description);
+const resolveOptions = async (command) => {
+    const initial = command.optsWithGlobals();
+    if (initial.stateDir) {
+        if (!isAbsolute(initial.stateDir))
+            throw new Error("state-dir must be absolute");
+        process.env.MEMOMATIC_HOME = initial.stateDir;
     }
-    return { command, rest };
-}
-async function main() {
-    const { command, rest } = parseArguments(process.argv.slice(2));
-    if (!command)
-        return;
-    if (command === "mcp-serve") {
-        const { runMcpServer } = await import("./mcp.js");
-        await runMcpServer();
-        return;
+    const config = await configFile(initial.config ?? memomaticPaths().settingsFile).catch((error) => {
+        if (!initial.config && error.code === "ENOENT")
+            return {};
+        throw error;
+    });
+    applyConfig(cli, config);
+    applyConfig(command, config);
+    const opts = command.optsWithGlobals();
+    if (opts.stateDir) {
+        if (!isAbsolute(opts.stateDir))
+            throw new Error("state-dir must be absolute");
+        process.env.MEMOMATIC_HOME = opts.stateDir;
     }
-    if (command === "mcp-selftest") {
-        process.stdout.write(await handleMcpRequest({ id: 1, method: "tools/list" }));
-        return;
+    if (opts.config)
+        process.env.MEMOMATIC_CONFIG = opts.config;
+    return opts;
+};
+const run = async (command, action) => {
+    const opts = await resolveOptions(command);
+    const log = reporter(opts);
+    const abort = cancellation();
+    const limited = opts.maxDuration
+        ? AbortSignal.any([abort.signal, AbortSignal.timeout(opts.maxDuration)])
+        : abort.signal;
+    let context;
+    try {
+        context = await openMemomatic({
+            readOnly: opts.dryRun || opts.plan || command.name() === "status",
+            configure: (settings) => {
+                const dream = { ...settings.dream };
+                for (const [flag, key] of [
+                    ["model", "model"],
+                    ["variant", "variant"],
+                    ["timeout", "timeoutMs"],
+                    ["maxDuration", "maxDurationMs"],
+                    ["maxSessions", "maxSessions"],
+                    ["chunkChars", "maxChars"],
+                    ["retries", "retries"],
+                    ["idle", "idleMs"],
+                    ["opencodeUrl", "opencodeUrl"],
+                ])
+                    if (opts[flag] !== undefined)
+                        Object.assign(dream, { [key]: opts[flag] });
+                return normalizeSettings({ ...settings, dream });
+            },
+        });
+        const signal = context.settings.dream.maxDurationMs && !opts.maxDuration
+            ? AbortSignal.any([limited, AbortSignal.timeout(context.settings.dream.maxDurationMs)])
+            : limited;
+        await action(context, opts, { signal, observe: log.emit });
     }
-    if (command === "--version") {
-        const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-        process.stdout.write(`${version}\n`);
+    finally {
+        context?.store.close();
+        abort.dispose();
+        log.close();
+    }
+};
+const output = (value, opts, summary) => console.log(opts.json || !process.stdout.isTTY ? JSON.stringify(value, null, 2) : summary);
+const dream = add("dream", "Drain the session snapshot, checkpointing completed fragments")
+    .option("--plan", "count pending work without model calls or writes")
+    .option("--dry-run", "preview without persistent writes (model calls still occur)")
+    .addOption(new Option("--model <provider/model>", "OpenCode model; defaults to settings.dream.model").env("MEMOMATIC_MODEL"))
+    .addOption(new Option("--variant <name>", "provider reasoning variant").env("MEMOMATIC_VARIANT"))
+    .addOption(new Option("--timeout <duration>", "per-model-call timeout (default 3m)")
+    .argParser(duration)
+    .env("MEMOMATIC_TIMEOUT"))
+    .addOption(new Option("--max-duration <duration>", "whole-run deadline; 0 means drain the snapshot")
+    .argParser(duration)
+    .env("MEMOMATIC_MAX_DURATION"))
+    .addOption(new Option("--max-sessions <count>", "optional session limit; 0 means all")
+    .argParser(integer)
+    .env("MEMOMATIC_MAX_SESSIONS"))
+    .addOption(new Option("--chunk-chars <count>", "maximum new text per fragment (default 24000)")
+    .argParser(integer)
+    .env("MEMOMATIC_CHUNK_CHARS"))
+    .addOption(new Option("--retries <count>", "additional model attempts (default 1)")
+    .argParser(integer)
+    .env("MEMOMATIC_RETRIES"))
+    .addOption(new Option("--idle <duration>", "minimum session idle age (default 10m)")
+    .argParser(duration)
+    .env("MEMOMATIC_IDLE"))
+    .addOption(new Option("--opencode-url <url>", "reuse an existing OpenCode server; otherwise start one per run").env("MEMOMATIC_OPENCODE_URL"))
+    .addOption(new Option("--database <path>", "OpenCode SQLite session database").env("MEMOMATIC_DATABASE"))
+    .addHelpText("after", "\nExamples:\n  memomatic dream\n  memomatic dream --max-duration 15m --log-format json\n  memomatic dream --dry-run --max-sessions 2\n\nCompleted fragments survive cancellation. Logs use stderr; --json keeps stdout machine-readable.");
+dream.action(async () => run(dream, async (context, opts, runtime) => {
+    if (opts.plan) {
+        const start = Date.now();
+        const plan = planIngestion(opts.database ?? opencodeDatabasePath(), context.store, {
+            before: Date.now() - context.settings.dream.idleMs,
+            maxChars: context.settings.dream.maxChars,
+            maxSessions: context.settings.dream.maxSessions,
+        });
+        const summary = {
+            sessions: plan.sessions,
+            messages: plan.messages,
+            fragments: plan.fragments.length,
+            characters: plan.characters,
+            cachedFragments: plan.cached,
+            cachedSessions: plan.cachedSessions,
+            unscannedSessions: plan.unscannedSessions,
+            scanMs: Date.now() - start,
+        };
+        output(summary, opts, `${summary.sessions} sessions, ${summary.fragments} fragments, ${summary.characters} characters (${summary.scanMs}ms scan). No model calls.`);
         return;
     }
-    const dryRun = (command === "dream" || command === "process") && rest.includes("--dry-run");
-    const context = await openMemomatic({ readOnly: dryRun });
+    const executor = context.settings.dream.model
+        ? new OpenCodeExecutor({
+            model: context.settings.dream.model,
+            variant: context.settings.dream.variant,
+            url: context.settings.dream.opencodeUrl,
+            timeoutMs: context.settings.dream.timeoutMs,
+            retries: context.settings.dream.retries,
+            ...runtime,
+        })
+        : null;
     try {
-        if (command === "dream" || command === "process") {
-            const execute = async () => {
-                if (command === "process")
-                    return processInbox(context, { dryRun });
-                const executor = context.settings.dream.model
-                    ? new OpenCodeExecutor({
-                        model: context.settings.dream.model,
-                        variant: context.settings.dream.variant,
-                    })
-                    : null;
-                return runDream(context, executor, { dryRun });
-            };
-            const result = dryRun ? await execute() : await withRunLock(context.paths, execute);
-            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-            return;
-        }
-        if (command === "search") {
-            const parts = [];
-            let explain = false;
-            let project;
-            for (let index = 0; index < rest.length; index += 1) {
-                if (rest[index] === "--explain")
-                    explain = true;
-                else if (rest[index] === "--project") {
-                    project = rest[++index];
-                    if (!project || project.startsWith("--"))
-                        throw new Error("--project requires a value");
-                }
-                else
-                    parts.push(rest[index]);
-            }
-            const query = parts.join(" ").trim();
-            if (!query)
-                throw new Error("search requires a query");
-            const hits = await searchMemory(context, query, { project });
-            if (!hits.length)
-                process.stdout.write("No relevant memory found.\n");
-            for (const hit of hits) {
-                process.stdout.write(`${hit.score.toFixed(3)}  ${hit.entry.file.replace(`${context.paths.stateRoot}/`, "")}:${hit.entry.line}  ${hit.snippet}\n`);
-                if (explain)
-                    process.stdout.write(`  ${JSON.stringify(hit.explanation)}\n`);
-            }
-            return;
-        }
-        if (command === "status") {
-            const count = await rebuildIndex(context);
-            const fts = context.store.hasFts();
-            process.stdout.write(`${JSON.stringify({ entries: count, fts5: fts, stateRoot: context.paths.stateRoot }, null, 2)}\n`);
-            return;
-        }
-        if (command === "index") {
-            process.stdout.write(`${await rebuildIndex(context)} entries indexed\n`);
-            return;
-        }
-        process.stderr.write(`unknown command: ${command}\n${USAGE}`);
-        process.exitCode = 2;
+        const execute = () => runDream(context, executor, {
+            ...runtime,
+            dryRun: opts.dryRun,
+            databaseFile: opts.database,
+        });
+        const result = opts.dryRun ? await execute() : await withRunLock(context.paths, execute);
+        output({ ...result, modelUsage: executor?.usage ?? null }, opts, `Dream complete: ${result.sessionsIngested} sessions, ${result.candidatesExtracted} candidates, ${result.elapsedMs}ms`);
     }
     finally {
-        context.store.close();
+        await executor?.close();
+    }
+}));
+const processCommand = add("process", "Process explicit inbox entries without LLM extraction").option("--dry-run", "preview without writes");
+processCommand.action(() => run(processCommand, async (context, opts, runtime) => {
+    const execute = () => processInbox(context, { ...runtime, dryRun: opts.dryRun });
+    const result = opts.dryRun ? await execute() : await withRunLock(context.paths, execute);
+    output(result, opts, `Processed ${result.filesProcessed} inbox files; ${result.entriesAppended} entries added`);
+}));
+const index = add("index", "Update derived search data, reusing unchanged embeddings").option("--force", "recompute all document embeddings");
+index.action(() => run(index, async (context, opts, runtime) => {
+    const entries = await rebuildIndex(context, { ...runtime, force: opts.force });
+    if (opts.json)
+        output({ entries }, opts, "");
+    else
+        console.log(`${entries} entries indexed`);
+}));
+const status = add("status", "Read corpus/index status without indexing or model calls");
+status.action(() => run(status, async (context, opts) => output({
+    entries: context.store.allEntries().length,
+    fts5: context.store.hasFts(),
+    stateRoot: context.paths.stateRoot,
+}, opts, `${context.store.allEntries().length} indexed entries in ${context.paths.stateRoot}`)));
+const search = add("search <query...>", "Find relevant memory or return no matches")
+    .option("--explain", "include relevance diagnostics")
+    .addOption(new Option("--project <name>", "restrict to a project and user-level memory").env("MEMOMATIC_PROJECT"));
+search.action((query) => run(search, async (context, opts) => {
+    const hits = await searchMemory(context, query.join(" "), { project: opts.project });
+    if (opts.json) {
+        console.log(JSON.stringify(hits.map((hit) => ({
+            file: hit.entry.file,
+            line: hit.entry.line,
+            score: hit.score,
+            text: hit.snippet,
+            ...(opts.explain ? { explanation: hit.explanation } : {}),
+        })), null, 2));
+        return;
     }
+    if (!hits.length)
+        console.log("No relevant memory found.");
+    for (const hit of hits) {
+        console.log(`${hit.score.toFixed(3)}  ${hit.entry.file.replace(`${context.paths.stateRoot}/`, "")}:${hit.entry.line}  ${hit.snippet}`);
+        if (opts.explain)
+            console.log(`  ${JSON.stringify(hit.explanation)}`);
+    }
+}));
+cli
+    .command("mcp-serve")
+    .description("Serve newline-delimited MCP; stdout is protocol-only")
+    .action(async () => {
+    await resolveOptions(cli);
+    const { runMcpServer } = await import("./mcp.js");
+    await runMcpServer();
+});
+cli
+    .command("mcp-selftest")
+    .description("Print the MCP tool registry without touching state")
+    .action(async () => {
+    const { handleMcpRequest } = await import("./mcp.js");
+    process.stdout.write(await handleMcpRequest({ id: 1, method: "tools/list" }));
+});
+try {
+    if (process.argv.length === 2)
+        cli.outputHelp();
+    else
+        await cli.parseAsync(process.argv);
+}
+catch (error) {
+    fail("memomatic", error, process.argv.includes("--json") || cli.opts().json === true || cli.opts().logFormat === "json");
 }
-await main();

package/dist/dream.d.ts

@@ -1,5 +1,6 @@
 import { type InboxReport } from "./inbox.js";
 import { type ModelExecutor } from "./executor.js";
+import { type OperationOptions } from "./operations.js";
 import type { MemomaticContext } from "./service.js";
 export type DreamReport = {
     inbox: InboxReport;
@@ -15,6 +16,21 @@ export type DreamReport = {
     archived: string[];
     appendOnlyFallback: boolean;
     dryRun: boolean;
+    ingestion?: {
+        messages: number;
+        fragments: number;
+        completed: number;
+        cached: number;
+        characters: number;
+        remaining: number;
+        cachedSessions: number;
+        unscannedSessions: number;
+    };
+    elapsedMs?: number;
+};
+export type DreamOptions = OperationOptions & {
+    dryRun?: boolean;
+    databaseFile?: string;
 };
 export type ExtractedCandidate = {
     text: string;
@@ -34,6 +50,4 @@ export type ConsolidationOperation = {
     key: string;
 };
 export declare function parseConsolidation(response: string): ConsolidationOperation[];
-export declare function runDream(context: MemomaticContext, executor: ModelExecutor | null, options?: {
-    dryRun?: boolean;
-}): Promise<DreamReport>;
+export declare function runDream(context: MemomaticContext, executor: ModelExecutor | null, options?: DreamOptions): Promise<DreamReport>;