@kisev/memomatic 1.0.0-dev.59.g0506803c61e5 → 1.0.0-dev.61.gdf462654550b

package/README.md

@@ -10,13 +10,13 @@ rebuildable SQLite index with FTS5 and optional local embeddings, and a nightly
 ## Install
 
 ```bash
-npm install @kisev/memomatic
+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`.
-The `@kisev/agentomatic` installer deploys the OpenCode plugin automatically;
-standalone use runs the CLI:
+Requires Node.js 22+. Explicitly select `memomatic` in the `@kisev/agentomatic`
+installer and restart OpenCode. For standalone use, run the CLI:
 
 ```bash
 memomatic process    # validate the inbox and index accepted entries (no model)
@@ -26,6 +26,10 @@ memomatic dream      # full sweep: inbox + sessions + consolidation
 The nightly sweep is scheduled by the systemd user units in `assets/systemd/`
 (`memomatic-dream.service` and `memomatic-dream.timer`).
 
+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).
+
 ## Inbox
 
 All writes are asynchronous. Skills, agents, and the `memory_write` tool

package/README.ru.md

@@ -10,13 +10,13 @@
 ## Установка
 
 ```bash
-npm install @kisev/memomatic
+npm install --global @kisev/memomatic
 ```
 
 Корпус живёт в `$XDG_STATE_HOME/memomatic/` (`MEMORY.md`, `USER.md`, ежедневные
 записи, `DREAMS.md`); правила — в `$XDG_CONFIG_HOME/memomatic/MEMORY_RULES.md`.
-Установщик `@kisev/agentomatic` разворачивает плагин OpenCode автоматически;
-автономное использование — через CLI:
+Нужен Node.js 22+. Явно выберите `memomatic` в установщике `@kisev/agentomatic`
+и перезапустите OpenCode. Автономное использование доступно через CLI:
 
 ```bash
 memomatic process    # валидация inbox и индексация принятого (без модели)
@@ -26,6 +26,10 @@ memomatic dream      # полный проход: inbox + сессии + кон
 Ночной проход планируют user-юниты systemd из `assets/systemd/`
 (`memomatic-dream.service` и `memomatic-dream.timer`).
 
+Перед извлечением сессий настройте `dream.model` и провайдера OpenCode;
+без модели отметка обработанных сессий сохраняется. См.
+[настройку, первую запись и расписание](../../docs/ru/how-to/memomatic.md).
+
 ## Inbox
 
 Все записи асинхронны. Скиллы, агенты и инструмент `memory_write` кладут

package/dist/cli.js

@@ -41,11 +41,11 @@ async function main() {
         process.stdout.write(`${version}\n`);
         return;
     }
-    const context = await openMemomatic();
+    const dryRun = (command === "dream" || command === "process") && rest.includes("--dry-run");
+    const context = await openMemomatic({ readOnly: dryRun });
     try {
         if (command === "dream" || command === "process") {
-            const dryRun = rest.includes("--dry-run");
-            const result = await withRunLock(context.paths, async () => {
+            const execute = async () => {
                 if (command === "process")
                     return processInbox(context, { dryRun });
                 const executor = context.settings.dream.model
@@ -55,7 +55,8 @@ async function main() {
                     })
                     : 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;
         }

package/dist/dream.js

@@ -71,6 +71,8 @@ export function parseConsolidation(response) {
     return result.slice(0, 32);
 }
 async function ingestSessions(context, executor) {
+    if (!executor)
+        return { sessions: 0, extracted: [], watermark: null, rejected: [] };
     const watermark = Number.parseInt(context.store.getMeta(WATERMARK_KEY) ?? "0", 10) || 0;
     const sessions = loadRecentSessions(opencodeDatabasePath(), watermark, {
         before: Date.now() - 10 * 60_000,
@@ -82,8 +84,6 @@ async function ingestSessions(context, executor) {
     let latest = watermark;
     for (const session of sessions) {
         latest = Math.max(latest, session.timeCreated);
-        if (!executor)
-            continue;
         const transcript = session.messages
             .map((message) => `${message.role}: ${message.text}`)
             .join("\n\n")
@@ -108,6 +108,17 @@ async function ingestSessions(context, executor) {
     };
 }
 export async function runDream(context, executor, options = {}) {
+    if (!options.dryRun)
+        return executeDream(context, executor, options);
+    const store = context.store.fork();
+    try {
+        return await executeDream({ ...context, store }, executor, options);
+    }
+    finally {
+        store.close();
+    }
+}
+async function executeDream(context, executor, options) {
     const dryRun = options.dryRun === true;
     const report = {
         inbox: {
@@ -168,12 +179,27 @@ export async function runDream(context, executor, options = {}) {
                 .map((candidate) => `- ${candidate.entry.text} <!-- key: ${candidate.entry.key ?? candidate.entry.stableId} -->`)
                 .join("\n")}`,
         });
-        const operations = parseConsolidation(response);
+        let operations;
+        let invalidResponse = false;
+        try {
+            operations = parseConsolidation(response);
+        }
+        catch {
+            invalidResponse = true;
+            operations = finalCandidates.map(({ entry }) => ({
+                op: "add",
+                line: entryLine(entry.text.replace(/^- /, ""), {
+                    key: entry.key ?? undefined,
+                    origin: entry.origin ?? "agent",
+                    source: entry.source ?? undefined,
+                }),
+            }));
+        }
         const outcome = await applyConsolidation(context, operations, current, dryRun);
         report.promoted = outcome.promoted;
         report.superseded = outcome.superseded;
         report.dropped = outcome.dropped;
-        report.appendOnlyFallback = outcome.appendOnlyFallback;
+        report.appendOnlyFallback = invalidResponse || outcome.appendOnlyFallback;
     }
     if (!dryRun)
         report.archived = await archiveOldEpisodic(context);
@@ -215,6 +241,9 @@ async function applyConsolidation(context, operations, currentMemory, dryRun) {
     const adds = operations.filter((operation) => operation.op === "add");
     const supersessions = operations.filter((operation) => operation.op === "supersede" && existingKeys.has(operation.key));
     const drops = operations.filter((operation) => operation.op === "drop" && existingKeys.has(operation.key));
+    // Consolidation never grants permission to delete curated memory.
+    if (drops.length)
+        result.appendOnlyFallback = true;
     if (removals.length !== supersessions.length + drops.length)
         result.appendOnlyFallback = true;
     if (!result.appendOnlyFallback && lossRatio > context.settings.dream.maxPriorEntryLoss)

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { writeCorpusFile } from "./corpus.js";
 export { entryLine, parseEntryLine } from "./entries.js";
 export { visibilityForSource } from "./visibility.js";
 export { dropToInbox, processInbox, withRunLock } from "./inbox.js";
-export { forgetEntry, getEntry, openMemomatic, searchMemory, writeEntry } from "./service.js";
+export { forgetEntry, getEntry, openMemomatic, searchMemory, searchMemoryResults, writeEntry, } from "./service.js";
 export type { MemomaticContext } from "./service.js";
 export { bootstrapContext, resolveProject } from "./bootstrap.js";
 export { opencodeDatabasePath, sessionFacts } from "./ingest.js";

package/dist/index.js

@@ -2,6 +2,6 @@ export { writeCorpusFile } from "./corpus.js";
 export { entryLine, parseEntryLine } from "./entries.js";
 export { visibilityForSource } from "./visibility.js";
 export { dropToInbox, processInbox, withRunLock } from "./inbox.js";
-export { forgetEntry, getEntry, openMemomatic, searchMemory, writeEntry } from "./service.js";
+export { forgetEntry, getEntry, openMemomatic, searchMemory, searchMemoryResults, writeEntry, } from "./service.js";
 export { bootstrapContext, resolveProject } from "./bootstrap.js";
 export { opencodeDatabasePath, sessionFacts } from "./ingest.js";

package/dist/mcp.js

@@ -1,5 +1,4 @@
-import { forgetEntry, getEntry, openMemomatic, searchMemory, writeEntry } from "./service.js";
-import { visibilityForSource } from "./visibility.js";
+import { forgetEntry, getEntry, openMemomatic, searchMemoryResults, writeEntry, } from "./service.js";
 const PROTOCOL_VERSION = "2025-06-18";
 const TOOLS = [
     {
@@ -69,16 +68,7 @@ async function callTool(name, args) {
             case "memory_search": {
                 if (typeof args.query !== "string" || !args.query.trim())
                     throw new Error("query is required");
-                const hits = await searchMemory(context, args.query);
-                return hits.map((hit) => ({
-                    file: hit.entry.file.replace(`${context.paths.stateRoot}/`, ""),
-                    kind: hit.entry.kind,
-                    line: hit.entry.line,
-                    score: Number(hit.score.toFixed(4)),
-                    snippet: hit.snippet,
-                    source: hit.entry.source,
-                    visibility: visibilityForSource(hit.entry.source),
-                }));
+                return await searchMemoryResults(context, args.query);
             }
             case "memory_get": {
                 if (typeof args.file !== "string" || !args.file)

package/dist/service.d.ts

@@ -20,9 +20,20 @@ export type MemomaticContext = {
     rules: MemoryRules;
     store: MemoryStore;
 };
-export declare function openMemomatic(): Promise<MemomaticContext>;
+export declare function openMemomatic(options?: {
+    readOnly?: boolean;
+}): Promise<MemomaticContext>;
 export declare function writeEntry(context: MemomaticContext, request: WriteRequest): Promise<string>;
 export declare function searchMemory(context: MemomaticContext, query: string): Promise<SearchHit[]>;
+export declare function searchMemoryResults(context: MemomaticContext, query: string): Promise<{
+    file: string;
+    kind: import("./store.js").EntryKind;
+    line: number;
+    score: number;
+    snippet: string;
+    source: string | null;
+    visibility: import("./visibility.js").EntryVisibility;
+}[]>;
 export declare function getEntry(context: MemomaticContext, file: string, line?: number): Promise<{
     file: string;
     line: number;

package/dist/service.js

@@ -1,27 +1,29 @@
-import { entryLine } from "./entries.js";
-import { archiveFile, readTextIfExists, replaceEntryLine } from "./corpus.js";
+import { entryLine, parseEntryLine } from "./entries.js";
+import { readTextIfExists, replaceEntryLine, writeCorpusFile } from "./corpus.js";
+import { assertSafePath } from "@kisev/safe-fs";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { rm } from "node:fs/promises";
 import { dropToInbox } from "./inbox.js";
 import { isForbidden, loadRules } from "./rules.js";
 import { memomaticPaths } from "./paths.js";
 import { loadSettings } from "./settings.js";
 import { reindex, search } from "./search.js";
 import { MemoryStore } from "./store.js";
-import { stat } from "node:fs/promises";
-async function exists(path) {
-    try {
-        await stat(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
+import { visibilityForSource } from "./visibility.js";
+async function memoryPath(context, file) {
+    const target = resolve(context.paths.stateRoot, file);
+    const part = relative(context.paths.stateRoot, target);
+    if (!part || part === ".." || part.startsWith(`..${sep}`) || isAbsolute(part))
+        throw new Error("path escapes memomatic state root");
+    await assertSafePath(target, { target: "file" });
+    return target;
 }
-export async function openMemomatic() {
+export async function openMemomatic(options = {}) {
     const paths = memomaticPaths();
     const [settings, rules, store] = await Promise.all([
         loadSettings(paths.settingsFile),
         loadRules(paths.rulesFile),
-        MemoryStore.open(paths.indexFile),
+        options.readOnly ? MemoryStore.preview(paths.indexFile) : MemoryStore.open(paths.indexFile),
     ]);
     return { paths, settings, rules, store };
 }
@@ -49,19 +51,26 @@ export async function writeEntry(context, request) {
 export async function searchMemory(context, query) {
     return search(context.store, query, context.settings);
 }
+export async function searchMemoryResults(context, query) {
+    return (await searchMemory(context, query)).map((hit) => ({
+        file: hit.entry.file.replace(`${context.paths.stateRoot}/`, ""),
+        kind: hit.entry.kind,
+        line: hit.entry.line,
+        score: Number(hit.score.toFixed(4)),
+        snippet: hit.snippet,
+        source: hit.entry.source,
+        visibility: visibilityForSource(hit.entry.source),
+    }));
+}
 export async function getEntry(context, file, line) {
-    const target = file.startsWith("/")
-        ? file
-        : `${context.paths.stateRoot}/${file.replace(/^\/+/, "")}`;
-    if (!target.startsWith(context.paths.stateRoot))
-        throw new Error("path escapes memomatic state root");
+    const target = await memoryPath(context, file);
     const content = await readTextIfExists(target);
     if (content === undefined)
         throw new Error(`memory file not found: ${file}`);
     if (line === undefined)
         return { file: target, line: 0, content };
     const lines = content.split("\n");
-    if (line < 1 || line > lines.length)
+    if (!Number.isSafeInteger(line) || line < 1 || line > lines.length)
         throw new Error("line is out of range");
     context.store.markUseful(context.store
         .allEntries()
@@ -70,16 +79,12 @@ export async function getEntry(context, file, line) {
     return { file: target, line, content: lines[line - 1] };
 }
 export async function forgetEntry(context, target) {
-    const file = target.file.startsWith("/")
-        ? target.file
-        : `${context.paths.stateRoot}/${target.file.replace(/^\/+/, "")}`;
-    if (!file.startsWith(context.paths.stateRoot))
-        throw new Error("path escapes memomatic state root");
+    const file = await memoryPath(context, target.file);
     const content = await readTextIfExists(file);
     if (content === undefined)
         throw new Error(`memory file not found: ${target.file}`);
     const lines = content.split("\n");
-    if (target.line < 1 || target.line > lines.length)
+    if (!Number.isSafeInteger(target.line) || target.line < 1 || target.line > lines.length)
         throw new Error("line is out of range");
     await replaceEntryLine(context.paths, file, target.line, null);
     return file;
@@ -90,20 +95,38 @@ export async function archiveOldEpisodic(context) {
         return archived;
     const rule = context.rules.autoClean;
     const cutoff = Date.now() - rule.olderThanDays * 86_400_000;
-    for (const entry of context.store.allEntries()) {
-        if (entry.kind !== "episodic" || !entry.observedAt || entry.observedAt >= cutoff)
-            continue;
-        if (rule.source && entry.source !== rule.source)
-            continue;
-        if (entry.pinned)
+    const files = new Set(context.store
+        .allEntries()
+        .filter((entry) => entry.kind === "episodic")
+        .map((entry) => entry.file));
+    for (const file of files) {
+        await memoryPath(context, file);
+        const content = await readTextIfExists(file);
+        if (content === undefined)
             continue;
-        if (!(await exists(entry.file)))
+        const selected = [];
+        const remaining = content.split("\n").filter((line) => {
+            const entry = parseEntryLine(line)?.annotations;
+            const observed = entry?.observed ? Date.parse(entry.observed) : NaN;
+            if (!entry ||
+                !Number.isFinite(observed) ||
+                observed >= cutoff ||
+                entry.pinned ||
+                (rule.source && entry.source !== rule.source))
+                return true;
+            selected.push(line);
+            return false;
+        });
+        if (!selected.length)
             continue;
-        const alreadyDone = archived.includes(entry.file);
-        if (!alreadyDone) {
-            await archiveFile(context.paths, entry.file);
-            archived.push(entry.file);
-        }
+        const target = join(context.paths.archiveDir, basename(file));
+        const prior = (await readTextIfExists(target)) ?? "";
+        const seen = new Set(prior.split("\n"));
+        await writeCorpusFile(context.paths, target, `${[prior.trimEnd(), ...selected.filter((line) => !seen.has(line))].filter(Boolean).join("\n")}\n`);
+        await writeCorpusFile(context.paths, file, remaining.join("\n"));
+        if (!remaining.some((line) => line.trim()))
+            await rm(file);
+        archived.push(file);
     }
     return archived;
 }

package/dist/store.d.ts

@@ -28,6 +28,9 @@ export declare class MemoryStore {
     private constructor();
     private migrate;
     static open(indexFile: string): Promise<MemoryStore>;
+    private static copy;
+    fork(): MemoryStore;
+    static preview(indexFile: string): Promise<MemoryStore>;
     private ensureFts;
     hasFts(): boolean;
     replaceEntries(entries: IndexedEntry[]): void;

package/dist/store.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { mkdir } from "node:fs/promises";
+import { mkdir, stat } from "node:fs/promises";
 import { dirname } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 export function stableIdFor(file, text, key) {
@@ -60,6 +60,44 @@ export class MemoryStore {
         await mkdir(dirname(indexFile), { mode: 0o700, recursive: true });
         return new MemoryStore(indexFile);
     }
+    static copy(database) {
+        const copy = new MemoryStore(":memory:");
+        try {
+            for (const table of ["entries", "usage", "vectors", "meta"]) {
+                for (const row of database.prepare(`SELECT * FROM ${table}`).all()) {
+                    const columns = Object.keys(row);
+                    copy.db
+                        .prepare(`INSERT INTO ${table} (${columns.join(",")}) VALUES (${columns.map(() => "?").join(",")})`)
+                        .run(...Object.values(row));
+                }
+            }
+            return copy;
+        }
+        catch (error) {
+            copy.close();
+            throw error;
+        }
+    }
+    fork() {
+        return MemoryStore.copy(this.db);
+    }
+    static async preview(indexFile) {
+        try {
+            await stat(indexFile);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return new MemoryStore(":memory:");
+            throw error;
+        }
+        const database = new DatabaseSync(indexFile, { readOnly: true });
+        try {
+            return MemoryStore.copy(database);
+        }
+        finally {
+            database.close();
+        }
+    }
     ensureFts() {
         try {
             this.db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS entries_fts USING fts5(stable_id UNINDEXED, text);");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kisev/memomatic",
-  "version": "1.0.0-dev.59.g0506803c61e5",
+  "version": "1.0.0-dev.61.gdf462654550b",
   "description": "Personal learning memory for agents: tiered Markdown corpus, rebuildable index, dream sweep.",
   "homepage": "https://github.com/kisev/skills#readme",
   "bugs": {
@@ -34,7 +34,7 @@
     "pack:check": "node test/pack-allowlist.mjs"
   },
   "dependencies": {
-    "@kisev/safe-fs": "1.0.0-dev.59.g0506803c61e5"
+    "@kisev/safe-fs": "1.0.0-dev.61.gdf462654550b"
   },
   "devDependencies": {
     "@types/node": "22.15.30",