@pencil-agent/nano-pencil 1.11.21 → 1.11.23

package/dist/packages/mem-core/engine.js

@@ -29,6 +29,8 @@ export class NanoMemEngine {
     cfg;
     llmFn;
     embeddingFn;
+    static AUTO_V2_LINK_PREFIX = "auto:v2:";
+    static AUTO_REVIVE_MAX_ITEMS = 2;
     knowledgePath;
     lessonsPath;
     eventsPath;
@@ -38,6 +40,13 @@ export class NanoMemEngine {
     metaPath;
     episodesDir;
     v2Paths;
+    archiveKnowledgePath;
+    archiveLessonsPath;
+    archiveEventsPath;
+    archivePreferencesPath;
+    archiveFacetsPath;
+    archiveWorkPath;
+    archiveV2Paths;
     constructor(overrides, llmFn) {
         this.cfg = getConfig(overrides);
         this.llmFn = llmFn;
@@ -53,6 +62,14 @@ export class NanoMemEngine {
         this.metaPath = join(this.cfg.memoryDir, "meta.json");
         this.episodesDir = join(this.cfg.memoryDir, "episodes");
         this.v2Paths = getV2Paths(this.cfg.memoryDir);
+        const archiveDir = join(this.cfg.memoryDir, "_archive");
+        this.archiveKnowledgePath = join(archiveDir, "knowledge.json");
+        this.archiveLessonsPath = join(archiveDir, "lessons.json");
+        this.archiveEventsPath = join(archiveDir, "events.json");
+        this.archivePreferencesPath = join(archiveDir, "preferences.json");
+        this.archiveFacetsPath = join(archiveDir, "facets.json");
+        this.archiveWorkPath = join(archiveDir, "work.json");
+        this.archiveV2Paths = getV2Paths(archiveDir);
     }
     setLlmFn(fn) {
         this.llmFn = fn;
@@ -70,6 +87,7 @@ export class NanoMemEngine {
         const events = await loadEntries(this.eventsPath);
         const prefs = await loadEntries(this.preferencesPath);
         const facets = await loadEntries(this.facetsPath);
+        const v2Semantic = await loadV2Semantic(this.v2Paths);
         for (const item of items) {
             const target = item.type === "lesson"
                 ? lessons
@@ -81,6 +99,7 @@ export class NanoMemEngine {
                             ? facets
                             : knowledge;
             applyExtraction(target, item, project, this.cfg);
+            this.upsertSemanticFromExtractedItem(v2Semantic, item, project);
         }
         const hl = this.cfg.halfLife;
         const ew = this.cfg.evictionWeights;
@@ -90,6 +109,7 @@ export class NanoMemEngine {
             saveEntries(this.eventsPath, events, this.cfg.maxEntries.events, (e) => utilityEntry(e, hl, ew)),
             saveEntries(this.preferencesPath, prefs, this.cfg.maxEntries.preferences, (e) => utilityEntry(e, hl, ew)),
             saveEntries(this.facetsPath, facets, this.cfg.maxEntries.facets, (e) => utilityEntry(e, hl, ew)),
+            saveV2Semantic(this.v2Paths, v2Semantic),
         ]);
         return items;
     }
@@ -156,6 +176,7 @@ export class NanoMemEngine {
         return { episodes, facets, semantic, procedural, links };
     }
     async searchV2Memories(query, limit = 10, scope) {
+        await this.autoReviveRelevantArchive(query, scope);
         const snapshot = await this.getV2Snapshot();
         const project = scope?.project ?? "";
         const episodes = this.filterAndCleanV2Episodes(snapshot.episodes, project, scope);
@@ -318,6 +339,7 @@ export class NanoMemEngine {
     }
     // ─── Retrieval & Injection (Progressive Recall) ────────────
     async getMemoryInjection(project, contextTags, scope) {
+        await this.autoReviveRelevantArchive([project, ...contextTags].join(" ").trim(), scope);
         const [allKnowledge, allLessons, allEvents, allPrefs, allFacets, allEpisodes, allWork, allV2Episodes, allV2EpisodeFacets, allV2Semantic, allProcedural] = await Promise.all([
             loadEntries(this.knowledgePath),
             loadEntries(this.lessonsPath),
@@ -415,12 +437,32 @@ export class NanoMemEngine {
         const cueEpisodeMemories = pickTop(v2Episodes.filter((item) => !activeEpisodeMemories.some((activeItem) => activeItem.id === item.id)), episodeScoreFn, episodeCueLen, Math.max(220, Math.floor(cueChars * 0.12)));
         const cueEpisodeFacets = pickTop(v2EpisodeFacets.filter((item) => !activeEpisodeFacets.some((activeItem) => activeItem.id === item.id)), episodeFacetScoreFn, episodeFacetCueLen, Math.max(220, Math.floor(cueChars * 0.12)));
         const cueSemanticMemories = pickTop(v2Semantic.filter((item) => !activeSemanticMemories.some((activeItem) => activeItem.id === item.id)), semanticMemoryScoreFn, semanticMemoryCueLen, Math.max(220, Math.floor(cueChars * 0.12)));
+        const legacyFacetBridgeActive = activeFacets.filter((entry) => entry.facetData?.kind === "pattern" || entry.facetData?.kind === "struggle");
+        const legacyFacetBridgeCue = dedupedCueFacets.filter((entry) => entry.facetData?.kind === "pattern" || entry.facetData?.kind === "struggle");
+        const v2SignalCount = activeEpisodeMemories.length +
+            activeEpisodeFacets.length +
+            activeSemanticMemories.length +
+            activeProcedural.length +
+            cueEpisodeMemories.length +
+            cueEpisodeFacets.length +
+            cueSemanticMemories.length +
+            cueProcedural.length;
+        const useLegacyFallback = v2SignalCount === 0;
+        const injectedActiveKnowledge = useLegacyFallback ? activeKnowledge : [];
+        const injectedActiveLessons = useLegacyFallback ? activeLessons : [];
+        const injectedActiveEvents = useLegacyFallback ? activeEvents : [];
+        const injectedActivePrefs = useLegacyFallback ? activePrefs : [];
+        const injectedCueKnowledge = useLegacyFallback ? dedupedCueKnowledge : [];
+        const injectedCueLessons = useLegacyFallback ? dedupedCueLessons : [];
+        const injectedCueEvents = useLegacyFallback ? dedupedCueEvents : [];
+        const injectedCuePrefs = useLegacyFallback ? dedupedCuePrefs : [];
+        const injectedCueEpisodes = useLegacyFallback ? topEpisodes : [];
         // Reinforce all recalled entries (Active + Cue) via spaced repetition
-        const allRecalledKnowledge = [...activeKnowledge, ...dedupedCueKnowledge];
-        const allRecalledLessons = [...activeLessons, ...dedupedCueLessons];
-        const allRecalledEvents = [...activeEvents, ...dedupedCueEvents];
-        const allRecalledPrefs = [...activePrefs, ...dedupedCuePrefs];
-        const allRecalledFacets = [...activeFacets, ...dedupedCueFacets];
+        const allRecalledKnowledge = [...injectedActiveKnowledge, ...injectedCueKnowledge];
+        const allRecalledLessons = [...injectedActiveLessons, ...injectedCueLessons];
+        const allRecalledEvents = [...injectedActiveEvents, ...injectedCueEvents];
+        const allRecalledPrefs = [...injectedActivePrefs, ...injectedCuePrefs];
+        const allRecalledFacets = [...legacyFacetBridgeActive, ...legacyFacetBridgeCue];
         await this.reinforceEntries(allRecalledKnowledge, allKnowledge, this.knowledgePath);
         await this.reinforceEntries(allRecalledLessons, allLessons, this.lessonsPath);
         await this.reinforceEntries(allRecalledEvents, allEvents, this.eventsPath);
@@ -438,22 +480,22 @@ export class NanoMemEngine {
             await this.reconsolidateIfNeeded(allRecalledLessons, contextTags, allLessons);
         }
         return this.buildProgressiveInjectionText({
-            knowledge: activeKnowledge,
-            lessons: activeLessons,
-            events: activeEvents,
-            preferences: activePrefs,
-            facets: activeFacets,
+            knowledge: injectedActiveKnowledge,
+            lessons: injectedActiveLessons,
+            events: injectedActiveEvents,
+            preferences: injectedActivePrefs,
+            facets: legacyFacetBridgeActive,
             episodeMemories: activeEpisodeMemories,
             episodeFacets: activeEpisodeFacets,
             semanticMemories: activeSemanticMemories,
             procedural: activeProcedural,
         }, {
-            knowledge: dedupedCueKnowledge,
-            lessons: dedupedCueLessons,
-            events: dedupedCueEvents,
-            preferences: dedupedCuePrefs,
-            facets: dedupedCueFacets,
-            episodes: topEpisodes,
+            knowledge: injectedCueKnowledge,
+            lessons: injectedCueLessons,
+            events: injectedCueEvents,
+            preferences: injectedCuePrefs,
+            facets: legacyFacetBridgeCue,
+            episodes: injectedCueEpisodes,
             work: topWork,
             episodeMemories: cueEpisodeMemories,
             episodeFacets: cueEpisodeFacets,
@@ -596,7 +638,7 @@ export class NanoMemEngine {
     }
     // ─── Stats ───────────────────────────────────────────────────
     async getStats() {
-        const [knowledge, lessons, events, prefs, facets, episodes, work, meta] = await Promise.all([
+        const [knowledge, lessons, events, prefs, facets, episodes, work, meta, archived] = await Promise.all([
             loadEntries(this.knowledgePath),
             loadEntries(this.lessonsPath),
             loadEntries(this.eventsPath),
@@ -605,6 +647,7 @@ export class NanoMemEngine {
             loadEpisodes(this.episodesDir),
             loadWork(this.workPath),
             loadMeta(this.metaPath),
+            this.exportArchive(),
         ]);
         return {
             knowledge: knowledge.length,
@@ -614,11 +657,17 @@ export class NanoMemEngine {
             facets: facets.length,
             episodes: episodes.length,
             work: work.length,
+            archivedKnowledge: archived.knowledge.length,
+            archivedLessons: archived.lessons.length,
+            archivedEvents: archived.events.length,
+            archivedPreferences: archived.preferences.length,
+            archivedFacets: archived.facets.length,
+            archivedWork: archived.work.length,
             totalSessions: meta.totalSessions,
         };
     }
     async getV2Stats() {
-        const [episodes, facets, semantic, procedural, links, embeddingIndex, meta] = await Promise.all([
+        const [episodes, facets, semantic, procedural, links, embeddingIndex, meta, archived] = await Promise.all([
             loadV2Episodes(this.v2Paths),
             loadV2Facets(this.v2Paths),
             loadV2Semantic(this.v2Paths),
@@ -626,12 +675,15 @@ export class NanoMemEngine {
             loadV2Links(this.v2Paths),
             loadEmbeddingIndex(this.cfg.memoryDir),
             loadV2Meta(this.v2Paths),
+            this.exportArchive(),
         ]);
         return {
             episodes: episodes.length,
             facets: facets.length,
             semantic: semantic.length,
             procedural: procedural.length,
+            archivedSemantic: archived.semantic.length,
+            archivedProcedural: archived.procedural.length,
             links: links.length,
             embeddings: embeddingIndex.records.length,
             lastEmbeddingSyncAt: meta.lastEmbeddingSyncAt,
@@ -648,13 +700,22 @@ export class NanoMemEngine {
             facets: await loadEntries(this.facetsPath),
         };
     }
+    async getRuntimeIdentityEntries() {
+        const runtime = await this.buildRuntimeMemoryView();
+        return {
+            knowledge: runtime.knowledge,
+            lessons: runtime.lessons,
+            preferences: runtime.preferences,
+            facets: runtime.facets,
+        };
+    }
     async getAllWork() {
         return loadWork(this.workPath);
     }
     async getAllEpisodes() {
         return loadEpisodes(this.episodesDir);
     }
-    async runStartupMaintenance(maintenanceVersion = 1) {
+    async runStartupMaintenance(maintenanceVersion = 3) {
         const [meta, v2Meta] = await Promise.all([loadMeta(this.metaPath), loadV2Meta(this.v2Paths)]);
         const alreadyMaintained = (meta.lastMaintenanceVersion ?? 0) >= maintenanceVersion &&
             (v2Meta.lastMaintenanceVersion ?? 0) >= maintenanceVersion;
@@ -664,6 +725,7 @@ export class NanoMemEngine {
                 backupPath: undefined,
                 deduplicated: { knowledge: 0, lessons: 0, events: 0, preferences: 0, facets: 0, work: 0, total: 0 },
                 migratedEpisodesToV2: 0,
+                archived: { knowledge: 0, lessons: 0, events: 0, preferences: 0, facets: 0, work: 0, semantic: 0, procedural: 0, total: 0 },
             };
         }
         const now = new Date().toISOString();
@@ -673,6 +735,9 @@ export class NanoMemEngine {
         for (const episode of episodes) {
             await this.syncEpisodeToV2(episode);
         }
+        await this.rebuildV2Links();
+        const archived = await this.archiveStaleMemories();
+        await this.rebuildV2Links();
         await Promise.all([
             writeJson(this.metaPath, {
                 ...(await loadMeta(this.metaPath)),
@@ -696,6 +761,7 @@ export class NanoMemEngine {
             backupPath,
             deduplicated,
             migratedEpisodesToV2: episodes.length,
+            archived,
         };
     }
     async createMaintenanceBackup(meta, v2Meta, maintenanceVersion, now) {
@@ -724,7 +790,7 @@ export class NanoMemEngine {
                 // Missing files are fine for first-run users.
             }
         }
-        for (const dirName of ["episodes", "v2"]) {
+        for (const dirName of ["episodes", "v2", "_archive"]) {
             const sourceDir = join(this.cfg.memoryDir, dirName);
             try {
                 await readdir(sourceDir);
@@ -954,23 +1020,108 @@ export class NanoMemEngine {
         };
     }
     async searchEntries(query, scope) {
+        await this.autoReviveRelevantArchive(query, scope);
+        const runtime = await this.buildRuntimeMemoryView();
         const tags = extractTags(query);
-        const { knowledge, lessons, events, preferences, facets } = await this.getAllEntries();
-        const all = [...knowledge, ...lessons, ...events, ...preferences, ...facets];
-        return filterByScope(all, scope)
-            .map((e) => ({
-            entry: e,
-            score: tagOverlap(e.tags, tags) +
-                (e.relations ?? [])
+        const v2Primary = runtime.v2SearchEntries
+            .map((entry) => ({
+            entry,
+            score: scoreEntry(entry, entry.project, tags, this.cfg.halfLife, this.cfg.scoreWeights),
+        }))
+            .filter((item) => item.score >= 0.42)
+            .sort((a, b) => b.score - a.score)
+            .map((item) => item.entry);
+        if (v2Primary.length > 0) {
+            const bridgeFacets = runtime.facets
+                .filter((entry) => entry.facetData?.kind === "pattern" || entry.facetData?.kind === "struggle")
+                .map((entry) => ({
+                entry,
+                score: scoreEntry(entry, entry.project, tags, this.cfg.halfLife, this.cfg.scoreWeights),
+            }))
+                .filter((item) => item.score >= 0.38)
+                .sort((a, b) => b.score - a.score)
+                .map((item) => item.entry);
+            return [...v2Primary, ...bridgeFacets].slice(0, 12);
+        }
+        const all = [...runtime.knowledge, ...runtime.lessons, ...runtime.events, ...runtime.preferences, ...runtime.facets];
+        return all
+            .map((entry) => ({
+            entry,
+            score: tagOverlap(entry.tags, tags) +
+                (entry.relations ?? [])
                     .filter((relation) => tags.some((tag) => relation.kind.includes(tag) || relation.id.includes(tag)))
                     .reduce((sum, relation) => sum + relation.weight * 0.12, 0),
         }))
-            .filter((x) => x.score > 0)
+            .filter((item) => item.score > 0)
             .sort((a, b) => b.score - a.score)
-            .map((x) => x.entry);
+            .map((item) => item.entry);
+    }
+    async autoReviveRelevantArchive(query, scope, options) {
+        const trimmed = query.trim();
+        const contextTags = extractTags(trimmed);
+        if (!trimmed || contextTags.length === 0)
+            return [];
+        const project = scope?.project ?? "";
+        const hl = this.cfg.halfLife;
+        const sw = this.cfg.scoreWeights;
+        const maxItems = options?.maxItems ?? NanoMemEngine.AUTO_REVIVE_MAX_ITEMS;
+        const legacyThreshold = options?.legacyThreshold ?? 0.82;
+        const v2Threshold = options?.v2Threshold ?? 0.8;
+        const revived = [];
+        const archive = await this.exportArchive();
+        const legacyCandidates = [
+            ...archive.knowledge.map((entry) => ({ entry, location: "knowledge" })),
+            ...archive.lessons.map((entry) => ({ entry, location: "lessons" })),
+            ...archive.events.map((entry) => ({ entry, location: "events" })),
+            ...archive.preferences.map((entry) => ({ entry, location: "preferences" })),
+            ...archive.facets.map((entry) => ({ entry, location: "facets" })),
+        ]
+            .filter(({ entry }) => !scope?.userId || !entry.scope?.userId || entry.scope.userId === scope.userId)
+            .filter(({ entry }) => !scope?.agentId || !entry.scope?.agentId || entry.scope.agentId === scope.agentId)
+            .map(({ entry, location }) => ({
+            id: entry.id,
+            location,
+            score: scoreEntry(entry, project || entry.project, contextTags, hl, sw),
+        }))
+            .filter((candidate) => candidate.score >= legacyThreshold)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, maxItems);
+        for (const candidate of legacyCandidates) {
+            const result = await this.restoreArchivedEntry(candidate.id);
+            if (result.ok && result.location)
+                revived.push({ id: candidate.id, location: result.location });
+        }
+        if (revived.length >= maxItems)
+            return revived;
+        const semanticCandidates = archive.semantic
+            .filter((entry) => !scope?.userId || !entry.scope?.userId || entry.scope.userId === scope.userId)
+            .filter((entry) => !scope?.agentId || !entry.scope?.agentId || entry.scope.agentId === scope.agentId)
+            .filter((entry) => !project || !entry.scope?.project || entry.scope.project === project)
+            .map((entry) => ({ id: entry.id, location: "semantic", score: this.scoreV2SemanticMemory(entry, project, contextTags) }))
+            .filter((candidate) => candidate.score >= v2Threshold);
+        const proceduralCandidates = archive.procedural
+            .filter((entry) => !scope?.userId || !entry.scope?.userId || entry.scope.userId === scope.userId)
+            .filter((entry) => !scope?.agentId || !entry.scope?.agentId || entry.scope.agentId === scope.agentId)
+            .filter((entry) => !project || !entry.scope?.project || entry.scope.project === project)
+            .map((entry) => ({
+            id: entry.id,
+            location: "procedural",
+            // Archived procedures are often older superseded versions, so revive scoring should not punish status as heavily.
+            score: this.scoreProceduralMemory(entry, project, contextTags) + (entry.status === "superseded" || entry.status === "deprecated" ? 0.24 : 0),
+        }))
+            .filter((candidate) => candidate.score >= v2Threshold);
+        const v2Candidates = [...semanticCandidates, ...proceduralCandidates]
+            .sort((a, b) => b.score - a.score)
+            .slice(0, Math.max(0, maxItems - revived.length));
+        for (const candidate of v2Candidates) {
+            const result = await this.restoreArchivedEntry(candidate.id);
+            if (result.ok && result.location)
+                revived.push({ id: candidate.id, location: result.location });
+        }
+        return revived;
     }
     async getAlignmentSnapshot() {
-        const all = await this.exportAll();
+        const all = await this.buildRuntimeMemoryView();
         const memoryEntries = [...all.knowledge, ...all.lessons, ...all.events, ...all.preferences, ...all.facets];
         const sortByInfluence = (entries) => [...entries].sort((a, b) => {
             const aScore = (a.salience ?? a.importance) * ((a.accessCount ?? 0) + 1) + (a.retention === "core" ? 2 : 0);
@@ -1029,6 +1180,19 @@ export class NanoMemEngine {
         ]);
         return { knowledge, lessons, events, preferences, facets, work, episodes, meta };
     }
+    async exportArchive() {
+        const [knowledge, lessons, events, preferences, facets, work, semantic, procedural] = await Promise.all([
+            loadEntries(this.archiveKnowledgePath),
+            loadEntries(this.archiveLessonsPath),
+            loadEntries(this.archiveEventsPath),
+            loadEntries(this.archivePreferencesPath),
+            loadEntries(this.archiveFacetsPath),
+            loadWork(this.archiveWorkPath),
+            loadV2Semantic(this.archiveV2Paths),
+            loadV2Procedural(this.archiveV2Paths),
+        ]);
+        return { knowledge, lessons, events, preferences, facets, work, semantic, procedural };
+    }
     async exportAllV2() {
         const [episodes, facets, semantic, procedural, links] = await Promise.all([
             loadV2Episodes(this.v2Paths),
@@ -1039,16 +1203,206 @@ export class NanoMemEngine {
         ]);
         return { episodes, facets, semantic, procedural, links };
     }
+    async rebuildV2Links() {
+        const snapshot = await this.exportAllV2();
+        const nextLinks = this.materializeV2Links(snapshot.semantic, snapshot.procedural, snapshot.links);
+        await saveV2Links(this.v2Paths, nextLinks);
+        return {
+            total: nextLinks.length,
+            auto: nextLinks.filter((link) => link.id.startsWith(NanoMemEngine.AUTO_V2_LINK_PREFIX)).length,
+        };
+    }
+    async archiveStaleMemories(now = new Date().toISOString()) {
+        const [knowledge, lessons, events, preferences, facets, work, archived, semantic, procedural, archivedSemantic, archivedProcedural] = await Promise.all([
+            loadEntries(this.knowledgePath),
+            loadEntries(this.lessonsPath),
+            loadEntries(this.eventsPath),
+            loadEntries(this.preferencesPath),
+            loadEntries(this.facetsPath),
+            loadWork(this.workPath),
+            this.exportArchive(),
+            loadV2Semantic(this.v2Paths),
+            loadV2Procedural(this.v2Paths),
+            loadV2Semantic(this.archiveV2Paths),
+            loadV2Procedural(this.archiveV2Paths),
+        ]);
+        const knowledgeResult = this.partitionArchivedEntries(knowledge, now);
+        const lessonsResult = this.partitionArchivedEntries(lessons, now);
+        const eventsResult = this.partitionArchivedEntries(events, now);
+        const preferencesResult = this.partitionArchivedEntries(preferences, now);
+        const facetsResult = this.partitionArchivedEntries(facets, now);
+        const workResult = this.partitionArchivedWork(work, now);
+        const semanticResult = this.partitionArchivedSemantic(semantic, now);
+        const proceduralResult = this.partitionArchivedProcedural(procedural, now);
+        const hl = this.cfg.halfLife;
+        const ew = this.cfg.evictionWeights;
+        await Promise.all([
+            saveEntries(this.knowledgePath, knowledgeResult.active, this.cfg.maxEntries.knowledge, (entry) => utilityEntry(entry, hl, ew)),
+            saveEntries(this.lessonsPath, lessonsResult.active, this.cfg.maxEntries.lessons, (entry) => utilityEntry(entry, hl, ew)),
+            saveEntries(this.eventsPath, eventsResult.active, this.cfg.maxEntries.events, (entry) => utilityEntry(entry, hl, ew)),
+            saveEntries(this.preferencesPath, preferencesResult.active, this.cfg.maxEntries.preferences, (entry) => utilityEntry(entry, hl, ew)),
+            saveEntries(this.facetsPath, facetsResult.active, this.cfg.maxEntries.facets, (entry) => utilityEntry(entry, hl, ew)),
+            saveWork(this.workPath, workResult.active, this.cfg.maxEntries.work, (entry) => utilityWork(entry, this.cfg.halfLife, this.cfg.evictionWeights)),
+            saveEntries(this.archiveKnowledgePath, this.mergeArchivedEntries(archived.knowledge, knowledgeResult.archived), Infinity, (entry) => utilityEntry(entry, hl, ew)),
+            saveEntries(this.archiveLessonsPath, this.mergeArchivedEntries(archived.lessons, lessonsResult.archived), Infinity, (entry) => utilityEntry(entry, hl, ew)),
+            saveEntries(this.archiveEventsPath, this.mergeArchivedEntries(archived.events, eventsResult.archived), Infinity, (entry) => utilityEntry(entry, hl, ew)),
+            saveEntries(this.archivePreferencesPath, this.mergeArchivedEntries(archived.preferences, preferencesResult.archived), Infinity, (entry) => utilityEntry(entry, hl, ew)),
+            saveEntries(this.archiveFacetsPath, this.mergeArchivedEntries(archived.facets, facetsResult.archived), Infinity, (entry) => utilityEntry(entry, hl, ew)),
+            saveWork(this.archiveWorkPath, this.mergeArchivedWork(archived.work, workResult.archived), Infinity, (entry) => utilityWork(entry, this.cfg.halfLife, this.cfg.evictionWeights)),
+            saveV2Semantic(this.v2Paths, semanticResult.active),
+            saveV2Procedural(this.v2Paths, proceduralResult.active),
+            saveV2Semantic(this.archiveV2Paths, this.mergeArchivedV2(archivedSemantic, semanticResult.archived)),
+            saveV2Procedural(this.archiveV2Paths, this.mergeArchivedV2(archivedProcedural, proceduralResult.archived)),
+        ]);
+        const total = knowledgeResult.archived.length +
+            lessonsResult.archived.length +
+            eventsResult.archived.length +
+            preferencesResult.archived.length +
+            facetsResult.archived.length +
+            workResult.archived.length +
+            semanticResult.archived.length +
+            proceduralResult.archived.length;
+        return {
+            knowledge: knowledgeResult.archived.length,
+            lessons: lessonsResult.archived.length,
+            events: eventsResult.archived.length,
+            preferences: preferencesResult.archived.length,
+            facets: facetsResult.archived.length,
+            work: workResult.archived.length,
+            semantic: semanticResult.archived.length,
+            procedural: proceduralResult.archived.length,
+            total,
+        };
+    }
+    async restoreArchivedEntry(id) {
+        const hl = this.cfg.halfLife;
+        const ew = this.cfg.evictionWeights;
+        const restoreLegacy = async (activePath, archivePath, location) => {
+            const [active, archived] = await Promise.all([loadEntries(activePath), loadEntries(archivePath)]);
+            const index = archived.findIndex((entry) => entry.id === id);
+            if (index < 0)
+                return { ok: false };
+            const [entry] = archived.splice(index, 1);
+            active.push({
+                ...entry,
+                archivedAt: undefined,
+                archiveReason: undefined,
+                revivedAt: new Date().toISOString(),
+            });
+            await Promise.all([
+                saveEntries(activePath, active, Infinity, (candidate) => utilityEntry(candidate, hl, ew)),
+                saveEntries(archivePath, archived, Infinity, (candidate) => utilityEntry(candidate, hl, ew)),
+            ]);
+            return { ok: true, location };
+        };
+        for (const [activePath, archivePath, location] of [
+            [this.knowledgePath, this.archiveKnowledgePath, "knowledge"],
+            [this.lessonsPath, this.archiveLessonsPath, "lessons"],
+            [this.eventsPath, this.archiveEventsPath, "events"],
+            [this.preferencesPath, this.archivePreferencesPath, "preferences"],
+            [this.facetsPath, this.archiveFacetsPath, "facets"],
+        ]) {
+            const result = await restoreLegacy(activePath, archivePath, location);
+            if (result.ok)
+                return result;
+        }
+        {
+            const [active, archived] = await Promise.all([loadWork(this.workPath), loadWork(this.archiveWorkPath)]);
+            const index = archived.findIndex((entry) => entry.id === id);
+            if (index >= 0) {
+                const [entry] = archived.splice(index, 1);
+                active.push({
+                    ...entry,
+                    archivedAt: undefined,
+                    archiveReason: undefined,
+                    revivedAt: new Date().toISOString(),
+                });
+                await Promise.all([
+                    saveWork(this.workPath, active, Infinity, (candidate) => utilityWork(candidate, this.cfg.halfLife, this.cfg.evictionWeights)),
+                    saveWork(this.archiveWorkPath, archived, Infinity, (candidate) => utilityWork(candidate, this.cfg.halfLife, this.cfg.evictionWeights)),
+                ]);
+                return { ok: true, location: "work" };
+            }
+        }
+        {
+            const [active, archived] = await Promise.all([loadV2Semantic(this.v2Paths), loadV2Semantic(this.archiveV2Paths)]);
+            const index = archived.findIndex((entry) => entry.id === id);
+            if (index >= 0) {
+                const [entry] = archived.splice(index, 1);
+                active.push({
+                    ...entry,
+                    archivedAt: undefined,
+                    archiveReason: undefined,
+                    revivedAt: new Date().toISOString(),
+                });
+                await Promise.all([saveV2Semantic(this.v2Paths, active), saveV2Semantic(this.archiveV2Paths, archived)]);
+                await this.rebuildV2Links();
+                return { ok: true, location: "semantic" };
+            }
+        }
+        {
+            const [active, archived] = await Promise.all([loadV2Procedural(this.v2Paths), loadV2Procedural(this.archiveV2Paths)]);
+            const index = archived.findIndex((entry) => entry.id === id);
+            if (index >= 0) {
+                const [entry] = archived.splice(index, 1);
+                active.push({
+                    ...entry,
+                    archivedAt: undefined,
+                    archiveReason: undefined,
+                    revivedAt: new Date().toISOString(),
+                });
+                await Promise.all([saveV2Procedural(this.v2Paths, active), saveV2Procedural(this.archiveV2Paths, archived)]);
+                await this.rebuildV2Links();
+                return { ok: true, location: "procedural" };
+            }
+        }
+        return { ok: false };
+    }
+    async inspectV2Memory(project = "", scope) {
+        const snapshot = await this.exportAllV2();
+        const episodes = this.filterAndCleanV2Episodes(snapshot.episodes, project, scope);
+        const facets = this.filterAndCleanV2Facets(snapshot.facets, project, scope);
+        const semantic = this.filterAndCleanV2Semantic(snapshot.semantic, project, scope);
+        const allProcedural = snapshot.procedural.filter((entry) => {
+            if (scope?.userId && entry.scope?.userId && entry.scope.userId !== scope.userId)
+                return false;
+            if (scope?.agentId && entry.scope?.agentId && entry.scope.agentId !== scope.agentId)
+                return false;
+            if (project && entry.scope?.project && entry.scope.project !== project)
+                return false;
+            return true;
+        });
+        const activeProcedural = allProcedural.filter((entry) => entry.status !== "deprecated" && entry.status !== "superseded");
+        const procedureChains = this.buildProceduralChains(allProcedural);
+        const proceduralConflicts = this.detectProceduralConflicts(activeProcedural);
+        const semanticConflicts = this.detectSemanticConflicts(semantic);
+        return {
+            counts: {
+                episodes: episodes.length,
+                facets: facets.length,
+                semantic: semantic.length,
+                procedural: allProcedural.length,
+                activeProcedural: activeProcedural.length,
+                supersededProcedural: allProcedural.filter((entry) => entry.status === "superseded").length,
+                semanticConflicts: semanticConflicts.length,
+                proceduralConflicts: proceduralConflicts.length,
+                procedureChains: procedureChains.length,
+            },
+            procedureChains,
+            proceduralConflicts,
+            semanticConflicts,
+        };
+    }
     // ─── Full Insights Report ────────────────────────────────────────
     async generateFullInsights() {
-        const all = await this.exportAll();
+        const all = await this.buildRuntimeMemoryView();
         return buildFullInsightsReport(all, this.llmFn, this.cfg.locale);
     }
     /**
      * 生成增强版洞察报告（包含大白话洞察 + 开发者画像 + 根因分析）
      */
     async generateEnhancedInsights() {
-        const all = await this.exportAll();
+        const all = await this.buildRuntimeMemoryView();
         // 并行生成基础报告和大白话洞察
         const [baseReport, humanData] = await Promise.all([
             buildFullInsightsReport(all, this.llmFn, this.cfg.locale),
@@ -1063,7 +1417,7 @@ export class NanoMemEngine {
     }
     // ─── Insights Generation ─────────────────────────────────────
     async generateInsights() {
-        const all = await this.exportAll();
+        const all = await this.buildRuntimeMemoryView();
         const stats = {
             knowledge: all.knowledge.length,
             lessons: all.lessons.length,
@@ -1219,10 +1573,10 @@ export class NanoMemEngine {
         await saveEntries(path, entries, max, (entry) => utilityEntry(entry, hl, ew));
     }
     filterAndCleanEntries(entries, scope) {
-        return filterByScope(evictExpiredEntries(entries), scope);
+        return filterByScope(evictExpiredEntries(entries).filter((entry) => !entry.archivedAt), scope);
     }
     filterAndCleanWork(entries, scope) {
-        return filterByScope(evictExpiredWork(entries), scope);
+        return filterByScope(evictExpiredWork(entries).filter((entry) => !entry.archivedAt), scope);
     }
     filterAndCleanProcedural(entries, project, scope) {
         return entries.filter((entry) => {
@@ -1232,7 +1586,7 @@ export class NanoMemEngine {
                 return false;
             if (project && entry.scope?.project && entry.scope.project !== project)
                 return false;
-            return entry.status !== "deprecated" && entry.status !== "superseded";
+            return !entry.archivedAt && entry.status !== "deprecated" && entry.status !== "superseded";
         });
     }
     filterAndCleanV2Episodes(entries, project, scope) {
@@ -1243,7 +1597,7 @@ export class NanoMemEngine {
                 return false;
             if (project && entry.scope?.project && entry.scope.project !== project)
                 return false;
-            return true;
+            return !entry.archivedAt;
         });
     }
     filterAndCleanV2Facets(entries, project, scope) {
@@ -1254,7 +1608,7 @@ export class NanoMemEngine {
                 return false;
             if (project && entry.scope?.project && entry.scope.project !== project)
                 return false;
-            return true;
+            return !entry.archivedAt;
         });
     }
     filterAndCleanV2Semantic(entries, project, scope) {
@@ -1265,9 +1619,498 @@ export class NanoMemEngine {
                 return false;
             if (project && entry.scope?.project && entry.scope.project !== project)
                 return false;
-            return !entry.supersededById;
+            return !entry.archivedAt && !entry.supersededById;
         });
     }
+    mergeArchivedEntries(existing, incoming) {
+        const merged = new Map(existing.map((entry) => [entry.id, entry]));
+        for (const entry of incoming)
+            merged.set(entry.id, entry);
+        return [...merged.values()].sort((a, b) => (b.archivedAt ?? b.created).localeCompare(a.archivedAt ?? a.created));
+    }
+    mergeArchivedWork(existing, incoming) {
+        const merged = new Map(existing.map((entry) => [entry.id, entry]));
+        for (const entry of incoming)
+            merged.set(entry.id, entry);
+        return [...merged.values()].sort((a, b) => (b.archivedAt ?? b.created).localeCompare(a.archivedAt ?? a.created));
+    }
+    mergeArchivedV2(existing, incoming) {
+        const merged = new Map(existing.map((entry) => [entry.id, entry]));
+        for (const entry of incoming)
+            merged.set(entry.id, entry);
+        return [...merged.values()].sort((a, b) => (b.archivedAt ?? b.createdAt).localeCompare(a.archivedAt ?? a.createdAt));
+    }
+    partitionArchivedEntries(entries, now) {
+        const active = [];
+        const archived = [];
+        for (const entry of entries) {
+            const reason = this.getLegacyArchiveReason(entry);
+            if (!reason) {
+                active.push(entry);
+                continue;
+            }
+            archived.push({
+                ...entry,
+                archivedAt: entry.archivedAt ?? now,
+                archiveReason: entry.archiveReason ?? reason,
+            });
+        }
+        return { active, archived };
+    }
+    partitionArchivedWork(entries, now) {
+        const active = [];
+        const archived = [];
+        for (const entry of entries) {
+            const reason = this.getWorkArchiveReason(entry);
+            if (!reason) {
+                active.push(entry);
+                continue;
+            }
+            archived.push({
+                ...entry,
+                archivedAt: entry.archivedAt ?? now,
+                archiveReason: entry.archiveReason ?? reason,
+            });
+        }
+        return { active, archived };
+    }
+    partitionArchivedSemantic(entries, now) {
+        const active = [];
+        const archived = [];
+        for (const entry of entries) {
+            const reason = this.getSemanticArchiveReason(entry);
+            if (!reason) {
+                active.push(entry);
+                continue;
+            }
+            archived.push({
+                ...entry,
+                archivedAt: entry.archivedAt ?? now,
+                archiveReason: entry.archiveReason ?? reason,
+            });
+        }
+        return { active, archived };
+    }
+    partitionArchivedProcedural(entries, now) {
+        const active = [];
+        const archived = [];
+        for (const entry of entries) {
+            const reason = this.getProceduralArchiveReason(entry);
+            if (!reason) {
+                active.push(entry);
+                continue;
+            }
+            archived.push({
+                ...entry,
+                archivedAt: entry.archivedAt ?? now,
+                archiveReason: entry.archiveReason ?? reason,
+            });
+        }
+        return { active, archived };
+    }
+    getLegacyArchiveReason(entry) {
+        if (entry.archivedAt)
+            return entry.archiveReason ?? "pre-archived";
+        if (entry.revivedAt && daysSince(entry.revivedAt) <= this.cfg.forgetting.reviveCooldownDays)
+            return undefined;
+        const anchor = entry.lastAccessed ?? entry.eventTime ?? entry.created;
+        const ageDays = daysSince(anchor);
+        const lowSignal = (entry.accessCount ?? 0) <= 1 && entry.importance <= 6 && (entry.salience ?? entry.importance) <= 6;
+        if (entry.retention === "ambient" && lowSignal && ageDays > this.cfg.forgetting.ambientTtlDays) {
+            return "stale-ambient-memory";
+        }
+        return undefined;
+    }
+    inferSemanticRetention(item) {
+        if (item.retention)
+            return item.retention;
+        if (item.stability === "situational" || item.stateData)
+            return "ambient";
+        switch (item.type) {
+            case "preference":
+            case "pattern":
+                return "core";
+            case "lesson":
+            case "decision":
+            case "event":
+            case "struggle":
+                return "key-event";
+            default:
+                return "ambient";
+        }
+    }
+    inferSemanticStability(item) {
+        if (item.stability === "situational")
+            return "situational";
+        if (item.stateData)
+            return "volatile";
+        switch (item.type) {
+            case "preference":
+            case "pattern":
+                return "stable";
+            case "event":
+            case "struggle":
+                return "situational";
+            default:
+                return "stable";
+        }
+    }
+    inferSemanticImportance(item) {
+        switch (item.type) {
+            case "struggle":
+            case "event":
+                return 9;
+            case "lesson":
+            case "decision":
+                return 8;
+            case "pattern":
+                return 7;
+            case "preference":
+                return 6;
+            default:
+                return 5;
+        }
+    }
+    mapExtractedItemToSemanticType(item) {
+        switch (item.type) {
+            case "lesson":
+                return "lesson";
+            case "preference":
+                return "preference";
+            case "decision":
+                return "decision";
+            case "pattern":
+                return "pattern";
+            case "struggle":
+                return "struggle";
+            case "event":
+                return "event";
+            default:
+                return "fact";
+        }
+    }
+    upsertSemanticFromExtractedItem(semantic, item, project) {
+        if (item.type === "retract")
+            return;
+        const detail = filterPII(item.detail || item.content || "");
+        const name = item.name || detail.slice(0, 30) || item.summary || "memory";
+        const summary = item.summary || detail.slice(0, 150) || name;
+        const semanticType = this.mapExtractedItemToSemanticType(item);
+        const tags = extractTags(`${name} ${summary} ${detail}`);
+        const now = new Date().toISOString();
+        const existing = semantic.find((entry) => entry.semanticType === semanticType &&
+            entry.scope?.project === project &&
+            (tagOverlap(entry.tags, tags) >= 0.72 ||
+                `${entry.name} ${entry.summary}`.trim().toLowerCase() === `${name} ${summary}`.trim().toLowerCase()));
+        if (existing) {
+            existing.name = name;
+            existing.summary = summary;
+            existing.detail = detail || existing.detail;
+            existing.tags = [...new Set(tags)];
+            existing.updatedAt = now;
+            existing.retention = this.inferSemanticRetention(item);
+            existing.stability = this.inferSemanticStability(item);
+            existing.salience = Math.max(existing.salience, this.inferSemanticImportance(item));
+            existing.importance = Math.max(existing.importance, this.inferSemanticImportance(item));
+            return;
+        }
+        semantic.push({
+            id: `semantic:extract:${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            kind: "semantic",
+            semanticType,
+            name,
+            summary,
+            detail,
+            accessCount: 0,
+            importance: this.inferSemanticImportance(item),
+            salience: Math.max(4, this.inferSemanticImportance(item)),
+            confidence: 0.8,
+            retention: this.inferSemanticRetention(item),
+            stability: this.inferSemanticStability(item),
+            tags,
+            evidence: [],
+            scope: { ...this.cfg.defaultScope, project },
+            createdAt: now,
+            updatedAt: now,
+            abstractionLevel: semanticType === "event" ? "instance" : "generalization",
+        });
+    }
+    semanticKindToLegacyType(kind) {
+        switch (kind) {
+            case "lesson":
+                return "lesson";
+            case "preference":
+                return "preference";
+            case "decision":
+                return "decision";
+            case "event":
+                return "event";
+            case "pattern":
+                return "pattern";
+            case "struggle":
+                return "struggle";
+            default:
+                return "fact";
+        }
+    }
+    semanticToRuntimeEntry(entry) {
+        const type = this.semanticKindToLegacyType(entry.semanticType);
+        return {
+            id: entry.id,
+            type,
+            name: entry.name,
+            summary: entry.summary,
+            detail: entry.detail,
+            content: entry.detail || entry.summary,
+            tags: entry.tags,
+            project: entry.scope?.project || "default",
+            importance: entry.importance,
+            strength: undefined,
+            created: entry.createdAt,
+            eventTime: entry.validFrom ?? entry.createdAt,
+            lastAccessed: entry.lastAccessedAt,
+            accessCount: entry.accessCount,
+            relatedIds: [...new Set([...(entry.supersedesIds ?? []), ...(entry.conflictWithIds ?? [])])],
+            scope: entry.scope,
+            retention: entry.retention === "ambient" ? "ambient" : entry.retention === "core" ? "core" : "key-event",
+            salience: entry.salience,
+            stability: entry.stability === "volatile" ? "situational" : entry.stability === "stable" ? "stable" : "situational",
+        };
+    }
+    proceduralToRuntimeEntry(entry) {
+        return {
+            id: entry.id,
+            type: "decision",
+            name: entry.name,
+            summary: entry.summary,
+            detail: [entry.contextText, entry.boundaries, entry.steps.map((step) => step.text).join("\n")].filter(Boolean).join("\n"),
+            content: entry.summary,
+            tags: entry.tags,
+            project: entry.scope?.project || "default",
+            importance: entry.importance,
+            strength: undefined,
+            created: entry.createdAt,
+            eventTime: entry.validFrom ?? entry.createdAt,
+            lastAccessed: entry.lastAccessedAt,
+            accessCount: entry.accessCount,
+            relatedIds: entry.supersedesIds,
+            scope: entry.scope,
+            retention: entry.retention === "ambient" ? "ambient" : entry.retention === "core" ? "core" : "key-event",
+            salience: entry.salience,
+            stability: entry.stability === "volatile" ? "situational" : entry.stability === "stable" ? "stable" : "situational",
+        };
+    }
+    async buildRuntimeMemoryView() {
+        const [legacy, work, episodes, meta, semantic, procedural] = await Promise.all([
+            this.exportAll(),
+            this.getAllWork(),
+            this.getAllEpisodes(),
+            loadMeta(this.metaPath),
+            loadV2Semantic(this.v2Paths),
+            loadV2Procedural(this.v2Paths),
+        ]);
+        const cleanSemantic = semantic.filter((entry) => !entry.archivedAt && !entry.supersededById);
+        const cleanProcedural = procedural.filter((entry) => !entry.archivedAt && entry.status !== "deprecated");
+        const semanticEntries = cleanSemantic.map((entry) => this.semanticToRuntimeEntry(entry));
+        const proceduralEntries = cleanProcedural.map((entry) => this.proceduralToRuntimeEntry(entry));
+        const v2SignalCount = semanticEntries.length + proceduralEntries.length;
+        const useLegacyFallback = v2SignalCount === 0;
+        const byType = (entries, type) => entries.filter((entry) => entry.type === type);
+        const runtimeEntries = [...semanticEntries, ...proceduralEntries];
+        return {
+            knowledge: useLegacyFallback ? legacy.knowledge : byType(runtimeEntries, "fact").filter((entry) => entry.type === "fact"),
+            lessons: useLegacyFallback ? legacy.lessons : byType(runtimeEntries, "lesson"),
+            events: useLegacyFallback ? legacy.events : byType(runtimeEntries, "event"),
+            preferences: useLegacyFallback ? legacy.preferences : byType(runtimeEntries, "preference"),
+            facets: legacy.facets,
+            work,
+            episodes,
+            meta,
+            v2SearchEntries: runtimeEntries,
+        };
+    }
+    getWorkArchiveReason(entry) {
+        if (entry.archivedAt)
+            return entry.archiveReason ?? "pre-archived";
+        if (entry.revivedAt && daysSince(entry.revivedAt) <= this.cfg.forgetting.reviveCooldownDays)
+            return undefined;
+        const anchor = entry.lastAccessed ?? entry.eventTime ?? entry.created;
+        const ageDays = daysSince(anchor);
+        if ((entry.accessCount ?? 0) <= 1 && entry.importance <= 6 && ageDays > this.cfg.forgetting.workTtlDays) {
+            return "stale-work-memory";
+        }
+        return undefined;
+    }
+    getSemanticArchiveReason(entry) {
+        if (entry.archivedAt)
+            return entry.archiveReason ?? "pre-archived";
+        if (entry.revivedAt && daysSince(entry.revivedAt) <= this.cfg.forgetting.reviveCooldownDays)
+            return undefined;
+        const anchor = entry.lastAccessedAt ?? entry.updatedAt ?? entry.createdAt;
+        const ageDays = daysSince(anchor);
+        if (entry.supersededById && ageDays > this.cfg.forgetting.ambientTtlDays) {
+            return "superseded-semantic-memory";
+        }
+        const lowSignal = (entry.accessCount ?? 0) <= 1 && entry.importance <= 6 && entry.confidence < 0.85;
+        if (entry.retention === "ambient" && lowSignal && ageDays > this.cfg.forgetting.ambientTtlDays * 2) {
+            return "stale-semantic-memory";
+        }
+        return undefined;
+    }
+    getProceduralArchiveReason(entry) {
+        if (entry.archivedAt)
+            return entry.archiveReason ?? "pre-archived";
+        if (entry.revivedAt && daysSince(entry.revivedAt) <= this.cfg.forgetting.reviveCooldownDays)
+            return undefined;
+        const anchor = entry.lastAccessedAt ?? entry.updatedAt ?? entry.createdAt;
+        const ageDays = daysSince(anchor);
+        if ((entry.status === "superseded" || entry.status === "deprecated") && ageDays > this.cfg.forgetting.ambientTtlDays) {
+            return "stale-procedure-version";
+        }
+        if (entry.status === "draft" && (entry.accessCount ?? 0) <= 1 && entry.importance <= 6 && ageDays > this.cfg.forgetting.ambientTtlDays * 2) {
+            return "abandoned-draft-procedure";
+        }
+        return undefined;
+    }
+    buildProceduralChains(entries) {
+        const byId = new Map(entries.map((entry) => [entry.id, entry]));
+        const roots = entries.filter((entry) => !entry.supersededById || !byId.has(entry.supersededById));
+        return roots
+            .map((root) => {
+            const ids = new Set();
+            const stack = [root.id];
+            while (stack.length) {
+                const currentId = stack.pop();
+                if (!currentId || ids.has(currentId))
+                    continue;
+                ids.add(currentId);
+                for (const entry of entries) {
+                    if (entry.supersededById === currentId)
+                        stack.push(entry.id);
+                    if (entry.supersedesIds?.includes(currentId))
+                        stack.push(entry.id);
+                }
+            }
+            const chainEntries = [...ids].map((id) => byId.get(id)).filter((entry) => Boolean(entry));
+            return {
+                rootId: root.id,
+                name: root.name,
+                status: root.status,
+                versionDepth: chainEntries.length,
+                ids: chainEntries
+                    .sort((a, b) => {
+                    const aVersion = a.version ?? 0;
+                    const bVersion = b.version ?? 0;
+                    if (aVersion !== bVersion)
+                        return bVersion - aVersion;
+                    return a.updatedAt.localeCompare(b.updatedAt);
+                })
+                    .map((entry) => entry.id),
+            };
+        })
+            .filter((chain) => chain.versionDepth > 1)
+            .sort((a, b) => b.versionDepth - a.versionDepth || a.name.localeCompare(b.name));
+    }
+    materializeV2Links(semantic, procedural, existingLinks, now = new Date().toISOString()) {
+        const manualLinks = existingLinks.filter((link) => !link.id.startsWith(NanoMemEngine.AUTO_V2_LINK_PREFIX));
+        const autoLinks = new Map();
+        const proceduralConflicts = this.detectProceduralConflicts(procedural.filter((entry) => entry.status !== "deprecated" && entry.status !== "superseded"));
+        const semanticConflicts = this.detectSemanticConflicts(semantic);
+        const addAutoLink = (fromId, toId, type, weight, evidence = []) => {
+            if (!fromId || !toId || fromId === toId)
+                return;
+            const directional = type === "supersedes";
+            const [normalizedFrom, normalizedTo] = directional || fromId < toId ? [fromId, toId] : [toId, fromId];
+            const id = `${NanoMemEngine.AUTO_V2_LINK_PREFIX}${type}:${normalizedFrom}->${normalizedTo}`;
+            autoLinks.set(id, {
+                id,
+                fromId: normalizedFrom,
+                toId: normalizedTo,
+                type,
+                weight,
+                explicit: false,
+                createdAt: autoLinks.get(id)?.createdAt ?? now,
+                updatedAt: now,
+                evidence,
+            });
+        };
+        for (const entry of semantic) {
+            for (const supersededId of entry.supersedesIds ?? []) {
+                addAutoLink(entry.id, supersededId, "supersedes", 0.92);
+            }
+            if (entry.supersededById) {
+                addAutoLink(entry.supersededById, entry.id, "supersedes", 0.92);
+            }
+        }
+        for (const entry of procedural) {
+            for (const supersededId of entry.supersedesIds ?? []) {
+                addAutoLink(entry.id, supersededId, "supersedes", 0.94);
+            }
+            if (entry.supersededById) {
+                addAutoLink(entry.supersededById, entry.id, "supersedes", 0.94);
+            }
+        }
+        for (const conflict of semanticConflicts) {
+            addAutoLink(conflict.aId, conflict.bId, "conflicts-with", 0.88);
+        }
+        for (const conflict of proceduralConflicts) {
+            addAutoLink(conflict.aId, conflict.bId, "conflicts-with", Math.max(0.72, conflict.score));
+        }
+        return [...manualLinks, ...autoLinks.values()].sort((a, b) => a.id.localeCompare(b.id));
+    }
+    detectProceduralConflicts(entries) {
+        const conflicts = [];
+        for (let i = 0; i < entries.length; i++) {
+            for (let j = i + 1; j < entries.length; j++) {
+                const a = entries[i];
+                const b = entries[j];
+                if (!a || !b || a.id === b.id)
+                    continue;
+                const tagScore = tagOverlap(a.tags ?? [], b.tags ?? []);
+                const lexicalScore = tagOverlap(extractTags(`${a.name} ${a.searchText} ${a.summary}`), extractTags(`${b.name} ${b.searchText} ${b.summary}`));
+                const similarity = Math.max(tagScore, lexicalScore);
+                const sameIntent = a.searchText.trim().toLowerCase() === b.searchText.trim().toLowerCase() ||
+                    a.name.trim().toLowerCase() === b.name.trim().toLowerCase();
+                const boundariesDiffer = (a.boundaries ?? "").trim().toLowerCase() !== (b.boundaries ?? "").trim().toLowerCase() ||
+                    (a.contextText ?? "").trim().toLowerCase() !== (b.contextText ?? "").trim().toLowerCase();
+                if ((similarity >= 0.72 || sameIntent) && boundariesDiffer) {
+                    conflicts.push({
+                        aId: a.id,
+                        bId: b.id,
+                        aName: a.name,
+                        bName: b.name,
+                        score: Number(similarity.toFixed(3)),
+                        reason: "High-overlap active procedures differ in boundaries or context.",
+                    });
+                }
+            }
+        }
+        return conflicts.sort((a, b) => b.score - a.score || a.aName.localeCompare(b.aName));
+    }
+    detectSemanticConflicts(entries) {
+        const byId = new Map(entries.map((entry) => [entry.id, entry]));
+        const seen = new Set();
+        const conflicts = [];
+        for (const entry of entries) {
+            for (const conflictId of entry.conflictWithIds ?? []) {
+                const other = byId.get(conflictId);
+                if (!other)
+                    continue;
+                const pairKey = [entry.id, other.id].sort().join("::");
+                if (seen.has(pairKey))
+                    continue;
+                seen.add(pairKey);
+                conflicts.push({
+                    aId: entry.id,
+                    bId: other.id,
+                    aName: entry.name,
+                    bName: other.name,
+                    reason: "Explicit semantic conflict link.",
+                });
+            }
+        }
+        return conflicts.sort((a, b) => a.aName.localeCompare(b.aName) || a.bName.localeCompare(b.bName));
+    }
     buildEmbeddingSourceItems(episodes, facets, semantic, procedural) {
         const episodeItems = episodes.map((entry) => ({
             memoryId: entry.id,
@@ -1437,6 +2280,7 @@ export class NanoMemEngine {
                 lastReconsolidationAt: new Date().toISOString(),
             }),
         ]);
+        await this.rebuildV2Links();
     }
     detectAlignmentConflicts(entries) {
         const candidates = entries.filter((entry) => entry.stability !== "situational" &&