@chendpoc/pi-memory 0.2.4 → 0.3.2

package/dist/store/ingestEntries.d.ts

@@ -0,0 +1,16 @@
+import type { ParsedEntry, StoreMemoryEntry } from "./types.js";
+export type MemoryStoreForIngest = {
+    listEntries(): Promise<ParsedEntry[]>;
+    appendMany(entries: StoreMemoryEntry[], opts?: {
+        mode?: "ifAbsent";
+    }): Promise<number>;
+};
+export type IngestMemoryExportResult = {
+    appended: number;
+};
+/** Parse Memory Export from summary text and append new facts to Ground Truth. */
+export declare function ingestMemoryExport(opts: {
+    store: MemoryStoreForIngest;
+    summary: string;
+    isSubagent: boolean;
+}): Promise<IngestMemoryExportResult>;

package/dist/store/ingestEntries.js

@@ -0,0 +1,22 @@
+import { parseMemoryExport } from "../compact/parseMemoryExport.js";
+import { filterCompactionDelta, shouldSkipSubagentCompactionIngest, } from "../compact/subagentDelta.js";
+/** Parse Memory Export from summary text and append new facts to Ground Truth. */
+export async function ingestMemoryExport(opts) {
+    const parsed = parseMemoryExport(opts.summary);
+    if (parsed.length === 0) {
+        return { appended: 0 };
+    }
+    let entries = parsed;
+    if (opts.isSubagent) {
+        const existing = await opts.store.listEntries();
+        entries = filterCompactionDelta(parsed, existing);
+        if (shouldSkipSubagentCompactionIngest(parsed, entries)) {
+            return { appended: 0 };
+        }
+    }
+    if (entries.length === 0) {
+        return { appended: 0 };
+    }
+    const appended = await opts.store.appendMany(entries, { mode: "ifAbsent" });
+    return { appended };
+}

package/dist/{init/workspace.d.ts → store/initWorkspace.d.ts}

@@ -6,7 +6,7 @@ export type InitMemoryWorkspaceResult = {
     reason?: "already_initialized";
 };
 /**
- * Ensure the memory data directory exists and MEMORY.md follows the canonical template.
+ * Ensure the memory data directory exists, `logs/` is present, and MEMORY.md follows the canonical template.
  * Never overwrites a non-empty MEMORY.md.
  */
 export declare function initializeMemoryWorkspace(agentDir: string): Promise<InitMemoryWorkspaceResult>;

package/dist/{init/workspace.js → store/initWorkspace.js}

@@ -1,10 +1,11 @@
 import { DEFAULT_MEMORY_FILE } from "../constants/memory.js";
-import { MarkdownMemoryBackend } from "../store/backend.js";
-import { defaultMemoryTemplate } from "../store/markdown/template.js";
-import { resolveAgentDir } from "../store/paths.js";
-import { joinPath, readText } from "../utils/fs.js";
+import { PI_LOGS_SUBDIR } from "../constants/paths.js";
+import { ensureDir, joinPath, readText } from "../utils/fs.js";
+import { MarkdownMemoryBackend } from "./backend.js";
+import { defaultMemoryTemplate } from "./markdown/template.js";
+import { resolveAgentDir } from "./paths.js";
 /**
- * Ensure the memory data directory exists and MEMORY.md follows the canonical template.
+ * Ensure the memory data directory exists, `logs/` is present, and MEMORY.md follows the canonical template.
  * Never overwrites a non-empty MEMORY.md.
  */
 export async function initializeMemoryWorkspace(agentDir) {
@@ -12,6 +13,7 @@ export async function initializeMemoryWorkspace(agentDir) {
     const memoryFile = joinPath(resolved, DEFAULT_MEMORY_FILE);
     const backend = new MarkdownMemoryBackend(memoryFile);
     await backend.ensureAgentDir();
+    await ensureDir(joinPath(resolved, PI_LOGS_SUBDIR));
     const existing = await backend.readText(memoryFile);
     if (existing.trim()) {
         return {

package/dist/store/listeners.d.ts

@@ -0,0 +1,11 @@
+export type NotifyAfterWriteOptions = {
+    skipConsolidateCheck?: boolean;
+};
+export type StoreListeners = {
+    onSyncToSidecar(listener: () => void): () => void;
+    onConsolidateCheck(listener: () => void): () => void;
+    notifySyncToSidecar(): void;
+    notifyAfterWrite(opts?: NotifyAfterWriteOptions): void;
+};
+/** Sidecar sync + debounced consolidate-check subscriptions after Ground Truth writes. */
+export declare function createStoreListeners(isConsolidating: () => boolean): StoreListeners;

package/dist/store/listeners.js

@@ -0,0 +1,27 @@
+/** Sidecar sync + debounced consolidate-check subscriptions after Ground Truth writes. */
+export function createStoreListeners(isConsolidating) {
+    const syncToSidecarListeners = new Set();
+    const consolidateCheckListeners = new Set();
+    return {
+        onSyncToSidecar(listener) {
+            syncToSidecarListeners.add(listener);
+            return () => syncToSidecarListeners.delete(listener);
+        },
+        onConsolidateCheck(listener) {
+            consolidateCheckListeners.add(listener);
+            return () => consolidateCheckListeners.delete(listener);
+        },
+        notifySyncToSidecar() {
+            for (const listener of syncToSidecarListeners)
+                listener();
+        },
+        notifyAfterWrite(opts) {
+            for (const listener of syncToSidecarListeners)
+                listener();
+            if (!opts?.skipConsolidateCheck && !isConsolidating()) {
+                for (const listener of consolidateCheckListeners)
+                    listener();
+            }
+        },
+    };
+}

package/dist/store/markdown/insert.d.ts

@@ -0,0 +1,3 @@
+import type { StoreMemoryEntry } from "../types.js";
+/** Insert one entry line under its section in MEMORY markdown. */
+export declare function insertEntryIntoMarkdown(content: string, entry: StoreMemoryEntry): string;

package/dist/store/markdown/insert.js

@@ -0,0 +1,23 @@
+import { formatEntryLine, formatSectionHeader } from "./format.js";
+/** Insert one entry line under its section in MEMORY markdown. */
+export function insertEntryIntoMarkdown(content, entry) {
+    const lines = content.split("\n");
+    const header = formatSectionHeader(entry.section);
+    const headerIdx = lines.findIndex((line) => line.trim() === header);
+    const line = formatEntryLine(entry);
+    if (headerIdx === -1) {
+        const trimmed = content.trimEnd();
+        return `${trimmed}\n\n${header}\n\n${line}\n`;
+    }
+    let insertAt = headerIdx + 1;
+    while (insertAt < lines.length && lines[insertAt]?.trim() === "")
+        insertAt++;
+    while (insertAt < lines.length) {
+        const current = lines[insertAt];
+        if (current.startsWith("## "))
+            break;
+        insertAt++;
+    }
+    const next = [...lines.slice(0, insertAt), line, ...lines.slice(insertAt)];
+    return `${next.join("\n").trimEnd()}\n`;
+}

package/dist/store/memoryStore.d.ts

@@ -1,14 +1,16 @@
 import { type TimeInput } from "../utils/time.js";
-import type { IndexDocument, IntegrityReport, LlmClient, MemoryStats, MemoryStoreOptions, ParsedEntry, ResolvedMemory, StoreMemoryEntry } from "./types.js";
-export declare class MemoryStore {
+import type { ConsolidateStoreAccess } from "./consolidatePort.js";
+import type { IndexDocument, IntegrityReport, MemoryStats, MemoryStoreOptions, ParsedEntry, ResolvedMemory, StoreMemoryEntry } from "./types.js";
+export declare class MemoryStore implements ConsolidateStoreAccess {
     private readonly paths;
     private readonly backend;
     private readonly maxLines;
     private readonly fallbackMaxChars;
-    private readonly syncToSidecarListeners;
-    private readonly consolidateCheckListeners;
+    private readonly listeners;
     private consolidating;
     constructor(opts: MemoryStoreOptions);
+    private collectResolvedOpts;
+    private writePathDeps;
     get agentDir(): string;
     ensureInitialized(): Promise<void>;
     isEmpty(): Promise<boolean>;
@@ -22,9 +24,8 @@ export declare class MemoryStore {
     appendUser(entry: Omit<StoreMemoryEntry, "userAuthored">): Promise<void>;
     appendMany(entries: StoreMemoryEntry[], opts?: {
         mode?: "ifAbsent";
-    }): Promise<void>;
+    }): Promise<number>;
     appendIfAbsent(entry: StoreMemoryEntry): Promise<boolean>;
-    /** Fire-and-forget: parse Memory Export from compact summary → appendIfAbsent. */
     appendFromCompaction(opts: {
         compactionId: string;
         summary: string;
@@ -38,28 +39,14 @@ export declare class MemoryStore {
     }): Promise<void>;
     rewrite(content: string): Promise<void>;
     shouldConsolidate(at?: TimeInput, cronFired?: boolean): Promise<boolean>;
-    consolidate(llm: LlmClient): Promise<void>;
-    consolidateInBackground(llm: LlmClient, opts?: {
-        onComplete?: () => void | Promise<void>;
-    }): void;
-    forceConsolidate(llm: LlmClient): Promise<void>;
+    isConsolidating(): boolean;
+    rewriteMemoryUnderLock(updateEntries: (entries: ParsedEntry[]) => Promise<ParsedEntry[]>): Promise<void>;
     hasProcessedCompaction(compactionId: string): Promise<boolean>;
     markCompactionProcessed(compactionId: string): Promise<void>;
     verifyIntegrity(): Promise<IntegrityReport>;
-    /** Register a listener to sync MEMORY.md changes to the sidecar vector index. */
     onSyncToSidecar(listener: () => void): () => void;
-    /** Register a listener invoked after writes to check shouldConsolidate. */
     onConsolidateCheck(listener: () => void): () => void;
-    private notifyAfterWrite;
-    private notifySyncToSidecar;
-    private notifyConsolidateCheck;
-    private appendUnlocked;
-    private appendIfAbsentUnlocked;
-    private appendToOverflowUnlocked;
-    private insertEntryIntoMarkdown;
-    private rewriteEntriesUnlocked;
     private readResolvedUnlocked;
-    private normalizeEntry;
     private newEntryId;
     private newAutoFilePath;
     private readGcTimestamp;

package/dist/store/memoryStore.js

@@ -1,26 +1,24 @@
 import { randomBytes } from "node:crypto";
-import { parseMemoryExport } from "../compact/parseMemoryExport.js";
-import { filterCompactionDelta, shouldSkipSubagentCompactionIngest, } from "../compact/subagentDelta.js";
-import { dedupeEntries } from "../consolidate/mergeEntries.js";
-import { mergeEntriesWithLlm } from "../consolidate/mergeWithLlm.js";
-import { MarkdownMemoryBackend } from "./backend.js";
-import { AUTO_FILE_PREFIX, CONSOLIDATE_GC_INTERVAL_DAYS, CONSOLIDATE_OVERFLOW_FILE_THRESHOLD, DEFAULT_FALLBACK_MAX_CHARS, DEFAULT_MAX_LINES, DEFAULT_MEMORY_FILE, } from "../constants/memory.js";
-import { countLines, formatEntryLine, formatSectionHeader } from "./markdown/format.js";
-import { listOverflowPointers, parseMemoryMarkdown } from "./markdown/parse.js";
-import { initializeMemoryWorkspace } from "../init/workspace.js";
+import { CONSOLIDATE_GC_INTERVAL_DAYS, CONSOLIDATE_OVERFLOW_FILE_THRESHOLD, DEFAULT_FALLBACK_MAX_CHARS, DEFAULT_MAX_LINES, DEFAULT_MEMORY_FILE, AUTO_FILE_PREFIX, } from "../constants/memory.js";
 import { readChunkingConfig } from "../config/chunking.js";
-import { joinPath, pathBasename, readText, readTextRequired, writeText, } from "../utils/fs.js";
-import { buildIndexDocuments } from "./indexChunks.js";
+import { initializeMemoryWorkspace } from "./initWorkspace.js";
+import { joinPath, readText, readTextRequired, writeText } from "../utils/fs.js";
 import { daysSince, formatLocalDate, formatTimestamp } from "../utils/time.js";
+import { ingestMemoryExport } from "./ingestEntries.js";
+import { MarkdownMemoryBackend } from "./backend.js";
+import { buildIndexDocuments } from "./indexChunks.js";
+import { createStoreListeners } from "./listeners.js";
+import { countLines } from "./markdown/format.js";
+import { listOverflowPointers } from "./markdown/parse.js";
 import { getAgentPaths, resolveAgentDir } from "./paths.js";
-import { MEMORY_SECTIONS } from "./types.js";
+import { collectResolvedEntries } from "./resolveEntries.js";
+import { appendIfAbsentUnlocked, rewriteEntriesUnlocked, tryAppendUnlocked, } from "./writePath.js";
 export class MemoryStore {
     paths;
     backend;
     maxLines;
     fallbackMaxChars;
-    syncToSidecarListeners = new Set();
-    consolidateCheckListeners = new Set();
+    listeners = createStoreListeners(() => this.consolidating);
     consolidating = false;
     constructor(opts) {
         const agentDir = resolveAgentDir(opts.agentDir);
@@ -29,6 +27,24 @@ export class MemoryStore {
         this.maxLines = opts.maxLines ?? DEFAULT_MAX_LINES;
         this.fallbackMaxChars = opts.defaultFallbackMaxChars ?? DEFAULT_FALLBACK_MAX_CHARS;
     }
+    collectResolvedOpts() {
+        return {
+            backend: this.backend,
+            agentDir: this.paths.agentDir,
+            memoryFile: this.paths.memoryFile,
+        };
+    }
+    writePathDeps() {
+        return {
+            backend: this.backend,
+            memoryFile: this.paths.memoryFile,
+            agentDir: this.paths.agentDir,
+            maxLines: this.maxLines,
+            createId: () => this.newEntryId(),
+            newAutoFilePath: () => this.newAutoFilePath(),
+            readResolvedUnlocked: () => this.readResolvedUnlocked(),
+        };
+    }
     get agentDir() {
         return this.paths.agentDir;
     }
@@ -60,22 +76,7 @@ export class MemoryStore {
     }
     async readResolved() {
         await this.ensureInitialized();
-        const main = await this.backend.readText(this.paths.memoryFile);
-        const entries = [...parseMemoryMarkdown(main, this.paths.memoryFile)];
-        for (const fileName of listOverflowPointers(main)) {
-            const path = this.backend.autoFilePath(this.paths.agentDir, fileName);
-            const overflow = await this.backend.readText(path);
-            entries.push(...parseMemoryMarkdown(overflow, path));
-        }
-        const autoFiles = await this.backend.listAutoFiles(this.paths.agentDir);
-        for (const fileName of autoFiles) {
-            if (listOverflowPointers(main).includes(fileName))
-                continue;
-            const path = this.backend.autoFilePath(this.paths.agentDir, fileName);
-            const orphan = await this.backend.readText(path);
-            entries.push(...parseMemoryMarkdown(orphan, path));
-        }
-        return { content: main, entries };
+        return collectResolvedEntries(this.collectResolvedOpts());
     }
     async readForFallback(maxChars = this.fallbackMaxChars) {
         const resolved = await this.readResolved();
@@ -95,43 +96,48 @@ export class MemoryStore {
         return buildIndexDocuments(resolved.entries, readChunkingConfig());
     }
     async append(entry) {
+        let written = false;
         await this.backend.withMemoryLock(async () => {
-            await this.appendUnlocked(entry);
+            written = await tryAppendUnlocked(this.writePathDeps(), entry);
         });
-        this.notifyAfterWrite();
+        if (written)
+            this.listeners.notifyAfterWrite();
     }
     async appendUser(entry) {
+        let written = false;
         await this.backend.withMemoryLock(async () => {
-            await this.appendUnlocked({ ...entry, userAuthored: true });
+            written = await tryAppendUnlocked(this.writePathDeps(), { ...entry, userAuthored: true });
         });
-        this.notifyAfterWrite();
+        if (written)
+            this.listeners.notifyAfterWrite();
     }
     async appendMany(entries, opts) {
+        let written = 0;
+        const deps = this.writePathDeps();
         await this.backend.withMemoryLock(async () => {
             for (const entry of entries) {
                 if (opts?.mode === "ifAbsent") {
-                    const added = await this.appendIfAbsentUnlocked(entry);
-                    if (!added)
-                        continue;
+                    if (await appendIfAbsentUnlocked(deps, entry))
+                        written += 1;
                 }
-                else {
-                    await this.appendUnlocked(entry);
+                else if (await tryAppendUnlocked(deps, entry)) {
+                    written += 1;
                 }
             }
         });
-        if (entries.length > 0)
-            this.notifyAfterWrite();
+        if (written > 0)
+            this.listeners.notifyAfterWrite();
+        return written;
     }
     async appendIfAbsent(entry) {
         let added = false;
         await this.backend.withMemoryLock(async () => {
-            added = await this.appendIfAbsentUnlocked(entry);
+            added = await appendIfAbsentUnlocked(this.writePathDeps(), entry);
         });
         if (added)
-            this.notifyAfterWrite();
+            this.listeners.notifyAfterWrite();
         return added;
     }
-    /** Fire-and-forget: parse Memory Export from compact summary → appendIfAbsent. */
     appendFromCompaction(opts) {
         void this.ingestCompactionSummary(opts).catch(() => { });
     }
@@ -139,26 +145,16 @@ export class MemoryStore {
         if (await this.hasProcessedCompaction(opts.compactionId))
             return;
         await this.ensureInitialized();
-        const parsed = parseMemoryExport(opts.summary);
-        if (opts.subagent) {
-            const existing = await this.listEntries();
-            const delta = filterCompactionDelta(parsed, existing);
-            if (shouldSkipSubagentCompactionIngest(parsed, delta)) {
-                await this.markCompactionProcessed(opts.compactionId);
-                await opts.onComplete?.();
-                return;
-            }
-            if (delta.length > 0) {
-                await this.appendMany(delta, { mode: "ifAbsent" });
-            }
-        }
-        else if (parsed.length > 0) {
-            await this.appendMany(parsed, { mode: "ifAbsent" });
-        }
+        await ingestMemoryExport({
+            store: this,
+            summary: opts.summary,
+            isSubagent: !!opts.subagent,
+        });
         await this.markCompactionProcessed(opts.compactionId);
         await opts.onComplete?.();
     }
     async updateEntry(id, patch) {
+        // Path B: correction detector should reuse prepareEntryForWrite when content is patched.
         await this.backend.withMemoryLock(async () => {
             const resolved = await this.readResolvedUnlocked();
             const target = resolved.entries.find((entry) => entry.id === id);
@@ -173,9 +169,9 @@ export class MemoryStore {
                 timestamp: patch.timestamp ?? target.timestamp,
                 userAuthored: patch.userAuthored ?? target.userAuthored,
             };
-            await this.rewriteEntriesUnlocked(resolved.entries.map((entry) => (entry.id === id ? { ...entry, ...next } : entry)));
+            await rewriteEntriesUnlocked(this.writePathDeps(), resolved.entries.map((entry) => (entry.id === id ? { ...entry, ...next } : entry)));
         });
-        this.notifyAfterWrite();
+        this.listeners.notifyAfterWrite();
     }
     async removeEntry(id, opts) {
         await this.backend.withMemoryLock(async () => {
@@ -186,15 +182,15 @@ export class MemoryStore {
             if (target.userAuthored && !opts?.force) {
                 throw new Error(`Cannot remove user-authored entry without force: ${id}`);
             }
-            await this.rewriteEntriesUnlocked(resolved.entries.filter((entry) => entry.id !== id));
+            await rewriteEntriesUnlocked(this.writePathDeps(), resolved.entries.filter((entry) => entry.id !== id));
         });
-        this.notifyAfterWrite();
+        this.listeners.notifyAfterWrite();
     }
     async rewrite(content) {
         await this.backend.withMemoryLock(async () => {
             await this.backend.writeText(this.paths.memoryFile, content);
         });
-        this.notifyAfterWrite({ skipConsolidateCheck: true });
+        this.listeners.notifyAfterWrite({ skipConsolidateCheck: true });
     }
     async shouldConsolidate(at, cronFired = false) {
         const stats = await this.getStats();
@@ -206,37 +202,26 @@ export class MemoryStore {
             return false;
         return daysSince(stats.lastConsolidatedAt, at) >= CONSOLIDATE_GC_INTERVAL_DAYS;
     }
-    async consolidate(llm) {
+    isConsolidating() {
+        return this.consolidating;
+    }
+    async rewriteMemoryUnderLock(updateEntries) {
         if (this.consolidating)
             return;
         this.consolidating = true;
         try {
             await this.backend.withMemoryLock(async () => {
                 const resolved = await this.readResolvedUnlocked();
-                let entries = dedupeEntries(resolved.entries);
-                try {
-                    entries = await mergeEntriesWithLlm(entries, llm);
-                }
-                catch {
-                    // rule-based dedupe only
-                }
-                await this.rewriteEntriesUnlocked(entries);
+                const entries = await updateEntries(resolved.entries);
+                await rewriteEntriesUnlocked(this.writePathDeps(), entries);
                 await writeText(this.paths.memoryGcFile, `${formatTimestamp()}\n`);
             });
-            this.notifySyncToSidecar();
+            this.listeners.notifySyncToSidecar();
         }
         finally {
             this.consolidating = false;
         }
     }
-    consolidateInBackground(llm, opts = {}) {
-        void this.consolidate(llm)
-            .then(() => opts.onComplete?.())
-            .catch(() => { });
-    }
-    async forceConsolidate(llm) {
-        await this.consolidate(llm);
-    }
     async hasProcessedCompaction(compactionId) {
         const state = await this.readCompactionState();
         return state.processed.includes(compactionId);
@@ -263,133 +248,14 @@ export class MemoryStore {
         }
         return { ok: issues.length === 0, issues };
     }
-    /** Register a listener to sync MEMORY.md changes to the sidecar vector index. */
     onSyncToSidecar(listener) {
-        this.syncToSidecarListeners.add(listener);
-        return () => this.syncToSidecarListeners.delete(listener);
+        return this.listeners.onSyncToSidecar(listener);
     }
-    /** Register a listener invoked after writes to check shouldConsolidate. */
     onConsolidateCheck(listener) {
-        this.consolidateCheckListeners.add(listener);
-        return () => this.consolidateCheckListeners.delete(listener);
-    }
-    notifyAfterWrite(opts) {
-        this.notifySyncToSidecar();
-        if (!opts?.skipConsolidateCheck && !this.consolidating) {
-            this.notifyConsolidateCheck();
-        }
-    }
-    notifySyncToSidecar() {
-        for (const listener of this.syncToSidecarListeners)
-            listener();
-    }
-    notifyConsolidateCheck() {
-        for (const listener of this.consolidateCheckListeners)
-            listener();
-    }
-    async appendUnlocked(entry) {
-        const normalized = this.normalizeEntry(entry);
-        const main = await this.backend.readText(this.paths.memoryFile);
-        if (countLines(main) >= this.maxLines) {
-            await this.appendToOverflowUnlocked(normalized, main);
-            return;
-        }
-        const next = this.insertEntryIntoMarkdown(main, normalized);
-        if (countLines(next) > this.maxLines) {
-            await this.appendToOverflowUnlocked(normalized, main);
-            return;
-        }
-        await this.backend.writeText(this.paths.memoryFile, next);
-    }
-    async appendIfAbsentUnlocked(entry) {
-        const resolved = await this.readResolvedUnlocked();
-        const exists = resolved.entries.some((item) => item.section === entry.section && item.content.trim() === entry.content.trim());
-        if (exists)
-            return false;
-        await this.appendUnlocked(entry);
-        return true;
-    }
-    async appendToOverflowUnlocked(entry, main) {
-        const autoFiles = await this.backend.listAutoFiles(this.paths.agentDir);
-        let targetName = autoFiles.at(-1);
-        let targetPath = targetName
-            ? this.backend.autoFilePath(this.paths.agentDir, targetName)
-            : this.newAutoFilePath();
-        if (!targetName) {
-            targetName = pathBasename(targetPath);
-            await this.backend.writeText(targetPath, `${formatSectionHeader(entry.section)}\n\n`);
-        }
-        let overflowContent = await this.backend.readText(targetPath);
-        const line = formatEntryLine(entry);
-        overflowContent = overflowContent.trimEnd() + `\n${line}\n`;
-        await this.backend.writeText(targetPath, overflowContent);
-        const pointer = `- (overflow) → ${targetName}`;
-        if (!main.includes(pointer)) {
-            const withPointer = `${main.trimEnd()}\n${pointer}\n`;
-            await this.backend.writeText(this.paths.memoryFile, withPointer);
-        }
-    }
-    insertEntryIntoMarkdown(content, entry) {
-        const lines = content.split("\n");
-        const header = formatSectionHeader(entry.section);
-        const headerIdx = lines.findIndex((line) => line.trim() === header);
-        const line = formatEntryLine(entry);
-        if (headerIdx === -1) {
-            const trimmed = content.trimEnd();
-            return `${trimmed}\n\n${header}\n\n${line}\n`;
-        }
-        let insertAt = headerIdx + 1;
-        while (insertAt < lines.length && lines[insertAt]?.trim() === "")
-            insertAt++;
-        while (insertAt < lines.length) {
-            const current = lines[insertAt];
-            if (current.startsWith("## "))
-                break;
-            insertAt++;
-        }
-        const next = [...lines.slice(0, insertAt), line, ...lines.slice(insertAt)];
-        return `${next.join("\n").trimEnd()}\n`;
-    }
-    async rewriteEntriesUnlocked(entries) {
-        const grouped = new Map();
-        for (const section of MEMORY_SECTIONS)
-            grouped.set(section, []);
-        for (const entry of entries) {
-            grouped.get(entry.section)?.push(entry);
-        }
-        const lines = [];
-        for (const section of MEMORY_SECTIONS) {
-            lines.push(formatSectionHeader(section), "");
-            for (const entry of grouped.get(section) ?? []) {
-                lines.push(formatEntryLine({
-                    id: entry.id,
-                    section: entry.section,
-                    content: entry.content,
-                    userAuthored: entry.userAuthored,
-                    timestamp: entry.timestamp,
-                }));
-            }
-            lines.push("");
-        }
-        await this.backend.writeText(this.paths.memoryFile, `${lines.join("\n").trimEnd()}\n`);
-        const autoFiles = await this.backend.listAutoFiles(this.paths.agentDir);
-        await Promise.all(autoFiles.map((fileName) => this.backend.deleteAutoFile(this.backend.autoFilePath(this.paths.agentDir, fileName))));
+        return this.listeners.onConsolidateCheck(listener);
     }
     async readResolvedUnlocked() {
-        const main = await this.backend.readText(this.paths.memoryFile);
-        const entries = [...parseMemoryMarkdown(main, this.paths.memoryFile)];
-        for (const fileName of listOverflowPointers(main)) {
-            const path = this.backend.autoFilePath(this.paths.agentDir, fileName);
-            entries.push(...parseMemoryMarkdown(await this.backend.readText(path), path));
-        }
-        return { content: main, entries };
-    }
-    normalizeEntry(entry) {
-        return {
-            ...entry,
-            id: entry.id || this.newEntryId(),
-            timestamp: entry.timestamp || formatTimestamp(),
-        };
+        return collectResolvedEntries(this.collectResolvedOpts());
     }
     newEntryId() {
         return randomBytes(6).toString("hex");

package/dist/store/resolveEntries.d.ts

@@ -0,0 +1,11 @@
+import type { MarkdownMemoryBackend } from "./backend.js";
+import type { ResolvedMemory } from "./types.js";
+export type CollectResolvedEntriesOpts = {
+    backend: MarkdownMemoryBackend;
+    agentDir: string;
+    memoryFile: string;
+    /** Include auto-*.md files not referenced by MEMORY.md overflow pointers. Default true. */
+    includeOrphans?: boolean;
+};
+/** Read main MEMORY.md plus overflow / orphan auto files into a single entry list. */
+export declare function collectResolvedEntries(opts: CollectResolvedEntriesOpts): Promise<ResolvedMemory>;

package/dist/store/resolveEntries.js

@@ -0,0 +1,23 @@
+import { listOverflowPointers, parseMemoryMarkdown } from "./markdown/parse.js";
+/** Read main MEMORY.md plus overflow / orphan auto files into a single entry list. */
+export async function collectResolvedEntries(opts) {
+    const main = await opts.backend.readText(opts.memoryFile);
+    const entries = [...parseMemoryMarkdown(main, opts.memoryFile)];
+    const pointers = listOverflowPointers(main);
+    for (const fileName of pointers) {
+        const path = opts.backend.autoFilePath(opts.agentDir, fileName);
+        const overflow = await opts.backend.readText(path);
+        entries.push(...parseMemoryMarkdown(overflow, path));
+    }
+    if (opts.includeOrphans !== false) {
+        const autoFiles = await opts.backend.listAutoFiles(opts.agentDir);
+        for (const fileName of autoFiles) {
+            if (pointers.includes(fileName))
+                continue;
+            const path = opts.backend.autoFilePath(opts.agentDir, fileName);
+            const orphan = await opts.backend.readText(path);
+            entries.push(...parseMemoryMarkdown(orphan, path));
+        }
+    }
+    return { content: main, entries };
+}

package/dist/store/types.d.ts

@@ -27,7 +27,6 @@ export type IntegrityReport = {
     ok: boolean;
     issues: string[];
 };
-export type { LlmClient } from "../adapters/llm/types.js";
 export type MemoryStoreOptions = {
     agentDir: string;
     memoryFileName?: string;