@phuetz/code-buddy 1.6.1 → 2.0.0

package/dist/memory/persistent-memory.js

@@ -3,8 +3,12 @@ import * as path from "path";
 import * as os from "os";
 import { EventEmitter } from "events";
 import { getHooksManager } from "../hooks/lifecycle-hooks.js";
+import { FactsExtractionError } from "./facts-memory.js";
 import { logger } from "../utils/logger.js";
 import { shouldWriteProjectRuntimeFiles } from "../utils/runtime-flags.js";
+import { decideForgets, isProtectedMemory, resolveForgettingConfig, } from "./memory-forgetting.js";
+import { withSessionLock } from "../persistence/session-lock.js";
+import { writeFileAtomic } from '../utils/atomic-write.js';
 function mapMemoryCategoryToFactCategory(cat) {
     switch (cat) {
         case 'project': return 'Projet';
@@ -16,6 +20,15 @@ function mapMemoryCategoryToFactCategory(cat) {
         default: return 'Profil';
     }
 }
+export function parseReconciledFactText(text) {
+    const colonIdx = text.indexOf(': ');
+    if (colonIdx <= 0)
+        return null;
+    return {
+        key: text.substring(0, colonIdx).trim(),
+        value: text.substring(colonIdx + 2).trim(),
+    };
+}
 function mapFactCategoryToMemoryCategory(cat) {
     switch (cat) {
         case 'Projet': return 'project';
@@ -49,12 +62,40 @@ export class MemoryWriteRejectedError extends Error {
         this.name = 'MemoryWriteRejectedError';
     }
 }
+export class MemoryPersistenceError extends Error {
+    scope;
+    constructor(scope, message) {
+        super(message ?? `${scope} memory store is unreadable; persistence was refused to protect existing data`);
+        this.scope = scope;
+        this.name = 'MemoryPersistenceError';
+    }
+}
 function parsePositiveInt(value, fallback) {
     if (!value)
         return fallback;
     const parsed = Number.parseInt(value, 10);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
+function parseMemoryMeta(body) {
+    const field = (name) => new RegExp(`\\b${name}=(\\S+)`).exec(body)?.[1];
+    const date = (raw) => {
+        if (!raw)
+            return undefined;
+        const parsed = new Date(raw);
+        return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+    };
+    const accessed = Number.parseInt(field("accessed") ?? "", 10);
+    return {
+        createdAt: date(field("created")),
+        updatedAt: date(field("updated")),
+        lastAccessedAt: date(field("last")),
+        accessCount: Number.isFinite(accessed) && accessed >= 0 ? accessed : undefined,
+    };
+}
+function renderMemoryMeta(memory) {
+    const last = memory.lastAccessedAt ? ` last=${memory.lastAccessedAt.toISOString()}` : "";
+    return `  <!-- meta: accessed=${memory.accessCount} created=${memory.createdAt.toISOString()} updated=${memory.updatedAt.toISOString()}${last} -->`;
+}
 function cloneMemoryMap(memories) {
     return new Map(Array.from(memories.entries()).map(([key, memory]) => [
         key,
@@ -62,10 +103,62 @@ function cloneMemoryMap(memories) {
             ...memory,
             createdAt: new Date(memory.createdAt),
             updatedAt: new Date(memory.updatedAt),
+            lastAccessedAt: memory.lastAccessedAt ? new Date(memory.lastAccessedAt) : undefined,
             tags: memory.tags ? [...memory.tags] : undefined,
         },
     ]));
 }
+function mergeMemoryTags(priorTags, factSource, fallbackTags) {
+    const sourceTags = factSource
+        ?.split(',')
+        .map((tag) => tag.trim())
+        .filter((tag) => tag.length > 0) ?? fallbackTags ?? [];
+    const tags = [...new Set([...(priorTags ?? []), ...sourceTags])];
+    return tags.length > 0 ? tags : undefined;
+}
+function normalizeMemoryCategory(category) {
+    switch (category.trim().toLowerCase()) {
+        case 'project': return 'project';
+        case 'preferences': return 'preferences';
+        case 'decisions': return 'decisions';
+        case 'patterns': return 'patterns';
+        case 'context': return 'context';
+        default: return 'custom';
+    }
+}
+function memoryEquals(left, right) {
+    if (!left || !right)
+        return left === right;
+    const leftTags = left.tags ?? [];
+    const rightTags = right.tags ?? [];
+    return left.key === right.key
+        && left.value === right.value
+        && left.category === right.category
+        && left.createdAt.getTime() === right.createdAt.getTime()
+        && left.updatedAt.getTime() === right.updatedAt.getTime()
+        && left.lastAccessedAt?.getTime() === right.lastAccessedAt?.getTime()
+        && left.accessCount === right.accessCount
+        && leftTags.length === rightTags.length
+        && leftTags.every((tag, index) => tag === rightTags[index]);
+}
+function mergeMemoryMaps(diskMemories, localMemories, persistedSnapshot) {
+    const merged = cloneMemoryMap(diskMemories);
+    // Apply only local additions/updates. Unchanged entries were loaded from
+    // the same snapshot and must not overwrite a newer process' changes.
+    for (const [key, memory] of localMemories) {
+        if (!memoryEquals(memory, persistedSnapshot.get(key))) {
+            merged.set(key, cloneMemoryMap(new Map([[key, memory]])).get(key));
+        }
+    }
+    // Propagate local deletions only when the disk entry is still the version
+    // this manager loaded. A concurrent update wins over a stale deletion.
+    for (const [key, persisted] of persistedSnapshot) {
+        if (!localMemories.has(key) && memoryEquals(merged.get(key), persisted)) {
+            merged.delete(key);
+        }
+    }
+    return merged;
+}
 const MEMORY_TEMPLATE = `# Code Buddy Memory
 
 This file stores persistent memory for the Code Buddy agent.
@@ -97,6 +190,13 @@ export class PersistentMemoryManager extends EventEmitter {
     config;
     projectMemories = new Map();
     userMemories = new Map();
+    /** Last disk snapshot used to distinguish local changes from stale state. */
+    persistedMemorySnapshots = new Map();
+    /** Audit 2026-09-02 — garde anti-amnésie : scopes dont le chargement a
+     * échoué pour une raison AUTRE que l'absence du fichier. Tant qu'un scope
+     * est dégradé, saveMemories refuse la réécriture destructrice (il retente
+     * d'abord un load + fusion, RAM prioritaire). */
+    degradedScopes = new Map();
     initialized = false;
     /**
      * Promise gate for concurrent initialize() callers (F31).
@@ -109,6 +209,9 @@ export class PersistentMemoryManager extends EventEmitter {
      * promise and returning it to every caller ensures a single run.
      */
     initPromise = null;
+    /** Scopes with unpersisted recall reinforcement (see reinforce/flushAccessMetadata). */
+    accessDirtyScopes = new Set();
+    accessFlushTimer = null;
     constructor(config = {}) {
         super();
         this.config = { ...DEFAULT_CONFIG, ...config };
@@ -146,14 +249,14 @@ export class PersistentMemoryManager extends EventEmitter {
             const projectDir = path.dirname(this.config.projectMemoryPath);
             await fs.ensureDir(projectDir);
             if (!(await fs.pathExists(this.config.projectMemoryPath))) {
-                await fs.writeFile(this.config.projectMemoryPath, MEMORY_TEMPLATE);
+                await writeFileAtomic(this.config.projectMemoryPath, MEMORY_TEMPLATE, { mode: 0o600 });
             }
         }
         // Ensure user memory file
         const userDir = path.dirname(this.config.userMemoryPath);
         await fs.ensureDir(userDir);
         if (!(await fs.pathExists(this.config.userMemoryPath))) {
-            await fs.writeFile(this.config.userMemoryPath, MEMORY_TEMPLATE);
+            await writeFileAtomic(this.config.userMemoryPath, MEMORY_TEMPLATE, { mode: 0o600 });
         }
     }
     async loadMemories(scope) {
@@ -164,13 +267,62 @@ export class PersistentMemoryManager extends EventEmitter {
         try {
             const content = await fs.readFile(filePath, "utf-8");
             const parsed = this.parseMemoryFile(content);
+            // Un fichier vide (0 octet ou blancs) n'a rien à protéger : magasin neuf,
+            // pas magasin corrompu (garde R28, alignée le 2026-09-02).
+            if (parsed.length === 0 && content.trim() !== '' && !this.isCanonicalEmptyMemoryFile(content)) {
+                throw new Error('non-canonical memory markdown contains no recoverable entries');
+            }
+            memories.clear();
             for (const memory of parsed) {
                 memories.set(memory.key, memory);
             }
+            this.persistedMemorySnapshots.set(scope, cloneMemoryMap(memories));
+            this.degradedScopes.delete(scope);
+        }
+        catch (error) {
+            // File doesn't exist -> start fresh (légitime). Toute AUTRE erreur
+            // (EACCES, EIO…) est transitoire : sans garde, la prochaine sauvegarde
+            // réécrirait le fichier entier depuis l'état vide — amnésie silencieuse.
+            if (error?.code !== 'ENOENT') {
+                const reason = error?.message ?? String(error);
+                this.degradedScopes.set(scope, reason);
+                logger.warn(`[persistent-memory] could not load ${scope} memory (${reason}) — destructive saves are blocked until a successful reload`);
+            }
+            else {
+                this.persistedMemorySnapshots.set(scope, new Map());
+            }
         }
-        catch (_error) {
-            // File doesn't exist or can't be read, start fresh
+    }
+    /** Only the generated empty template is safe to treat as a new empty store. */
+    isCanonicalEmptyMemoryFile(content) {
+        const requiredCategories = [
+            'Project Context',
+            'User Preferences',
+            'Decisions',
+            'Patterns',
+            'Custom',
+        ];
+        const allowedCategories = [...requiredCategories, 'Context'];
+        const seenCategories = new Set();
+        const allowedText = new Set([
+            '# Code Buddy Memory',
+            'This file stores persistent memory for the Code Buddy agent.',
+            'It is automatically managed but can be manually edited.',
+            '---',
+        ]);
+        for (const rawLine of content.split('\n')) {
+            const line = rawLine.trim();
+            if (!line || allowedText.has(line) || /^<!--.*-->$/.test(line) || /^\*Last updated: .*\*$/.test(line)) {
+                continue;
+            }
+            const category = /^## (.+)$/.exec(line)?.[1];
+            if (category && allowedCategories.includes(category)) {
+                seenCategories.add(category);
+                continue;
+            }
+            return false;
         }
+        return requiredCategories.every((category) => seenCategories.has(category));
     }
     parseMemoryFile(content) {
         const memories = [];
@@ -186,7 +338,18 @@ export class PersistentMemoryManager extends EventEmitter {
         const lines = content.split("\n");
         let currentKey = "";
         let currentValue = "";
+        let currentMeta;
+        let currentTags;
         let inMemoryBlock = false;
+        const pushCurrent = () => {
+            if (currentKey && currentValue) {
+                memories.push(this.createMemory(currentKey, currentValue.trim(), currentCategory, currentMeta, currentTags));
+            }
+            currentKey = "";
+            currentValue = "";
+            currentMeta = undefined;
+            currentTags = undefined;
+        };
         for (const line of lines) {
             // Check for category headers
             if (line.startsWith("## ")) {
@@ -199,9 +362,7 @@ export class PersistentMemoryManager extends EventEmitter {
             // Check for memory entries (format: - **key**: value)
             const memoryMatch = line.match(/^-\s*\*\*([^*]+)\*\*:\s*(.*)$/);
             if (memoryMatch) {
-                if (currentKey && currentValue) {
-                    memories.push(this.createMemory(currentKey, currentValue.trim(), currentCategory));
-                }
+                pushCurrent();
                 // Group 1 (`[^*]+`) always matches at least one char; group 2 (`.*`) defaults to "" when empty.
                 const [, matchedKey = "", matchedValue = ""] = memoryMatch;
                 currentKey = matchedKey;
@@ -209,34 +370,58 @@ export class PersistentMemoryManager extends EventEmitter {
                 inMemoryBlock = true;
                 continue;
             }
+            // Metadata comment (written by saveMemories; absent in older files).
+            // Must be checked BEFORE the multi-line continuation branch or it would
+            // be folded into the value.
+            const metaMatch = line.match(/^\s*<!--\s*meta:\s*(.*?)\s*-->\s*$/);
+            if (metaMatch && inMemoryBlock) {
+                currentMeta = parseMemoryMeta(metaMatch[1] ?? "");
+                continue;
+            }
+            // Tags line written by saveMemories (`  Tags: a, b`). Audit 2026-09-02 :
+            // sans cette branche, la ligne était refondue dans la valeur au 1er
+            // reload puis détruite au 2e — `pinned` ne protégeait plus rien après
+            // un redémarrage.
+            const tagsMatch = line.match(/^ {2}Tags:\s*(.*)$/);
+            if (tagsMatch && inMemoryBlock && currentTags === undefined) {
+                currentTags = (tagsMatch[1] ?? "")
+                    .split(",")
+                    .map((t) => t.trim())
+                    .filter((t) => t.length > 0);
+                continue;
+            }
+            // New saves prefix continuation lines with `  |` so their original
+            // indentation and any literal `Tags:` text remain unambiguous.
+            if (inMemoryBlock && line.startsWith("  |")) {
+                currentValue += "\n" + line.slice(3);
+                continue;
+            }
             // Continue multi-line value
             if (inMemoryBlock && line.startsWith("  ")) {
-                currentValue += "\n" + line.trim();
+                // Legacy files used two transport spaces without a marker. Remove
+                // only that transport prefix; do not destroy content indentation.
+                currentValue += "\n" + line.slice(2);
             }
             else if (inMemoryBlock && line.trim() === "") {
                 // End of memory block
-                if (currentKey && currentValue) {
-                    memories.push(this.createMemory(currentKey, currentValue.trim(), currentCategory));
-                }
-                currentKey = "";
-                currentValue = "";
+                pushCurrent();
                 inMemoryBlock = false;
             }
         }
         // Don't forget last memory
-        if (currentKey && currentValue) {
-            memories.push(this.createMemory(currentKey, currentValue.trim(), currentCategory));
-        }
+        pushCurrent();
         return memories;
     }
-    createMemory(key, value, category) {
+    createMemory(key, value, category, meta, tags) {
         return {
             key,
             value,
             category,
-            createdAt: new Date(),
-            updatedAt: new Date(),
-            accessCount: 0,
+            createdAt: meta?.createdAt ?? new Date(),
+            updatedAt: meta?.updatedAt ?? new Date(),
+            ...(meta?.lastAccessedAt ? { lastAccessedAt: meta.lastAccessedAt } : {}),
+            accessCount: meta?.accessCount ?? 0,
+            ...(tags && tags.length > 0 ? { tags } : {}),
         };
     }
     /**
@@ -260,7 +445,7 @@ export class PersistentMemoryManager extends EventEmitter {
             };
         }
         const previousMemories = cloneMemoryMap(memories);
-        const status = existing ? 'updated' : 'stored';
+        let resultKey = normalizedKey;
         try {
             const { FactsMemoryService } = await import('./facts-memory.js');
             const service = new FactsMemoryService();
@@ -282,22 +467,32 @@ export class PersistentMemoryManager extends EventEmitter {
                 for (const fact of reconciledFacts) {
                     let fKey = `fact-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`;
                     let fValue = fact.text;
-                    const colonIdx = fact.text.indexOf(': ');
-                    if (colonIdx > 0 && colonIdx < 50) {
-                        fKey = fact.text.substring(0, colonIdx).trim();
-                        fValue = fact.text.substring(colonIdx + 2).trim();
+                    const parsed = parseReconciledFactText(fact.text);
+                    if (parsed) {
+                        fKey = parsed.key;
+                        fValue = parsed.value;
                     }
-                    const existing = memories.get(fKey);
+                    // The map was cleared above — prior metadata lives in previousMemories.
+                    const prior = previousMemories.get(fKey);
                     memories.set(fKey, {
                         key: fKey,
                         value: fValue,
                         category: mapFactCategoryToMemoryCategory(fact.category),
-                        createdAt: existing?.createdAt || fact.updatedAt || new Date(),
+                        createdAt: prior?.createdAt || fact.updatedAt || new Date(),
                         updatedAt: fact.updatedAt || new Date(),
-                        accessCount: existing?.accessCount || 0,
-                        tags: fact.source ? [fact.source] : tags
+                        ...(prior?.lastAccessedAt ? { lastAccessedAt: prior.lastAccessedAt } : {}),
+                        accessCount: prior?.accessCount || 0,
+                        tags: mergeMemoryTags(prior?.tags, fact.source, tags)
                     });
                 }
+                if (!memories.has(normalizedKey)) {
+                    const newKeys = Array.from(memories.keys()).filter((memoryKey) => !previousMemories.has(memoryKey));
+                    const reconciledKey = newKeys[newKeys.length - 1];
+                    if (!reconciledKey) {
+                        throw new Error(`Reconciliation did not retain the new memory "${normalizedKey}"`);
+                    }
+                    resultKey = reconciledKey;
+                }
             }
             else {
                 // Fallback to default direct write
@@ -323,17 +518,31 @@ export class PersistentMemoryManager extends EventEmitter {
             }
             throw err;
         }
-        await this.saveMemories(scope);
-        this.emit("memory:remembered", { key: normalizedKey, scope, category });
+        try {
+            await this.saveMemories(scope);
+        }
+        catch (error) {
+            memories.clear();
+            for (const [memoryKey, memory] of previousMemories) {
+                memories.set(memoryKey, memory);
+            }
+            throw error;
+        }
+        const persistedMemory = memories.get(resultKey);
+        if (!persistedMemory) {
+            throw new MemoryPersistenceError(scope, `Memory reconciliation reported key "${resultKey}" but did not retain it`);
+        }
+        const status = previousMemories.has(resultKey) ? 'updated' : 'stored';
+        this.emit("memory:remembered", { key: resultKey, scope, category: persistedMemory.category });
         return {
             status,
-            key: normalizedKey,
+            key: resultKey,
             scope,
-            category,
+            category: persistedMemory.category,
             usage: this.getMemoryUsage(scope),
             message: status === 'updated'
-                ? `Updated "${normalizedKey}" in ${scope} memory.`
-                : `Stored "${normalizedKey}" in ${scope} memory.`,
+                ? `Updated "${resultKey}" in ${scope} memory.`
+                : `Stored "${resultKey}" in ${scope} memory.`,
         };
     }
     async replace(key, value, options = {}) {
@@ -341,6 +550,7 @@ export class PersistentMemoryManager extends EventEmitter {
         const memories = scope === 'project' ? this.projectMemories : this.userMemories;
         const normalizedKey = key.trim();
         const normalizedValue = value.trim();
+        this.assertScopeReadable(scope);
         const existing = memories.get(normalizedKey);
         if (!existing) {
             return {
@@ -387,9 +597,10 @@ export class PersistentMemoryManager extends EventEmitter {
         const memory = {
             key,
             value,
-            category,
+            category: normalizeMemoryCategory(category),
             createdAt: existing?.createdAt || new Date(),
             updatedAt: new Date(),
+            ...(existing?.lastAccessedAt ? { lastAccessedAt: existing.lastAccessedAt } : {}),
             accessCount: existing?.accessCount || 0,
             tags,
         };
@@ -467,29 +678,96 @@ export class PersistentMemoryManager extends EventEmitter {
      */
     recall(key, scope) {
         if (scope) {
+            this.assertScopeReadable(scope);
             const memories = scope === "project" ? this.projectMemories : this.userMemories;
             const memory = memories.get(key);
             if (memory) {
-                memory.accessCount++;
+                this.reinforce(memory, scope);
                 return memory.value;
             }
             return null;
         }
         // Search both scopes, project first
-        let memory = this.projectMemories.get(key);
-        if (!memory) {
-            memory = this.userMemories.get(key);
-        }
+        this.assertScopeReadable('project');
+        this.assertScopeReadable('user');
+        const projectHit = this.projectMemories.get(key);
+        const memory = projectHit ?? this.userMemories.get(key);
         if (memory) {
-            memory.accessCount++;
+            this.reinforce(memory, projectHit ? "project" : "user");
             return memory.value;
         }
         return null;
     }
+    /**
+     * Recall reinforcement: bump the spaced-repetition signals the forgetting
+     * curve reads (accessCount → stability, lastAccessedAt → decay anchor) and
+     * schedule a debounced persist so they survive restarts.
+     */
+    reinforce(memory, scope) {
+        memory.accessCount++;
+        memory.lastAccessedAt = new Date();
+        this.scheduleAccessFlush(scope);
+    }
+    scheduleAccessFlush(scope) {
+        this.accessDirtyScopes.add(scope);
+        if (this.accessFlushTimer)
+            return;
+        this.accessFlushTimer = setTimeout(() => {
+            void this.flushAccessMetadata();
+        }, 10_000);
+        this.accessFlushTimer.unref?.();
+    }
+    /** Persist pending recall reinforcement now (also runs on a 10s debounce). Never throws. */
+    async flushAccessMetadata() {
+        if (this.accessFlushTimer) {
+            clearTimeout(this.accessFlushTimer);
+            this.accessFlushTimer = null;
+        }
+        const scopes = Array.from(this.accessDirtyScopes);
+        this.accessDirtyScopes.clear();
+        for (const scope of scopes) {
+            try {
+                // Headless one-shot runs must not create project runtime files just
+                // because something was recalled (same invariant as ensureMemoryFiles).
+                if (scope === "project" &&
+                    !shouldWriteProjectRuntimeFiles() &&
+                    !(await fs.pathExists(this.config.projectMemoryPath))) {
+                    continue;
+                }
+                await this.saveMemories(scope);
+            }
+            catch (err) {
+                logger.warn(`[persistent-memory] could not persist recall reinforcement (${scope}): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    /**
+     * Non-reinforcing single-entry read. Unlike `recall()`, this does NOT bump
+     * `accessCount`/`lastAccessedAt`, so surface reads (REST GET, listings)
+     * don't distort the Ebbinghaus forgetting curve. With no scope, project is
+     * checked first, then user — the same precedence as `recall()`.
+     */
+    get(key, scope) {
+        const normalizedKey = key.trim();
+        if (!scope || scope === "project") {
+            this.assertScopeReadable('project');
+            const memory = this.projectMemories.get(normalizedKey);
+            if (memory)
+                return { ...memory, scope: "project" };
+        }
+        if (!scope || scope === "user") {
+            this.assertScopeReadable('user');
+            const memory = this.userMemories.get(normalizedKey);
+            if (memory)
+                return { ...memory, scope: "user" };
+        }
+        return undefined;
+    }
     /**
      * Forget something (remove from memory)
      */
     async forget(key, scope = "project") {
+        this.assertScopeReadable(scope);
         const memories = scope === "project" ? this.projectMemories : this.userMemories;
         const deleted = memories.delete(key);
         if (deleted) {
@@ -502,14 +780,16 @@ export class PersistentMemoryManager extends EventEmitter {
      * Get memories relevant to a query (simple keyword matching)
      */
     getRelevantMemories(query, limit = 5) {
+        this.assertScopeReadable('project');
+        this.assertScopeReadable('user');
         const queryLower = query.toLowerCase();
         const queryWords = queryLower.split(/\s+/);
         const allMemories = [
-            ...this.projectMemories.values(),
-            ...this.userMemories.values(),
+            ...Array.from(this.projectMemories.values(), (memory) => ({ memory, scope: "project" })),
+            ...Array.from(this.userMemories.values(), (memory) => ({ memory, scope: "user" })),
         ];
         // Score memories by relevance
-        const scored = allMemories.map((memory) => {
+        const scored = allMemories.map(({ memory, scope }) => {
             const textLower = `${memory.key} ${memory.value}`.toLowerCase();
             let score = 0;
             for (const word of queryWords) {
@@ -519,19 +799,231 @@ export class PersistentMemoryManager extends EventEmitter {
             }
             // Boost by access count
             score += memory.accessCount * 0.1;
-            return { memory, score };
+            return { memory, scope, score };
         });
         // Sort by score and return top results
-        return scored
+        const top = scored
             .filter((s) => s.score > 0)
             .sort((a, b) => b.score - a.score)
-            .slice(0, limit)
-            .map((s) => s.memory);
+            .slice(0, limit);
+        // Retrieval-for-prompt counts as recall: reinforce the returned hits
+        // (unlike getContextForPrompt, which renders everything indiscriminately).
+        for (const { memory, scope } of top) {
+            this.reinforce(memory, scope);
+        }
+        return top.map((s) => s.memory);
+    }
+    /**
+     * Read-only enumeration of live memories (copies) for inspection tooling —
+     * the Curator's dry-run forgetting scan reads through this instead of
+     * poking the private maps. Does NOT reinforce (unlike getRelevantMemories).
+     */
+    listMemories(scope) {
+        this.assertScopeReadable(scope);
+        const memories = scope === "project" ? this.projectMemories : this.userMemories;
+        return Array.from(memories.values()).map((m) => ({
+            ...m,
+            ...(m.tags ? { tags: [...m.tags] } : {}),
+        }));
+    }
+    /**
+     * Ebbinghaus forgetting pass (recoverable): memories whose retention decayed
+     * below the threshold are appended to a sibling `*.archive.md`, then removed.
+     * An archive write failure aborts the pass — we never drop what we could not
+     * preserve. `preferences`/`decisions` and `pinned`-tagged entries never decay
+     * (see memory-forgetting.ts).
+     */
+    async applyForgetting(scope, options = {}) {
+        this.assertScopeReadable(scope);
+        const memories = scope === "project" ? this.projectMemories : this.userMemories;
+        const now = options.now ?? new Date();
+        const candidates = decideForgets(memories.values(), now, options.config);
+        if (candidates.length === 0)
+            return { forgotten: [] };
+        const archivePath = this.getArchivePath(scope);
+        const lines = candidates.map((candidate) => {
+            const memory = memories.get(candidate.key);
+            const tags = memory.tags?.length ? ` [${memory.tags.join(", ")}]` : "";
+            return (`- **${memory.key}** (${memory.category}${tags}, accessed ${memory.accessCount}×, ` +
+                `age ${Math.round(candidate.ageDays)}d, retention ${candidate.retention.toFixed(3)}): ${escapeArchiveValue(memory.value)}`);
+        });
+        try {
+            await fs.ensureDir(path.dirname(archivePath));
+            await fs.appendFile(archivePath, `\n## Forgotten ${now.toISOString()}\n${lines.join("\n")}\n`);
+        }
+        catch (err) {
+            logger.warn(`[persistent-memory] forgetting aborted — archive write failed, keeping all ${scope} memories: ${err instanceof Error ? err.message : String(err)}`);
+            return { forgotten: [] };
+        }
+        for (const candidate of candidates) {
+            memories.delete(candidate.key);
+        }
+        await this.saveMemories(scope);
+        for (const candidate of candidates) {
+            this.emit("memory:forgotten", { key: candidate.key, scope, reason: "decay", retention: candidate.retention });
+        }
+        logger.info(`[persistent-memory] ${scope}: ${candidates.length} memories faded (archived to ${archivePath})`);
+        return { forgotten: candidates };
+    }
+    getArchivePath(scope) {
+        const filePath = scope === "project" ? this.config.projectMemoryPath : this.config.userMemoryPath;
+        return filePath.replace(/\.md$/i, "") + ".archive.md";
+    }
+    /**
+     * List the entries the forgetting pass archived (newest first). Parses the
+     * `*.archive.md` sections written by applyForgetting():
+     *   `## Forgotten <ISO>` then `- **key** (category[ [tags]], accessed N×,
+     *   age Dd, retention R): value`.
+     */
+    async listArchived(scope) {
+        const scopes = scope ? [scope] : ["project", "user"];
+        const out = [];
+        for (const s of scopes) {
+            const parsed = await this.parseArchive(s);
+            out.push(...parsed.map(({ lineIndex: _lineIndex, ...entry }) => entry));
+        }
+        return out.sort((a, b) => (a.forgottenAt < b.forgottenAt ? 1 : a.forgottenAt > b.forgottenAt ? -1 : 0));
+    }
+    /**
+     * Restore a forgotten entry from the archive back into live memory — the
+     * "recoverable" half of the Ebbinghaus pass. The LATEST archived version of
+     * the key wins (project checked before user when no scope is given). The
+     * critical action is the re-remember (restoring = re-learning: the curve
+     * restarts fresh); on success the restored line is removed from the archive
+     * (atomic rewrite, best-effort — a cleanup failure never undoes the restore).
+     * Returns null when the key is not in the archive.
+     */
+    async restoreFromArchive(key, scope) {
+        const normalizedKey = key.trim();
+        const scopes = scope ? [scope] : ["project", "user"];
+        for (const s of scopes) {
+            const parsed = await this.parseArchive(s);
+            const matches = parsed.filter((e) => e.key === normalizedKey);
+            if (matches.length === 0)
+                continue;
+            // Latest version wins: sections are appended chronologically, so the
+            // last file occurrence is the most recent forgetting of this key.
+            const entry = matches[matches.length - 1];
+            const result = await this.remember(entry.key, entry.value, {
+                scope: s,
+                category: entry.category,
+                ...(entry.tags?.length ? { tags: entry.tags } : {}),
+            });
+            if (result.status === "stored" || result.status === "updated") {
+                await this.verifyPersistedMemory(s, result.key, entry.value);
+                await this.removeArchiveLine(s, entry.lineIndex);
+                this.emit("memory:restored", { key: entry.key, scope: s });
+            }
+            const { lineIndex: _lineIndex, ...restored } = entry;
+            return { result, restored };
+        }
+        return null;
+    }
+    /** Re-read the live store before deleting the only archived copy. */
+    async verifyPersistedMemory(scope, key, expectedValue) {
+        const filePath = scope === 'project' ? this.config.projectMemoryPath : this.config.userMemoryPath;
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            const persisted = this.parseMemoryFile(content).find((memory) => memory.key === key);
+            if (persisted?.value === expectedValue)
+                return;
+        }
+        catch (err) {
+            logger.warn(`[persistent-memory] restored memory verification failed (${scope}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        throw new MemoryPersistenceError(scope, `Memory "${key}" was not durably persisted in the ${scope} store; archive left intact`);
+    }
+    /** Parse one scope's archive file into entries carrying their raw line index. */
+    async parseArchive(scope) {
+        const archivePath = this.getArchivePath(scope);
+        let content;
+        try {
+            content = await fs.readFile(archivePath, "utf-8");
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return [];
+            const reason = err instanceof Error ? err.message : String(err);
+            logger.warn(`[persistent-memory] ${scope} memory archive is unreadable: ${reason}`);
+            throw new MemoryPersistenceError(scope, `${scope} memory archive is unreadable (${reason}); it is not empty`);
+        }
+        const entries = [];
+        let forgottenAt = "";
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const section = line.match(/^## Forgotten (.+)$/);
+            if (section) {
+                forgottenAt = section[1].trim();
+                continue;
+            }
+            const entry = line.match(/^- \*\*(.+?)\*\* \((\w+)(?: \[([^\]]*)\])?, accessed \d+×, age \d+d, retention [\d.]+\): (.*)$/);
+            if (!entry)
+                continue;
+            const [, entryKey, rawCategory, rawTags, value] = entry;
+            if (entryKey === undefined || value === undefined)
+                continue;
+            const category = ["project", "preferences", "decisions", "patterns", "context", "custom"].includes(rawCategory)
+                ? rawCategory
+                : "custom";
+            const tags = rawTags
+                ?.split(",")
+                .map((t) => t.trim())
+                .filter(Boolean);
+            entries.push({
+                key: entryKey,
+                value: unescapeArchiveValue(value),
+                category,
+                ...(tags?.length ? { tags } : {}),
+                forgottenAt,
+                scope,
+                lineIndex: i,
+            });
+        }
+        return entries;
+    }
+    /** Drop one restored line from the archive (and any now-empty section), atomically. */
+    async removeArchiveLine(scope, lineIndex) {
+        const archivePath = this.getArchivePath(scope);
+        try {
+            const lines = (await fs.readFile(archivePath, "utf-8")).split("\n");
+            lines.splice(lineIndex, 1);
+            // Remove sections left with no entry lines before the next section.
+            const cleaned = [];
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                if (/^## Forgotten /.test(line)) {
+                    let j = i + 1;
+                    let hasEntry = false;
+                    while (j < lines.length && !/^## Forgotten /.test(lines[j])) {
+                        if (lines[j].startsWith("- "))
+                            hasEntry = true;
+                        j++;
+                    }
+                    if (!hasEntry) {
+                        i = j - 1; // skip the empty section (header + blank filler)
+                        continue;
+                    }
+                }
+                cleaned.push(line);
+            }
+            await writeFileAtomic(archivePath, cleaned.join("\n"), { mode: 0o600 });
+        }
+        catch (err) {
+            logger.warn(`[persistent-memory] archive cleanup after restore failed (restore itself succeeded): ${err instanceof Error ? err.message : String(err)}`);
+        }
     }
     /**
      * Get all memories for a category
      */
     getByCategory(category, scope) {
+        if (scope) {
+            this.assertScopeReadable(scope);
+        }
+        else {
+            this.assertScopeReadable('project');
+            this.assertScopeReadable('user');
+        }
         const memories = [];
         if (!scope || scope === "project") {
             for (const memory of this.projectMemories.values()) {
@@ -553,11 +1045,13 @@ export class PersistentMemoryManager extends EventEmitter {
      * Clear old memories
      */
     async forgetOlderThan(days, scope = "project") {
+        this.assertScopeReadable(scope);
         const memories = scope === "project" ? this.projectMemories : this.userMemories;
         const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+        const forgettingConfig = resolveForgettingConfig();
         let count = 0;
         for (const [key, memory] of memories) {
-            if (memory.updatedAt < cutoff) {
+            if (memory.updatedAt < cutoff && !isProtectedMemory(memory, forgettingConfig)) {
                 memories.delete(key);
                 count++;
             }
@@ -575,69 +1069,118 @@ export class PersistentMemoryManager extends EventEmitter {
         const filePath = scope === "project"
             ? this.config.projectMemoryPath
             : this.config.userMemoryPath;
-        // Group by category
-        const byCategory = new Map();
-        for (const memory of memories.values()) {
-            const list = byCategory.get(memory.category) || [];
-            list.push(memory);
-            byCategory.set(memory.category, list);
-        }
-        // Generate markdown
-        let content = `# Code Buddy Memory\n\n`;
-        content += `This file stores persistent memory for the Code Buddy agent.\n`;
-        content += `It is automatically managed but can be manually edited.\n\n`;
-        const categoryNames = {
-            project: "Project Context",
-            preferences: "User Preferences",
-            decisions: "Decisions",
-            patterns: "Patterns",
-            context: "Context",
-            custom: "Custom",
-        };
-        for (const [category, name] of Object.entries(categoryNames)) {
-            content += `## ${name}\n`;
-            const categoryMemories = byCategory.get(category) || [];
-            if (categoryMemories.length === 0) {
-                content += `<!-- No memories in this category -->\n`;
+        // Garde anti-amnésie (audit 2026-09-02) : si le dernier chargement a
+        // échoué autrement que par ENOENT, ce Map ne reflète PAS le fichier.
+        // On retente un load (fusion : les entrées en RAM, plus récentes,
+        // gagnent) ; si le fichier reste illisible, on refuse d'écraser —
+        // fail-closed, comme l'archive de l'oubli.
+        if (this.degradedScopes.has(scope)) {
+            const ramSnapshot = cloneMemoryMap(memories);
+            await this.loadMemories(scope);
+            if (this.degradedScopes.has(scope)) {
+                logger.warn(`[persistent-memory] ${scope} memory file is still unreadable — skipping save to avoid overwriting history`);
+                throw new MemoryPersistenceError(scope);
             }
-            else {
-                for (const memory of categoryMemories) {
-                    content += `- **${memory.key}**: ${memory.value}\n`;
-                    if (memory.tags && memory.tags.length > 0) {
-                        content += `  Tags: ${memory.tags.join(", ")}\n`;
+            for (const [key, memory] of ramSnapshot) {
+                memories.set(key, memory);
+            }
+        }
+        await withSessionLock(filePath, async () => {
+            const diskMemories = new Map();
+            try {
+                const diskContent = await fs.readFile(filePath, "utf-8");
+                const parsed = this.parseMemoryFile(diskContent);
+                if (parsed.length === 0 &&
+                    diskContent.trim() !== '' &&
+                    !this.isCanonicalEmptyMemoryFile(diskContent)) {
+                    throw new Error('non-canonical memory markdown contains no recoverable entries');
+                }
+                for (const memory of parsed)
+                    diskMemories.set(memory.key, memory);
+            }
+            catch (error) {
+                if (error?.code !== 'ENOENT') {
+                    throw new MemoryPersistenceError(scope, `could not reload ${scope} memory before save: ${error?.message ?? String(error)}`);
+                }
+            }
+            const persistedSnapshot = this.persistedMemorySnapshots.get(scope) ?? new Map();
+            const mergedMemories = mergeMemoryMaps(diskMemories, memories, persistedSnapshot);
+            memories.clear();
+            for (const [key, memory] of mergedMemories)
+                memories.set(key, memory);
+            // Group by category
+            const byCategory = new Map();
+            for (const memory of memories.values()) {
+                const list = byCategory.get(memory.category) || [];
+                list.push(memory);
+                byCategory.set(memory.category, list);
+            }
+            // Generate markdown
+            let content = `# Code Buddy Memory\n\n`;
+            content += `This file stores persistent memory for the Code Buddy agent.\n`;
+            content += `It is automatically managed but can be manually edited.\n\n`;
+            const categoryNames = {
+                project: "Project Context",
+                preferences: "User Preferences",
+                decisions: "Decisions",
+                patterns: "Patterns",
+                context: "Context",
+                custom: "Custom",
+            };
+            for (const [category, name] of Object.entries(categoryNames)) {
+                content += `## ${name}\n`;
+                const categoryMemories = byCategory.get(category) || [];
+                if (categoryMemories.length === 0) {
+                    content += `<!-- No memories in this category -->\n`;
+                }
+                else {
+                    for (const memory of categoryMemories) {
+                        // Prefix continuation lines with an explicit transport marker so
+                        // their original indentation and literal metadata-like text survive
+                        // a reload. `  |` also encodes an empty internal line as `  |\n`.
+                        const [first = '', ...rest] = memory.value.split('\n');
+                        content += `- **${memory.key}**: ${first}\n`;
+                        for (const cont of rest) {
+                            content += `  |${cont}\n`;
+                        }
+                        if (memory.tags && memory.tags.length > 0) {
+                            content += `  Tags: ${memory.tags.join(", ")}\n`;
+                        }
+                        content += `${renderMemoryMeta(memory)}\n`;
                     }
                 }
+                content += `\n`;
             }
-            content += `\n`;
-        }
-        content += `---\n`;
-        content += `*Last updated: ${new Date().toISOString()}*\n`;
-        try {
-            const hooksManager = getHooksManager();
-            const results = await hooksManager.executeHooks("before-memory-write", {
-                file: filePath,
-                content: content,
-            });
-            let abort = false;
-            let modifiedContent = content;
-            for (const res of results) {
-                if (res.abort) {
-                    abort = true;
+            content += `---\n`;
+            content += `*Last updated: ${new Date().toISOString()}*\n`;
+            try {
+                const hooksManager = getHooksManager();
+                const results = await hooksManager.executeHooks("before-memory-write", {
+                    file: filePath,
+                    content: content,
+                });
+                let abort = false;
+                let modifiedContent = content;
+                for (const res of results) {
+                    if (res.abort) {
+                        abort = true;
+                    }
+                    if (res.modified?.content !== undefined) {
+                        modifiedContent = res.modified.content;
+                    }
                 }
-                if (res.modified?.content !== undefined) {
-                    modifiedContent = res.modified.content;
+                if (abort) {
+                    return;
                 }
+                content = modifiedContent;
             }
-            if (abort) {
-                return;
+            catch (_err) {
+                // Ignored
             }
-            content = modifiedContent;
-        }
-        catch (_err) {
-            // Ignored
-        }
-        await fs.ensureDir(path.dirname(filePath));
-        await fs.writeFile(filePath, content);
+            await fs.ensureDir(path.dirname(filePath));
+            await writeFileAtomic(filePath, content, { mode: 0o600 });
+            this.persistedMemorySnapshots.set(scope, cloneMemoryMap(memories));
+        });
     }
     /**
      * Get context string for system prompt
@@ -649,6 +1192,10 @@ export class PersistentMemoryManager extends EventEmitter {
         return `--- PERSISTENT MEMORY ---\n${snapshot}\n--- END MEMORY ---\n`;
     }
     getHermesSnapshotForPrompt() {
+        if (this.degradedScopes.size > 0) {
+            const details = Array.from(this.degradedScopes, ([scope, reason]) => `${scope}: ${reason}`).join('; ');
+            return `<memory-store-error>MEMORY STORE ERROR: ${details}. The affected store is unavailable, not empty; do not infer that memories are absent.</memory-store-error>`;
+        }
         const sections = [];
         const projectEntries = this.renderScopeEntries(this.projectMemories);
         const userEntries = this.renderScopeEntries(this.userMemories);
@@ -692,36 +1239,47 @@ export class PersistentMemoryManager extends EventEmitter {
                 updatedAt: memory.updatedAt
             }));
             // 2. Extract facts from the conversation turn
-            const extractedFacts = await service.extractFacts(`User: ${message}\nAssistant: ${response}`);
+            // Only user-authored text is eligible for durable facts. The assistant's
+            // response may contain hypotheses or hallucinations, so it must never
+            // become evidence for the persistent memory store.
+            const extractedFacts = await service.extractFacts(`User: ${message}`);
             if (extractedFacts.length === 0)
                 return;
             // 3. Reconcile facts
             const reconciledFacts = await service.reconcileFacts(currentProjectFacts, extractedFacts);
-            // 4. Update project memories with reconciled facts
+            // 4. Update project memories with reconciled facts (preserving each
+            // surviving key's recall-reinforcement metadata).
+            const priorProjectMemories = new Map(this.projectMemories);
             this.projectMemories.clear();
             for (const fact of reconciledFacts) {
                 let key = `fact-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`;
                 let value = fact.text;
-                const colonIdx = fact.text.indexOf(': ');
-                if (colonIdx > 0 && colonIdx < 50) {
-                    key = fact.text.substring(0, colonIdx).trim();
-                    value = fact.text.substring(colonIdx + 2).trim();
+                const parsed = parseReconciledFactText(fact.text);
+                if (parsed) {
+                    key = parsed.key;
+                    value = parsed.value;
                 }
+                const prior = priorProjectMemories.get(key);
                 this.projectMemories.set(key, {
                     key,
                     value,
                     category: mapFactCategoryToMemoryCategory(fact.category),
-                    createdAt: fact.updatedAt || new Date(),
+                    createdAt: prior?.createdAt || fact.updatedAt || new Date(),
                     updatedAt: fact.updatedAt || new Date(),
-                    accessCount: 0,
-                    tags: fact.source ? [fact.source] : ['auto-captured']
+                    ...(prior?.lastAccessedAt ? { lastAccessedAt: prior.lastAccessedAt } : {}),
+                    accessCount: prior?.accessCount || 0,
+                    tags: mergeMemoryTags(prior?.tags, fact.source, ['auto-captured'])
                 });
             }
             await this.saveMemories("project");
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            logger.warn(`[FactsMemory] Failed to autoCapture facts, falling back to pattern matching: ${message}`);
+            const reason = err instanceof Error ? err.message : String(err);
+            if (err instanceof FactsExtractionError) {
+                logger.warn(`[FactsMemory] Failed to autoCapture facts: ${reason}`);
+                return;
+            }
+            logger.warn(`[FactsMemory] Failed to autoCapture facts, falling back to pattern matching: ${reason}`);
             // Fallback: Detect project context
             const projectPatterns = [
                 /this (?:is|project) (?:a|an) ([^.]+)/i,
@@ -729,7 +1287,7 @@ export class PersistentMemoryManager extends EventEmitter {
                 /the (?:main|entry) (?:file|point) is ([^\s]+)/i,
             ];
             for (const pattern of projectPatterns) {
-                const match = message.match(pattern) || response.match(pattern);
+                const match = message.match(pattern);
                 if (match) {
                     await this.remember(`auto-${Date.now()}`, match[0], {
                         category: "project",
@@ -740,7 +1298,7 @@ export class PersistentMemoryManager extends EventEmitter {
             // Detect preferences
             const prefPatterns = [
                 /(?:i |we )prefer ([^.]+)/i,
-                /(?:always |never )([^.]+)/i,
+                /(?:i |we )(?:(?:always|never) (?:use|choose|write|format|keep|avoid|run|work with) )([^.]+)/i,
                 /use ([^.]+) (?:style|convention|format)/i,
             ];
             for (const pattern of prefPatterns) {
@@ -758,7 +1316,7 @@ export class PersistentMemoryManager extends EventEmitter {
                 /(?:will|should) use ([^.]+) (?:for|because)/i,
             ];
             for (const pattern of decisionPatterns) {
-                const match = message.match(pattern) || response.match(pattern);
+                const match = message.match(pattern);
                 if (match) {
                     await this.remember(`decision-${Date.now()}`, match[0], {
                         category: "decisions",
@@ -779,6 +1337,13 @@ export class PersistentMemoryManager extends EventEmitter {
      * arrive out of order.
      */
     getRecentMemories(limit = 10, scope) {
+        if (scope) {
+            this.assertScopeReadable(scope);
+        }
+        else {
+            this.assertScopeReadable('project');
+            this.assertScopeReadable('user');
+        }
         const all = [];
         if (!scope || scope === "project") {
             for (const m of this.projectMemories.values()) {
@@ -798,6 +1363,13 @@ export class PersistentMemoryManager extends EventEmitter {
      * Format memories for display
      */
     formatMemories(scope) {
+        if (scope) {
+            this.assertScopeReadable(scope);
+        }
+        else {
+            this.assertScopeReadable('project');
+            this.assertScopeReadable('user');
+        }
         let output = `\n🧠 Persistent Memory\n${"═".repeat(50)}\n\n`;
         const formatScope = (name, memories, memoryScope) => {
             const usage = this.getMemoryUsage(memoryScope);
@@ -825,12 +1397,32 @@ export class PersistentMemoryManager extends EventEmitter {
         return output;
     }
     getStats() {
+        this.assertScopeReadable('project');
+        this.assertScopeReadable('user');
         return {
             project: this.projectMemories.size,
             user: this.userMemories.size,
             total: this.projectMemories.size + this.userMemories.size,
         };
     }
+    assertScopeReadable(scope) {
+        const reason = this.degradedScopes.get(scope);
+        if (!reason)
+            return;
+        throw new MemoryPersistenceError(scope, `${scope} memory store is unreadable or unavailable (${reason}); it is not an empty store`);
+    }
+}
+const ARCHIVE_ESCAPED_VALUE_PREFIX = "@codebuddy-escaped-v1:";
+function escapeArchiveValue(value) {
+    return ARCHIVE_ESCAPED_VALUE_PREFIX + value.replace(/\\/g, "\\\\").replace(/\r?\n/g, "\\n");
+}
+/** Decode backslash/newline escapes in one pass so a literal `\\n` stays literal. */
+function unescapeArchiveValue(value) {
+    if (!value.startsWith(ARCHIVE_ESCAPED_VALUE_PREFIX))
+        return value;
+    return value
+        .slice(ARCHIVE_ESCAPED_VALUE_PREFIX.length)
+        .replace(/\\(\\|n)/g, (_match, escaped) => escaped === "n" ? "\n" : "\\");
 }
 // Default singleton instance (no bot scope) + per-bot instances.
 let memoryManagerInstance = null;