byterover-cli 1.8.0 → 2.0.0

package/dist/agent/infra/tools/implementations/memory-path-matcher.js

@@ -0,0 +1,217 @@
+/**
+ * Detect the matching mode from a pattern string.
+ * - Starts with "/" → absolute (exact path match)
+ * - Contains "/" → relative (suffix matching, right-to-left)
+ * - No "/" → simple (any symbol with that name)
+ */
+function detectMatchMode(pattern) {
+    if (pattern.startsWith('/')) {
+        return 'absolute';
+    }
+    if (pattern.includes('/')) {
+        return 'relative';
+    }
+    return 'simple';
+}
+/**
+ * Check if a symbol name matches a component, optionally with substring matching.
+ */
+function componentMatches(symbolName, component, substring) {
+    const normalizedSymbol = symbolName.toLowerCase();
+    const normalizedComponent = component.toLowerCase();
+    if (normalizedSymbol === normalizedComponent) {
+        return true;
+    }
+    if (substring && normalizedSymbol.includes(normalizedComponent)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Collect all ancestor names for a symbol (from leaf to root), excluding the symbol itself.
+ */
+function getAncestorNames(symbol) {
+    const names = [];
+    let current = symbol.parent;
+    while (current) {
+        names.push(current.name);
+        current = current.parent;
+    }
+    return names;
+}
+/**
+ * Match a pattern against a symbol using reversed component iteration.
+ * Adapted from Serena's NamePathMatcher — matches from innermost component outward.
+ *
+ * @param symbol - The symbol to test
+ * @param components - Pattern components (already split by "/")
+ * @param isAbsolute - Whether the pattern requires an exact full-path match
+ * @param substringMatching - Whether the last component supports substring matching
+ */
+function matchesReversedComponents(symbol, components, isAbsolute, substringMatching) {
+    // Match from last component backward
+    const ancestors = getAncestorNames(symbol);
+    const fullChain = [symbol.name, ...ancestors];
+    if (components.length > fullChain.length) {
+        return false;
+    }
+    for (let i = 0; i < components.length; i++) {
+        const isLastComponent = i === 0;
+        const useSubstring = substringMatching && isLastComponent;
+        if (!componentMatches(fullChain[i], components[components.length - 1 - i], useSubstring)) {
+            return false;
+        }
+    }
+    // Absolute match: ensure no extra ancestors beyond the pattern
+    if (isAbsolute && components.length !== fullChain.length) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Match a memory path pattern against the symbol tree.
+ * Inspired by Serena's NamePathMatcher with three matching modes:
+ *
+ * - Simple: "jwt" → any symbol named "jwt"
+ * - Relative: "auth/jwt" → jwt under auth (suffix matching)
+ * - Absolute: "/auth/jwt-tokens" → exact path match
+ *
+ * Substring matching applies to the LAST component only:
+ * - "auth/refresh" matches "auth/jwt-tokens/refresh-token-rotation"
+ *
+ * @returns Matching symbols sorted by specificity (exact > relative > substring)
+ */
+export function matchMemoryPath(tree, pattern, options) {
+    const substringMatching = options?.substringMatching ?? true;
+    const trimmedPattern = pattern.trim();
+    if (!trimmedPattern) {
+        return [];
+    }
+    const mode = detectMatchMode(trimmedPattern);
+    const cleanPattern = trimmedPattern.replace(/^\/+/, '');
+    const components = cleanPattern.split('/').filter(Boolean);
+    if (components.length === 0) {
+        return [];
+    }
+    // Fast path: try direct lookup in symbolMap for exact path
+    const directMatch = tree.symbolMap.get(cleanPattern);
+    if (directMatch) {
+        return [{ matchedSymbol: directMatch, matchType: 'absolute' }];
+    }
+    // Also try with .md extension for leaf lookups
+    if (!cleanPattern.endsWith('.md')) {
+        const withMd = tree.symbolMap.get(`${cleanPattern}.md`);
+        if (withMd) {
+            return [{ matchedSymbol: withMd, matchType: 'absolute' }];
+        }
+    }
+    const results = [];
+    const isAbsolute = mode === 'absolute';
+    // Traverse entire tree and test each symbol
+    function traverse(symbol) {
+        // Try exact match first (no substring)
+        if (matchesReversedComponents(symbol, components, isAbsolute, false)) {
+            const matchType = isAbsolute ? 'absolute' : mode === 'relative' ? 'relative' : 'simple';
+            results.push({ matchedSymbol: symbol, matchType });
+        }
+        else if (substringMatching && matchesReversedComponents(symbol, components, isAbsolute, true)) {
+            results.push({ matchedSymbol: symbol, matchType: 'substring' });
+        }
+        for (const child of symbol.children) {
+            traverse(child);
+        }
+    }
+    for (const rootNode of tree.root) {
+        traverse(rootNode);
+    }
+    // Sort by specificity: absolute > relative > simple > substring
+    const specificity = {
+        absolute: 0,
+        relative: 1,
+        simple: 2,
+        substring: 3,
+    };
+    results.sort((a, b) => (specificity[a.matchType] ?? 4) - (specificity[b.matchType] ?? 4));
+    return results;
+}
+/**
+ * Determine if a query string looks like it could be a symbolic path query.
+ * Returns true if the query contains "/" or if a leading word matches a known domain.
+ */
+export function isPathLikeQuery(query, tree) {
+    if (query.includes('/')) {
+        return true;
+    }
+    // Check if the first word matches a known domain name
+    const firstWord = query.split(/\s+/)[0]?.toLowerCase();
+    if (!firstWord) {
+        return false;
+    }
+    for (const rootNode of tree.root) {
+        if (rootNode.name.toLowerCase() === firstWord) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Parse a query into a symbolic scope prefix and a remaining text query.
+ * Tries to match leading words against known domains/topics in the tree.
+ *
+ * Examples:
+ *   "auth/jwt refresh strategy" → { scopePath: "auth/jwt", textQuery: "refresh strategy" }
+ *   "auth jwt refresh"          → { scopePath: "auth", textQuery: "jwt refresh" }
+ *   "random text query"         → { scopePath: undefined, textQuery: "random text query" }
+ */
+export function parseSymbolicQuery(query, tree) {
+    const trimmed = query.trim();
+    // Case 1: explicit path with "/" separator
+    const slashIdx = trimmed.indexOf('/');
+    if (slashIdx !== -1) {
+        // Find where the path ends and text begins (first space after path segment)
+        const afterSlash = trimmed.indexOf(' ', slashIdx);
+        if (afterSlash === -1) {
+            // Entire query is a path
+            const pathPart = trimmed.replace(/^\/+/, '');
+            const matches = matchMemoryPath(tree, pathPart, { substringMatching: false });
+            if (matches.length > 0) {
+                return { scopePath: matches[0].matchedSymbol.path, textQuery: '' };
+            }
+            return { scopePath: undefined, textQuery: trimmed };
+        }
+        const pathPart = trimmed.slice(0, afterSlash).replace(/^\/+/, '');
+        const textPart = trimmed.slice(afterSlash + 1).trim();
+        const matches = matchMemoryPath(tree, pathPart, { substringMatching: false });
+        if (matches.length > 0) {
+            return { scopePath: matches[0].matchedSymbol.path, textQuery: textPart };
+        }
+        return { scopePath: undefined, textQuery: trimmed };
+    }
+    // Case 2: space-separated words — try leading word(s) as scope
+    const words = trimmed.split(/\s+/);
+    // Try first word as domain
+    if (words.length >= 2) {
+        const firstWord = words[0].toLowerCase();
+        for (const rootNode of tree.root) {
+            if (rootNode.name.toLowerCase() === firstWord) {
+                // Try first two words as domain/topic
+                if (words.length >= 3) {
+                    const secondWord = words[1].toLowerCase();
+                    for (const child of rootNode.children) {
+                        if (child.name.toLowerCase() === secondWord) {
+                            return {
+                                scopePath: child.path,
+                                textQuery: words.slice(2).join(' '),
+                            };
+                        }
+                    }
+                }
+                return {
+                    scopePath: rootNode.path,
+                    textQuery: words.slice(1).join(' '),
+                };
+            }
+        }
+    }
+    return { scopePath: undefined, textQuery: trimmed };
+}

package/dist/agent/infra/tools/implementations/memory-symbol-tree.d.ts

@@ -0,0 +1,101 @@
+import type { FrontmatterScoring } from '../../../../server/core/domain/knowledge/markdown-writer.js';
+/**
+ * Symbol kinds in the memory hierarchy, ordered by depth.
+ * Mirrors Serena's SymbolKind pattern for code symbols.
+ */
+export declare enum MemorySymbolKind {
+    Context = 4,
+    Domain = 1,
+    Subtopic = 3,
+    Topic = 2
+}
+/**
+ * A node in the memory symbol tree.
+ * Represents a domain, topic, subtopic, or individual context entry.
+ */
+export interface MemorySymbol {
+    children: MemorySymbol[];
+    kind: MemorySymbolKind;
+    metadata: SymbolMetadata;
+    name: string;
+    parent: MemorySymbol | undefined;
+    /** Relative path within context-tree, e.g. "auth/jwt-tokens/refresh.md" */
+    path: string;
+}
+export interface SymbolMetadata {
+    importance: number;
+    keywords: string[];
+    maturity: string;
+    tags: string[];
+}
+/**
+ * The complete memory symbol tree, built from the context-tree filesystem.
+ */
+export interface MemorySymbolTree {
+    /** All top-level domain nodes */
+    root: MemorySymbol[];
+    /** O(1) lookup: relative path → symbol node */
+    symbolMap: Map<string, MemorySymbol>;
+}
+/**
+ * Entry returned by getSymbolOverview.
+ */
+export interface OverviewEntry {
+    childCount: number;
+    importance: number;
+    kind: string;
+    maturity: string;
+    name: string;
+    path: string;
+}
+/**
+ * Bidirectional reference index built from @relation annotations.
+ */
+export interface ReferenceIndex {
+    /** target path → source paths that reference it */
+    backlinks: Map<string, string[]>;
+    /** source path → target paths it references */
+    forwardLinks: Map<string, string[]>;
+}
+/**
+ * Minimal document shape needed by the tree builder.
+ * Matches the IndexedDocument interface in search-knowledge-service.ts.
+ */
+interface DocumentLike {
+    content: string;
+    id: string;
+    path: string;
+    scoring: FrontmatterScoring;
+    title: string;
+}
+/**
+ * Build a symbol tree from the indexed document map.
+ * No filesystem I/O — operates entirely on the already-loaded documents.
+ *
+ * context.md files are absorbed into their parent folder node (enriching its metadata)
+ * rather than being treated as leaf Context nodes.
+ */
+export declare function buildSymbolTree(documentMap: Map<string, DocumentLike>): MemorySymbolTree;
+/**
+ * Get a structural overview of the symbol tree at configurable depth.
+ *
+ * @param tree - The memory symbol tree
+ * @param path - Optional path to scope the overview (e.g. "auth" for auth domain only)
+ * @param depth - Max depth to traverse (default 2: domains + topics)
+ */
+export declare function getSymbolOverview(tree: MemorySymbolTree, path?: string, depth?: number): OverviewEntry[];
+/**
+ * Collect all leaf document IDs (Context nodes) under a given path.
+ * Used for scoped search — restricts MiniSearch to a subtree.
+ */
+export declare function getSubtreeDocumentIds(tree: MemorySymbolTree, path: string): Set<string>;
+/**
+ * Build a bidirectional reference index from @relation annotations in document content.
+ * Reuses the existing parseRelations() function from relation-parser.ts.
+ */
+export declare function buildReferenceIndex(documentMap: Map<string, DocumentLike>): ReferenceIndex;
+/**
+ * Get the symbol kind label for display in search results.
+ */
+export declare function getSymbolKindLabel(kind: MemorySymbolKind): string;
+export {};

package/dist/agent/infra/tools/implementations/memory-symbol-tree.js

@@ -0,0 +1,259 @@
+import { CONTEXT_FILE } from '../../../../server/constants.js';
+import { parseRelations } from '../../../../server/core/domain/knowledge/relation-parser.js';
+/**
+ * Symbol kinds in the memory hierarchy, ordered by depth.
+ * Mirrors Serena's SymbolKind pattern for code symbols.
+ */
+export var MemorySymbolKind;
+(function (MemorySymbolKind) {
+    MemorySymbolKind[MemorySymbolKind["Context"] = 4] = "Context";
+    MemorySymbolKind[MemorySymbolKind["Domain"] = 1] = "Domain";
+    MemorySymbolKind[MemorySymbolKind["Subtopic"] = 3] = "Subtopic";
+    MemorySymbolKind[MemorySymbolKind["Topic"] = 2] = "Topic";
+})(MemorySymbolKind || (MemorySymbolKind = {}));
+const SYMBOL_KIND_LABELS = {
+    [MemorySymbolKind.Context]: 'context',
+    [MemorySymbolKind.Domain]: 'domain',
+    [MemorySymbolKind.Subtopic]: 'subtopic',
+    [MemorySymbolKind.Topic]: 'topic',
+};
+const DEFAULT_METADATA = {
+    importance: 50,
+    keywords: [],
+    maturity: 'draft',
+    tags: [],
+};
+/**
+ * Determine the MemorySymbolKind based on path depth and whether it's a context.md file.
+ * Path structure: domain/topic/file.md or domain/topic/subtopic/file.md
+ */
+function determineKind(segments) {
+    switch (segments.length) {
+        case 1: {
+            return MemorySymbolKind.Domain;
+        }
+        case 2: {
+            return MemorySymbolKind.Topic;
+        }
+        case 3: {
+            return MemorySymbolKind.Subtopic;
+        }
+        default: {
+            // 4+ segments: treat deepest folder as subtopic-level
+            return MemorySymbolKind.Subtopic;
+        }
+    }
+}
+function extractMetadataFromScoring(scoring) {
+    return {
+        importance: scoring.importance ?? 50,
+        keywords: [],
+        maturity: scoring.maturity ?? 'draft',
+        tags: [],
+    };
+}
+/**
+ * Get or create a folder symbol (Domain/Topic/Subtopic) at the given path.
+ * Creates intermediate nodes as needed.
+ */
+function getOrCreateFolderNode(symbolMap, root, folderPath, folderSegments) {
+    const existing = symbolMap.get(folderPath);
+    if (existing) {
+        return existing;
+    }
+    // Ensure parent exists first (recursive)
+    let parentNode;
+    if (folderSegments.length > 1) {
+        const parentSegments = folderSegments.slice(0, -1);
+        const parentPath = parentSegments.join('/');
+        parentNode = getOrCreateFolderNode(symbolMap, root, parentPath, parentSegments);
+    }
+    const kind = determineKind(folderSegments);
+    const node = {
+        children: [],
+        kind,
+        metadata: { ...DEFAULT_METADATA },
+        name: folderSegments.at(-1),
+        parent: parentNode,
+        path: folderPath,
+    };
+    symbolMap.set(folderPath, node);
+    if (parentNode) {
+        parentNode.children.push(node);
+    }
+    else {
+        // Top-level domain
+        root.push(node);
+    }
+    return node;
+}
+/**
+ * Build a symbol tree from the indexed document map.
+ * No filesystem I/O — operates entirely on the already-loaded documents.
+ *
+ * context.md files are absorbed into their parent folder node (enriching its metadata)
+ * rather than being treated as leaf Context nodes.
+ */
+export function buildSymbolTree(documentMap) {
+    const root = [];
+    const symbolMap = new Map();
+    // First pass: collect all documents, create folder nodes, identify context.md files
+    const contextFiles = [];
+    const leafDocuments = [];
+    for (const doc of documentMap.values()) {
+        const segments = doc.path.split('/');
+        const fileName = segments.at(-1);
+        if (fileName === CONTEXT_FILE) {
+            contextFiles.push(doc);
+        }
+        else {
+            leafDocuments.push(doc);
+        }
+    }
+    // Second pass: create folder nodes for all unique directory paths
+    const allFolderPaths = new Set();
+    for (const doc of documentMap.values()) {
+        const segments = doc.path.split('/');
+        // Collect all ancestor folder paths
+        for (let i = 1; i < segments.length; i++) {
+            allFolderPaths.add(segments.slice(0, i).join('/'));
+        }
+    }
+    for (const folderPath of allFolderPaths) {
+        const folderSegments = folderPath.split('/');
+        getOrCreateFolderNode(symbolMap, root, folderPath, folderSegments);
+    }
+    // Third pass: absorb context.md files into their parent folder nodes
+    for (const doc of contextFiles) {
+        const segments = doc.path.split('/');
+        const folderPath = segments.slice(0, -1).join('/');
+        const folderNode = symbolMap.get(folderPath);
+        if (folderNode) {
+            folderNode.metadata = {
+                ...folderNode.metadata,
+                ...extractMetadataFromScoring(doc.scoring),
+            };
+        }
+        // Also register the context.md path itself for direct lookups
+        symbolMap.set(doc.path, folderNode ?? getOrCreateFolderNode(symbolMap, root, folderPath, segments.slice(0, -1)));
+    }
+    // Fourth pass: create leaf Context nodes for non-context.md documents
+    for (const doc of leafDocuments) {
+        const segments = doc.path.split('/');
+        const folderPath = segments.slice(0, -1).join('/');
+        const parentNode = symbolMap.get(folderPath);
+        const contextNode = {
+            children: [],
+            kind: MemorySymbolKind.Context,
+            metadata: extractMetadataFromScoring(doc.scoring),
+            name: doc.title || segments.at(-1).replace(/\.md$/, ''),
+            parent: parentNode,
+            path: doc.path,
+        };
+        symbolMap.set(doc.path, contextNode);
+        if (parentNode) {
+            parentNode.children.push(contextNode);
+        }
+    }
+    // Sort root domains and all children alphabetically
+    sortSymbolChildren(root);
+    return { root, symbolMap };
+}
+function sortSymbolChildren(symbols) {
+    symbols.sort((a, b) => a.name.localeCompare(b.name));
+    for (const symbol of symbols) {
+        if (symbol.children.length > 0) {
+            sortSymbolChildren(symbol.children);
+        }
+    }
+}
+/**
+ * Get a structural overview of the symbol tree at configurable depth.
+ *
+ * @param tree - The memory symbol tree
+ * @param path - Optional path to scope the overview (e.g. "auth" for auth domain only)
+ * @param depth - Max depth to traverse (default 2: domains + topics)
+ */
+export function getSymbolOverview(tree, path, depth = 2) {
+    const entries = [];
+    let startNodes;
+    if (path) {
+        const node = tree.symbolMap.get(path);
+        if (!node) {
+            return [];
+        }
+        startNodes = [node];
+    }
+    else {
+        startNodes = tree.root;
+    }
+    function traverse(symbols, currentDepth) {
+        for (const symbol of symbols) {
+            entries.push({
+                childCount: symbol.children.length,
+                importance: symbol.metadata.importance,
+                kind: SYMBOL_KIND_LABELS[symbol.kind] ?? 'unknown',
+                maturity: symbol.metadata.maturity,
+                name: symbol.name,
+                path: symbol.path,
+            });
+            if (currentDepth < depth && symbol.children.length > 0) {
+                traverse(symbol.children, currentDepth + 1);
+            }
+        }
+    }
+    traverse(startNodes, 1);
+    return entries;
+}
+/**
+ * Collect all leaf document IDs (Context nodes) under a given path.
+ * Used for scoped search — restricts MiniSearch to a subtree.
+ */
+export function getSubtreeDocumentIds(tree, path) {
+    const ids = new Set();
+    const node = tree.symbolMap.get(path);
+    if (!node) {
+        return ids;
+    }
+    function collect(symbol) {
+        if (symbol.kind === MemorySymbolKind.Context) {
+            ids.add(symbol.path);
+        }
+        for (const child of symbol.children) {
+            collect(child);
+        }
+    }
+    collect(node);
+    return ids;
+}
+/**
+ * Build a bidirectional reference index from @relation annotations in document content.
+ * Reuses the existing parseRelations() function from relation-parser.ts.
+ */
+export function buildReferenceIndex(documentMap) {
+    const backlinks = new Map();
+    const forwardLinks = new Map();
+    for (const doc of documentMap.values()) {
+        const relations = parseRelations(doc.content);
+        if (relations.length === 0) {
+            continue;
+        }
+        forwardLinks.set(doc.path, relations);
+        for (const target of relations) {
+            const existing = backlinks.get(target);
+            if (existing) {
+                existing.push(doc.path);
+            }
+            else {
+                backlinks.set(target, [doc.path]);
+            }
+        }
+    }
+    return { backlinks, forwardLinks };
+}
+/**
+ * Get the symbol kind label for display in search results.
+ */
+export function getSymbolKindLabel(kind) {
+    return SYMBOL_KIND_LABELS[kind] ?? 'unknown';
+}

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

@@ -9,6 +9,25 @@ export interface SearchKnowledgeServiceConfig {
     /** Cache TTL in milliseconds (defaults to 5000) */
     cacheTtlMs?: number;
 }
+/**
+ * Extended search options supporting symbolic filters.
+ */
+export interface SearchOptions {
+    /** Symbol kinds to exclude from results (e.g. ['subtopic']) */
+    excludeKinds?: string[];
+    /** Symbol kinds to include in results (e.g. ['domain', 'context']) */
+    includeKinds?: string[];
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Minimum maturity tier for results */
+    minMaturity?: 'core' | 'draft' | 'validated';
+    /** If true, return tree structure overview instead of search results */
+    overview?: boolean;
+    /** Depth for overview mode (default: 2) */
+    overviewDepth?: number;
+    /** Path prefix to scope search within (e.g. "auth" or "auth/jwt-tokens") */
+    scope?: string;
+}
 /**
  * SearchKnowledgeService implementation.
  * Provides knowledge search functionality with caching and indexing.
@@ -17,18 +36,41 @@ export declare class SearchKnowledgeService implements ISearchKnowledgeService {
     private readonly baseDirectory;
     private readonly cacheTtlMs;
     private readonly fileSystem;
+    private readonly pendingAccessHits;
     private readonly state;
     constructor(fileSystem: IFileSystem, config?: SearchKnowledgeServiceConfig);
+    /**
+     * Flush accumulated access hits to disk by updating frontmatter scoring.
+     * Called during index rebuild to batch writes and avoid write amplification.
+     * Best-effort: errors are swallowed per file.
+     */
+    flushAccessHits(contextTreePath: string): Promise<void>;
     /**
      * Search the knowledge base for relevant topics.
+     * Supports symbolic path queries, scoped search, kind/maturity filtering, and overview mode.
      *
-     * @param query - Natural language query string
-     * @param options - Search options
-     * @returns Search results with matching topics
+     * @param query - Natural language query string or symbolic path (e.g. "auth/jwt")
+     * @param options - Search options including symbolic filters
+     * @returns Search results with matching topics, enriched with symbolic metadata
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchKnowledgeResult>;
+    private accumulateAccessHits;
+    /**
+     * Build overview result showing the tree structure at configurable depth.
+     */
+    private buildOverviewResult;
+    /**
+     * Enrich a search result with symbolic metadata and backlink info.
+     */
+    private enrichResult;
+    /**
+     * Run the standard text-based MiniSearch pipeline, optionally scoped to a subtree.
+     */
+    private runTextSearch;
+    /**
+     * Try to resolve the query as a symbolic path. Returns null if no path match found.
      */
-    search(query: string, options?: {
-        limit?: number;
-    }): Promise<SearchKnowledgeResult>;
+    private trySymbolicSearch;
 }
 /**
  * Factory function to create a SearchKnowledgeService instance.