@log0u7/opencode-memory 0.3.0 → 0.5.0

package/dist/lib/reflection.js

@@ -0,0 +1,130 @@
+/**
+ * Optional end-of-turn reflection: distills durable lessons from a session tail with
+ * one bounded LLM call and saves them as `lesson` entries. Best-effort by design:
+ * a disabled config wires nothing, a failing run is swallowed, and each session is
+ * reflected at most once.
+ */
+const MAX_LESSONS_DEFAULT = 3;
+const MAX_LESSONS_CAP = 10;
+const TRANSCRIPT_CHARS_DEFAULT = 8000;
+const TRANSCRIPT_CHARS_MIN = 500;
+const TRANSCRIPT_CHARS_MAX = 50000;
+const TIMEOUT_MS_DEFAULT = 60000;
+const TIMEOUT_MS_MIN = 1000;
+const TIMEOUT_MS_MAX = 600000;
+/** Below this much transcript there is nothing to distill; saves the LLM call. */
+const TRANSCRIPT_MIN_CHARS = 256;
+const MAX_TRACKED = 512;
+export function parseReflectionConfig(raw) {
+    if (raw === null || typeof raw !== "object" || raw.enabled !== true) {
+        return null;
+    }
+    const rawConfig = raw;
+    return {
+        enabled: true,
+        model: typeof rawConfig.model === "string" && rawConfig.model.includes("/")
+            ? rawConfig.model
+            : undefined,
+        maxLessons: clamp(rawConfig.maxLessons, 1, MAX_LESSONS_CAP, MAX_LESSONS_DEFAULT),
+        transcriptChars: clamp(rawConfig.transcriptChars, TRANSCRIPT_CHARS_MIN, TRANSCRIPT_CHARS_MAX, TRANSCRIPT_CHARS_DEFAULT),
+        timeoutMs: clamp(rawConfig.timeoutMs, TIMEOUT_MS_MIN, TIMEOUT_MS_MAX, TIMEOUT_MS_DEFAULT),
+    };
+}
+function clamp(value, min, max, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.min(max, Math.max(min, Math.round(value)));
+}
+export function distillPrompt(transcript, maxLessons) {
+    return (`You are the persistent-memory reflection for this project's OpenCode sessions. Below is the tail of one ` +
+        `coding session transcript. Extract at most ${maxLessons} durable, reusable lessons: non-obvious approaches ` +
+        `that clearly failed and why, non-obvious approaches that clearly worked and why, or constraints discovered ` +
+        `the hard way. Exclude anything trivially re-derivable from the code, anything session-specific, and any ` +
+        `credential. Reply with ONLY a JSON array, no markdown fences and no prose: ` +
+        `[{"title": "max 120 chars", "body": "the lesson, max 8000 chars"}]. Reply [] when nothing qualifies.\n\n` +
+        `SESSION TRANSCRIPT:\n${transcript}`);
+}
+export function parseLessons(text, max) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        const fenced = text
+            .replace(/^```(?:json)?/m, "")
+            .replace(/```$/m, "")
+            .trim();
+        try {
+            parsed = JSON.parse(fenced);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!Array.isArray(parsed)) {
+        return [];
+    }
+    const lessons = [];
+    for (const item of parsed.slice(0, max)) {
+        if (item === null || typeof item !== "object") {
+            continue;
+        }
+        const { title, body } = item;
+        if (typeof title !== "string" || typeof body !== "string" || !title.trim() || !body.trim()) {
+            continue;
+        }
+        lessons.push({ title: title.slice(0, 120), body: body.slice(0, 8000) });
+    }
+    return lessons;
+}
+export function createReflection(config, deps) {
+    const done = new Set();
+    const inFlight = new Set();
+    const run = async (sessionID) => {
+        // Only a session we actually tried to reflect is marked done. A too-short
+        // transcript leaves it unsettled, so a later, longer idle can still reflect it
+        // once: idle fires at the end of every turn, not once per session.
+        let settled = false;
+        try {
+            if (await deps.isSubagent(sessionID)) {
+                settled = true;
+                return;
+            }
+            const tail = (await deps.transcript(sessionID)).slice(-config.transcriptChars);
+            if (tail.length < Math.min(TRANSCRIPT_MIN_CHARS, config.transcriptChars)) {
+                return;
+            }
+            settled = true;
+            // Bound the LLM call: a hung provider must not wedge a session forever. The
+            // hosts forward this signal to the SDK, so the abort also unblocks their own
+            // cleanup (the v1 host deletes the ephemeral child session in its `finally`).
+            const reply = await deps.generate(distillPrompt(tail, config.maxLessons), sessionID, AbortSignal.timeout(config.timeoutMs));
+            for (const lesson of parseLessons(reply, config.maxLessons)) {
+                deps.saveLesson(lesson.title, lesson.body);
+            }
+        }
+        catch {
+            // Reflection is best-effort: never surface a failure to the host. A failed
+            // attempt still settles the session so a broken pipeline is not retried forever.
+            settled = true;
+        }
+        finally {
+            inFlight.delete(sessionID);
+            if (settled) {
+                done.add(sessionID);
+                if (done.size > MAX_TRACKED) {
+                    done.clear();
+                }
+            }
+        }
+    };
+    return (sessionID) => {
+        if (!sessionID || !config.enabled || done.has(sessionID) || inFlight.has(sessionID)) {
+            return;
+        }
+        inFlight.add(sessionID);
+        void run(sessionID);
+    };
+}
+//# sourceMappingURL=reflection.js.map

package/dist/lib/reflection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection.js","sourceRoot":"","sources":["../../src/lib/reflection.ts"],"names":[],"mappings":"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"}

package/dist/lib/sqlite.d.ts

@@ -5,5 +5,5 @@ export interface SqliteConn {
     exec(sql: string): void;
     close(): void;
 }
-export declare function openSqlite(path: string): SqliteConn;
+export declare function openSqlite(path: string, load?: (id: string) => unknown): SqliteConn;
 //# sourceMappingURL=sqlite.d.ts.map

package/dist/lib/sqlite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/lib/sqlite.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;IACvD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC5D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC3C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,IAAI,IAAI,CAAC;CACf;AAqED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAanD"}
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/lib/sqlite.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;IACvD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC5D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC3C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,IAAI,IAAI,CAAC;CACf;AAsED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAqB,GAAG,UAAU,CAQhG"}

package/dist/lib/sqlite.js

@@ -40,16 +40,19 @@ function createBunConn(db) {
         },
     };
 }
-// Open a sqlite connection with the runtime's bundled engine: bun:sqlite when
-// running inside OpenCode (Bun), node:sqlite when running under Node (tests, CI).
-export function openSqlite(path) {
-    const globalRuntime = globalThis;
-    if (globalRuntime.Bun) {
-        return createBunConn(new globalRuntime.Bun.sqlite.Database(path));
+// Open a sqlite connection with the runtime's bundled engine: bun:sqlite when running
+// inside OpenCode (Bun), node:sqlite when running under Node (tests, CI).
+// Bun 1.3 removed the Bun.sqlite global and ships the engine as the bun:sqlite module, so
+// the branch reads the runtime version and the module goes through the same createRequire
+// seam either way: the module exists in old and new Bun alike, and a bare require is not
+// defined in the ES module the plugin ships as.
+// The loader is a parameter so tests can supply the module on a runtime that lacks it.
+export function openSqlite(path, load = nodeRequire) {
+    if (process.versions.bun !== undefined) {
+        const { Database } = load("bun:sqlite");
+        return createBunConn(new Database(path));
     }
-    // node:sqlite ships with Node >= 22.5. createRequire keeps the load lazy for
-    // runtimes without node:sqlite: a bare require is not defined in an ES module.
-    const { DatabaseSync } = nodeRequire("node:sqlite");
+    const { DatabaseSync } = load("node:sqlite");
     return createPreparedConn(new DatabaseSync(path));
 }
 const nodeRequire = createRequire(import.meta.url);

package/dist/lib/sqlite.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/lib/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAgC5C,SAAS,kBAAkB,CAAC,EAAsB;IAChD,OAAO;QACL,GAAG,CAAc,GAAW,EAAE,MAAkB;YAC9C,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAQ,CAAC;QAC5C,CAAC;QACD,GAAG,CAAc,GAAW,EAAE,MAAkB;YAC9C,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC7B,OAAQ,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAmB,IAAI,IAAI,CAAC;QAChE,CAAC;QACD,GAAG,CAAC,GAAW,EAAE,MAAkB;YACjC,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,CAAC,GAAW;YACd,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;QACD,KAAK;YACH,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,EAAqB;IAC1C,OAAO;QACL,GAAG,CAAc,GAAW,EAAE,MAAkB;YAC9C,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAQ,CAAC;QACrD,CAAC;QACD,GAAG,CAAc,GAAW,EAAE,MAAkB;YAC9C,OAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAmB,IAAI,IAAI,CAAC;QACzE,CAAC;QACD,GAAG,CAAC,GAAW,EAAE,MAAkB;YACjC,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,GAAW;YACd,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,CAAC;QACD,KAAK;YACH,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,kFAAkF;AAClF,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,aAAa,GAAG,UAErB,CAAC;IAEF,IAAI,aAAa,CAAC,GAAG,EAAE,CAAC;QACtB,OAAO,aAAa,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACpE,CAAC;IAED,6EAA6E;IAC7E,+EAA+E;IAC/E,MAAM,EAAE,YAAY,EAAE,GAAG,WAAW,CAAC,aAAa,CAAsB,CAAC;IACzE,OAAO,kBAAkB,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC"}
+{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/lib/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA4B5C,SAAS,kBAAkB,CAAC,EAAsB;IAChD,OAAO;QACL,GAAG,CAAc,GAAW,EAAE,MAAkB;YAC9C,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAQ,CAAC;QAC5C,CAAC;QACD,GAAG,CAAc,GAAW,EAAE,MAAkB;YAC9C,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC7B,OAAQ,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAmB,IAAI,IAAI,CAAC;QAChE,CAAC;QACD,GAAG,CAAC,GAAW,EAAE,MAAkB;YACjC,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,CAAC,GAAW;YACd,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;QACD,KAAK;YACH,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,EAAqB;IAC1C,OAAO;QACL,GAAG,CAAc,GAAW,EAAE,MAAkB;YAC9C,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAQ,CAAC;QACrD,CAAC;QACD,GAAG,CAAc,GAAW,EAAE,MAAkB;YAC9C,OAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAmB,IAAI,IAAI,CAAC;QACzE,CAAC;QACD,GAAG,CAAC,GAAW,EAAE,MAAkB;YACjC,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,GAAW;YACd,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,CAAC;QACD,KAAK;YACH,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,0EAA0E;AAC1E,0FAA0F;AAC1F,0FAA0F;AAC1F,yFAAyF;AACzF,gDAAgD;AAChD,uFAAuF;AACvF,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,IAAI,GAA4B,WAAW;IAClF,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,YAAY,CAAqB,CAAC;QAC5D,OAAO,aAAa,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC,aAAa,CAAsB,CAAC;IAClE,OAAO,kBAAkB,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC"}

package/dist/lib/store.d.ts

@@ -12,6 +12,9 @@ export declare const DEFAULT_LIMIT: {
 };
 /** Scope used when no worktree and no directory is known, so rows stay addressable. */
 export declare const FALLBACK_SCOPE = "/";
+/** How long a trashed entry stays restorable before a sweep drops it for good. A
+ * recoverable delete is worthless if the trash itself grows without bound. */
+export declare const TRASH_RETENTION_MS: number;
 export declare class SecretDetectedError extends Error {
     constructor();
 }
@@ -33,9 +36,27 @@ export declare function renderEntries(entries: Entry[]): string;
 export declare function sweep(db: MemoryDb, options?: {
     now?: number;
 }): number;
+/** Whether a save inserted a row or rewrote the one already holding that scope and
+ * title, so a caller can tell the model what actually happened. */
+export type SaveResult = {
+    entry: Entry;
+    created: boolean;
+};
 export declare function save(db: MemoryDb, input: EntryInput, options?: {
     now?: number;
 }): Entry;
+export declare function saveEntry(db: MemoryDb, input: EntryInput, options?: {
+    now?: number;
+}): SaveResult;
+/**
+ * Fused search. The strict pass runs first and the prefix pass only fills what is left of
+ * the limit, so a query never loses the loose matches it used to discard: two entries
+ * holding every token answer a limit of ten with two results today.
+ *
+ * A strict hit contains every token by construction, so it is definitionally stronger
+ * than a prefix hit. Pinning strict above prefix is therefore the correct special case of
+ * reciprocal rank fusion, without the score arithmetic.
+ */
 export declare function search(db: MemoryDb, query: {
     query: string;
     scope: string;
@@ -46,6 +67,7 @@ export declare function list(db: MemoryDb, query: {
     scope: string;
     limit?: number;
     now?: number;
+    kind?: string;
 }): Entry[];
 export type ForgetTarget = {
     scope: string;
@@ -54,10 +76,35 @@ export type ForgetTarget = {
 } | {
     query: string;
 });
+/** Counts by kind for one scope plus `global`, expired entries excluded. */
+export declare function stats(db: MemoryDb, query: {
+    scope: string;
+    now?: number;
+}): Array<{
+    kind: string;
+    count: number;
+}>;
+/** Creation date of the oldest live entry in one scope plus `global`, or null when the
+ * scope is empty: the store grows without bound, so age is the signal that knowledge is
+ * rotting rather than accumulating. */
+export declare function oldestCreated(db: MemoryDb, query: {
+    scope: string;
+    now?: number;
+}): number | null;
 /**
- * Deletes inside one scope (plus the shared `global` scope), never across the whole
- * machine: the store is shared, so an unscoped delete would silently hit other
- * projects.
+ * Query deletes stay inside one scope (plus the shared `global` scope): a fuzzy match
+ * must never silently hit other projects' entries. Id deletes are machine-wide because
+ * the id is globally unique: closed worktrees stay cleanable from any project.
+ *
+ * Both forms trash instead of dropping, so a wrong delete is recoverable, and both report
+ * the entries they moved: a broad query can take many rows at once, and the caller has to
+ * be able to say which ones. Only live rows count, so a second delete of the same target
+ * is a no-op.
  */
-export declare function forget(db: MemoryDb, target: ForgetTarget): number;
+export declare function forget(db: MemoryDb, target: ForgetTarget): Entry[];
+/** Puts a trashed entry back into every read. Machine-wide by id, mirroring the delete it
+ * undoes; `null` when the id is not in the trash. */
+export declare function restore(db: MemoryDb, target: {
+    id: string;
+}): Entry | null;
 //# sourceMappingURL=store.d.ts.map

package/dist/lib/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/lib/store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAK3D,eAAO,MAAM,OAAO,KAAK,CAAC;AAC1B,eAAO,MAAM,QAAQ,KAAK,CAAC;AAC3B,sFAAsF;AACtF,eAAO,MAAM,SAAS,KAAK,CAAC;AAC5B,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,eAAO,MAAM,aAAa;IAAK,MAAM;IAAM,IAAI;CAAM,CAAC;AAEtD,uFAAuF;AACvF,eAAO,MAAM,cAAc,MAAM,CAAC;AAQlC,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,cAGC;CACF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,UAAU,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,CAM/E;AA+BD;;yBAEyB;AACzB,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKlF;AASD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,CAEtD;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAI1E;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,KAAK,CAuE3F;AAED,wBAAgB,MAAM,CACpB,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE,KAAK,EAAE,CAqBT;AAED,wBAAgB,IAAI,CAClB,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD,KAAK,EAAE,CAcT;AAED,MAAM,MAAM,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEpF;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAwBjE"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/lib/store.ts"],"names":[],"mappings":"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"}

package/dist/lib/store.js

@@ -11,10 +11,32 @@ export const BODY_PREVIEW_MAX = 500;
 export const DEFAULT_LIMIT = { search: 10, list: 20 };
 /** Scope used when no worktree and no directory is known, so rows stay addressable. */
 export const FALLBACK_SCOPE = "/";
+/** How long a trashed entry stays restorable before a sweep drops it for good. A
+ * recoverable delete is worthless if the trash itself grows without bound. */
+export const TRASH_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/** Live rows only: a trashed entry is invisible to every read until it is restored. */
+const LIVE = "deleted_at IS NULL";
+// High-confidence credential formats only: a generic "password =" rule would block
+// ordinary prose. Extend with care, one false positive costs a legitimate save.
+// The three patterns whose tail class allows `_` or `-` (github_pat_, gl(pat|rt)- and
+// ya29.) demand a digit or an uppercase letter in the tail: without it, a sentence written
+// as one long token after the prefix is refused as a credential. The older sk-, AIza and
+// xox[ap]- patterns keep their original shape and carry the same false-positive class;
+// left as they are to keep this change focused.
 const SECRET_PATTERNS = [
-    /\bsk-[A-Za-z0-9_-]{20,}\b/,
-    /\bghp_[A-Za-z0-9]{30,}\b/,
-    /\bxoxb-\d{10,}-\d{10,}\b/,
+    /\bsk-[A-Za-z0-9_-]{20,}\b/, // OpenAI-style, also covers Anthropic sk-ant- keys
+    /\bgh[posur]_[A-Za-z0-9]{30,}\b/, // GitHub PAT, OAuth, server-to-server, user-to-server, refresh
+    /\bgithub_pat_(?=[A-Za-z0-9_]*[0-9A-Z])[A-Za-z0-9_]{22,}\b/, // GitHub fine-grained PAT
+    /\bxoxb-\d{10,}-\d{10,}\b/, // Slack bot token
+    /\bxox[ap]-[0-9A-Za-z-]{10,}/, // Slack user / app token
+    /https:\/\/hooks\.slack\.com\/services\/T[A-Za-z0-9]+/, // Slack incoming webhook
+    /\bA(?:K|S)IA[0-9A-Z]{16}\b/, // AWS access key id, long-lived and temporary
+    /\bgl(?:pat|rt)-(?=[0-9A-Za-z_-]*[0-9A-Z])[0-9A-Za-z_-]{20,}\b/, // GitLab PAT and rotate token
+    /\bnpm_[A-Za-z0-9]{36}\b/, // npm granular token
+    /\bAIza[0-9A-Za-z_-]{35}/, // Google API key
+    /\bya29\.(?=[0-9A-Za-z_-]*[0-9A-Z])[0-9A-Za-z_-]{20,}\b/, // Google OAuth access token
+    /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/, // JWT
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/, // PEM private key block header
 ];
 export class SecretDetectedError extends Error {
     constructor() {
@@ -86,9 +108,19 @@ export function renderEntries(entries) {
 export function sweep(db, options = {}) {
     const now = options.now ?? Date.now();
     db.conn.run("DELETE FROM entries WHERE expires_at IS NOT NULL AND expires_at <= ?", [now]);
+    const expired = changesOf(db);
+    db.conn.run("DELETE FROM entries WHERE deleted_at IS NOT NULL AND deleted_at <= ?", [
+        now - TRASH_RETENTION_MS,
+    ]);
+    return expired + changesOf(db);
+}
+function changesOf(db) {
     return db.conn.get("SELECT changes() AS changes")?.changes ?? 0;
 }
 export function save(db, input, options = {}) {
+    return saveEntry(db, input, options).entry;
+}
+export function saveEntry(db, input, options = {}) {
     validateEntry(input);
     const scope = canonicalScope(input.scope);
     const now = options.now ?? Date.now();
@@ -100,30 +132,35 @@ export function save(db, input, options = {}) {
     // different case is not deduped; and the read-then-write is not transactional, so two
     // concurrent saves of the same title can both insert. Ceiling is a rare duplicate, not
     // data loss. Upgrade path: a normalized key column plus BEGIN IMMEDIATE.
-    const existing = db.conn.get("SELECT id, created_at FROM entries WHERE scope = ? AND lower(trim(title)) = ?", [scope, input.title.trim().toLowerCase()]);
+    const existing = db.conn.get(`SELECT id, created_at FROM entries WHERE scope = ? AND lower(trim(title)) = ? AND ${LIVE}`, [scope, input.title.trim().toLowerCase()]);
     if (existing) {
-        db.conn.run("UPDATE entries SET kind = ?, body = ?, tags = ?, updated_at = ?, expires_at = ? WHERE id = ?", [
+        db.conn.run("UPDATE entries SET kind = ?, body = ?, tags = ?, updated_at = ?, expires_at = ?, source = ? WHERE id = ?", [
             input.kind,
             input.body,
             JSON.stringify(input.tags),
             now,
             input.expires_at ?? null,
+            input.source ?? null,
             existing.id,
         ]);
         return {
-            id: existing.id,
-            scope,
-            kind: input.kind,
-            title: input.title,
-            body: input.body,
-            tags: input.tags,
-            created_at: existing.created_at,
-            updated_at: now,
-            expires_at: input.expires_at,
+            entry: {
+                id: existing.id,
+                scope,
+                kind: input.kind,
+                title: input.title,
+                body: input.body,
+                tags: input.tags,
+                created_at: existing.created_at,
+                updated_at: now,
+                expires_at: input.expires_at,
+                ...(input.source !== undefined ? { source: input.source } : {}),
+            },
+            created: false,
         };
     }
     const id = randomUUID();
-    db.conn.run("INSERT INTO entries (id, scope, kind, title, body, tags, created_at, updated_at, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)", [
+    db.conn.run("INSERT INTO entries (id, scope, kind, title, body, tags, created_at, updated_at, expires_at, source) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", [
         id,
         scope,
         input.kind,
@@ -133,75 +170,141 @@ export function save(db, input, options = {}) {
         now,
         now,
         input.expires_at,
+        input.source ?? null,
     ]);
     return {
-        id,
-        scope,
-        kind: input.kind,
-        title: input.title,
-        body: input.body,
-        tags: input.tags,
-        created_at: now,
-        updated_at: now,
-        expires_at: input.expires_at,
+        entry: {
+            id,
+            scope,
+            kind: input.kind,
+            title: input.title,
+            body: input.body,
+            tags: input.tags,
+            created_at: now,
+            updated_at: now,
+            expires_at: input.expires_at,
+            ...(input.source !== undefined ? { source: input.source } : {}),
+        },
+        created: true,
     };
 }
+/**
+ * Fused search. The strict pass runs first and the prefix pass only fills what is left of
+ * the limit, so a query never loses the loose matches it used to discard: two entries
+ * holding every token answer a limit of ten with two results today.
+ *
+ * A strict hit contains every token by construction, so it is definitionally stronger
+ * than a prefix hit. Pinning strict above prefix is therefore the correct special case of
+ * reciprocal rank fusion, without the score arithmetic.
+ */
 export function search(db, query) {
     const scope = canonicalScope(query.scope);
     const limit = clampLimit(query.limit, DEFAULT_LIMIT.search);
     const now = query.now ?? Date.now();
+    const hits = [];
+    const seen = new Set();
     for (const match of searchCandidates(query.query)) {
-        const hits = db.conn
-            .all(`SELECT e.* FROM entries_fts JOIN entries e ON e.rowid = entries_fts.rowid
-         WHERE entries_fts MATCH ? AND (e.scope = ? OR e.scope = 'global')
-           AND (e.expires_at IS NULL OR e.expires_at > ?)
-         ORDER BY bm25(entries_fts) ASC, e.updated_at DESC
-         LIMIT ?`, [match, scope, now, limit])
-            .map(rowToEntry);
-        if (hits.length > 0) {
-            return hits;
+        for (const entry of ftsHits(db, match, scope, now, limit)) {
+            if (!seen.has(entry.id)) {
+                seen.add(entry.id);
+                hits.push(entry);
+            }
+        }
+        if (hits.length >= limit) {
+            break;
         }
     }
-    return [];
+    return hits.slice(0, limit);
+}
+function ftsHits(db, match, scope, now, limit) {
+    return db.conn
+        .all(`SELECT e.* FROM entries_fts JOIN entries e ON e.rowid = entries_fts.rowid
+       WHERE entries_fts MATCH ? AND (e.scope = ? OR e.scope = 'global')
+         AND (e.expires_at IS NULL OR e.expires_at > ?) AND e.${LIVE}
+       ORDER BY bm25(entries_fts) ASC, e.updated_at DESC
+       LIMIT ?`, [match, scope, now, limit])
+        .map(rowToEntry);
 }
 export function list(db, query) {
     const scope = canonicalScope(query.scope);
     const limit = clampLimit(query.limit, DEFAULT_LIMIT.list);
     const now = query.now ?? Date.now();
+    const kindFilter = query.kind === undefined ? "" : "AND kind = ? ";
+    const kindArgs = query.kind === undefined ? [] : [query.kind];
     return db.conn
         .all(`SELECT * FROM entries
-       WHERE (scope = ? OR scope = 'global') AND (expires_at IS NULL OR expires_at > ?)
+       WHERE (scope = ? OR scope = 'global') AND (expires_at IS NULL OR expires_at > ?) ${kindFilter}
+         AND ${LIVE}
        ORDER BY updated_at DESC, id ASC
-       LIMIT ?`, [scope, now, limit])
+       LIMIT ?`, [scope, now, ...kindArgs, limit])
         .map(rowToEntry);
 }
+/** Counts by kind for one scope plus `global`, expired entries excluded. */
+export function stats(db, query) {
+    const scope = canonicalScope(query.scope);
+    const now = query.now ?? Date.now();
+    return db.conn.all(`SELECT kind, COUNT(*) AS count FROM entries
+     WHERE (scope = ? OR scope = 'global') AND (expires_at IS NULL OR expires_at > ?) AND ${LIVE}
+     GROUP BY kind ORDER BY count DESC, kind ASC`, [scope, now]);
+}
+/** Creation date of the oldest live entry in one scope plus `global`, or null when the
+ * scope is empty: the store grows without bound, so age is the signal that knowledge is
+ * rotting rather than accumulating. */
+export function oldestCreated(db, query) {
+    const scope = canonicalScope(query.scope);
+    const now = query.now ?? Date.now();
+    const row = db.conn.get(`SELECT MIN(created_at) AS oldest FROM entries
+     WHERE (scope = ? OR scope = 'global') AND (expires_at IS NULL OR expires_at > ?) AND ${LIVE}`, [scope, now]);
+    return row?.oldest ?? null;
+}
 /**
- * Deletes inside one scope (plus the shared `global` scope), never across the whole
- * machine: the store is shared, so an unscoped delete would silently hit other
- * projects.
+ * Query deletes stay inside one scope (plus the shared `global` scope): a fuzzy match
+ * must never silently hit other projects' entries. Id deletes are machine-wide because
+ * the id is globally unique: closed worktrees stay cleanable from any project.
+ *
+ * Both forms trash instead of dropping, so a wrong delete is recoverable, and both report
+ * the entries they moved: a broad query can take many rows at once, and the caller has to
+ * be able to say which ones. Only live rows count, so a second delete of the same target
+ * is a no-op.
  */
 export function forget(db, target) {
-    const scope = canonicalScope(target.scope);
-    if ("id" in target) {
-        db.conn.run("DELETE FROM entries WHERE id = ? AND (scope = ? OR scope = 'global')", [
-            target.id,
-            scope,
-        ]);
-        return changesOf(db);
+    const trashed = "id" in target
+        ? db.conn.all(`SELECT * FROM entries WHERE id = ? AND ${LIVE}`, [target.id])
+        : trashedByQuery(db, target);
+    if (trashed.length === 0) {
+        return [];
     }
+    const now = Date.now();
+    const ids = trashed.map((row) => row.id);
+    db.conn.run(`UPDATE entries SET deleted_at = ? WHERE id IN (${ids.map(() => "?").join(", ")})`, [
+        now,
+        ...ids,
+    ]);
+    return trashed.map(rowToEntry);
+}
+/** Puts a trashed entry back into every read. Machine-wide by id, mirroring the delete it
+ * undoes; `null` when the id is not in the trash. */
+export function restore(db, target) {
+    const row = db.conn.get(`SELECT * FROM entries WHERE id = ? AND deleted_at IS NOT NULL`, [
+        target.id,
+    ]);
+    if (row === null) {
+        return null;
+    }
+    db.conn.run("UPDATE entries SET deleted_at = NULL WHERE id = ?", [target.id]);
+    return rowToEntry(row);
+}
+function trashedByQuery(db, target) {
+    const scope = canonicalScope(target.scope);
     // Deleting is precision-first: only the strict all-token match, never the fuzzy
-    // fallback. A wrong read costs the model a retry, a wrong delete is unrecoverable.
+    // fallback. A wrong read costs the model a retry, a wrong delete used to be
+    // unrecoverable; it now costs a restore.
     const match = strictMatch(target.query);
     if (match === null) {
-        return 0;
+        return [];
     }
-    db.conn.run(`DELETE FROM entries WHERE id IN (
-       SELECT e.id FROM entries_fts JOIN entries e ON e.rowid = entries_fts.rowid WHERE entries_fts MATCH ?
-     ) AND (scope = ? OR scope = 'global')`, [match, scope]);
-    return changesOf(db);
-}
-function changesOf(db) {
-    return db.conn.get("SELECT changes() AS changes")?.changes ?? 0;
+    return db.conn.all(`SELECT e.* FROM entries_fts JOIN entries e ON e.rowid = entries_fts.rowid
+     WHERE entries_fts MATCH ? AND (e.scope = ? OR e.scope = 'global') AND e.${LIVE}`, [match, scope]);
 }
 function rowToEntry(row) {
     return {
@@ -214,6 +317,7 @@ function rowToEntry(row) {
         created_at: row.created_at,
         updated_at: row.updated_at,
         expires_at: row.expires_at,
+        ...(row.source !== null ? { source: row.source } : {}),
     };
 }
 function parseTags(raw) {
@@ -227,8 +331,8 @@ function parseTags(raw) {
 }
 /**
  * FTS5 candidates, most precise first, each quoted so arbitrary model input stays a
- * literal search. The strict AND match is tried before the looser prefix OR match:
- * recall matters more than precision once the strict match found nothing.
+ * literal search. The strict AND match is fused ahead of the looser prefix OR match:
+ * precision leads, recall fills what is left of the limit.
  */
 function searchCandidates(raw) {
     const strict = strictMatch(raw);