byterover-cli 3.0.1 → 3.2.0

package/dist/agent/infra/session/session-compressor.d.ts

@@ -0,0 +1,43 @@
+import type { IContentGenerator } from '../../core/interfaces/i-content-generator.js';
+import type { InternalMessage } from '../../core/interfaces/message-types.js';
+import type { MemoryDeduplicator } from '../memory/memory-deduplicator.js';
+import type { MemoryManager } from '../memory/memory-manager.js';
+/**
+ * Result of a session compression pass.
+ */
+export interface CompressionResult {
+    created: number;
+    merged: number;
+    skipped: number;
+}
+/**
+ * Extracts and persists memories from a completed task session.
+ *
+ * Flow:
+ * 1. Serialize session messages into a text digest
+ * 2. LLM call: extract 5-category draft memories
+ * 3. Load existing agent memories for deduplication
+ * 4. Apply deduplication decisions (CREATE/MERGE/SKIP)
+ */
+export declare class SessionCompressor {
+    private readonly deduplicator;
+    private readonly generator;
+    private readonly memoryManager;
+    constructor(deduplicator: MemoryDeduplicator, generator: IContentGenerator, memoryManager: MemoryManager);
+    /**
+     * Compress a session into persistent memories.
+     *
+     * @param messages - Session message history
+     * @param commandType - Session command type (e.g. 'curate', 'query')
+     * @param options - Compression options
+     * @param options.minMessages - Minimum message count required before compression runs
+     * @returns Summary of actions taken
+     */
+    compress(messages: InternalMessage[], commandType: string, options?: {
+        minMessages?: number;
+    }): Promise<CompressionResult>;
+    private buildFallbackDrafts;
+    private deduplicateFallbackDrafts;
+    private extractDrafts;
+    private serializeMessages;
+}

package/dist/agent/infra/session/session-compressor.js

@@ -0,0 +1,296 @@
+import { randomUUID } from 'node:crypto';
+import { streamToText } from '../llm/stream-to-text.js';
+/**
+ * Five extraction categories for ByteRover session memories.
+ */
+const CATEGORIES = ['DECISIONS', 'ENTITIES', 'PATTERNS', 'PREFERENCES', 'SKILLS'];
+const SYSTEM_PROMPT = `You are a session memory extractor for ByteRover, a code intelligence tool.
+Extract reusable memories from the conversation in exactly these 5 categories:
+- PATTERNS: reusable code or workflow patterns discovered
+- PREFERENCES: user style/naming/structure decisions
+- ENTITIES: key files, modules, APIs, dependencies discovered
+- DECISIONS: architectural choices (always extract, even if already known — immutable log)
+- SKILLS: tool invocation recipes that worked
+
+Return ONLY a JSON array of memory objects:
+[{"category": "PATTERNS", "content": "...", "tags": ["optional"]}, ...]
+
+Extract 0-3 memories per category. Skip categories with nothing new. Be concise (max 200 chars per memory).`;
+const MAX_DIGEST_CHARS = 12_000;
+const FALLBACK_DIGEST_PREVIEW_CHARS = 4000;
+const MIN_BOUNDARY_RATIO = 0.6;
+const SOURCE_PATH_PATTERN = /\b(?:src|app|lib|packages|docs|test|tests)\/[A-Za-z0-9_./-]+\b/g;
+function truncateDigestAtBoundary(digest, maxChars = MAX_DIGEST_CHARS) {
+    if (digest.length <= maxChars) {
+        return digest;
+    }
+    const clipped = digest.slice(0, maxChars);
+    const boundary = clipped.lastIndexOf('\n\n');
+    // Prefer a natural message boundary when it falls reasonably close to the cap.
+    return boundary >= Math.floor(maxChars * MIN_BOUNDARY_RATIO) ? clipped.slice(0, boundary) : clipped;
+}
+/**
+ * Extracts and persists memories from a completed task session.
+ *
+ * Flow:
+ * 1. Serialize session messages into a text digest
+ * 2. LLM call: extract 5-category draft memories
+ * 3. Load existing agent memories for deduplication
+ * 4. Apply deduplication decisions (CREATE/MERGE/SKIP)
+ */
+export class SessionCompressor {
+    deduplicator;
+    generator;
+    memoryManager;
+    constructor(deduplicator, generator, memoryManager) {
+        this.deduplicator = deduplicator;
+        this.generator = generator;
+        this.memoryManager = memoryManager;
+    }
+    /**
+     * Compress a session into persistent memories.
+     *
+     * @param messages - Session message history
+     * @param commandType - Session command type (e.g. 'curate', 'query')
+     * @param options - Compression options
+     * @param options.minMessages - Minimum message count required before compression runs
+     * @returns Summary of actions taken
+     */
+    async compress(messages, commandType, options) {
+        const minMessages = options?.minMessages ?? 4;
+        const hasAssistantContent = messages.some((message) => (message.role === 'assistant' &&
+            getMessageText(message).trim().length > 0));
+        const effectiveMinMessages = commandType.startsWith('curate') && hasAssistantContent
+            ? Math.min(minMessages, 1)
+            : minMessages;
+        if (messages.length < effectiveMinMessages) {
+            return { created: 0, merged: 0, skipped: 0 };
+        }
+        const digest = this.serializeMessages(messages);
+        if (!digest.trim()) {
+            return { created: 0, merged: 0, skipped: 0 };
+        }
+        // Step 1: Extract draft memories via LLM
+        const useFallbackDraftsFirst = shouldPreferFallbackDrafts(commandType);
+        let drafts = useFallbackDraftsFirst ? this.buildFallbackDrafts(digest, commandType) : await this.extractDrafts(digest, commandType);
+        let usedFallbackDrafts = useFallbackDraftsFirst && drafts.length > 0;
+        if (drafts.length === 0) {
+            drafts = this.buildFallbackDrafts(digest, commandType);
+            usedFallbackDrafts = drafts.length > 0;
+        }
+        if (drafts.length === 0) {
+            return { created: 0, merged: 0, skipped: 0 };
+        }
+        // Step 2: Load the most recently updated agent memories for deduplication.
+        // MemoryManager.list() sorts by updatedAt DESC before applying the limit.
+        const existing = await this.memoryManager.list({ limit: 60, source: 'agent' });
+        // Step 3: Deduplicate
+        const actions = usedFallbackDrafts
+            ? this.deduplicateFallbackDrafts(drafts, existing)
+            : await this.deduplicator.deduplicate(drafts, existing);
+        // Step 4: Apply decisions
+        let created = 0;
+        let merged = 0;
+        let skipped = 0;
+        /* eslint-disable no-await-in-loop */
+        for (const action of actions) {
+            try {
+                if (action.action === 'CREATE') {
+                    await this.memoryManager.create({
+                        content: action.memory.content,
+                        metadata: { category: action.memory.category, source: 'agent' },
+                        tags: action.memory.tags,
+                    });
+                    created++;
+                }
+                else if (action.action === 'MERGE') {
+                    await this.memoryManager.update(action.targetId, { content: action.mergedContent });
+                    merged++;
+                }
+                else {
+                    skipped++;
+                }
+            }
+            catch (error) {
+                // Fail-open: skip individual memory errors
+                const msg = error instanceof Error ? error.message : String(error);
+                console.debug(`[SessionCompressor] Failed to apply ${action.action} action: ${msg}`);
+                skipped++;
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+        return { created, merged, skipped };
+    }
+    buildFallbackDrafts(digest, commandType) {
+        if (!commandType.startsWith('curate')) {
+            return [];
+        }
+        const preview = digest.slice(0, FALLBACK_DIGEST_PREVIEW_CHARS);
+        const fingerprint = computeFingerprint(preview);
+        const sourcePaths = [...new Set((preview.match(SOURCE_PATH_PATTERN) ?? []).filter((path) => !path.startsWith('.brv/')))];
+        const moduleLabel = deriveModuleLabel(sourcePaths);
+        const tags = moduleLabel === 'the working module' ? undefined : [moduleLabel];
+        return [
+            {
+                category: 'DECISIONS',
+                content: `Session ${fingerprint}: curated ${moduleLabel} knowledge into the context tree.`,
+                tags,
+            },
+            {
+                category: 'DECISIONS',
+                content: `Session ${fingerprint}: preserved ${moduleLabel} findings as durable knowledge instead of chat-only context.`,
+                tags,
+            },
+            {
+                category: 'PATTERNS',
+                content: `Session ${fingerprint}: used recon -> extraction -> curate apply workflow for ${moduleLabel}.`,
+                tags,
+            },
+            {
+                category: 'PATTERNS',
+                content: `Session ${fingerprint}: separated durable notes from raw source snippets while curating ${moduleLabel}.`,
+                tags,
+            },
+            {
+                category: 'SKILLS',
+                content: `Session ${fingerprint}: start ${commandType} with tools.curation.recon, then mapExtract, then verify applied file paths.`,
+                tags,
+            },
+            {
+                category: 'ENTITIES',
+                content: `${moduleLabel} is an actively curated module surfaced during ${commandType}.`,
+                tags,
+            },
+        ];
+    }
+    deduplicateFallbackDrafts(drafts, existing) {
+        const dedupCategories = ['ENTITIES', 'PATTERNS', 'SKILLS'];
+        const existingKeys = new Map();
+        for (const category of dedupCategories) {
+            existingKeys.set(category, new Set(existing
+                .filter((memory) => getMemoryCategory(memory) === category)
+                .map((memory) => normalizeForFallbackDedup(memory.content, category))));
+        }
+        return drafts.map((memory) => {
+            // DECISIONS always CREATE — temporal audit records that should accumulate
+            if (memory.category === 'DECISIONS') {
+                return { action: 'CREATE', memory };
+            }
+            const categorySet = existingKeys.get(memory.category);
+            if (!categorySet) {
+                return { action: 'CREATE', memory };
+            }
+            const key = normalizeForFallbackDedup(memory.content, memory.category);
+            if (categorySet.has(key)) {
+                return { action: 'SKIP', memory };
+            }
+            categorySet.add(key);
+            return { action: 'CREATE', memory };
+        });
+    }
+    async extractDrafts(digest, commandType) {
+        try {
+            const truncatedDigest = truncateDigestAtBoundary(digest);
+            const prompt = `## Session Type: ${commandType}
+
+## Conversation
+${truncatedDigest}
+
+Extract reusable memories from this session.`;
+            // Use streaming — ChatGPT OAuth Codex endpoint requires stream: true
+            const responseText = await streamToText(this.generator, {
+                config: { maxTokens: 1000, temperature: 0 },
+                contents: [{ content: prompt, role: 'user' }],
+                model: 'default',
+                systemPrompt: SYSTEM_PROMPT,
+                taskId: randomUUID(),
+            });
+            // Strip markdown code fences — some providers wrap JSON in ```json ... ```
+            const jsonText = responseText.replace(/^```(?:json)?\s*\n?/i, '').replace(/\n?```\s*$/i, '').trim();
+            const parsed = JSON.parse(jsonText);
+            if (!Array.isArray(parsed))
+                return [];
+            return parsed
+                .filter((item) => CATEGORIES.includes(item.category) && item.content?.trim())
+                .map((item) => ({
+                category: item.category,
+                content: item.content.trim(),
+                tags: item.tags,
+            }));
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            console.debug(`[SessionCompressor] Failed to extract drafts (${commandType}): ${msg}`);
+            return [];
+        }
+    }
+    serializeMessages(messages) {
+        const lines = [];
+        for (const msg of messages) {
+            const role = msg.role.toUpperCase();
+            const text = getMessageText(msg);
+            if (text.trim()) {
+                lines.push(`[${role}]: ${text.slice(0, 2000)}`);
+            }
+        }
+        return lines.join('\n\n');
+    }
+}
+function getMessageText(message) {
+    if (typeof message.content === 'string') {
+        return message.content;
+    }
+    if (!Array.isArray(message.content)) {
+        return '';
+    }
+    return message.content
+        .filter((part) => 'text' in part && typeof part.text === 'string')
+        .map((part) => part.text)
+        .join(' ');
+}
+function computeFingerprint(text) {
+    /* eslint-disable no-bitwise, unicorn/prefer-code-point */
+    let hash = 0;
+    for (const char of text) {
+        hash = (hash * 31 + char.charCodeAt(0)) >>> 0;
+    }
+    /* eslint-enable no-bitwise, unicorn/prefer-code-point */
+    return hash.toString(16).padStart(8, '0').slice(0, 8);
+}
+function deriveModuleLabel(sourcePaths) {
+    if (sourcePaths.length === 0) {
+        return 'the working module';
+    }
+    const firstPath = sourcePaths[0];
+    const segments = firstPath.split('/').filter(Boolean);
+    if (segments.length >= 2) {
+        return `${segments[0]}/${segments[1]}`;
+    }
+    return firstPath;
+}
+function normalizeMemoryContent(content) {
+    return content.trim().toLowerCase().replaceAll(/\s+/g, ' ');
+}
+function normalizeForFallbackDedup(content, category) {
+    let normalized = normalizeMemoryContent(content);
+    // PATTERNS and SKILLS are session-fingerprinted ("Session abc123: ...").
+    // Strip the prefix so repeated curate sessions on the same module are detected as duplicates.
+    if (category === 'PATTERNS' || category === 'SKILLS') {
+        normalized = normalized.replace(/^session\s+\S+:\s*/, '');
+    }
+    return normalized;
+}
+function getMemoryCategory(memory) {
+    if (!memory.metadata || typeof memory.metadata !== 'object') {
+        return undefined;
+    }
+    const { category } = memory.metadata;
+    return typeof category === 'string' ? category : undefined;
+}
+// Curate sessions always use deterministic fallback drafts instead of LLM extraction.
+// Fallback drafts are faster (no LLM call), cheaper, and produce consistent categorized
+// memories that can be deduped via string matching. LLM extraction is reserved for
+// non-curate sessions (e.g., query) where conversation content is unpredictable.
+function shouldPreferFallbackDrafts(commandType) {
+    return commandType.startsWith('curate');
+}

package/dist/agent/infra/session/session-manager.d.ts

@@ -160,6 +160,13 @@ export declare class SessionManager {
      * @returns Session instance or undefined if not found
      */
     getSession(id: string): IChatSession | undefined;
+    /**
+     * Get the command type (agent name) registered for a session.
+     *
+     * @param id - Session ID
+     * @returns Command type string (e.g. 'curate', 'query') or undefined if not found
+     */
+    getSessionCommandType(id: string): string | undefined;
     /**
      * Get the number of active sessions.
      *

package/dist/agent/infra/session/session-manager.js

@@ -283,6 +283,15 @@ export class SessionManager {
     getSession(id) {
         return this.sessions.get(id);
     }
+    /**
+     * Get the command type (agent name) registered for a session.
+     *
+     * @param id - Session ID
+     * @returns Command type string (e.g. 'curate', 'query') or undefined if not found
+     */
+    getSessionCommandType(id) {
+        return this.sessionAgentNames.get(id);
+    }
     /**
      * Get the number of active sessions.
      *

package/dist/agent/infra/tools/implementations/curate-tool.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { Tool, ToolExecutionContext } from '../../../core/domain/tools/types.js';
+import type { AbstractGenerationQueue } from '../../map/abstract-queue.js';
 /**
  * Operation types for curating knowledge topics.
  * Inspired by ACE Curator patterns.
@@ -573,6 +574,6 @@ export interface CurateOutput {
  * Execute curate operations on knowledge topics.
  * Exported for use by CurateService in sandbox.
  */
-export declare function executeCurate(input: unknown, _context?: ToolExecutionContext): Promise<CurateOutput>;
-export declare function createCurateTool(workingDirectory?: string): Tool;
+export declare function executeCurate(input: unknown, _context?: ToolExecutionContext, abstractQueue?: AbstractGenerationQueue): Promise<CurateOutput>;
+export declare function createCurateTool(workingDirectory?: string, abstractQueue?: AbstractGenerationQueue): Tool;
 export {};

package/dist/agent/infra/tools/implementations/curate-tool.js

@@ -293,7 +293,7 @@ function generateSubtopicContextMarkdown(subtopicName, context) {
     }
     return sections.join('\n');
 }
-async function createDomainContextIfMissing(basePath, domain, domainContext) {
+async function createDomainContextIfMissing(basePath, domain, domainContext, onAfterWrite) {
     const normalizedDomain = toSnakeCase(domain);
     const contextPath = join(basePath, normalizedDomain, 'context.md');
     const exists = await DirectoryManager.fileExists(contextPath);
@@ -305,9 +305,10 @@ async function createDomainContextIfMissing(basePath, domain, domainContext) {
     }
     const content = generateDomainContextMarkdown(normalizedDomain, domainContext);
     await DirectoryManager.writeFileAtomic(contextPath, content);
+    onAfterWrite?.(contextPath, content);
     return { created: true, path: contextPath };
 }
-async function ensureTopicContextMd(basePath, domain, topic, topicContext) {
+async function ensureTopicContextMd(basePath, domain, topic, topicContext, onAfterWrite) {
     const normalizedDomain = toSnakeCase(domain);
     const normalizedTopic = toSnakeCase(topic);
     const topicPath = join(basePath, normalizedDomain, normalizedTopic);
@@ -327,6 +328,7 @@ async function ensureTopicContextMd(basePath, domain, topic, topicContext) {
     }
     const content = generateTopicContextMarkdown(normalizedTopic, topicContext);
     await DirectoryManager.writeFileAtomic(contextPath, content);
+    onAfterWrite?.(contextPath, content);
     return { created: true, path: contextPath };
 }
 /**
@@ -334,7 +336,7 @@ async function ensureTopicContextMd(basePath, domain, topic, topicContext) {
  * Only creates context.md if LLM provides subtopicContext - no static templates.
  */
 async function ensureSubtopicContextMd(options) {
-    const { basePath, domain, subtopic, subtopicContext, topic } = options;
+    const { basePath, domain, onAfterWrite, subtopic, subtopicContext, topic } = options;
     const normalizedDomain = toSnakeCase(domain);
     const normalizedTopic = toSnakeCase(topic);
     const normalizedSubtopic = toSnakeCase(subtopic);
@@ -355,26 +357,43 @@ async function ensureSubtopicContextMd(options) {
     }
     const content = generateSubtopicContextMarkdown(normalizedSubtopic, subtopicContext);
     await DirectoryManager.writeFileAtomic(contextPath, content);
+    onAfterWrite?.(contextPath, content);
     return { created: true, path: contextPath };
 }
 /**
  * Ensure context.md exists at all levels for a given path (topic and subtopic).
  * This is called during ADD operations to create context.md files with LLM-provided content.
  */
-async function ensureContextMd(basePath, parsed, topicContext, subtopicContext) {
+async function ensureContextMd(basePath, parsed, topicContext, subtopicContext, onAfterWrite) {
     // Ensure topic-level context.md exists
-    await ensureTopicContextMd(basePath, parsed.domain, parsed.topic, topicContext);
+    await ensureTopicContextMd(basePath, parsed.domain, parsed.topic, topicContext, onAfterWrite);
     // If subtopic exists, ensure subtopic-level context.md exists
     if (parsed.subtopic) {
         await ensureSubtopicContextMd({
             basePath,
             domain: parsed.domain,
+            onAfterWrite,
             subtopic: parsed.subtopic,
             subtopicContext,
             topic: parsed.topic,
         });
     }
 }
+async function deleteDerivedSiblings(contextPath) {
+    const siblingPaths = [
+        contextPath.replace(/\.md$/, '.abstract.md'),
+        contextPath.replace(/\.md$/, '.overview.md'),
+    ];
+    /* eslint-disable no-await-in-loop */
+    for (const siblingPath of siblingPaths) {
+        if (siblingPath === contextPath)
+            continue;
+        if (await DirectoryManager.fileExists(siblingPath)) {
+            await DirectoryManager.deleteFile(siblingPath);
+        }
+    }
+    /* eslint-enable no-await-in-loop */
+}
 /**
  * Parse a path into domain, topic, and optional subtopic.
  */
@@ -432,7 +451,7 @@ function buildFullPath(basePath, knowledgePath) {
 /**
  * Execute ADD operation - create new domain/topic/subtopic with {title}.md
  */
-async function executeAdd(basePath, operation) {
+async function executeAdd(basePath, operation, onAfterWrite) {
     const { confidence, content, domainContext, impact, path, reason, subtopicContext, summary, title, topicContext } = operation;
     const reviewMeta = deriveReviewMetadata('ADD', confidence, impact);
     if (!title) {
@@ -478,7 +497,7 @@ async function executeAdd(basePath, operation) {
                 type: 'ADD',
             };
         }
-        await createDomainContextIfMissing(basePath, parsed.domain, domainContext);
+        await createDomainContextIfMissing(basePath, parsed.domain, domainContext, onAfterWrite);
         const domainPath = join(basePath, toSnakeCase(parsed.domain));
         const topicPath = join(domainPath, toSnakeCase(parsed.topic));
         const finalPath = parsed.subtopic ? join(topicPath, toSnakeCase(parsed.subtopic)) : topicPath;
@@ -500,7 +519,8 @@ async function executeAdd(basePath, operation) {
         const filename = `${toSnakeCase(title)}.md`;
         const contextPath = join(finalPath, filename);
         await DirectoryManager.writeFileAtomic(contextPath, contextContent);
-        await ensureContextMd(basePath, parsed, topicContext, subtopicContext);
+        onAfterWrite?.(contextPath, contextContent);
+        await ensureContextMd(basePath, parsed, topicContext, subtopicContext, onAfterWrite);
         return {
             ...reviewMeta,
             filePath: contextPath,
@@ -533,7 +553,7 @@ function maxImpact(a, b) {
 /**
  * Execute UPDATE operation - modify existing {title}.md
  */
-async function executeUpdate(basePath, operation) {
+async function executeUpdate(basePath, operation, onAfterWrite) {
     const { confidence, content, domainContext, impact, path, reason, subtopicContext, summary, title, topicContext } = operation;
     // Used for early-exit validation failures (before structural loss can be assessed)
     const baseReviewMeta = deriveReviewMetadata('UPDATE', confidence, impact);
@@ -583,7 +603,7 @@ async function executeUpdate(basePath, operation) {
                 type: 'UPDATE',
             };
         }
-        await createDomainContextIfMissing(basePath, parsed.domain, domainContext);
+        await createDomainContextIfMissing(basePath, parsed.domain, domainContext, onAfterWrite);
         // Read existing file to preserve scoring metadata and detect structural loss
         const existingContent = await DirectoryManager.readFile(contextPath);
         const existingScoring = existingContent ? parseFrontmatterScoring(existingContent) : undefined;
@@ -623,7 +643,8 @@ async function executeUpdate(basePath, operation) {
         });
         await backupBeforeWrite(contextPath, basePath);
         await DirectoryManager.writeFileAtomic(contextPath, contextContent);
-        await ensureContextMd(basePath, parsed, topicContext, subtopicContext);
+        onAfterWrite?.(contextPath, contextContent);
+        await ensureContextMd(basePath, parsed, topicContext, subtopicContext, onAfterWrite);
         return {
             ...reviewMeta,
             filePath: contextPath,
@@ -651,7 +672,7 @@ async function executeUpdate(basePath, operation) {
  * Execute UPSERT operation - automatically creates or updates based on file existence
  * This is the recommended operation type as it eliminates the need for pre-checks.
  */
-async function executeUpsert(basePath, operation) {
+async function executeUpsert(basePath, operation, onAfterWrite) {
     const { path, reason, title } = operation;
     const reviewMeta = deriveReviewMetadata('UPSERT', operation.confidence, operation.impact);
     if (!title) {
@@ -693,7 +714,7 @@ async function executeUpsert(basePath, operation) {
         const exists = await DirectoryManager.fileExists(contextPath);
         if (exists) {
             // File exists - delegate to UPDATE logic
-            const result = await executeUpdate(basePath, { ...operation, type: 'UPDATE' });
+            const result = await executeUpdate(basePath, { ...operation, type: 'UPDATE' }, onAfterWrite);
             // Return with UPSERT type but indicate it was an update
             return {
                 ...result,
@@ -702,7 +723,7 @@ async function executeUpsert(basePath, operation) {
             };
         }
         // File doesn't exist - delegate to ADD logic
-        const result = await executeAdd(basePath, { ...operation, type: 'ADD' });
+        const result = await executeAdd(basePath, { ...operation, type: 'ADD' }, onAfterWrite);
         // Return with UPSERT type but indicate it was an add
         return {
             ...result,
@@ -724,7 +745,7 @@ async function executeUpsert(basePath, operation) {
 /**
  * Execute MERGE operation - combine source file into target file, delete source file
  */
-async function executeMerge(basePath, operation) {
+async function executeMerge(basePath, operation, onAfterWrite) {
     const { confidence, domainContext, impact, mergeTarget, mergeTargetTitle, path, reason, subtopicContext, summary, title, topicContext, } = operation;
     const reviewMeta = deriveReviewMetadata('MERGE', confidence, impact);
     if (!title) {
@@ -798,8 +819,8 @@ async function executeMerge(basePath, operation) {
                 type: 'MERGE',
             };
         }
-        await createDomainContextIfMissing(basePath, sourceParsed.domain, domainContext);
-        await createDomainContextIfMissing(basePath, targetParsed.domain, domainContext);
+        await createDomainContextIfMissing(basePath, sourceParsed.domain, domainContext, onAfterWrite);
+        await createDomainContextIfMissing(basePath, targetParsed.domain, domainContext, onAfterWrite);
         const sourceContent = await DirectoryManager.readFile(sourceContextPath);
         const targetContent = await DirectoryManager.readFile(targetContextPath);
         // Extract previous summary from target file (for review UI)
@@ -810,9 +831,11 @@ async function executeMerge(basePath, operation) {
         await backupBeforeWrite(sourceContextPath, basePath);
         const mergedContent = MarkdownWriter.mergeContexts(sourceContent, targetContent, reason, summary);
         await DirectoryManager.writeFileAtomic(targetContextPath, mergedContent);
+        onAfterWrite?.(targetContextPath, mergedContent);
         await DirectoryManager.deleteFile(sourceContextPath);
-        await ensureContextMd(basePath, sourceParsed, topicContext, subtopicContext);
-        await ensureContextMd(basePath, targetParsed, topicContext, subtopicContext);
+        await deleteDerivedSiblings(sourceContextPath);
+        await ensureContextMd(basePath, sourceParsed, topicContext, subtopicContext, onAfterWrite);
+        await ensureContextMd(basePath, targetParsed, topicContext, subtopicContext, onAfterWrite);
         return {
             ...reviewMeta,
             additionalFilePaths: [sourceContextPath],
@@ -874,6 +897,7 @@ async function executeDelete(basePath, operation) {
             }
             await backupBeforeWrite(filePath, basePath);
             await DirectoryManager.deleteFile(filePath);
+            await deleteDerivedSiblings(filePath);
             return {
                 ...reviewMeta,
                 filePath,
@@ -948,7 +972,7 @@ async function executeDelete(basePath, operation) {
  * Execute curate operations on knowledge topics.
  * Exported for use by CurateService in sandbox.
  */
-export async function executeCurate(input, _context) {
+export async function executeCurate(input, _context, abstractQueue) {
     const parseResult = CurateInputSchema.safeParse(input);
     if (!parseResult.success) {
         return {
@@ -974,6 +998,9 @@ export async function executeCurate(input, _context) {
         };
     }
     const { basePath, operations } = parseResult.data;
+    const onAfterWrite = abstractQueue
+        ? (contextPath, content) => { abstractQueue.enqueue({ contextPath, fullContent: content }); }
+        : undefined;
     const applied = [];
     const summary = {
         added: 0,
@@ -987,7 +1014,7 @@ export async function executeCurate(input, _context) {
         let result;
         switch (operation.type) {
             case 'ADD': {
-                result = await executeAdd(basePath, operation);
+                result = await executeAdd(basePath, operation, onAfterWrite);
                 if (result.status === 'success')
                     summary.added++;
                 break;
@@ -999,19 +1026,19 @@ export async function executeCurate(input, _context) {
                 break;
             }
             case 'MERGE': {
-                result = await executeMerge(basePath, operation);
+                result = await executeMerge(basePath, operation, onAfterWrite);
                 if (result.status === 'success')
                     summary.merged++;
                 break;
             }
             case 'UPDATE': {
-                result = await executeUpdate(basePath, operation);
+                result = await executeUpdate(basePath, operation, onAfterWrite);
                 if (result.status === 'success')
                     summary.updated++;
                 break;
             }
             case 'UPSERT': {
-                result = await executeUpsert(basePath, operation);
+                result = await executeUpsert(basePath, operation, onAfterWrite);
                 // UPSERT counts as either added or updated based on what happened
                 if (result.status === 'success') {
                     if (result.message?.includes('created new')) {
@@ -1046,7 +1073,7 @@ export async function executeCurate(input, _context) {
     /* eslint-enable no-await-in-loop */
     return { applied, summary };
 }
-export function createCurateTool(workingDirectory) {
+export function createCurateTool(workingDirectory, abstractQueue) {
     return {
         description: `Curate knowledge topics with atomic operations. This tool manages the knowledge structure using four operation types and supports a two-part context model: Raw Concept + Narrative.
 
@@ -1246,10 +1273,10 @@ export function createCurateTool(workingDirectory) {
                 const parseResult = CurateInputSchema.safeParse(input);
                 if (parseResult.success) {
                     parseResult.data.basePath = resolve(workingDirectory, parseResult.data.basePath);
-                    return executeCurate(parseResult.data, context);
+                    return executeCurate(parseResult.data, context, abstractQueue);
                 }
             }
-            return executeCurate(input, context);
+            return executeCurate(input, context, abstractQueue);
         },
         id: ToolName.CURATE,
         inputSchema: CurateInputSchema,

package/dist/agent/infra/tools/implementations/expand-knowledge-tool.d.ts

@@ -8,9 +8,9 @@ export interface ExpandKnowledgeToolConfig {
 /**
  * Creates the expand knowledge tool.
  *
- * Retrieves full content from archived knowledge entries by reading the
- * lossless .full.md file that the stub points to. No LLM call needed —
- * purely file-based lookup.
+ * Two modes:
+ * - stubPath: retrieves full content from archived knowledge entries (archive drill-down)
+ * - overviewPath: retrieves L1 overview content from .overview.md sibling files
  *
  * @param config - Optional configuration
  * @returns Configured expand knowledge tool