@kisev/memomatic 1.0.0-dev.100.g21366c4ad740

package/README.md

@@ -0,0 +1,97 @@
+# memomatic
+
+[Русская версия](README.ru.md)
+
+`@kisev/memomatic` is a personal learning memory for agents following the OpenClaw
+memory architecture: a tiered Markdown corpus you can read as plain files, a
+rebuildable SQLite index with FTS5 and optional local embeddings, a `sessions`
+extraction pass, and a nightly `dream` consolidation sweep.
+
+## Install
+
+```bash
+# Registry version
+npm view --prefer-online @kisev/memomatic@latest version
+
+# Install
+npm install --global @kisev/memomatic
+
+# Installed package and active CLI
+npm list --global @kisev/memomatic --depth=0
+memomatic --version
+```
+
+Tags can move between preview and installation; the last commands show the
+installed package and the CLI resolved from PATH. Use `@dev` in both the view
+and install commands for the development channel.
+
+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.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:
+
+```bash
+memomatic process    # validate the inbox and index accepted entries (no model)
+memomatic sessions   # extract episodic memory from OpenCode sessions (model)
+memomatic dream      # consolidation: inbox + promotion + bounded rewrite + archive
+```
+
+Nightly runs are scheduled by the systemd user units in `assets/systemd/`
+(`memomatic-sessions.service`/`.timer` for extraction and
+`memomatic-dream.service`/`.timer` for consolidation).
+
+Configure `sessions.model` (or keep a legacy `dream.model`) and an OpenCode
+V2 provider before expecting session extraction; without a model, the session
+watermark is preserved. Session extraction and its model server require
+OpenCode `2.x`; a pre-V2 session database is not parsed. Follow the
+[setup, first-entry, and scheduling guide](../../docs/how-to/memomatic.md).
+
+## CLI, Sessions, and Dream
+
+See [CLI conventions](../../docs/reference/cli.md) and
+[Dream controls](../../docs/how-to/memomatic.md#observe-limit-and-resume-dream).
+`sessions --plan` inspects pending session work without a model; `dream --plan`
+counts pending inbox files and promotion candidates. `--dry-run` previews
+either command and may still call models. Sessions drain the eligible snapshot
+with per-fragment checkpoints, reusing one OpenCode server and unchanged
+embeddings; Dream then promotes usage-gated episodic entries into `MEMORY.md`
+through bounded consolidation and archives old entries. The first
+legacy-cursor migration checks prior history once without discarding existing
+memory. `status` shows the queue: pending inbox files, session backlog,
+promotion candidates, and the last run of each sweep.
+
+## Inbox
+
+All writes are asynchronous. Skills, agents, and the `memory_write` tool
+append Markdown entry lines to `$XDG_STATE_HOME/memomatic/inbox/`:
+
+```markdown
+- Durable outcome in one sentence. <!-- source: team-retro --> <!-- key: stable-id -->
+```
+
+The next `process` or `dream` pass validates drops, applies `never-save`
+rules, deduplicates exact texts, supersedes entries sharing a `key`, rebuilds
+the SQLite index with batch embeddings, and moves rejected drops to
+`inbox/rejected/`. Producers detect the inbox by presence and skip silently
+when memomatic is absent.
+
+Every entry can carry a `source` annotation. Visibility derives from it:
+`team-*`, `gitlab`, and `spec-manage` entries may be quoted in team-facing
+artifacts; every other source (`people-journal`, `stopit`,
+`mattermost-triage`, `task-*`, `docs-*`, `user`) is personal-only. The label
+is exposed in search responses.
+
+## Surfaces
+
+- `memomatic` CLI: `process`, `sessions`, `dream`, `search`, `status`, `index`.
+- MCP stdio server with `memory_search`, `memory_get`, `memory_write`, and
+  `memory_forget` tools.
+
+The model initiates memory searches through visible MCP tool calls. The
+`sessions` command processes OpenCode history separately; connecting another
+host does not import its session history. Agentomatic and memomatic are
+installed independently.
+
+Nothing is deleted without the explicit directives documented in
+`MEMORY_RULES.md`.

package/README.ru.md

@@ -0,0 +1,95 @@
+# memomatic
+
+[English version](README.md)
+
+`@kisev/memomatic` — персональная обучающая память для агентов по архитектуре
+памяти OpenClaw: ярусный Markdown-корпус, который можно читать как обычные файлы,
+пересобираемый SQLite-индекс с FTS5 и опциональными локальными эмбеддингами,
+проход извлечения `sessions` и ночной проход консолидации `dream`.
+
+## Установка
+
+```bash
+# Registry version
+npm view --prefer-online @kisev/memomatic@latest version
+
+# Install
+npm install --global @kisev/memomatic
+
+# Installed package and active CLI
+npm list --global @kisev/memomatic --depth=0
+memomatic --version
+```
+
+Тег может сдвинуться между просмотром и установкой; последние команды показывают
+установленный пакет и CLI из PATH. Для dev-канала укажите `@dev` и в просмотре,
+и в установке.
+
+Корпус живёт в `$XDG_STATE_HOME/memomatic/` (`MEMORY.md`, `USER.md`, ежедневные
+записи, `DREAMS.md`); правила — в `$XDG_CONFIG_HOME/memomatic/MEMORY_RULES.md`.
+Нужен Node.js 22.13+. Подключите `memomatic mcp-serve` как локальный MCP-сервер stdio
+в OpenCode, Kilo, MiMo или другом MCP-хосте и перезапустите хост. Плагин и
+автоматическая подстановка контекста не используются. Фоновая обработка доступна через CLI:
+
+```bash
+memomatic process    # валидация inbox и индексация принятого (без модели)
+memomatic sessions   # извлечение эпизодической памяти из сессий OpenCode (модель)
+memomatic dream      # консолидация: inbox + продвижение + перезапись + архив
+```
+
+Ночные проходы планируют user-юниты systemd из `assets/systemd/`
+(`memomatic-sessions.service`/`.timer` для извлечения и
+`memomatic-dream.service`/`.timer` для консолидации).
+
+Перед извлечением сессий настройте `sessions.model` (или оставьте старый
+`dream.model`) и провайдера OpenCode V2; без модели отметка обработанных сессий
+сохраняется. Извлечение сессий и его сервер модели требуют OpenCode `2.x`;
+база сессий до V2 не разбирается. См.
+[настройку, первую запись и расписание](../../docs/ru/how-to/memomatic.md).
+
+## CLI, Sessions и Dream
+
+См. [соглашения CLI](../../docs/ru/reference/cli.md) и
+[управление Dream](../../docs/ru/how-to/memomatic.md#наблюдение-ограничения-и-продолжение-dream).
+`sessions --plan` читает очередь сессий без модели; `dream --plan` считает
+ожидающие файлы inbox и кандидатов на продвижение. `--dry-run` показывает
+превью любой команды и может вызывать модели. Sessions обрабатывают весь
+подходящий снимок с контрольными точками фрагментов, переиспользуя один сервер
+OpenCode и неизменённые эмбеддинги; Dream затем продвигает эпизодические записи,
+прошедшие пороги использования, в `MEMORY.md` через ограниченную консолидацию и
+архивирует старое. Первая миграция старого курсора перепроверяет историю один
+раз, сохраняя накопленную память. `status` показывает очередь: ожидающие файлы
+inbox, бэклог сессий, кандидатов на продвижение и время последнего прохода.
+
+## Inbox
+
+Все записи асинхронны. Скиллы, агенты и инструмент `memory_write` кладут
+строки записей Markdown в `$XDG_STATE_HOME/memomatic/inbox/`:
+
+```markdown
+- Durable-вывод одним предложением. <!-- source: team-retro --> <!-- key: stable-id -->
+```
+
+Следующий проход `process` или `dream` валидирует дропы, применяет правила
+`never-save`, дедуплицирует точные тексты, замещает записи с тем же `key`,
+пересобирает SQLite-индекс с батч-эмбеддингами и переносит отклонённое в
+`inbox/rejected/`. Продюсеры детектируют inbox по наличию и молча
+пропускают дроп, если memomatic нет.
+
+Каждая запись может нести аннотацию `source`. Из неё выводится видимость:
+записи `team-*`, `gitlab` и `spec-manage` можно цитировать в командных
+артефактах; остальные источники (`people-journal`, `stopit`,
+`mattermost-triage`, `task-*`, `docs-*`, `user`) — personal-only. Метка
+возвращается в поиске.
+
+## Поверхности
+
+- CLI `memomatic`: `process`, `sessions`, `dream`, `search`, `status`, `index`.
+- MCP-сервер stdio с инструментами `memory_search`, `memory_get`,
+  `memory_write` и `memory_forget`.
+
+Модель сама инициирует поиск памяти через видимые MCP-вызовы. Команда
+`sessions` отдельно обрабатывает историю OpenCode; подключение другого хоста
+не импортирует его сессии. Agentomatic и memomatic устанавливаются независимо.
+
+Без явных директив, описанных в `MEMORY_RULES.md`, ничего не удаляется.

package/assets/systemd/memomatic-dream.service

@@ -0,0 +1,9 @@
+[Unit]
+Description=Memomatic dream: background memory consolidation sweep
+Documentation=https://github.com/kisev/skills#memomatic
+After=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=/bin/sh -lc 'exec memomatic dream'
+Environment=MEMOMATIC_DREAM=1

package/assets/systemd/memomatic-dream.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Run the Memomatic dream sweep nightly after session extraction
+
+[Timer]
+OnCalendar=*-*-* 04:30:00
+RandomizedDelaySec=30m
+Persistent=true
+
+[Install]
+WantedBy=timers.target

package/assets/systemd/memomatic-sessions.service

@@ -0,0 +1,9 @@
+[Unit]
+Description=Memomatic sessions: extract episodic memory from OpenCode sessions
+Documentation=https://github.com/kisev/skills#memomatic
+After=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=/bin/sh -lc 'exec memomatic sessions'
+Environment=MEMOMATIC_SESSIONS=1

package/assets/systemd/memomatic-sessions.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Run the Memomatic session extraction early nightly
+
+[Timer]
+OnCalendar=*-*-* 02:00:00
+RandomizedDelaySec=30m
+Persistent=true
+
+[Install]
+WantedBy=timers.target

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { openMemomatic, rebuildIndex, searchMemory } from "./service.js";
+import { runDream } from "./dream.js";
+import { runSessions } from "./sessions.js";
+import { processInbox, withRunLock } from "./inbox.js";
+import { OpenCodeExecutor } from "./executor.js";
+import { normalizeSettings } from "./settings.js";
+import { planIngestion } from "./ingestion.js";
+import { opencodeDatabasePath } from "./ingest.js";
+import { promotionCandidates, relevanceByFts } from "./gates.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;
+    }
+    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 (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 sessions = { ...settings.sessions };
+                const dream = { ...settings.dream };
+                for (const [flag, key] of [
+                    ["model", "model"],
+                    ["variant", "variant"],
+                    ["timeout", "timeoutMs"],
+                    ["maxDuration", "maxDurationMs"],
+                    ["retries", "retries"],
+                ]) {
+                    if (opts[flag] !== undefined) {
+                        Object.assign(sessions, { [key]: opts[flag] });
+                        Object.assign(dream, { [key]: opts[flag] });
+                    }
+                }
+                for (const [flag, key] of [
+                    ["maxSessions", "maxSessions"],
+                    ["chunkChars", "maxChars"],
+                    ["idle", "idleMs"],
+                    ["opencodeUrl", "opencodeUrl"],
+                ])
+                    if (opts[flag] !== undefined)
+                        Object.assign(sessions, { [key]: opts[flag] });
+                return normalizeSettings({ ...settings, sessions, dream });
+            },
+        });
+        const deadline = (section) => context.settings[section].maxDurationMs && !opts.maxDuration
+            ? AbortSignal.any([limited, AbortSignal.timeout(context.settings[section].maxDurationMs)])
+            : limited;
+        const signal = command.name() === "sessions" ? deadline("sessions") : deadline("dream");
+        await action(context, opts, { signal, observe: log.emit });
+    }
+    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 modelOptions = (command) => command
+    .addOption(new Option("--model <provider/model>", "OpenCode model; defaults to settings").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 unlimited")
+    .argParser(duration)
+    .env("MEMOMATIC_MAX_DURATION"))
+    .addOption(new Option("--retries <count>", "additional model attempts (default 1)")
+    .argParser(integer)
+    .env("MEMOMATIC_RETRIES"));
+const executor = (context, runtime) => {
+    const sections = {
+        sessions: context.settings.sessions,
+        dream: context.settings.dream,
+    };
+    const create = (section) => {
+        const config = sections[section];
+        return config.model
+            ? new OpenCodeExecutor({
+                model: config.model,
+                variant: config.variant,
+                url: "opencodeUrl" in config ? config.opencodeUrl : null,
+                timeoutMs: config.timeoutMs,
+                retries: config.retries,
+                ...runtime,
+            })
+            : null;
+    };
+    return create;
+};
+const sessions = add("sessions", "Drain the OpenCode session snapshot into episodic memory, checkpointing fragments")
+    .option("--plan", "count pending work without model calls or writes")
+    .option("--dry-run", "preview without persistent writes (model calls still occur)");
+modelOptions(sessions)
+    .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("--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 sessions\n  memomatic sessions --max-duration 15m --log-format json\n  memomatic sessions --dry-run --max-sessions 2\n\nCompleted fragments survive cancellation. Logs use stderr; --json keeps stdout machine-readable.");
+sessions.action(async () => run(sessions, async (context, opts, runtime) => {
+    if (opts.plan) {
+        const start = Date.now();
+        const plan = planIngestion(opts.database ?? opencodeDatabasePath(), context.store, {
+            before: Date.now() - context.settings.sessions.idleMs,
+            maxChars: context.settings.sessions.maxChars,
+            maxSessions: context.settings.sessions.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 create = executor(context, runtime);
+    const model = create("sessions");
+    try {
+        const execute = () => runSessions(context, model, {
+            ...runtime,
+            dryRun: opts.dryRun,
+            databaseFile: opts.database,
+        });
+        const result = opts.dryRun ? await execute() : await withRunLock(context.paths, execute);
+        output({ ...result, modelUsage: model?.usage ?? null }, opts, `Sessions complete: ${result.sessionsIngested} sessions, ${result.candidatesExtracted} candidates, ${result.elapsedMs}ms`);
+    }
+    finally {
+        await model?.close();
+    }
+}));
+const dream = add("dream", "Consolidate memory: inbox, promotion, bounded rewrite, archive")
+    .option("--plan", "count pending work without model calls or writes")
+    .option("--dry-run", "preview without persistent writes (model calls still occur)");
+modelOptions(dream).addHelpText("after", "\nExamples:\n  memomatic dream\n  memomatic dream --max-duration 15m --log-format json\n  memomatic dream --dry-run\n\nSession extraction lives in `memomatic sessions`. Logs use stderr; --json keeps stdout machine-readable.");
+dream.action(async () => run(dream, async (context, opts, runtime) => {
+    if (opts.plan) {
+        const relevance = relevanceByFts(context.store, context.settings);
+        const candidates = promotionCandidates(context.store, context.settings, relevance);
+        const inboxFiles = (await readdir(context.paths.inboxDir).catch(() => [])).filter((name) => name.endsWith(".md")).length;
+        const summary = { inboxFiles, promotionCandidates: candidates.length };
+        output(summary, opts, `${summary.inboxFiles} inbox files, ${summary.promotionCandidates} promotion candidates. No model calls.`);
+        return;
+    }
+    const create = executor(context, runtime);
+    const model = create("dream");
+    try {
+        const execute = () => runDream(context, model, { ...runtime, dryRun: opts.dryRun });
+        const result = opts.dryRun ? await execute() : await withRunLock(context.paths, execute);
+        output({ ...result, modelUsage: model?.usage ?? null }, opts, `Dream complete: ${result.promoted.length} promoted, ${result.superseded.length} superseded, ${result.elapsedMs}ms`);
+    }
+    finally {
+        await model?.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/queue status without indexing or model calls");
+status.action(() => run(status, async (context, opts, runtime) => {
+    const inboxFiles = (await readdir(context.paths.inboxDir).catch(() => [])).filter((name) => name.endsWith(".md")).length;
+    let sessionBacklog = null;
+    const databaseFile = opencodeDatabasePath();
+    if (await stat(databaseFile).catch(() => null)) {
+        try {
+            const plan = planIngestion(databaseFile, context.store, {
+                before: Date.now() - context.settings.sessions.idleMs,
+                maxChars: context.settings.sessions.maxChars,
+                maxSessions: context.settings.sessions.maxSessions,
+            });
+            sessionBacklog = {
+                sessions: plan.sessions,
+                messages: plan.messages,
+                fragments: plan.fragments.length,
+                characters: plan.characters,
+                cachedFragments: plan.cached,
+                cachedSessions: plan.cachedSessions,
+                unscannedSessions: plan.unscannedSessions,
+            };
+        }
+        catch (error) {
+            runtime.observe({
+                phase: "status.sessions",
+                message: `Cannot read OpenCode sessions: ${error.message}`,
+                level: "warn",
+            });
+        }
+    }
+    const relevance = relevanceByFts(context.store, context.settings);
+    const candidates = promotionCandidates(context.store, context.settings, relevance);
+    const report = {
+        entries: context.store.allEntries().length,
+        fts5: context.store.hasFts(),
+        stateRoot: context.paths.stateRoot,
+        queue: {
+            inboxFiles,
+            sessions: sessionBacklog,
+            promotionCandidates: candidates.length,
+        },
+        lastRun: {
+            dream: context.store.getMeta("last-dream-at"),
+            sessions: context.store.getMeta("last-sessions-at"),
+        },
+    };
+    output(report, opts, `${report.entries} indexed entries, ${inboxFiles} inbox files, ${sessionBacklog ? `${sessionBacklog.fragments} pending fragments` : "no session database"}, ${candidates.length} promotion candidates 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");
+}

package/dist/corpus.d.ts

@@ -0,0 +1,12 @@
+import { type CorpusEntry } from "./entries.js";
+import type { MemomaticPaths } from "./paths.js";
+export declare function readTextIfExists(path: string): Promise<string | undefined>;
+export declare function writeCorpusFile(paths: MemomaticPaths, file: string, next: string): Promise<void>;
+export declare function dailyNotePath(paths: MemomaticPaths, date?: Date): string;
+export declare function entryKind(file: string): "curated" | "user" | "episodic";
+export declare function parseCorpusEntries(markdown: string, file: string): CorpusEntry[];
+export declare function appendDailyEntry(paths: MemomaticPaths, line: string, date?: Date): Promise<string>;
+export declare function replaceEntryLine(paths: MemomaticPaths, file: string, line: number, replacement: string | null): Promise<void>;
+export declare function appendDreams(paths: MemomaticPaths, report: string): Promise<void>;
+export declare function archiveFile(paths: MemomaticPaths, file: string): Promise<string>;
+export declare function isCuratedFile(file: string): boolean;