byterover-cli 3.0.0 → 3.1.0

package/dist/agent/infra/tools/implementations/search-knowledge-service.js

@@ -1,7 +1,8 @@
 import MiniSearch from 'minisearch';
+import { realpath } from 'node:fs/promises';
 import { join } from 'node:path';
 import { removeStopwords } from 'stopword';
-import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, SUMMARY_INDEX_FILE } from '../../../../server/constants.js';
+import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, OVERVIEW_EXTENSION, SUMMARY_INDEX_FILE } from '../../../../server/constants.js';
 import { parseFrontmatterScoring, updateScoringInContent, } from '../../../../server/core/domain/knowledge/markdown-writer.js';
 import { applyDecay, applyDefaultScoring, compoundScore, determineTier, recordAccessHits, } from '../../../../server/core/domain/knowledge/memory-scoring.js';
 import { isArchiveStub, isDerivedArtifact } from '../../../../server/infra/context-tree/derived-artifact.js';
@@ -13,9 +14,9 @@ const DEFAULT_CACHE_TTL_MS = 5000;
 /** Bump when MINISEARCH_OPTIONS fields/boost change to invalidate cached indexes */
 const INDEX_SCHEMA_VERSION = 4;
 /** Only include results whose normalized score is at least this fraction of the top result's score */
-const SCORE_GAP_RATIO = 0.75;
+const SCORE_GAP_RATIO = 0.7;
 /** Minimum normalized score for the top result. Below this, the query is considered out-of-domain */
-const MINIMUM_RELEVANCE_SCORE = 0.6;
+const MINIMUM_RELEVANCE_SCORE = 0.45;
 /** Normalized score threshold above which results are trusted despite unmatched query terms */
 const UNMATCHED_TERM_SCORE_THRESHOLD = 0.85;
 /** Minimum query term length to consider "significant" for OOD term-based detection */
@@ -33,6 +34,59 @@ const CHUNK_OVERLAP_CHARS = 120;
 function normalizeScore(rawScore) {
     return rawScore / (1 + rawScore);
 }
+/**
+ * Propagate BM25 scores upward to parent domain/topic nodes.
+ *
+ * For each matched result, walks the parent chain and computes a decayed boost
+ * (score * propagationFactor per level). New summary entries are added for
+ * parent nodes that have a _index.md in summaryMap but are not already in results.
+ *
+ * @param results - Already-enriched search results (gap-ratio filtered)
+ * @param symbolTree - Symbol tree for parent-chain traversal
+ * @param summaryMap - Map of _index.md file paths → SummaryDocLike (for excerpt/metadata)
+ * @param propagationFactor - Score multiplier per level up (default 0.55)
+ * @returns New parent entries only — caller merges and re-sorts
+ */
+function propagateScoresToParents(results, symbolTree, summaryMap, documentMap, propagationFactor = 0.55) {
+    const boosts = new Map();
+    for (const r of results) {
+        const symbol = symbolTree.symbolMap.get(r.path);
+        let parent = symbol?.parent;
+        let factor = propagationFactor;
+        while (parent) {
+            const cur = boosts.get(parent.path) ?? 0;
+            boosts.set(parent.path, Math.max(cur, r.bm25Score * factor));
+            parent = parent.parent;
+            factor *= propagationFactor;
+        }
+    }
+    const existingPaths = new Set(results.map((r) => r.path));
+    const boosted = [];
+    for (const [parentPath, score] of boosts.entries()) {
+        if (existingPaths.has(parentPath))
+            continue;
+        const doc = getSummarySource(parentPath, summaryMap, documentMap);
+        if (!doc)
+            continue;
+        // Propagate the strongest child BM25 signal upward, then apply the parent
+        // summary's own scoring exactly once. This avoids double-counting lifecycle
+        // weights that are already baked into child compound scores.
+        const finalScore = doc.scoring
+            ? compoundScore(score, doc.scoring.importance ?? 50, doc.scoring.recency ?? 0.5, doc.scoring.maturity ?? 'draft')
+            : score;
+        boosted.push({
+            backlinkCount: 0,
+            excerpt: doc.excerpt,
+            path: parentPath,
+            score: finalScore,
+            symbolKind: 'summary',
+            title: parentPath,
+        });
+    }
+    return boosted;
+}
+/** Numeric rank for maturity tiers — used for minMaturity filtering in both BM25 and propagated results. */
+const MATURITY_TIER_RANK = { core: 3, draft: 1, validated: 2 };
 const MINISEARCH_OPTIONS = {
     fields: ['title', 'content', 'path'],
     idField: 'id',
@@ -43,6 +97,28 @@ const MINISEARCH_OPTIONS = {
     },
     storeFields: ['title', 'path'],
 };
+function getSummaryAccessPath(path, summaryMap, documentMap) {
+    return getSummarySource(path, summaryMap, documentMap)?.path ?? `${path}/${SUMMARY_INDEX_FILE}`;
+}
+function getSummarySource(path, summaryMap, documentMap) {
+    const summaryDoc = summaryMap.get(`${path}/${SUMMARY_INDEX_FILE}`);
+    if (summaryDoc) {
+        return {
+            excerpt: summaryDoc.excerpt ?? '',
+            path: summaryDoc.path,
+            scoring: summaryDoc.scoring,
+        };
+    }
+    const contextDoc = documentMap.get(`${path}/context.md`);
+    if (contextDoc) {
+        return {
+            excerpt: extractExcerpt(contextDoc.content, contextDoc.title),
+            path: contextDoc.path,
+            scoring: contextDoc.scoring,
+        };
+    }
+    return undefined;
+}
 function filterStopWords(query) {
     const words = query.toLowerCase().split(/\s+/);
     const filtered = removeStopwords(words);
@@ -162,6 +238,9 @@ function extractExcerpt(content, query, maxLength = 800) {
     }
     return excerpt || cleanContent.slice(0, maxLength) + (cleanContent.length > maxLength ? '...' : '');
 }
+function stripMarkdownFrontmatter(content) {
+    return content.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, '').trim();
+}
 async function findMarkdownFilesWithMtime(fileSystem, contextTreePath) {
     try {
         const globResult = await fileSystem.globFiles(`**/*${CONTEXT_FILE_EXTENSION}`, {
@@ -213,19 +292,27 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
             symbolTree: { root: [], symbolMap: new Map() },
         };
     }
-    // Partition files: _index.md → summaryFiles, derived artifacts → skip, rest → indexable
+    // Partition files: _index.md → summaryFiles, .overview.md → overviewFiles (for cache
+    // invalidation + sibling detection), other derived artifacts → skip, rest → indexable
     const summaryFiles = [];
+    const overviewFiles = [];
     const indexableFiles = [];
+    // Track all known paths for sibling detection (e.g. .overview.md presence check)
+    const knownPaths = new Set(filesWithMtime.map((f) => f.path));
     for (const file of filesWithMtime) {
         const fileName = file.path.split('/').at(-1) ?? '';
         if (fileName === SUMMARY_INDEX_FILE) {
             summaryFiles.push(file);
         }
+        else if (file.path.endsWith(OVERVIEW_EXTENSION)) {
+            // Track mtimes so cache invalidates when a new .overview.md appears; not BM25-indexed
+            overviewFiles.push(file);
+        }
         else if (!isDerivedArtifact(file.path)) {
             // Includes regular .md files AND .stub.md files (stubs are searchable)
             indexableFiles.push(file);
         }
-        // .full.md and _manifest.json are skipped (isDerivedArtifact returns true)
+        // .full.md, .abstract.md, and _manifest.json are skipped (isDerivedArtifact returns true)
     }
     // Read indexable documents for BM25 index
     const documentPromises = indexableFiles.map(async ({ mtime, path: filePath }) => {
@@ -234,10 +321,14 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
             const { content } = await fileSystem.readFile(fullPath);
             const title = extractTitle(content, filePath.replace(/\.md$/, '').split('/').pop() || filePath);
             const scoring = parseFrontmatterScoring(content) ?? applyDefaultScoring();
+            // Check if a .overview.md sibling exists (written by abstract generation queue)
+            const overviewRelPath = filePath.replace(/\.md$/, OVERVIEW_EXTENSION);
+            const overviewPath = knownPaths.has(overviewRelPath) ? overviewRelPath : undefined;
             return {
                 content,
                 id: filePath,
                 mtime,
+                ...(overviewPath !== undefined && { overviewPath }),
                 path: filePath,
                 scoring,
                 title,
@@ -255,9 +346,16 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
             const fm = parseSummaryFrontmatter(content);
             if (!fm)
                 return null;
+            // Persist frontmatter scoring so propagateScoresToParents can apply hotness/tier boosts
+            const frontmatter = parseFrontmatterScoring(content);
+            const scoring = frontmatter
+                ? { importance: frontmatter.importance, maturity: frontmatter.maturity, recency: frontmatter.recency }
+                : undefined;
             return {
                 condensationOrder: fm.condensation_order,
+                excerpt: stripMarkdownFrontmatter(content).slice(0, 400),
                 path: filePath,
+                scoring,
                 tokenCount: fm.token_count,
             };
         }
@@ -280,6 +378,10 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
     for (const sf of summaryFiles) {
         fileMtimes.set(sf.path, sf.mtime);
     }
+    // Track .overview.md mtimes so the cache invalidates when a new overview is written
+    for (const ov of overviewFiles) {
+        fileMtimes.set(ov.path, ov.mtime);
+    }
     const summaryMap = new Map();
     for (const summary of summaryResults) {
         if (summary) {
@@ -345,12 +447,27 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs, onBeforeB
                 };
             }
         }
-        const allFiles = await findMarkdownFilesWithMtime(fileSystem, contextTreePath);
+        let allFiles = await findMarkdownFilesWithMtime(fileSystem, contextTreePath);
         // Exclude non-indexable derived artifacts (.full.md) so that currentFiles
         // matches what buildFreshIndex tracks in fileMtimes. Without this filter,
         // isCacheValid() sees a size mismatch once archives exist, causing cache thrash.
         // _index.md is kept (tracked for summary staleness), .stub.md is kept (BM25 indexed).
-        const currentFiles = allFiles.filter((f) => !isDerivedArtifact(f.path) || f.path.split('/').at(-1) === SUMMARY_INDEX_FILE);
+        // Keep _index.md (summary tracking) and .overview.md (sibling detection for overviewPath).
+        // .full.md, .abstract.md, and _manifest.json remain excluded.
+        let currentFiles = allFiles.filter((f) => !isDerivedArtifact(f.path) ||
+            f.path.split('/').at(-1) === SUMMARY_INDEX_FILE ||
+            f.path.endsWith(OVERVIEW_EXTENSION));
+        // Flush pending access hits before reusing a stale-enough cache entry.
+        // The flush updates frontmatter on disk, so refresh mtimes before the cache-valid check.
+        if (onBeforeBuild) {
+            const wroteScoringUpdates = await onBeforeBuild(contextTreePath);
+            if (wroteScoringUpdates) {
+                allFiles = await findMarkdownFilesWithMtime(fileSystem, contextTreePath);
+                currentFiles = allFiles.filter((f) => !isDerivedArtifact(f.path) ||
+                    f.path.split('/').at(-1) === SUMMARY_INDEX_FILE ||
+                    f.path.endsWith(OVERVIEW_EXTENSION));
+            }
+        }
         // Re-check cache validity after getting file list (another call may have finished)
         if (state.cachedIndex &&
             state.cachedIndex.contextTreePath === contextTreePath &&
@@ -364,10 +481,6 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs, onBeforeB
             state.cachedIndex = updatedCache;
             return updatedCache;
         }
-        // Flush pending access hits before building so updated scoring is picked up
-        if (onBeforeBuild) {
-            await onBeforeBuild(contextTreePath);
-        }
         // Build fresh index
         const freshIndex = await buildFreshIndex(fileSystem, contextTreePath, currentFiles);
         state.cachedIndex = freshIndex;
@@ -420,7 +533,7 @@ export class SearchKnowledgeService {
      */
     async flushAccessHits(contextTreePath) {
         if (this.pendingAccessHits.size === 0) {
-            return;
+            return false;
         }
         const hits = new Map(this.pendingAccessHits);
         this.pendingAccessHits.clear();
@@ -440,6 +553,7 @@ export class SearchKnowledgeService {
             }
         });
         await Promise.allSettled(tasks);
+        return true;
     }
     /**
      * Search the knowledge base for relevant topics.
@@ -451,14 +565,15 @@ export class SearchKnowledgeService {
      */
     async search(query, options) {
         const limit = options?.limit ?? 10;
-        const contextTreePath = join(this.baseDirectory, BRV_DIR, CONTEXT_TREE_DIR);
+        const resolvedBaseDirectory = await realpath(this.baseDirectory).catch(() => this.baseDirectory);
+        const contextTreePath = join(resolvedBaseDirectory, BRV_DIR, CONTEXT_TREE_DIR);
         // Acquire index with parallel-safe locking; flush pending access hits before any rebuild
         const indexResult = await acquireIndex(this.state, this.fileSystem, contextTreePath, this.cacheTtlMs, (ctxPath) => this.flushAccessHits(ctxPath));
         // Handle error case (context tree not initialized)
         if ('error' in indexResult) {
             return indexResult.result;
         }
-        const { documentMap, index, referenceIndex, symbolTree } = indexResult;
+        const { documentMap, index, referenceIndex, summaryMap, symbolTree } = indexResult;
         if (documentMap.size === 0) {
             return {
                 message: 'Context tree is empty. Use /curate to add knowledge.',
@@ -472,7 +587,7 @@ export class SearchKnowledgeService {
         }
         // Symbolic path resolution: try path-based query first
         if (isPathLikeQuery(query, symbolTree)) {
-            const symbolicResult = this.trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, options);
+            const symbolicResult = this.trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, summaryMap, options);
             if (symbolicResult) {
                 return symbolicResult;
             }
@@ -482,10 +597,10 @@ export class SearchKnowledgeService {
         const effectiveScope = options?.scope ?? parsed.scopePath;
         const effectiveQuery = parsed.scopePath ? parsed.textQuery : query;
         // Run text-based MiniSearch (existing pipeline), optionally scoped to a subtree
-        const textResult = this.runTextSearch(effectiveQuery || query, documentMap, index, limit, effectiveScope, symbolTree, referenceIndex, options);
+        const textResult = this.runTextSearch(effectiveQuery || query, documentMap, index, limit, effectiveScope, symbolTree, referenceIndex, summaryMap, options);
         // If scoped search returned nothing and we had a scope, fall back to global search
         if (textResult.results.length === 0 && effectiveScope && effectiveQuery) {
-            return this.runTextSearch(query, documentMap, index, limit, undefined, symbolTree, referenceIndex, options);
+            return this.runTextSearch(query, documentMap, index, limit, undefined, symbolTree, referenceIndex, summaryMap, options);
         }
         return textResult;
     }
@@ -536,19 +651,27 @@ export class SearchKnowledgeService {
                 }
             }
         }
+        const doc = documentMap.get(result.path);
+        const overviewPath = doc?.overviewPath;
+        const isContextSummary = doc?.path.endsWith('/context.md') || doc?.path === 'context.md';
+        const summaryPath = isContextSummary
+            ? doc?.path.slice(0, -'/context.md'.length) || doc?.path || result.path
+            : result.path;
         return {
             ...result,
             ...(archiveFullPath && { archiveFullPath }),
+            ...(overviewPath && { overviewPath }),
             backlinkCount: backlinks?.length ?? 0,
+            ...(isContextSummary && { path: summaryPath }),
             relatedPaths: backlinks?.slice(0, 3),
-            symbolKind,
-            symbolPath: symbol?.path,
+            symbolKind: isContextSummary ? 'summary' : symbolKind,
+            symbolPath: isContextSummary ? summaryPath : symbol?.path,
         };
     }
     /**
      * Run the standard text-based MiniSearch pipeline, optionally scoped to a subtree.
      */
-    runTextSearch(query, documentMap, index, limit, scopePath, symbolTree, referenceIndex, options) {
+    runTextSearch(query, documentMap, index, limit, scopePath, symbolTree, referenceIndex, summaryMap, options) {
         const filteredQuery = filterStopWords(query);
         const filteredWords = filteredQuery.split(/\s+/).filter((w) => w.length >= 2);
         // Build scope filter if a subtree is specified
@@ -585,11 +708,14 @@ export class SearchKnowledgeService {
             const bm25 = normalizeScore(r.score);
             return {
                 ...r,
+                bm25Score: bm25,
                 score: compoundScore(bm25, decayed.importance ?? 50, decayed.recency ?? 1, decayed.maturity ?? 'draft'),
             };
         });
         searchResults.sort((a, b) => b.score - a.score);
         const results = [];
+        const propagationInputs = [];
+        let scoreFloor;
         if (searchResults.length > 0) {
             // OOD detection: if the best result scores below the minimum floor,
             // the query has no meaningful match in the knowledge base.
@@ -615,7 +741,7 @@ export class SearchKnowledgeService {
                 };
             }
             const topScore = searchResults[0].score;
-            const scoreFloor = topScore * SCORE_GAP_RATIO;
+            scoreFloor = topScore * SCORE_GAP_RATIO;
             const resultLimit = Math.min(limit, searchResults.length);
             for (let i = 0; i < resultLimit; i++) {
                 const result = searchResults[i];
@@ -638,22 +764,54 @@ export class SearchKnowledgeService {
                         continue;
                     }
                     if (options?.minMaturity && enriched.symbolKind) {
-                        const tierRank = { core: 3, draft: 1, validated: 2 };
-                        const symbol = symbolTree.symbolMap.get(document.path);
-                        const docMaturity = symbol?.metadata.maturity ?? 'draft';
-                        if ((tierRank[docMaturity] ?? 1) < (tierRank[options.minMaturity] ?? 1)) {
+                        const docMaturity = enriched.symbolKind === 'summary'
+                            ? getSummarySource(enriched.path, summaryMap, documentMap)?.scoring?.maturity
+                                ?? symbolTree.symbolMap.get(enriched.path)?.metadata.maturity
+                                ?? 'draft'
+                            : symbolTree.symbolMap.get(document.path)?.metadata.maturity ?? 'draft';
+                        if ((MATURITY_TIER_RANK[docMaturity] ?? 1) < (MATURITY_TIER_RANK[options.minMaturity] ?? 1)) {
                             continue;
                         }
                     }
                     results.push(enriched);
+                    propagationInputs.push({
+                        bm25Score: result.bm25Score,
+                        path: document.path,
+                    });
                 }
             }
         }
-        // Accumulate access hits for returned results (flushed during next index rebuild)
-        // Disabled for benchmark: prevents feedback loop from distorting scores across queries
-        // if (results.length > 0) {
-        //   this.accumulateAccessHits(results.map((r) => r.path))
-        // }
+        // Propagate scores upward to parent domain/topic nodes (hierarchical retrieval)
+        const propagated = propagateScoresToParents(propagationInputs, symbolTree, summaryMap, documentMap);
+        for (const p of propagated) {
+            if (scoreFloor !== undefined && p.score < scoreFloor)
+                continue;
+            if (options?.includeKinds && p.symbolKind && !options.includeKinds.includes(p.symbolKind))
+                continue;
+            if (options?.excludeKinds && p.symbolKind && options.excludeKinds.includes(p.symbolKind))
+                continue;
+            if (options?.minMaturity && p.symbolKind === 'summary') {
+                const summaryDoc = getSummarySource(p.path, summaryMap, documentMap);
+                const summaryMaturity = summaryDoc?.scoring?.maturity ?? 'draft';
+                if ((MATURITY_TIER_RANK[summaryMaturity] ?? 1) < (MATURITY_TIER_RANK[options.minMaturity] ?? 1))
+                    continue;
+            }
+            results.push(p);
+        }
+        if (propagated.length > 0) {
+            results.sort((a, b) => b.score - a.score);
+            // Trim back to the caller-requested limit after propagated entries are merged in.
+            if (results.length > limit)
+                results.splice(limit);
+        }
+        // Accumulate access hits for returned results (flushed during next index rebuild).
+        // Synthetic 'summary' results carry folder-style paths (e.g. 'auth') that are not
+        // real files; map them to their _index.md so flushAccessHits can read and update them.
+        if (results.length > 0) {
+            this.accumulateAccessHits(results.map((r) => (r.symbolKind === 'summary'
+                ? getSummaryAccessPath(r.path, summaryMap, documentMap)
+                : r.path)));
+        }
         return {
             message: results.length > 0
                 ? `Found ${searchResults.length} result(s). Use read_file to view full content.`
@@ -665,7 +823,7 @@ export class SearchKnowledgeService {
     /**
      * Try to resolve the query as a symbolic path. Returns null if no path match found.
      */
-    trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, options) {
+    trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, summaryMap, options) {
         const pathMatches = matchMemoryPath(symbolTree, query.split(/\s+/)[0].includes('/') ? query.split(/\s+/)[0] : query);
         if (pathMatches.length === 0) {
             return null;
@@ -691,11 +849,25 @@ export class SearchKnowledgeService {
         const textPart = query.slice(query.indexOf(pathPart) + pathPart.length).trim();
         if (textPart) {
             // Scoped search: search text within the matched subtree
-            return this.runTextSearch(textPart, documentMap, index, limit, topMatch.path, symbolTree, referenceIndex, options);
+            return this.runTextSearch(textPart, documentMap, index, limit, topMatch.path, symbolTree, referenceIndex, summaryMap, options);
         }
         // No text part — return all children of the matched node
         const subtreeIds = getSubtreeDocumentIds(symbolTree, topMatch.path);
         const results = [];
+        const accessHitPaths = [];
+        const summaryDoc = getSummarySource(topMatch.path, summaryMap, documentMap);
+        if (summaryDoc) {
+            results.push({
+                backlinkCount: 0,
+                excerpt: summaryDoc.excerpt,
+                path: topMatch.path,
+                score: 1,
+                symbolKind: 'summary',
+                symbolPath: topMatch.path,
+                title: topMatch.name,
+            });
+            accessHitPaths.push(summaryDoc.path);
+        }
         for (const docId of subtreeIds) {
             if (results.length >= limit)
                 break;
@@ -703,9 +875,10 @@ export class SearchKnowledgeService {
             if (!doc)
                 continue;
             results.push(this.enrichResult({ excerpt: extractExcerpt(doc.content, query), path: doc.path, score: 0.9, title: doc.title }, symbolTree, referenceIndex, documentMap));
+            accessHitPaths.push(doc.path);
         }
-        if (results.length > 0) {
-            this.accumulateAccessHits(results.map((r) => r.path));
+        if (accessHitPaths.length > 0) {
+            this.accumulateAccessHits(accessHitPaths);
         }
         return {
             message: `Found ${results.length} entries under ${topMatch.path}. Use read_file to view full content.`,

package/dist/agent/infra/tools/implementations/search-knowledge-tool.js

@@ -4,11 +4,11 @@ import { SearchKnowledgeService } from './search-knowledge-service.js';
 const SearchKnowledgeInputSchema = z
     .object({
     excludeKinds: z
-        .array(z.enum(['archive_stub', 'context', 'domain', 'subtopic', 'topic']))
+        .array(z.enum(['archive_stub', 'context', 'domain', 'subtopic', 'summary', 'topic']))
         .optional()
         .describe('Symbol kinds to exclude from results'),
     includeKinds: z
-        .array(z.enum(['archive_stub', 'context', 'domain', 'subtopic', 'topic']))
+        .array(z.enum(['archive_stub', 'context', 'domain', 'subtopic', 'summary', 'topic']))
         .optional()
         .describe('Symbol kinds to include in results (filters out others)'),
     limit: z

package/dist/agent/infra/tools/tool-provider.js

@@ -18,6 +18,7 @@ export class ToolProvider {
      * TypeScript ensures this object matches ToolServices keys at compile time.
      */
     static VALID_SERVICE_KEYS = new Set(Object.keys({
+        abstractQueue: 0,
         agentInstance: 0,
         contentGenerator: 0,
         environmentContext: 0,

package/dist/agent/infra/tools/tool-registry.d.ts

@@ -9,6 +9,7 @@ import type { IProcessService } from '../../core/interfaces/i-process-service.js
 import type { ISandboxService } from '../../core/interfaces/i-sandbox-service.js';
 import type { ITodoStorage } from '../../core/interfaces/i-todo-storage.js';
 import type { ITokenizer } from '../../core/interfaces/i-tokenizer.js';
+import type { AbstractGenerationQueue } from '../map/abstract-queue.js';
 import type { MemoryManager } from '../memory/memory-manager.js';
 import type { ToolProviderGetter } from './tool-provider-getter.js';
 import { ToolMarker } from './tool-markers.js';
@@ -17,6 +18,8 @@ import { ToolMarker } from './tool-markers.js';
  * Tools declare which services they need via requiredServices.
  */
 export interface ToolServices {
+    /** Abstract generation queue for background L0/L1 abstract file generation */
+    abstractQueue?: AbstractGenerationQueue;
     /** Agent instance for creating sub-sessions (used by agentic_map) */
     agentInstance?: ICipherAgent;
     /** Content generator for stateless LLM calls (used by llm_map) */

package/dist/agent/infra/tools/tool-registry.js

@@ -6,6 +6,7 @@ import { createCurateTool } from './implementations/curate-tool.js';
 import { createExpandKnowledgeTool } from './implementations/expand-knowledge-tool.js';
 import { createGlobFilesTool } from './implementations/glob-files-tool.js';
 import { createGrepContentTool } from './implementations/grep-content-tool.js';
+import { createIngestResourceTool } from './implementations/ingest-resource-tool.js';
 import { createListDirectoryTool } from './implementations/list-directory-tool.js';
 import { createLlmMapTool } from './implementations/llm-map-tool.js';
 import { createReadFileTool } from './implementations/read-file-tool.js';
@@ -54,7 +55,7 @@ export const TOOL_REGISTRY = {
     },
     [ToolName.CODE_EXEC]: {
         descriptionFile: 'code_exec',
-        factory({ environmentContext, fileSystemService, sandboxService }) {
+        factory({ abstractQueue, environmentContext, fileSystemService, sandboxService }) {
             const sandbox = getRequiredService(sandboxService, 'sandboxService');
             // Inject file system service into sandbox for Tools SDK
             if (fileSystemService && sandbox.setFileSystem) {
@@ -67,7 +68,7 @@ export const TOOL_REGISTRY = {
             }
             // Inject curate service into sandbox for Tools SDK
             if (sandbox.setCurateService) {
-                const curateService = createCurateService(environmentContext?.workingDirectory);
+                const curateService = createCurateService(environmentContext?.workingDirectory, abstractQueue);
                 sandbox.setCurateService(curateService);
             }
             // Inject environment context into sandbox for env.* access
@@ -81,10 +82,10 @@ export const TOOL_REGISTRY = {
     },
     [ToolName.CURATE]: {
         descriptionFile: 'curate',
-        factory: ({ environmentContext }) => createCurateTool(environmentContext?.workingDirectory),
+        factory: ({ abstractQueue, environmentContext }) => createCurateTool(environmentContext?.workingDirectory, abstractQueue),
         markers: [ToolMarker.ContextBuilding, ToolMarker.Modification],
         outputGuidance: 'curate',
-        requiredServices: [], // Uses DirectoryManager and MarkdownWriter for file operations
+        requiredServices: [],
     },
     [ToolName.EXPAND_KNOWLEDGE]: {
         descriptionFile: 'expand_knowledge',
@@ -104,6 +105,16 @@ export const TOOL_REGISTRY = {
         markers: [ToolMarker.Core, ToolMarker.Discovery],
         requiredServices: ['fileSystemService'],
     },
+    [ToolName.INGEST_RESOURCE]: {
+        factory: ({ abstractQueue, contentGenerator, environmentContext, fileSystemService }) => createIngestResourceTool({
+            abstractQueue,
+            baseDirectory: environmentContext?.workingDirectory,
+            contentGenerator,
+            fileSystem: fileSystemService,
+        }),
+        markers: [ToolMarker.ContextBuilding, ToolMarker.Modification],
+        requiredServices: ['contentGenerator', 'fileSystemService'],
+    },
     [ToolName.LIST_DIRECTORY]: {
         descriptionFile: 'list_directory',
         factory: (services) => createListDirectoryTool(getRequiredService(services.fileSystemService, 'fileSystemService')),

package/dist/server/constants.d.ts

@@ -55,6 +55,8 @@ export declare const SUMMARY_INDEX_FILE = "_index.md";
 export declare const ARCHIVE_DIR = "_archived";
 export declare const STUB_EXTENSION = ".stub.md";
 export declare const FULL_ARCHIVE_EXTENSION = ".full.md";
+export declare const ABSTRACT_EXTENSION = ".abstract.md";
+export declare const OVERVIEW_EXTENSION = ".overview.md";
 export declare const MANIFEST_FILE = "_manifest.json";
 export declare const ARCHIVE_IMPORTANCE_THRESHOLD = 35;
 export declare const DEFAULT_GHOST_CUE_MAX_TOKENS = 220;

package/dist/server/constants.js

@@ -75,6 +75,8 @@ export const SUMMARY_INDEX_FILE = '_index.md';
 export const ARCHIVE_DIR = '_archived';
 export const STUB_EXTENSION = '.stub.md';
 export const FULL_ARCHIVE_EXTENSION = '.full.md';
+export const ABSTRACT_EXTENSION = '.abstract.md';
+export const OVERVIEW_EXTENSION = '.overview.md';
 export const MANIFEST_FILE = '_manifest.json';
 export const ARCHIVE_IMPORTANCE_THRESHOLD = 35;
 export const DEFAULT_GHOST_CUE_MAX_TOKENS = 220;

package/dist/server/core/domain/knowledge/memory-scoring.d.ts

@@ -19,11 +19,11 @@ export declare const ACCESS_IMPORTANCE_BONUS = 3;
 /** Importance bonus per curate update */
 export declare const UPDATE_IMPORTANCE_BONUS = 5;
 /** BM25 relevance weight in compound score */
-export declare const W_RELEVANCE = 1;
+export declare const W_RELEVANCE = 0.6;
 /** Importance weight in compound score */
-export declare const W_IMPORTANCE = 0;
+export declare const W_IMPORTANCE = 0.2;
 /** Recency weight in compound score */
-export declare const W_RECENCY = 0;
+export declare const W_RECENCY = 0.2;
 /** Importance threshold to promote draft -> validated */
 export declare const PROMOTE_TO_VALIDATED = 65;
 /** Importance threshold to promote validated -> core */

package/dist/server/core/domain/knowledge/memory-scoring.js

@@ -21,11 +21,11 @@ export const ACCESS_IMPORTANCE_BONUS = 3;
 /** Importance bonus per curate update */
 export const UPDATE_IMPORTANCE_BONUS = 5;
 /** BM25 relevance weight in compound score */
-export const W_RELEVANCE = 1;
+export const W_RELEVANCE = 0.6;
 /** Importance weight in compound score */
-export const W_IMPORTANCE = 0;
+export const W_IMPORTANCE = 0.2;
 /** Recency weight in compound score */
-export const W_RECENCY = 0;
+export const W_RECENCY = 0.2;
 /** Importance threshold to promote draft -> validated */
 export const PROMOTE_TO_VALIDATED = 65;
 /** Importance threshold to promote validated -> core */
@@ -36,8 +36,8 @@ export const DEMOTE_FROM_CORE = 60;
 export const DEMOTE_FROM_VALIDATED = 35;
 /** Search score multiplier per maturity tier */
 export const TIER_BOOST = {
-    core: 1,
-    draft: 1,
+    core: 1.15,
+    draft: 0.85,
     validated: 1,
 };
 // ---------------------------------------------------------------------------

package/dist/server/core/domain/knowledge/summary-types.d.ts

@@ -41,6 +41,10 @@ export interface ArchiveStubFrontmatter {
     type: 'archive_stub';
 }
 export interface ManifestEntry {
+    /** Relative path to .abstract.md sibling, if it exists */
+    abstractPath?: string;
+    /** Token count of .abstract.md (used for lane budgeting) */
+    abstractTokens?: number;
     /** Importance score from frontmatter (0-100, default 50) */
     importance?: number;
     /** Condensation order (only for summaries) */