@oharness/engine 0.5.0 → 0.6.0

package/dist/agent/memory-review.js

@@ -0,0 +1,127 @@
+import { createHash } from "node:crypto";
+import { buildLinkGraph } from "./memory-links.js";
+import { tokenize } from "./memory-recall.js";
+/**
+ * Checks over a set of notes that need no model: what a person tidying up
+ * would want pointed out.
+ *
+ * Each finding carries a key made from the notes it is about, at their current
+ * hashes. Dismissing a finding stores the key, so the same finding stays
+ * hidden, and any edit to one of its notes brings it back as a new one.
+ *
+ * Only `duplicate` may ever be acted on without a person (AUTO_KINDS): a note
+ * nobody recalled lately, or one naming a file that moved, can still be right.
+ */
+export const REVIEW_KINDS = ["duplicate", "dangling", "stale-path", "unused", "oversized"];
+export const AUTO_KINDS = new Set(["duplicate"]);
+const DAY = 86_400_000;
+const MAX_GROUP = 6;
+/** A token in more notes than this says nothing about which notes are alike. */
+const COMMON_TOKEN = 50;
+const PATH = /(?:^|[\s`(\["'])((?:\.{1,2}\/)?(?:[\w@.-]+\/)+[\w@.-]+\.[a-zA-Z0-9]{1,8})(?=$|[\s`)\]"',:;])/gm;
+const FENCE = /^(```|~~~)[^\n]*\n[\s\S]*?^\1[ \t]*$/gm;
+const findingKey = (kind, scope, notes, detail) => `${kind}:${createHash("sha256").update(JSON.stringify([scope, notes.map((note) => [note.id, note.hash]), detail])).digest("hex").slice(0, 24)}`;
+/** Paths a note names in prose, relative ones only. URLs and code blocks are skipped. */
+export function mentionedPaths(body) {
+    const found = new Set();
+    for (const match of body.replace(FENCE, "").matchAll(PATH)) {
+        const candidate = match[1];
+        const before = body.slice(Math.max(0, match.index - 3), match.index + 1);
+        if (before.includes(":/") || candidate.includes("://"))
+            continue;
+        found.add(candidate.replace(/^\.\//, ""));
+        if (found.size >= 10)
+            break;
+    }
+    return [...found];
+}
+function subjectTokens(note) {
+    return new Set([...tokenize(note.summary), ...note.tags.flatMap((tag) => tokenize(tag.replace(/[-:/.]/g, " ")))]);
+}
+/** Groups of notes in one scope that are about the same thing, by summary and tags. */
+export function duplicateGroups(notes, threshold = 0.6) {
+    const tokens = notes.map(subjectTokens);
+    const normalized = notes.map((note) => note.summary.toLowerCase().replace(/[\s\p{P}]+/gu, " ").trim());
+    const byToken = new Map();
+    tokens.forEach((set, index) => { for (const token of set) {
+        const list = byToken.get(token) ?? [];
+        list.push(index);
+        byToken.set(token, list);
+    } });
+    const parent = notes.map((_, index) => index);
+    const find = (i) => { while (parent[i] !== i) {
+        parent[i] = parent[parent[i]];
+        i = parent[i];
+    } return i; };
+    for (let i = 0; i < notes.length; i++) {
+        const candidates = new Set();
+        for (const token of tokens[i]) {
+            const list = byToken.get(token);
+            if (list.length > COMMON_TOKEN)
+                continue;
+            for (const j of list)
+                if (j > i)
+                    candidates.add(j);
+        }
+        for (let j = i + 1; j < notes.length; j++)
+            if (normalized[i] && normalized[i] === normalized[j])
+                candidates.add(j);
+        for (const j of candidates) {
+            if (notes[i].scope !== notes[j].scope)
+                continue;
+            const a = tokens[i], b = tokens[j];
+            let shared = 0;
+            for (const token of a)
+                if (b.has(token))
+                    shared++;
+            const union = a.size + b.size - shared;
+            const same = normalized[i] !== "" && normalized[i] === normalized[j];
+            if (same || (a.size >= 2 && b.size >= 2 && union > 0 && shared / union >= threshold))
+                parent[find(i)] = find(j);
+        }
+    }
+    const groups = new Map();
+    notes.forEach((note, index) => { const root = find(index); groups.set(root, [...(groups.get(root) ?? []), note]); });
+    return [...groups.values()]
+        .filter((group) => group.length > 1)
+        .map((group) => [...group].sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id)).slice(0, MAX_GROUP));
+}
+export function reviewNotes(notes, options = {}) {
+    const now = options.now ?? Date.now();
+    const dismissed = options.dismissed ?? new Set();
+    const findings = [];
+    const push = (kind, scope, group, detail = []) => {
+        const key = findingKey(kind, scope, group, detail);
+        if (!dismissed.has(key))
+            findings.push({ key, kind, scope, ids: group.map((note) => note.id), detail });
+    };
+    for (const group of duplicateGroups(notes, options.duplicateThreshold))
+        push("duplicate", group[0].scope, group);
+    const graph = buildLinkGraph(notes);
+    for (const note of notes) {
+        const missing = graph.dangling.get(note.id);
+        if (missing?.length)
+            push("dangling", note.scope, [note], missing);
+    }
+    if (options.pathExists) {
+        for (const note of notes) {
+            if (note.scope !== "project")
+                continue;
+            const missing = mentionedPaths(note.body).filter((one) => !options.pathExists(one));
+            if (missing.length)
+                push("stale-path", note.scope, [note], missing);
+        }
+    }
+    const unusedMs = (options.unusedDays ?? 90) * DAY;
+    for (const note of notes) {
+        const last = Math.max(options.usage?.(note.scope, note.id)?.last ?? 0, note.updatedAt ?? note.createdAt);
+        if (now - last > unusedMs)
+            push("unused", note.scope, [note]);
+    }
+    const oversized = options.oversizedChars ?? 8_000;
+    for (const note of notes)
+        if (note.body.length > oversized)
+            push("oversized", note.scope, [note]);
+    return findings;
+}
+//# sourceMappingURL=memory-review.js.map

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

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

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

@@ -0,0 +1,24 @@
+/**
+ * How often each note has been recalled, on this machine only.
+ *
+ * Kept outside the note files: writing a counter into a note would make every
+ * recall an edit, and every edit a sync upload.
+ */
+export interface UsageRecord {
+    count: number;
+    last: number;
+}
+export declare class MemoryUsage {
+    private readonly file;
+    private records?;
+    private pending?;
+    private writing;
+    constructor(directory: string);
+    private load;
+    get(id: string): UsageRecord | undefined;
+    record(ids: readonly string[], now?: number): void;
+    /** Drop records for notes that no longer exist. */
+    prune(existing: ReadonlySet<string>): void;
+    private schedule;
+    flush(): Promise<void>;
+}

package/dist/agent/memory-usage.js

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { readUserFile, writeUserFile } from "../config-files.js";
+export class MemoryUsage {
+    file;
+    records;
+    pending;
+    writing = Promise.resolve();
+    constructor(directory) {
+        const key = createHash("sha256").update(path.resolve(directory)).digest("hex").slice(0, 32);
+        this.file = `memory-usage/${key}.json`;
+    }
+    load() {
+        if (this.records)
+            return this.records;
+        try {
+            const raw = readUserFile(this.file);
+            this.records = raw?.notes && typeof raw.notes === "object" ? raw.notes : {};
+        }
+        catch {
+            this.records = {};
+        }
+        return this.records;
+    }
+    get(id) {
+        const record = this.load()[id];
+        return record && typeof record.count === "number" ? record : undefined;
+    }
+    record(ids, now = Date.now()) {
+        if (!ids.length)
+            return;
+        const records = this.load();
+        for (const id of ids) {
+            const previous = records[id];
+            records[id] = { count: (previous?.count ?? 0) + 1, last: now };
+        }
+        this.schedule();
+    }
+    /** Drop records for notes that no longer exist. */
+    prune(existing) {
+        const records = this.load();
+        let changed = false;
+        for (const id of Object.keys(records)) {
+            if (!existing.has(id)) {
+                delete records[id];
+                changed = true;
+            }
+        }
+        if (changed)
+            this.schedule();
+    }
+    schedule() {
+        if (this.pending)
+            return;
+        this.pending = setTimeout(() => { this.pending = undefined; void this.flush(); }, 1_000);
+        this.pending.unref?.();
+    }
+    flush() {
+        if (this.pending) {
+            clearTimeout(this.pending);
+            this.pending = undefined;
+        }
+        const snapshot = { notes: { ...this.load() } };
+        this.writing = this.writing.then(() => writeUserFile(this.file, snapshot)).catch(() => { });
+        return this.writing;
+    }
+}
+//# sourceMappingURL=memory-usage.js.map

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

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

package/dist/agent/memory.d.ts

@@ -1,3 +1,9 @@
+import type { MemoryRecallPolicy, MemoryScope, MemoryType } from "./memory-limits.ts";
+import type { LinkGraph } from "./memory-links.ts";
+import type { Ranked, RankOptions, RecallNote } from "./memory-recall.ts";
+import type { MemoryUsage } from "./memory-usage.ts";
+import type { MemoryRecallInput, MemoryRecallResult } from "./memory-provider.ts";
+export type { MemoryScope, MemoryType } from "./memory-limits.ts";
 /**
  * Durable lessons the agent writes for its future self.
  *
@@ -7,48 +13,165 @@
  *
  * One fact per file, deliberately. A single growing notes file gets rewritten
  * wholesale on every update, which loses entries to careless edits and makes
- * "what changed" unanswerable.
+ * "what changed" unanswerable — and it is what lets cloud sync reconcile note
+ * by note instead of file against file.
  */
 export interface MemoryEntry {
     id: string;
-    /** One line, shown in the prompt index. */
+    /** One line, shown in the prompt index and matched by recall. */
     summary: string;
     /** The full note. */
     body: string;
     /** Free-form tags for retrieval. */
     tags: string[];
+    /** What kind of fact this is. Notes written before types existed have none. */
+    type?: MemoryType;
     createdAt: number;
     updatedAt?: number;
     file: string;
 }
 export type MemoryNote = Omit<MemoryEntry, "file">;
 export declare const validMemoryId: (id: unknown) => id is string;
+/**
+ * The identity of a note's content, compared across machines.
+ *
+ * `type` takes part only when a note has one. Every note written before the
+ * field existed keeps exactly the hash that its sync baseline and the server's
+ * manifest already recorded; including an absent type as `null` would have
+ * made every existing note look edited on every machine at once.
+ */
 export declare function noteHash(note: MemoryNote | undefined): string | null;
+/**
+ * Tags as a model writes them, made into tags a note can hold.
+ *
+ * Models pad them (" aesthetics"), prefix them ("#design"), and put two in one
+ * string ("design, ux"). Refusing the whole note over that loses a note the
+ * user asked for, so each is trimmed, split and de-duplicated, and anything
+ * still unusable is dropped.
+ */
+export declare function normalizeTags(tags: readonly unknown[]): string[];
 export declare function memoryNote(entry: MemoryEntry): MemoryNote;
-export declare function validateNote(note: MemoryNote): void;
+export declare function validateNote(note: MemoryNote, maxNoteBytes?: number): void;
+/** `sync` is a write a pull applied; every other write is `local`. */
+export type MemoryWriteOrigin = "local" | "sync";
+export interface MemoryChange {
+    id: string;
+    origin: MemoryWriteOrigin;
+}
+export interface MemoryStoreOptions {
+    /** Past this many files, only the most recently modified are loaded. */
+    maxNotes?: number;
+    maxNoteBytes?: number;
+    /** Which scope this directory holds; carried onto recall results. */
+    scope?: MemoryScope;
+    /** Told once per distinct condition worth a person's attention, such as notes left unloaded. */
+    onWarning?(message: string): void;
+}
+export interface MemorySnapshot {
+    entries: MemoryEntry[];
+    /** Notes present on disk but not loaded because the directory is over its limit. */
+    omitted: number;
+    links: LinkGraph;
+}
+/** A note as recall and the tools see it: its scope, and the entry behind it. */
+export type ScopedNote = RecallNote & {
+    entry: MemoryEntry;
+};
 export declare class MemoryStore {
     private readonly dir;
-    constructor(dir: string);
+    readonly maxNotes: number;
+    readonly maxNoteBytes: number;
+    readonly scope: MemoryScope;
+    private readonly onWarning?;
+    private files;
+    private cached?;
+    private warnedOmitted;
+    private readonly scoped;
+    private readonly listeners;
+    constructor(dir: string, options?: MemoryStoreOptions);
     get location(): string;
+    /** Told after every write this store makes, once the file is in place. */
+    onChange(listener: (change: MemoryChange) => void): () => void;
+    private emit;
     load(): Promise<MemoryEntry[]>;
+    /**
+     * Every note, read from disk only where a file changed.
+     *
+     * Recall scores notes on every user message, so rereading the directory each
+     * time would put thousands of file reads in front of every reply. A file's
+     * size and timestamps decide whether its parsed note is reused; the store's
+     * own writes drop their file from that cache outright, because two writes
+     * inside one timestamp tick with bodies of equal length would otherwise look
+     * unchanged.
+     */
+    snapshot(): Promise<MemorySnapshot>;
+    private readNote;
+    /**
+     * Write a note. With `id`, that note is updated and must exist. Without it,
+     * a note whose summary matches (ignoring case) is updated rather than
+     * duplicated, and otherwise a new one is created.
+     */
     remember(input: {
         summary: string;
         body: string;
         tags?: string[];
+        type?: MemoryType;
+        id?: string;
     }): Promise<MemoryEntry>;
     forget(id: string): Promise<boolean>;
     /** Compare before applying downloaded data; never overwrite a concurrent edit. */
-    apply(id: string, note: MemoryNote | undefined, expected: string | null): Promise<void>;
+    apply(id: string, note: MemoryNote | undefined, expected: string | null, origin?: MemoryWriteOrigin): Promise<void>;
     private exclusive;
+    private invalidate;
     private atomic;
-    /** Full-text search across summaries, bodies and tags. */
+    /** Notes as recall sees them, with this store's scope. Stable objects while a file is unchanged. */
+    scopedNotes(entries: readonly MemoryEntry[]): ScopedNote[];
+    /** Notes scored against a query, best first. */
+    rank(query: string, options?: RankOptions): Promise<Ranked<ScopedNote>[]>;
+    /** Scored search across summaries, bodies and tags, falling back to plain substring matching. */
     search(query: string): Promise<MemoryEntry[]>;
-    /**
-     * The index that goes into the system prompt: summaries only.
-     *
-     * Same reasoning as skills — putting every note's body in the prompt would
-     * grow without bound and crowd out the actual conversation. The model reads
-     * a summary, then asks for the body if it matters.
-     */
-    promptSection(): Promise<string | undefined>;
+    /** The index for this store alone. See `memoryIndexSection`. */
+    promptSection(indexChars?: number): Promise<string | undefined>;
+}
+/** Project and user notes together. The user store is absent when its directory could not be created. */
+export interface MemoryStores {
+    project: MemoryStore;
+    user?: MemoryStore;
+}
+export interface ScopedMemory {
+    notes: ScopedNote[];
+    links: LinkGraph;
+    omitted: number;
 }
+/**
+ * Both scopes loaded as one list, project notes first, with links resolved
+ * across the two: a note in either may link to a note in the other.
+ */
+export declare function loadScoped(stores: MemoryStores): Promise<ScopedMemory>;
+/** A note by id, project scope first. */
+export declare function findScoped(notes: readonly ScopedNote[], id: string): ScopedNote | undefined;
+export declare function storeFor(stores: MemoryStores, scope: MemoryScope): MemoryStore;
+export declare const MEMORY_GUIDANCE: string;
+/**
+ * The index that goes into the system prompt: one line per note, summaries only.
+ *
+ * Same reasoning as skills — putting every note's body in the prompt would
+ * grow without bound and crowd out the actual conversation. The model reads a
+ * summary, then asks for the body if it matters; notes that match a message
+ * are attached to it without being asked for.
+ *
+ * Most recently touched first, which is not the order the notes are stored in.
+ * The budget drops whatever does not fit, so this ordering decides which notes
+ * stop being listed once there are more than about fifty. A note written a year
+ * ago and corrected on Tuesday is the more useful of the two, and updatedAt is
+ * the only thing here that knows that. Nothing is lost, only unlisted: the line
+ * at the end says how many, and the tool searches every note.
+ */
+export declare function memoryIndexSection(notes: readonly ScopedNote[], indexChars: number, options: {
+    showScope: boolean;
+}): string | undefined;
+/** Recall across both scopes, rendered for attaching to a user message. */
+export declare function recallFromStores(stores: MemoryStores, input: MemoryRecallInput, policy: MemoryRecallPolicy, usage?: {
+    project?: MemoryUsage;
+    user?: MemoryUsage;
+}): Promise<MemoryRecallResult | undefined>;