@oharness/engine 0.12.0 → 0.14.0

package/dist/agent/memory-dream.js

@@ -0,0 +1,237 @@
+import { MEMORY_SAFETY, isMemoryType } from "./memory-limits.js";
+import { rankNotes } from "./memory-recall.js";
+import { redactSecrets } from "./memory-redact.js";
+export const DREAM_PROMPT = `You maintain the durable notes an assistant reads in future sessions. You are given new claims taken from recent conversations, with the evidence for each, and the existing notes they may touch. Propose the smallest set of edits that makes the notes true and useful.
+
+Operations:
+- "create": a new note from one or more claims that no existing note covers.
+- "update": rewrite one existing note because claims correct or extend it. Write the complete new body, keeping every detail of the old body that is still true.
+- "merge": several existing notes say the same thing; write the one note that replaces them.
+- "stale": a note's content has lapsed (a date passed, work finished) according to the claims. Do not rewrite it.
+- "conflict": claims contradict a note and nobody said which one replaces the other. Do not choose; explain.
+
+Rules:
+- Cite the claims each operation rests on by id. Every operation except "merge" must cite at least one claim.
+- Only touch notes listed below, by their id.
+- Newer evidence is the claim's time, never a note's "last edited" time. Replace a note's statement only when a claim says the user replaced it.
+- Never turn a plan into a completed fact because its date passed.
+- If claims add nothing, leave them out. Proposing nothing is a good outcome.
+- Create a note only for something a later conversation would need: a preference, a correction, a decision and its reason, an ongoing goal. Never for the specification of one task (its columns, steps or format).
+
+How a note is written, because recall matches words, not meaning:
+- "summary": one concrete line naming what the note is about.
+- "tags": the words someone might search with instead of the summary's own, including synonyms and the term in the other language in use. A merge keeps every tag of the notes it combines unless one is plainly wrong.
+- "body": the fact, then a line starting "Why:" and a line starting "How to apply:".
+- A note that has been recalled often is revised conservatively: keep its summary's key words and its tags unless the evidence says they are wrong.
+
+Respond with a JSON array and nothing else. Each element is one of:
+{"op":"create","scope":"project"|"user","claims":["<claim id>"],"summary":"...","body":"...","tags":["..."],"type":"user"|"feedback"|"project"|"reference"}
+{"op":"update","id":"<note id>","claims":["..."],"summary":"...","body":"...","tags":["..."],"type":"..."}
+{"op":"merge","ids":["<note id>","<note id>"],"claims":["..."],"summary":"...","body":"...","tags":["..."],"type":"..."}
+{"op":"stale","id":"<note id>","claims":["..."],"reason":"..."}
+{"op":"conflict","id":"<note id>","claims":["..."],"reason":"..."}
+
+Return [] when nothing should change.`;
+const when = (at) => new Date(at).toISOString().slice(0, 10);
+/** The prompt for one scope: claims with their evidence, notes with their history. */
+export function dreamPrompt(claims, notes, now = Date.now()) {
+    const claimBlocks = claims.map((claim) => {
+        const extra = [
+            `kind=${claim.kind}`, `said=${when(claim.at)}`, `scope=${claim.scope}`, `session=${claim.session}`,
+            claim.validUntil ? `validUntil=${when(claim.validUntil)}` : "",
+            claim.supersedes ? `supersedes="${claim.supersedes}"` : "",
+            claim.lasting ? "lasting=yes" : "",
+            claim.inContext?.length ? `noteInContext=${claim.inContext.join(",")}` : "",
+        ].filter(Boolean).join(" ");
+        return `<claim id="${claim.id}" ${extra}>\n${claim.text}${claim.quote ? `\nUser's words: "${claim.quote}"` : ""}\n</claim>`;
+    });
+    const noteBlocks = notes.map((note) => {
+        const meta = [
+            `id=${note.id}`, `scope=${note.scope}`, note.type ? `type=${note.type}` : "",
+            `lastEdited=${when(note.updatedAt ?? note.createdAt)}`,
+            note.recalled ? `recalled=${note.recalled.count}x,last=${when(note.recalled.last)}` : "recalled=never",
+            note.tags.length ? `tags=${note.tags.join(",")}` : "",
+        ].filter(Boolean).join(" ");
+        return `<note ${meta}>\n${note.summary}\n\n${note.body}\n</note>`;
+    });
+    return [
+        `Today is ${when(now)}.`,
+        "",
+        "New claims:",
+        claimBlocks.join("\n\n") || "(none)",
+        "",
+        "Existing notes you may touch:",
+        noteBlocks.join("\n\n") || "(none)",
+        "",
+        "Propose the edits now, as a JSON array.",
+    ].join("\n");
+}
+/**
+ * The notes a dream may touch: those most related to each claim, and every
+ * note a claim says was recalled when it was made, whether or not the ranker
+ * finds it. Bodies are shown in full, so the set is bounded.
+ */
+export function chooseNotes(claims, notes, limit = 12, bodyBudget = 24_000) {
+    const byId = new Map(notes.map((note) => [`${note.scope}:${note.id}`, note]));
+    const chosen = new Map();
+    const take = (note) => {
+        if (!note || chosen.has(`${note.scope}:${note.id}`) || chosen.size >= limit)
+            return;
+        if (note.body.length > bodyBudget)
+            return;
+        bodyBudget -= note.body.length;
+        chosen.set(`${note.scope}:${note.id}`, note);
+    };
+    for (const claim of claims)
+        for (const id of claim.inContext ?? [])
+            take(byId.get(`${claim.scope}:${id}`) ?? byId.get(`project:${id}`) ?? byId.get(`user:${id}`));
+    for (const claim of claims)
+        for (const ranked of rankNotes(notes, claim.text).slice(0, 3))
+            take(ranked.note);
+    return [...chosen.values()];
+}
+function cleanTags(tags) {
+    if (!Array.isArray(tags))
+        return [];
+    const out = [];
+    for (const tag of tags) {
+        if (typeof tag !== "string")
+            continue;
+        const value = tag.trim().toLowerCase();
+        if (MEMORY_SAFETY.tagPattern.test(value) && !out.includes(value))
+            out.push(value);
+        if (out.length >= MEMORY_SAFETY.maxTags)
+            break;
+    }
+    return out;
+}
+function draft(value) {
+    const summary = typeof value.summary === "string" ? redactSecrets(value.summary.replace(/[\r\n]+/g, " ").trim()).text : "";
+    const body = typeof value.body === "string" ? redactSecrets(value.body.trim()).text : "";
+    if (summary.length < 4 || summary.length > MEMORY_SAFETY.maxSummaryChars || body.length < 4)
+        return undefined;
+    return { summary, body, tags: cleanTags(value.tags), ...(isMemoryType(value.type) ? { type: value.type } : {}) };
+}
+const text = (value, max) => typeof value === "string" ? redactSecrets(value.replace(/\s+/g, " ").trim()).text.slice(0, max) : "";
+/**
+ * Validate a dream reply against what it was shown. Operations on notes it
+ * was not shown, citing claims it was not given, or crossing scopes are
+ * dropped; so is a second operation on a note already touched.
+ */
+export function parseDreamOps(reply, claims, notes) {
+    const start = reply.indexOf("["), end = reply.lastIndexOf("]");
+    if (start === -1 || end <= start)
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(reply.slice(start, end + 1));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(raw))
+        return [];
+    const claimById = new Map(claims.map((claim) => [claim.id, claim]));
+    const noteById = new Map(notes.map((note) => [note.id, note]));
+    const touched = new Set();
+    const ops = [];
+    for (const item of raw.slice(0, 30)) {
+        if (!item || typeof item !== "object")
+            continue;
+        const value = item;
+        const cited = Array.isArray(value.claims)
+            ? [...new Set(value.claims.filter((id) => typeof id === "string" && claimById.has(id)))]
+            : [];
+        const target = typeof value.id === "string" ? noteById.get(value.id) : undefined;
+        const fresh = (note) => !!note && !touched.has(note.id);
+        // A claim about one scope cannot change a note in another.
+        const sameScope = (scope) => cited.every((id) => claimById.get(id).scope === scope);
+        if (value.op === "create") {
+            const body = draft(value);
+            if (!body || !cited.length)
+                continue;
+            const scope = claimById.get(cited[0]).scope;
+            if (!sameScope(scope))
+                continue;
+            ops.push({ op: "create", scope, claims: cited, ...body });
+        }
+        else if (value.op === "update") {
+            const body = draft(value);
+            if (!body || !cited.length || !fresh(target) || !sameScope(target.scope))
+                continue;
+            touched.add(target.id);
+            ops.push({ op: "update", id: target.id, scope: target.scope, claims: cited, expectedHash: target.hash, ...body, ...(body.type ?? target.type ? { type: body.type ?? target.type } : {}) });
+        }
+        else if (value.op === "merge") {
+            const body = draft(value);
+            const ids = Array.isArray(value.ids) ? [...new Set(value.ids.filter((id) => typeof id === "string"))] : [];
+            const group = ids.map((id) => noteById.get(id));
+            if (!body || group.length < 2 || group.length > 6 || !group.every(fresh))
+                continue;
+            const scope = group[0].scope;
+            if (!group.every((note) => note.scope === scope) || !sameScope(scope))
+                continue;
+            for (const note of group)
+                touched.add(note.id);
+            ops.push({ op: "merge", ids: group.map((note) => note.id), scope, claims: cited, expectedHashes: group.map((note) => note.hash), ...body });
+        }
+        else if (value.op === "stale" || value.op === "conflict") {
+            const reason = text(value.reason, 300);
+            if (!cited.length || !reason || !fresh(target) || !sameScope(target.scope))
+                continue;
+            touched.add(target.id);
+            ops.push({ op: value.op, id: target.id, scope: target.scope, claims: cited, reason, expectedHash: target.hash });
+        }
+    }
+    return ops;
+}
+const DIRECT = new Set(["stated", "confirmed"]);
+/**
+ * Whether an operation may be applied without asking. Conservative by
+ * design: an inference from one conversation, a user-wide preference drawn
+ * from inference, anything about lapsed or contradicted notes, and edits to
+ * notes changed by hand since a dream last wrote them all wait for a person.
+ *
+ * `dreamWrote` maps a note id to the hash a dream last left it at, when one did.
+ */
+export function dispose(op, claims, dreamWrote = new Map()) {
+    if (op.op === "stale")
+        return { op, disposition: "review", why: "stale" };
+    if (op.op === "conflict")
+        return { op, disposition: "review", why: "conflict" };
+    const byId = new Map(claims.map((claim) => [claim.id, claim]));
+    const cited = op.claims.map((id) => byId.get(id)).filter((claim) => !!claim);
+    const targets = op.op === "update" ? [{ id: op.id, hash: op.expectedHash }]
+        : op.op === "merge" ? op.ids.map((id, i) => ({ id, hash: op.expectedHashes[i] })) : [];
+    if (targets.some((target) => dreamWrote.has(target.id) && dreamWrote.get(target.id) !== target.hash)) {
+        return { op, disposition: "review", why: "hand-edited" };
+    }
+    if (op.op === "merge" && !cited.length)
+        return { op, disposition: "apply" };
+    const sessions = new Set(cited.map((claim) => claim.session));
+    const inferred = cited.filter((claim) => !DIRECT.has(claim.kind));
+    if (inferred.length) {
+        if (op.scope === "user")
+            return { op, disposition: "review", why: "user-scope-inference" };
+        if (sessions.size < 2)
+            return { op, disposition: "review", why: "inferred-once" };
+    }
+    // A new note is the riskiest change: most of what one conversation says is
+    // about that conversation. It applies on its own only when the user said it
+    // lasts, or more than one conversation says it.
+    if (op.op === "create" && sessions.size < 2 && !cited.some((claim) => claim.lasting)) {
+        return { op, disposition: "review", why: "one-conversation" };
+    }
+    return { op, disposition: "apply" };
+}
+/** One model call for one scope. Writes nothing. */
+export async function dreamScope(run) {
+    if (!run.claims.length)
+        return { ops: [], shown: [], chars: 0 };
+    const shown = chooseNotes(run.claims, run.notes);
+    const prompt = dreamPrompt(run.claims, shown, run.now);
+    const reply = await run.generate(DREAM_PROMPT, prompt, run.signal);
+    const ops = parseDreamOps(reply, run.claims, shown).map((op) => dispose(op, run.claims, run.dreamWrote));
+    return { ops, shown, chars: DREAM_PROMPT.length + prompt.length + reply.length };
+}
+//# sourceMappingURL=memory-dream.js.map

package/dist/agent/memory-dream.js.map

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

package/dist/agent/memory-ledger.d.ts

@@ -0,0 +1,154 @@
+import type { DigestClaim } from "./memory-digest.ts";
+import type { MemoryNote } from "./memory.ts";
+/**
+ * What dreaming keeps on this machine, beside the notes and never in them.
+ *
+ * - `digests/<session>.jsonl`: the claims each conversation produced.
+ * - `cursors.json`: which messages of each conversation have been read.
+ * - `ledger/<scope>.jsonl`: runs, proposals and, later, applied changes.
+ * - `state.json`: the day's model budget and when each scope last dreamed.
+ *
+ * Machine-local like recall counts: none of it syncs, so another device sees
+ * a dreamed note but not why it was written. Nothing here is read by recall.
+ */
+export interface StoredClaim extends DigestClaim {
+    /** The project the conversation belonged to, for project-scope claims. */
+    project: string;
+}
+/** A claim as kept with a change, so the change can show its evidence after the claim is consumed. */
+export interface EvidenceSnapshot {
+    id: string;
+    kind: string;
+    text: string;
+    quote?: string;
+    at: number;
+}
+/** A note as it was before a change, or null when the change created it. */
+export interface NoteBefore {
+    id: string;
+    note: MemoryNote | null;
+}
+/** One change a dream wrote, enough to show it and to undo it. */
+export interface AppliedChange {
+    id: string;
+    op: "create" | "update" | "merge";
+    summary: string;
+    before: NoteBefore[];
+    after: Array<{
+        id: string;
+        hash: string | null;
+    }>;
+    evidence: EvidenceSnapshot[];
+    /** Set when it came from a suggestion a person applied. */
+    fromProposal?: string;
+    /** The run that made it. */
+    run?: string;
+}
+/** One pass of dreaming over a project, for its history. */
+export interface RunRecord {
+    id: string;
+    at: number;
+    trigger: "auto" | "manual";
+    seconds: number;
+    digested: number;
+    applied: number;
+    proposals: number;
+    /** Ids of the changes it applied. */
+    changes: string[];
+    /** As the provider reported them; input includes cached prompt tokens. */
+    tokens: {
+        input: number;
+        output: number;
+    };
+    costUsd: number;
+    model?: string;
+    outcome: "changed" | "suggested" | "nothing" | "no-call" | "refused" | "failed" | "budget";
+    errors: string[];
+}
+export type LedgerEvent = {
+    type: "preview";
+    at: number;
+    scope: string;
+    claims: number;
+    ops: unknown[];
+    chars: number;
+} | {
+    type: "consumed";
+    at: number;
+    claims: string[];
+} | {
+    type: "applied";
+    at: number;
+    scope: string;
+    changes: AppliedChange[];
+} | {
+    type: "proposal";
+    at: number;
+    scope: string;
+    id: string;
+    op: unknown;
+    why?: string;
+    evidence: EvidenceSnapshot[];
+} | {
+    type: "proposal-state";
+    at: number;
+    id: string;
+    state: "applied" | "dismissed" | "stale";
+} | {
+    type: "undone";
+    at: number;
+    change: string;
+} | {
+    type: "failed";
+    at: number;
+    scope: string;
+    error: string;
+};
+/** Today, in this machine's calendar. */
+export declare function localDay(at?: number): string;
+export declare class DreamStore {
+    private readonly fixedRoot?;
+    private writing;
+    constructor(root?: string);
+    /**
+     * Resolved on use, not at construction: the process's store is built when
+     * the module loads, before a test or fixture has pointed `OHARNESS_HOME`
+     * somewhere else, and fixing the path then would write into the real home.
+     */
+    get root(): string;
+    /** Writes one at a time: two passes in one process never interleave a file. */
+    private serial;
+    private readJson;
+    private writeJson;
+    private readLines;
+    private append;
+    digested(session: string): Promise<Set<string>>;
+    /**
+     * Claims first, cursor after: a crash between the two reads the stretch
+     * again rather than losing it, and the claim ids it produces are the same,
+     * so `claims()` holds each once.
+     */
+    recordDigest(session: string, project: string, claims: readonly DigestClaim[], keys: readonly string[]): Promise<void>;
+    /** A deleted conversation takes its claims and its cursor with it. */
+    dropSession(session: string): Promise<void>;
+    /**
+     * Claims not yet consumed, for one scope: a project's (by its id) or the
+     * user's own. Oldest first, each id once.
+     */
+    claims(scope: {
+        scope: "user";
+    } | {
+        scope: "project";
+        project: string;
+    }, ledgerKey: string): Promise<StoredClaim[]>;
+    ledger(key: string): Promise<LedgerEvent[]>;
+    record(key: string, event: LedgerEvent): Promise<void>;
+    /** Tokens spent on model calls today, as providers reported them. */
+    spentToday(now?: number): Promise<number>;
+    spend(tokens: number, now?: number): Promise<void>;
+    recordRun(project: string, run: RunRecord): Promise<void>;
+    /** A project's runs, newest first. */
+    runs(project: string, limit?: number): Promise<RunRecord[]>;
+    dreamedToday(key: string, now?: number): Promise<boolean>;
+    markDreamed(key: string, now?: number): Promise<void>;
+}

package/dist/agent/memory-ledger.js

@@ -0,0 +1,179 @@
+import { appendFile, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { userPath } from "../paths.js";
+import { renameWithRetry } from "../util/fs.js";
+/** Today, in this machine's calendar. */
+export function localDay(at = Date.now()) {
+    const d = new Date(at);
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+const fileKey = (value) => createHash("sha256").update(value).digest("hex").slice(0, 32);
+const safeSession = (id) => /^[A-Za-z0-9_-]{1,128}$/.test(id) ? id : fileKey(id);
+export class DreamStore {
+    fixedRoot;
+    writing = Promise.resolve();
+    constructor(root) { this.fixedRoot = root; }
+    /**
+     * Resolved on use, not at construction: the process's store is built when
+     * the module loads, before a test or fixture has pointed `OHARNESS_HOME`
+     * somewhere else, and fixing the path then would write into the real home.
+     */
+    get root() { return this.fixedRoot ?? userPath("dreams"); }
+    /** Writes one at a time: two passes in one process never interleave a file. */
+    serial(work) {
+        const next = this.writing.then(work, work);
+        this.writing = next.catch(() => { });
+        return next;
+    }
+    async readJson(name, fallback) {
+        try {
+            return JSON.parse(await readFile(path.join(this.root, name), "utf8"));
+        }
+        catch {
+            return fallback;
+        }
+    }
+    async writeJson(name, data) {
+        const file = path.join(this.root, name);
+        await mkdir(path.dirname(file), { recursive: true });
+        const temp = `${file}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temp, JSON.stringify(data) + "\n", { mode: 0o600, flag: "wx" });
+            await renameWithRetry(temp, file);
+        }
+        finally {
+            await rm(temp, { force: true });
+        }
+    }
+    async readLines(name) {
+        let raw;
+        try {
+            raw = await readFile(path.join(this.root, name), "utf8");
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const line of raw.split("\n")) {
+            if (!line.trim())
+                continue;
+            // A line cut short by a crash is skipped, not fatal.
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* skip */ }
+        }
+        return out;
+    }
+    async append(name, rows) {
+        if (!rows.length)
+            return;
+        const file = path.join(this.root, name);
+        await mkdir(path.dirname(file), { recursive: true });
+        await appendFile(file, rows.map((row) => JSON.stringify(row)).join("\n") + "\n", { mode: 0o600 });
+    }
+    // --- cursors ------------------------------------------------------------
+    async digested(session) {
+        const cursors = await this.readJson("cursors.json", { sessions: {} });
+        return new Set(cursors.sessions?.[session]?.keys ?? []);
+    }
+    /**
+     * Claims first, cursor after: a crash between the two reads the stretch
+     * again rather than losing it, and the claim ids it produces are the same,
+     * so `claims()` holds each once.
+     */
+    async recordDigest(session, project, claims, keys) {
+        await this.serial(async () => {
+            await this.append(`digests/${safeSession(session)}.jsonl`, claims.map((claim) => ({ ...claim, project })));
+            const cursors = await this.readJson("cursors.json", { sessions: {} });
+            const held = new Set(cursors.sessions?.[session]?.keys ?? []);
+            for (const key of keys)
+                held.add(key);
+            cursors.sessions = { ...cursors.sessions, [session]: { keys: [...held], at: Date.now() } };
+            await this.writeJson("cursors.json", cursors);
+        });
+    }
+    /** A deleted conversation takes its claims and its cursor with it. */
+    async dropSession(session) {
+        await this.serial(async () => {
+            await rm(path.join(this.root, "digests", `${safeSession(session)}.jsonl`), { force: true });
+            const cursors = await this.readJson("cursors.json", { sessions: {} });
+            if (!cursors.sessions?.[session])
+                return;
+            delete cursors.sessions[session];
+            await this.writeJson("cursors.json", cursors);
+        });
+    }
+    // --- claims -------------------------------------------------------------
+    /**
+     * Claims not yet consumed, for one scope: a project's (by its id) or the
+     * user's own. Oldest first, each id once.
+     */
+    async claims(scope, ledgerKey) {
+        let files;
+        try {
+            files = (await readdir(path.join(this.root, "digests"))).filter((name) => name.endsWith(".jsonl"));
+        }
+        catch {
+            files = [];
+        }
+        const consumed = new Set();
+        for (const event of await this.ledger(ledgerKey))
+            if (event.type === "consumed")
+                for (const id of event.claims)
+                    consumed.add(id);
+        const byId = new Map();
+        for (const name of files) {
+            for (const claim of await this.readLines(`digests/${name}`)) {
+                if (!claim || typeof claim.id !== "string" || consumed.has(claim.id) || byId.has(claim.id))
+                    continue;
+                if (claim.scope !== scope.scope)
+                    continue;
+                if (scope.scope === "project" && claim.project !== scope.project)
+                    continue;
+                byId.set(claim.id, claim);
+            }
+        }
+        return [...byId.values()].sort((a, b) => a.at - b.at);
+    }
+    // --- ledger -------------------------------------------------------------
+    async ledger(key) {
+        return this.readLines(`ledger/${fileKey(key)}.jsonl`);
+    }
+    async record(key, event) {
+        await this.serial(() => this.append(`ledger/${fileKey(key)}.jsonl`, [event]));
+    }
+    // --- budget and days ----------------------------------------------------
+    /** Tokens spent on model calls today, as providers reported them. */
+    async spentToday(now = Date.now()) {
+        const state = await this.readJson("state.json", {});
+        return state.day === localDay(now) ? state.tokens ?? 0 : 0;
+    }
+    async spend(tokens, now = Date.now()) {
+        await this.serial(async () => {
+            const { chars: _chars, ...state } = await this.readJson("state.json", {});
+            const day = localDay(now);
+            await this.writeJson("state.json", { ...state, day, tokens: (state.day === day ? state.tokens ?? 0 : 0) + tokens });
+        });
+    }
+    // --- runs ---------------------------------------------------------------
+    async recordRun(project, run) {
+        await this.serial(() => this.append(`runs/${fileKey(project)}.jsonl`, [run]));
+    }
+    /** A project's runs, newest first. */
+    async runs(project, limit = 100) {
+        return (await this.readLines(`runs/${fileKey(project)}.jsonl`)).sort((a, b) => b.at - a.at).slice(0, limit);
+    }
+    async dreamedToday(key, now = Date.now()) {
+        const state = await this.readJson("state.json", {});
+        return state.dreamed?.[key] === localDay(now);
+    }
+    async markDreamed(key, now = Date.now()) {
+        await this.serial(async () => {
+            const state = await this.readJson("state.json", {});
+            await this.writeJson("state.json", { ...state, dreamed: { ...state.dreamed, [key]: localDay(now) } });
+        });
+    }
+}
+//# sourceMappingURL=memory-ledger.js.map

package/dist/agent/memory-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-ledger.js","sourceRoot":"","sources":["../../src/agent/memory-ledger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAwEhD,yCAAyC;AACzC,MAAM,UAAU,QAAQ,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE;IACtC,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;IACvB,OAAO,GAAG,CAAC,CAAC,WAAW,EAAE,IAAI,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AACnH,CAAC;AAED,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACjG,MAAM,WAAW,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,wBAAwB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AAEzF,MAAM,OAAO,UAAU;IACJ,SAAS,CAAU;IAC5B,OAAO,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAEtD,YAAY,IAAa,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC;IAErD;;;;OAIG;IACH,IAAI,IAAI,KAAa,OAAO,IAAI,CAAC,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAEnE,+EAA+E;IACvE,MAAM,CAAI,IAAsB;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,KAAK,CAAC,QAAQ,CAAI,IAAY,EAAE,QAAW;QACjD,IAAI,CAAC;YAAC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAM,CAAC;QAAC,CAAC;QACnF,MAAM,CAAC;YAAC,OAAO,QAAQ,CAAC;QAAC,CAAC;IAC5B,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,IAAY;QAChD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACxC,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,GAAG,IAAI,IAAI,UAAU,EAAE,MAAM,CAAC;QAC3C,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAChF,MAAM,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACpC,CAAC;gBAAS,CAAC;YAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAAC,CAAC;IAChD,CAAC;IAEO,KAAK,CAAC,SAAS,CAAI,IAAY;QACrC,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YAAC,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,EAAE,CAAC;QAAC,CAAC;QACtF,MAAM,GAAG,GAAQ,EAAE,CAAC;QACpB,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;gBAAE,SAAS;YAC3B,qDAAqD;YACrD,IAAI,CAAC;gBAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,IAAuB;QACxD,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACxC,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,MAAM,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpG,CAAC;IAED,2EAA2E;IAE3E,KAAK,CAAC,QAAQ,CAAC,OAAe;QAC5B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAU,cAAc,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;QAC/E,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAAC,OAAe,EAAE,OAAe,EAAE,MAA8B,EAAE,IAAuB;QAC1G,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;YAC3B,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,WAAW,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;YAC3G,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAU,cAAc,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;YAC/E,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;YAC9D,KAAK,MAAM,GAAG,IAAI,IAAI;gBAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACtC,OAAO,CAAC,QAAQ,GAAG,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC;YAC3F,MAAM,IAAI,CAAC,SAAS,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;IACL,CAAC;IAED,sEAAsE;IACtE,KAAK,CAAC,WAAW,CAAC,OAAe;QAC/B,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;YAC3B,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5F,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAU,cAAc,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;YAC/E,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC;gBAAE,OAAO;YACzC,OAAO,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACjC,MAAM,IAAI,CAAC,SAAS,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;IACL,CAAC;IAED,2EAA2E;IAE3E;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,KAAgE,EAAE,SAAiB;QAC9F,IAAI,KAAe,CAAC;QACpB,IAAI,CAAC;YAAC,KAAK,GAAG,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAC,CAAC;QAC3G,MAAM,CAAC;YAAC,KAAK,GAAG,EAAE,CAAC;QAAC,CAAC;QACrB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;QACnC,KAAK,MAAM,KAAK,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;YAAE,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;gBAAE,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,MAAM;oBAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACjI,MAAM,IAAI,GAAG,IAAI,GAAG,EAAuB,CAAC;QAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,KAAK,MAAM,KAAK,IAAI,MAAM,IAAI,CAAC,SAAS,CAAc,WAAW,IAAI,EAAE,CAAC,EAAE,CAAC;gBACzE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;oBAAE,SAAS;gBACrG,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK;oBAAE,SAAS;gBAC1C,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO;oBAAE,SAAS;gBAC3E,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;QACD,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,2EAA2E;IAE3E,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,OAAO,IAAI,CAAC,SAAS,CAAc,UAAU,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrE,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,KAAkB;QAC1C,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAChF,CAAC;IAED,2EAA2E;IAE3E,qEAAqE;IACrE,KAAK,CAAC,UAAU,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QAC/B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAQ,YAAY,EAAE,EAAE,CAAC,CAAC;QAC3D,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,MAAc,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QAC1C,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;YAC3B,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAA6B,YAAY,EAAE,EAAE,CAAC,CAAC;YACtG,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC1B,MAAM,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,CAAC,CAAC;QACtH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,2EAA2E;IAE3E,KAAK,CAAC,SAAS,CAAC,OAAe,EAAE,GAAc;QAC7C,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAChF,CAAC;IAED,sCAAsC;IACtC,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,KAAK,GAAG,GAAG;QACrC,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAY,QAAQ,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACzH,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,GAAW,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QAC9C,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAQ,YAAY,EAAE,EAAE,CAAC,CAAC;QAC3D,OAAO,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,GAAW,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QAC7C,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;YAC3B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAQ,YAAY,EAAE,EAAE,CAAC,CAAC;YAC3D,MAAM,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;QACxG,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/agent/memory-provider.d.ts

@@ -14,11 +14,21 @@ export interface MemoryRecallInput {
     context?: string;
     /** Notes already attached in this session since the last compaction. */
     exclude: ReadonlySet<string>;
+    /**
+     * The content hash each of those notes had when it was attached, where
+     * known. A note that has changed since is attached again, as updated, so a
+     * conversation resumed after a dream does not go on with the old text.
+     */
+    shown?: ReadonlyMap<string, string>;
 }
 export interface MemoryRecallItem {
     id: string;
     summary: string;
     scope?: MemoryScope;
+    /** Content hash as attached, recorded so a later change can be noticed. */
+    hash?: string;
+    /** Attached again because it changed since it was last shown. */
+    changed?: boolean;
 }
 export interface MemoryRecallResult {
     /** Rendered block appended to the user message. */
@@ -70,4 +80,6 @@ export interface MemoryExtractionTarget {
 export interface MemoryProvider {
     recall(input: MemoryRecallInput): Promise<MemoryRecallResult | undefined>;
     extraction?: MemoryExtractionTarget;
+    /** Changes made in the background since the last call (a dream), each told once. */
+    notices?(): Promise<ExtractedSummary[]>;
 }

package/dist/agent/memory-recall.d.ts

@@ -63,6 +63,8 @@ export interface RecalledNote {
         id: string;
         summary: string;
     }>;
+    /** Shown earlier in this conversation and changed since. */
+    changed?: boolean;
 }
 /**
  * Render recalled notes for the user message they are attached to, inside