@phuetz/code-buddy 1.6.0 → 2.0.0

package/dist/memory/hybrid-mmr.js

@@ -0,0 +1,127 @@
+/**
+ * Hybrid retrieval core — BM25 + embeddings fused by Reciprocal Rank Fusion,
+ * reranked with MMR (Maximal Marginal Relevance). Pure and deterministic:
+ * callers supply the scores/vectors, this module only ranks.
+ *
+ * WHY RRF and not a weighted sum: BM25 scores are unbounded and
+ * corpus-dependent, cosine similarities live in [-1, 1] with a
+ * model-dependent distribution — a linear mix of the two is an arbitrary
+ * calibration that silently shifts whenever the corpus or the embedding
+ * model changes. RRF (Cormack, Clarke & Buettcher 2009) fuses RANKS:
+ * `score(d) = Σ_leg w_leg / (K + rank_leg(d))` — scale-free, robust, no
+ * per-corpus tuning, and it degrades gracefully when one leg is missing
+ * (a doc unranked by a leg simply contributes nothing for that leg).
+ * `semanticWeight` weighs the legs (weighted-RRF variant), K=60 is the
+ * literature default (flattens the head so one leg cannot dictate alone).
+ *
+ * WHY MMR (Carbonell & Goldstein 1998): naive top-k maximizes relevance
+ * only, so near-duplicate passages crowd the result and — in an auditable
+ * context injection — waste the token budget AND bias the agent by
+ * majority-through-duplication. MMR selects greedily
+ * `argmax λ·rel(d) − (1−λ)·max_sim(d, selected)`: λ=1 is pure relevance
+ * (== naive top-k), λ=0 is pure diversity; λ≈0.7 keeps the head relevant
+ * while forcing coverage of distinct facts.
+ *
+ * @module memory/hybrid-mmr
+ */
+const DEFAULT_LAMBDA = 0.7;
+const DEFAULT_SEMANTIC_WEIGHT = 0.7;
+const DEFAULT_RRF_K = 60;
+export function cosineSimilarityF32(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    const denom = Math.sqrt(na) * Math.sqrt(nb);
+    return denom === 0 ? 0 : dot / denom;
+}
+/** 1-based ranks for the ids, ordered by score desc; null/absent scores are unranked. */
+function ranksByScore(entries) {
+    const ranked = entries
+        .filter((e) => e.score !== null && Number.isFinite(e.score))
+        .sort((a, b) => b.score - a.score);
+    const ranks = new Map();
+    ranked.forEach((e, i) => ranks.set(e.id, i + 1));
+    return ranks;
+}
+/**
+ * Weighted Reciprocal Rank Fusion over the two legs, then domain priors.
+ * Returns candidates sorted by fused relevance (no diversity yet).
+ */
+export function fuseHybrid(candidates, opts = {}) {
+    const wSem = clamp01(opts.semanticWeight ?? DEFAULT_SEMANTIC_WEIGHT);
+    const rrfK = opts.rrfK ?? DEFAULT_RRF_K;
+    const lexRanks = ranksByScore(candidates.map((c) => ({ id: c.id, score: c.lexicalScore > 0 ? c.lexicalScore : null })));
+    const semRanks = ranksByScore(candidates.map((c) => ({ id: c.id, score: c.semanticScore })));
+    return candidates
+        .map((c) => {
+        const lexicalRank = lexRanks.get(c.id) ?? null;
+        const semanticRank = semRanks.get(c.id) ?? null;
+        const rrf = (semanticRank !== null ? wSem / (rrfK + semanticRank) : 0) +
+            (lexicalRank !== null ? (1 - wSem) / (rrfK + lexicalRank) : 0);
+        return {
+            id: c.id,
+            relevance: rrf * (c.prior ?? 1),
+            lexicalRank,
+            semanticRank,
+        };
+    })
+        .sort((a, b) => b.relevance - a.relevance);
+}
+function clamp01(n) {
+    return Number.isFinite(n) ? Math.max(0, Math.min(1, n)) : 0;
+}
+/**
+ * MMR greedy selection over fused candidates. Diversity similarity uses the
+ * candidate VECTORS (cosine); candidates without a vector fall back to a
+ * zero similarity (they can only be crowded out by relevance, never by
+ * diversity — honest degradation when embeddings are unavailable).
+ */
+export function mmrSelect(fused, vectors, opts) {
+    const lambda = clamp01(opts.lambda ?? DEFAULT_LAMBDA);
+    const k = Math.max(1, opts.k);
+    if (fused.length === 0)
+        return [];
+    // Normalise relevance to [0,1] so λ trades off against a comparable
+    // diversity term (cosine is already ≤ 1).
+    const maxRel = fused[0].relevance || 1;
+    const pool = fused.map((c) => ({ ...c, rel: maxRel === 0 ? 0 : c.relevance / maxRel }));
+    const selected = [];
+    const remaining = [...pool];
+    while (selected.length < k && remaining.length > 0) {
+        let bestIdx = 0;
+        let bestScore = -Infinity;
+        for (let i = 0; i < remaining.length; i++) {
+            const cand = remaining[i];
+            const v = vectors.get(cand.id) ?? null;
+            let maxSim = 0;
+            if (v) {
+                for (const s of selected) {
+                    const sv = vectors.get(s.id) ?? null;
+                    if (sv)
+                        maxSim = Math.max(maxSim, cosineSimilarityF32(v, sv));
+                }
+            }
+            const mmr = lambda * cand.rel - (1 - lambda) * maxSim;
+            if (mmr > bestScore) {
+                bestScore = mmr;
+                bestIdx = i;
+            }
+        }
+        selected.push(remaining.splice(bestIdx, 1)[0]);
+    }
+    return selected.map(({ id, relevance, lexicalRank, semanticRank }) => ({ id, relevance, lexicalRank, semanticRank }));
+}
+/** Fusion + MMR in one call — the shape recallHybrid consumes. */
+export function hybridMmrRank(candidates, opts) {
+    const fused = fuseHybrid(candidates, opts);
+    const vectors = new Map(candidates.map((c) => [c.id, c.vector]));
+    return mmrSelect(fused, vectors, opts);
+}
+//# sourceMappingURL=hybrid-mmr.js.map

package/dist/memory/hybrid-search.js

@@ -96,7 +96,10 @@ export class BM25Index {
     tokenize(text) {
         return text
             .toLowerCase()
-            .replace(/[^\w\s]/g, ' ')
+            // Unicode-aware: `\w` is ASCII-only, so `[^\w\s]` deleted accented
+            // characters ("créer" → "cr"+"er"), wrecking memory recall for French
+            // (and other non-ASCII) content. Keep letters/digits/underscore.
+            .replace(/[^\p{L}\p{N}_\s]/gu, ' ')
             .split(/\s+/)
             .filter(t => t.length > 0);
     }

package/dist/memory/knowledge-graph.d.ts

@@ -21,8 +21,8 @@
  *   - Background-safe extraction (fire-and-forget)
  *   - Reinforcement counting (frequently mentioned = more important)
  */
-export type EntityType = 'user' | 'project' | 'person' | 'tool' | 'concept' | 'preference' | 'habit' | 'file' | 'technology' | 'organization';
-export type RelationType = 'prefers' | 'dislikes' | 'uses' | 'works_on' | 'knows' | 'related_to' | 'created_by' | 'depends_on' | 'temporal_pattern' | 'has_style' | 'avoids' | 'collaborates_with' | 'owns';
+export type EntityType = 'user' | 'project' | 'person' | 'tool' | 'concept' | 'preference' | 'habit' | 'file' | 'technology' | 'organization' | 'agent' | 'task' | 'lesson' | 'decision' | 'fact' | 'discovery';
+export type RelationType = 'prefers' | 'dislikes' | 'uses' | 'works_on' | 'knows' | 'related_to' | 'created_by' | 'depends_on' | 'temporal_pattern' | 'has_style' | 'avoids' | 'collaborates_with' | 'owns' | 'decided_by' | 'blocks' | 'learned_from' | 'supersedes' | 'verified_by' | 'supports' | 'contradicts' | 'builds_on';
 export interface Entity {
     id: string;
     type: EntityType;
@@ -34,6 +34,16 @@ export interface Entity {
     mentions: number;
     createdAt: Date;
     updatedAt: Date;
+    /** Valid-time start: when the fact became true (Zep bi-temporal). */
+    validFrom?: Date;
+    /** Valid-time end: when it stopped being true; `null`/absent = currently true. */
+    validTo?: Date | null;
+    /** Transaction-time: when the system recorded it (drives cross-machine merge). */
+    recordedAt?: Date;
+    /** Which agent contributed this (`<host>/<repo>`, defaultFleetAgentId). */
+    agentId?: string;
+    /** Provenance label (e.g. 'chat', 'council', 'worklog', 'dream'). */
+    source?: string;
 }
 export interface Relation {
     id: string;
@@ -49,6 +59,16 @@ export interface Relation {
     mentions: number;
     createdAt: Date;
     updatedAt: Date;
+    /** Valid-time start: when the relation became true. */
+    validFrom?: Date;
+    /** Valid-time end: when it stopped being true; `null`/absent = currently true. */
+    validTo?: Date | null;
+    /** Transaction-time: when the system recorded it. */
+    recordedAt?: Date;
+    /** Which agent contributed this. */
+    agentId?: string;
+    /** Provenance label. */
+    source?: string;
 }
 export interface GraphQuery {
     /** Starting entity name or ID */
@@ -114,6 +134,7 @@ export declare class KnowledgeGraph {
     private dbPath;
     private dirty;
     private loaded;
+    private loadPromise;
     private saveTimer;
     private idCounter;
     /** memU Layer 3: auto-categories with summaries */

package/dist/memory/knowledge-graph.js

@@ -22,9 +22,9 @@
  *   - Reinforcement counting (frequently mentioned = more important)
  */
 import { createHash } from 'crypto';
-import { existsSync } from 'fs';
-import { dirname, join } from 'path';
+import { join } from 'path';
 import { logger } from '../utils/logger.js';
+import { readJsonAtomic, writeJsonAtomic } from '../utils/atomic-write.js';
 import { shouldWriteProjectRuntimeFiles } from '../utils/runtime-flags.js';
 // ============================================================================
 // memU Salience Scoring
@@ -176,6 +176,7 @@ export class KnowledgeGraph {
     dbPath;
     dirty = false;
     loaded = false;
+    loadPromise = null;
     saveTimer = null;
     idCounter = 0;
     /** memU Layer 3: auto-categories with summaries */
@@ -772,51 +773,67 @@ export class KnowledgeGraph {
     async load() {
         if (this.loaded)
             return;
-        this.loaded = true;
-        try {
-            if (!existsSync(this.dbPath))
-                return;
-            const { readFile } = await import('fs/promises');
-            const content = await readFile(this.dbPath, 'utf-8');
-            const data = JSON.parse(content);
-            // Restore entities
-            for (const e of data.entities || []) {
-                e.createdAt = new Date(e.createdAt);
-                e.updatedAt = new Date(e.updatedAt);
-                this.entities.set(e.id, e);
-                this.adjacency.set(e.id, new Set());
-                this.reverseAdjacency.set(e.id, new Set());
-                const idNum = parseInt(e.id.split('_')[1] || '0');
-                if (idNum > this.idCounter)
-                    this.idCounter = idNum;
-            }
-            // Restore relations
-            for (const r of data.relations || []) {
-                r.createdAt = new Date(r.createdAt);
-                r.updatedAt = new Date(r.updatedAt);
-                this.relations.set(r.id, r);
-                if (this.adjacency.has(r.sourceId))
-                    this.adjacency.get(r.sourceId).add(r.id);
-                if (this.reverseAdjacency.has(r.targetId))
-                    this.reverseAdjacency.get(r.targetId).add(r.id);
-                const idNum = parseInt(r.id.split('_')[1] || '0');
-                if (idNum > this.idCounter)
-                    this.idCounter = idNum;
+        if (this.loadPromise)
+            return this.loadPromise;
+        this.loadPromise = (async () => {
+            try {
+                const data = await readJsonAtomic(this.dbPath, {
+                    entities: [],
+                    relations: [],
+                    categories: [],
+                    contentHashes: [],
+                }, {
+                    mode: 0o600,
+                    isValid: (value) => Boolean(value && typeof value === 'object'
+                        && Array.isArray(value.entities)
+                        && Array.isArray(value.relations)
+                        && Array.isArray(value.categories)
+                        && Array.isArray(value.contentHashes)),
+                });
+                // Restore entities
+                for (const e of data.entities || []) {
+                    e.createdAt = new Date(e.createdAt);
+                    e.updatedAt = new Date(e.updatedAt);
+                    this.entities.set(e.id, e);
+                    this.adjacency.set(e.id, new Set());
+                    this.reverseAdjacency.set(e.id, new Set());
+                    const idNum = parseInt(e.id.split('_')[1] || '0');
+                    if (idNum > this.idCounter)
+                        this.idCounter = idNum;
+                }
+                // Restore relations
+                for (const r of data.relations || []) {
+                    r.createdAt = new Date(r.createdAt);
+                    r.updatedAt = new Date(r.updatedAt);
+                    this.relations.set(r.id, r);
+                    if (this.adjacency.has(r.sourceId))
+                        this.adjacency.get(r.sourceId).add(r.id);
+                    if (this.reverseAdjacency.has(r.targetId))
+                        this.reverseAdjacency.get(r.targetId).add(r.id);
+                    const idNum = parseInt(r.id.split('_')[1] || '0');
+                    if (idNum > this.idCounter)
+                        this.idCounter = idNum;
+                }
+                // Restore categories (memU Layer 3)
+                for (const c of data.categories || []) {
+                    c.updatedAt = new Date(c.updatedAt);
+                    this.categories.set(c.name, c);
+                }
+                // Restore content hashes
+                for (const h of data.contentHashes || []) {
+                    this.contentHashes.add(h);
+                }
+                logger.debug(`KnowledgeGraph: loaded ${this.entities.size} entities, ${this.relations.size} relations, ${this.categories.size} categories`);
             }
-            // Restore categories (memU Layer 3)
-            for (const c of data.categories || []) {
-                c.updatedAt = new Date(c.updatedAt);
-                this.categories.set(c.name, c);
+            catch (err) {
+                logger.debug(`KnowledgeGraph load failed: ${err instanceof Error ? err.message : String(err)}`);
             }
-            // Restore content hashes
-            for (const h of data.contentHashes || []) {
-                this.contentHashes.add(h);
+            finally {
+                this.loaded = true;
+                this.loadPromise = null;
             }
-            logger.debug(`KnowledgeGraph: loaded ${this.entities.size} entities, ${this.relations.size} relations, ${this.categories.size} categories`);
-        }
-        catch (err) {
-            logger.debug(`KnowledgeGraph load failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
+        })();
+        return this.loadPromise;
     }
     async save() {
         if (!this.dirty)
@@ -826,7 +843,6 @@ export class KnowledgeGraph {
             return;
         }
         try {
-            const { mkdir, writeFile } = await import('fs/promises');
             const data = {
                 version: 2,
                 savedAt: new Date().toISOString(),
@@ -835,8 +851,7 @@ export class KnowledgeGraph {
                 categories: [...this.categories.values()],
                 contentHashes: [...this.contentHashes],
             };
-            await mkdir(dirname(this.dbPath), { recursive: true });
-            await writeFile(this.dbPath, JSON.stringify(data, null, 2), 'utf-8');
+            await writeJsonAtomic(this.dbPath, data, { mode: 0o600 });
             this.dirty = false;
             logger.debug(`KnowledgeGraph: saved ${data.entities.length} entities, ${data.relations.length} relations, ${data.categories.length} categories`);
         }

package/dist/memory/memory-candidate-queue.js

@@ -10,6 +10,7 @@ import fs from 'fs';
 import path from 'path';
 import { scanForSecrets, redactSecrets } from '../fleet/privacy-lint.js';
 import { logger } from '../utils/logger.js';
+import { readJsonAtomicSync, writeJsonAtomicSync } from '../utils/atomic-write.js';
 import { getMemoryManager, } from './persistent-memory.js';
 export const MEMORY_CANDIDATE_SCHEMA_VERSION = 1;
 const VALID_CATEGORIES = [
@@ -178,9 +179,13 @@ export class MemoryCandidateQueue {
             return;
         this.loaded = true;
         try {
-            if (!fs.existsSync(this.filePath))
-                return;
-            const parsed = JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
+            const parsed = readJsonAtomicSync(this.filePath, {
+                schemaVersion: MEMORY_CANDIDATE_SCHEMA_VERSION,
+                candidates: [],
+            }, {
+                mode: 0o600,
+                isValid: (value) => Boolean(value && typeof value === 'object' && Array.isArray(value.candidates)),
+            });
             if (Array.isArray(parsed.candidates)) {
                 this.candidates = parsed.candidates.filter(isValidCandidate);
             }
@@ -198,7 +203,7 @@ export class MemoryCandidateQueue {
                 schemaVersion: MEMORY_CANDIDATE_SCHEMA_VERSION,
                 candidates: this.candidates,
             };
-            fs.writeFileSync(this.filePath, JSON.stringify(file, null, 2), 'utf-8');
+            writeJsonAtomicSync(this.filePath, file, { mode: 0o600 });
         }
         catch (err) {
             logger.warn('[memory-candidates] failed to save queue', {

package/dist/memory/memory-consolidation.d.ts

@@ -44,6 +44,14 @@ export declare function extractMemoriesFromMessages(messages: Array<{
     role: string;
     content: string;
 }>, source?: string): ExtractedMemory[];
+/**
+ * Extract memories from a rollout or a persisted session payload.
+ *
+ * Rollouts are commonly represented as JSONL, while SessionStore persists a
+ * JSON object containing a `messages` array. Supporting both shapes keeps the
+ * background worker independent from the session persistence format.
+ */
+export declare function extractMemoriesFromRollout(rollout: unknown, source?: string): ExtractedMemory[];
 /**
  * Consolidate extracted memories into the progressive-disclosure folder.
  */

package/dist/memory/memory-consolidation.js

@@ -15,6 +15,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { logger } from '../utils/logger.js';
+import { readTextAtomicSync, writeFileAtomicSync } from '../utils/atomic-write.js';
 // ============================================================================
 // Phase 1: Extraction
 // ============================================================================
@@ -71,6 +72,64 @@ export function extractMemoriesFromMessages(messages, source = 'session') {
     }
     return memories;
 }
+/**
+ * Extract memories from a rollout or a persisted session payload.
+ *
+ * Rollouts are commonly represented as JSONL, while SessionStore persists a
+ * JSON object containing a `messages` array. Supporting both shapes keeps the
+ * background worker independent from the session persistence format.
+ */
+export function extractMemoriesFromRollout(rollout, source = 'rollout') {
+    let payload = rollout;
+    if (typeof rollout === 'string') {
+        let contents = rollout;
+        try {
+            if (fs.existsSync(rollout)) {
+                contents = fs.readFileSync(rollout, 'utf8');
+                source = rollout;
+            }
+        }
+        catch {
+            // Treat the input as rollout content when a path cannot be read.
+        }
+        try {
+            payload = JSON.parse(contents);
+        }
+        catch {
+            payload = contents
+                .split(/\r?\n/)
+                .filter(line => line.trim())
+                .flatMap(line => {
+                try {
+                    return [JSON.parse(line)];
+                }
+                catch {
+                    return [];
+                }
+            });
+        }
+    }
+    const rawMessages = Array.isArray(payload)
+        ? payload
+        : isRecord(payload) && Array.isArray(payload.messages)
+            ? payload.messages
+            : [];
+    const messages = rawMessages.flatMap(message => {
+        if (!isRecord(message) || typeof message.content !== 'string') {
+            return [];
+        }
+        const role = typeof message.role === 'string'
+            ? message.role
+            : typeof message.type === 'string'
+                ? message.type
+                : null;
+        return role ? [{ role, content: message.content }] : [];
+    });
+    return extractMemoriesFromMessages(messages, source);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 // ============================================================================
 // Phase 2: Consolidation
 // ============================================================================
@@ -91,10 +150,7 @@ export function consolidateMemories(newMemories, cwd = process.cwd()) {
         fs.mkdirSync(rolloutDir, { recursive: true });
     // Load existing memories
     const memoryFilePath = path.join(memDir, MEMORY_FILE);
-    let existingContent = '';
-    if (fs.existsSync(memoryFilePath)) {
-        existingContent = fs.readFileSync(memoryFilePath, 'utf-8');
-    }
+    const existingContent = readTextAtomicSync(memoryFilePath, '');
     const existingLines = new Set(existingContent.split('\n')
         .filter(l => l.startsWith('- '))
         .map(l => l.slice(2).trim().toLowerCase()));
@@ -136,7 +192,7 @@ export function consolidateMemories(newMemories, cwd = process.cwd()) {
             // Atomic lock: O_EXCL fails if file exists
             fs.writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
             try {
-                fs.appendFileSync(memoryFilePath, section);
+                fs.appendFileSync(memoryFilePath, section, { encoding: 'utf8', mode: 0o600 });
             }
             finally {
                 try {
@@ -147,7 +203,7 @@ export function consolidateMemories(newMemories, cwd = process.cwd()) {
         }
         catch {
             // Lock failed (another process writing) — append anyway (appendFileSync is atomic on most OS for small writes)
-            fs.appendFileSync(memoryFilePath, section);
+            fs.appendFileSync(memoryFilePath, section, { encoding: 'utf8', mode: 0o600 });
         }
     }
     // Update summary (first 500 chars of key facts)
@@ -159,7 +215,7 @@ export function consolidateMemories(newMemories, cwd = process.cwd()) {
         .join('\n');
     if (preferences.trim()) {
         const summaryContent = `# Memory Summary\n\nKey preferences and patterns:\n${preferences}\n`;
-        fs.writeFileSync(summaryPath, summaryContent.substring(0, 2000));
+        writeFileAtomicSync(summaryPath, summaryContent.substring(0, 2000), { mode: 0o600 });
     }
     // Write rollout summary
     const firstMemory = newMemories[0];
@@ -174,7 +230,7 @@ export function consolidateMemories(newMemories, cwd = process.cwd()) {
             ``,
             ...newMemories.map(m => `- [${m.category}] ${m.summary}`),
         ].join('\n');
-        fs.writeFileSync(rolloutPath, rolloutContent);
+        writeFileAtomicSync(rolloutPath, rolloutContent, { mode: 0o600 });
         // Prune old rollout summaries (keep last 30)
         try {
             const summaries = fs.readdirSync(rolloutDir).sort();
@@ -200,14 +256,7 @@ export function consolidateMemories(newMemories, cwd = process.cwd()) {
  */
 export function loadMemorySummary(cwd = process.cwd()) {
     const summaryPath = path.join(cwd, MEMORY_DIR, SUMMARY_FILE);
-    try {
-        if (fs.existsSync(summaryPath)) {
-            const content = fs.readFileSync(summaryPath, 'utf-8');
-            if (content.trim())
-                return content;
-        }
-    }
-    catch { /* optional */ }
-    return null;
+    const content = readTextAtomicSync(summaryPath, '');
+    return content || null;
 }
 //# sourceMappingURL=memory-consolidation.js.map

package/dist/memory/memory-forgetting.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Memory forgetting — Ebbinghaus retention curve with recall reinforcement.
+ *
+ * retention(t) = exp(−ageDays / stability), where stability grows with every
+ * recall: stability = baseStabilityDays × (1 + accessCount). A memory that is
+ * never recalled fades below the forget threshold in a few weeks; one the
+ * agent actually uses keeps strengthening and survives — the spaced-repetition
+ * shape, driven by the accessCount the store already tracks.
+ *
+ * Pure decision logic only: PersistentMemoryManager owns the recoverable
+ * archive-then-delete, sensory/dreaming owns the cadence (sleep consolidates
+ * AND prunes). Convergent priority from the MySoulmate mining + 2026 survey
+ * (MemoryBank 2305.10250): a companion that never forgets drowns its own
+ * char-budgeted memory file.
+ */
+/** Structural subset of persistent-memory's Memory (no import — keeps this module dependency-free). */
+export interface ForgettableMemory {
+    key: string;
+    value: string;
+    category: string;
+    createdAt: Date;
+    updatedAt: Date;
+    lastAccessedAt?: Date;
+    accessCount: number;
+    tags?: string[];
+}
+export interface ForgettingConfig {
+    /** Stability (days) of a never-recalled memory — retention hits e⁻¹ at this age. */
+    baseStabilityDays: number;
+    /** Forget when retention falls below this (0..1). */
+    retentionThreshold: number;
+    /** Grace period: never forget a memory younger than this many days. */
+    minAgeDays: number;
+    /** Categories that never decay (durable by nature). */
+    protectedCategories: ReadonlySet<string>;
+    /** A memory carrying one of these tags never decays. */
+    protectedTags: ReadonlySet<string>;
+}
+export declare const DEFAULT_FORGETTING_CONFIG: ForgettingConfig;
+/** Env overrides: CODEBUDDY_MEMORY_FORGET_BASE_DAYS / _THRESHOLD / _MIN_AGE_DAYS. */
+export declare function resolveForgettingConfig(env?: NodeJS.ProcessEnv): ForgettingConfig;
+export declare function isProtectedMemory(memory: ForgettableMemory, config: ForgettingConfig): boolean;
+export declare function stabilityDays(accessCount: number, baseStabilityDays: number): number;
+export declare function retentionOf(ageDays: number, accessCount: number, config: ForgettingConfig): number;
+export interface ForgetCandidate {
+    key: string;
+    category: string;
+    ageDays: number;
+    accessCount: number;
+    retention: number;
+}
+/**
+ * Decide which memories have faded below the retention threshold. Age is
+ * measured from the last recall (fallback: last update), so reinforcement
+ * both restarts the clock AND raises stability.
+ */
+export declare function decideForgets(memories: Iterable<ForgettableMemory>, now: Date, config?: Partial<ForgettingConfig>): ForgetCandidate[];