byterover-cli 1.7.2 → 1.8.0

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

@@ -4,11 +4,21 @@ import { removeStopwords } from 'stopword';
 import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR } from '../../../../server/constants.js';
 const MAX_CONTEXT_TREE_FILES = 10_000;
 const DEFAULT_CACHE_TTL_MS = 5000;
+/** Bump when MINISEARCH_OPTIONS fields/boost change to invalidate cached indexes */
+const INDEX_SCHEMA_VERSION = 3;
+/** Only include results whose score is at least this fraction of the top result's score */
+const SCORE_GAP_RATIO = 0.2;
+/** Minimum absolute score for the top result. Below this, the query is considered out-of-domain */
+const MINIMUM_RELEVANCE_SCORE = 4;
+/** Score threshold above which results are trusted despite unmatched query terms */
+const UNMATCHED_TERM_SCORE_THRESHOLD = 8;
+/** Minimum query term length to consider "significant" for OOD term-based detection */
+const UNMATCHED_TERM_MIN_LENGTH = 4;
 const MINISEARCH_OPTIONS = {
-    fields: ['title', 'content'],
+    fields: ['title', 'content', 'path'],
     idField: 'id',
     searchOptions: {
-        boost: { title: 2 },
+        boost: { path: 1.5, title: 3 },
         fuzzy: 0.2,
         prefix: true,
     },
@@ -19,6 +29,24 @@ function filterStopWords(query) {
     const filtered = removeStopwords(words);
     return filtered.length > 0 ? filtered.join(' ') : query;
 }
+/**
+ * Checks if any significant query term is completely unmatched across search results.
+ * Uses MiniSearch's queryTerms property to identify which terms actually matched.
+ * A "significant" term is one with length >= UNMATCHED_TERM_MIN_LENGTH (filters out
+ * short generic words that are noisy for OOD detection).
+ */
+function hasUnmatchedSignificantTerms(queryTerms, searchResults) {
+    const significantTerms = queryTerms.filter((t) => t.length >= UNMATCHED_TERM_MIN_LENGTH);
+    if (significantTerms.length === 0)
+        return false;
+    const allMatchedQueryTerms = new Set();
+    for (const result of searchResults.slice(0, 10)) {
+        for (const term of result.queryTerms) {
+            allMatchedQueryTerms.add(term);
+        }
+    }
+    return significantTerms.some((t) => !allMatchedQueryTerms.has(t));
+}
 function extractTitle(content, fallbackTitle) {
     const match = /^# (.+)$/m.exec(content);
     return match ? match[1].trim() : fallbackTitle;
@@ -110,6 +138,7 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
             fileMtimes: new Map(),
             index,
             lastValidatedAt: now,
+            schemaVersion: INDEX_SCHEMA_VERSION,
         };
     }
     const documentPromises = filesWithMtime.map(async ({ mtime, path: filePath }) => {
@@ -145,6 +174,7 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
         fileMtimes,
         index,
         lastValidatedAt: now,
+        schemaVersion: INDEX_SCHEMA_VERSION,
     };
 }
 /**
@@ -156,6 +186,7 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs) {
     // Fast path: TTL-based cache hit (no I/O needed)
     if (state.cachedIndex &&
         state.cachedIndex.contextTreePath === contextTreePath &&
+        state.cachedIndex.schemaVersion === INDEX_SCHEMA_VERSION &&
         ttlMs > 0 &&
         now - state.cachedIndex.lastValidatedAt < ttlMs) {
         return state.cachedIndex;
@@ -181,6 +212,7 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs) {
                     fileMtimes: new Map(),
                     index: emptyIndex,
                     lastValidatedAt: 0,
+                    schemaVersion: INDEX_SCHEMA_VERSION,
                 };
             }
         }
@@ -188,6 +220,7 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs) {
         // Re-check cache validity after getting file list (another call may have finished)
         if (state.cachedIndex &&
             state.cachedIndex.contextTreePath === contextTreePath &&
+            state.cachedIndex.schemaVersion === INDEX_SCHEMA_VERSION &&
             isCacheValid(state.cachedIndex, currentFiles)) {
             // Update timestamp atomically by creating a new object
             const updatedCache = {
@@ -266,19 +299,63 @@ export class SearchKnowledgeService {
             };
         }
         const filteredQuery = filterStopWords(query);
-        const searchResults = index.search(filteredQuery, { combineWith: 'OR' });
+        const filteredWords = filteredQuery.split(/\s+/).filter((w) => w.length >= 2);
+        // AND-first strategy: for multi-word queries, try AND for concentrated scores.
+        // If AND returns no results, fall back to OR to ensure no regression.
+        let searchResults;
+        let andSearchFailed = false;
+        if (filteredWords.length >= 2) {
+            searchResults = index.search(filteredQuery, { combineWith: 'AND' });
+            if (searchResults.length === 0) {
+                andSearchFailed = true;
+                searchResults = index.search(filteredQuery, { combineWith: 'OR' });
+            }
+        }
+        else {
+            searchResults = index.search(filteredQuery, { combineWith: 'OR' });
+        }
         const results = [];
-        const resultLimit = Math.min(limit, searchResults.length);
-        for (let i = 0; i < resultLimit; i++) {
-            const result = searchResults[i];
-            const document = documentMap.get(result.id);
-            if (document) {
-                results.push({
-                    excerpt: extractExcerpt(document.content, query),
-                    path: document.path,
-                    score: Math.round(result.score * 100) / 100,
-                    title: document.title,
-                });
+        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.
+            // Only apply for corpora with enough documents for reliable BM25 scoring.
+            if (documentMap.size >= 50 && searchResults[0].score < MINIMUM_RELEVANCE_SCORE) {
+                return {
+                    message: 'No matching knowledge found for this query. The topic may not be covered in the context tree.',
+                    results: [],
+                    totalFound: 0,
+                };
+            }
+            // Term-based OOD: when AND search failed, check if significant query terms
+            // are completely absent from the corpus. If unmatched terms exist and the
+            // score is below the trusted threshold, the query is about an uncovered topic.
+            if (andSearchFailed &&
+                documentMap.size >= 50 &&
+                searchResults[0].score < UNMATCHED_TERM_SCORE_THRESHOLD &&
+                hasUnmatchedSignificantTerms(filteredWords, searchResults)) {
+                return {
+                    message: 'No matching knowledge found for this query. The topic may not be covered in the context tree.',
+                    results: [],
+                    totalFound: 0,
+                };
+            }
+            const topScore = searchResults[0].score;
+            const scoreFloor = topScore * SCORE_GAP_RATIO;
+            const resultLimit = Math.min(limit, searchResults.length);
+            for (let i = 0; i < resultLimit; i++) {
+                const result = searchResults[i];
+                // Score-gap filter: skip results too far below the top score
+                if (result.score < scoreFloor)
+                    break;
+                const document = documentMap.get(result.id);
+                if (document) {
+                    results.push({
+                        excerpt: extractExcerpt(document.content, query),
+                        path: document.path,
+                        score: Math.round(result.score * 100) / 100,
+                        title: document.title,
+                    });
+                }
             }
         }
         return {

package/dist/agent/infra/tools/index.d.ts

@@ -3,14 +3,10 @@ export { ToolName } from '../../core/domain/tools/constants.js';
 export type { KnownTool } from '../../core/domain/tools/constants.js';
 export type { JSONSchema7, Tool, ToolExecutionContext, ToolSet } from '../../core/domain/tools/types.js';
 export type { IToolProvider } from '../../core/interfaces/i-tool-provider.js';
-export { createCreateKnowledgeTopicTool } from './implementations/create-knowledge-topic-tool.js';
-export { createEditFileTool } from './implementations/edit-file-tool.js';
 export { createGlobFilesTool } from './implementations/glob-files-tool.js';
 export { createGrepContentTool } from './implementations/grep-content-tool.js';
 export { createReadFileTool } from './implementations/read-file-tool.js';
-export { createSearchHistoryTool } from './implementations/search-history-tool.js';
 export { createSearchKnowledgeTool } from './implementations/search-knowledge-tool.js';
-export { createSpecAnalyzeTool } from './implementations/spec-analyze-tool.js';
 export { createWriteFileTool } from './implementations/write-file-tool.js';
 export { ToolManager } from './tool-manager.js';
 export { ToolProvider } from './tool-provider.js';

package/dist/agent/infra/tools/index.js

@@ -3,14 +3,10 @@ export { ToolError, ToolExecutionError, ToolNotFoundError, ToolProviderNotInitia
 // Constants
 export { ToolName } from '../../core/domain/tools/constants.js';
 // Tool implementations (for direct access if needed)
-export { createCreateKnowledgeTopicTool } from './implementations/create-knowledge-topic-tool.js';
-export { createEditFileTool } from './implementations/edit-file-tool.js';
 export { createGlobFilesTool } from './implementations/glob-files-tool.js';
 export { createGrepContentTool } from './implementations/grep-content-tool.js';
 export { createReadFileTool } from './implementations/read-file-tool.js';
-export { createSearchHistoryTool } from './implementations/search-history-tool.js';
 export { createSearchKnowledgeTool } from './implementations/search-knowledge-tool.js';
-export { createSpecAnalyzeTool } from './implementations/spec-analyze-tool.js';
 export { createWriteFileTool } from './implementations/write-file-tool.js';
 // Registry and provider
 export { ToolManager } from './tool-manager.js';

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

@@ -1,30 +1,14 @@
 import { ToolName } from '../../core/domain/tools/constants.js';
 import { createCurateService } from '../sandbox/curate-service.js';
-import { createBashExecTool } from './implementations/bash-exec-tool.js';
-import { createBashOutputTool } from './implementations/bash-output-tool.js';
-import { createBatchTool } from './implementations/batch-tool.js';
 import { createCodeExecTool } from './implementations/code-exec-tool.js';
-import { createCreateKnowledgeTopicTool } from './implementations/create-knowledge-topic-tool.js';
 import { createCurateTool } from './implementations/curate-tool.js';
-import { createDeleteMemoryTool } from './implementations/delete-memory-tool.js';
-import { createEditFileTool } from './implementations/edit-file-tool.js';
-import { createEditMemoryTool } from './implementations/edit-memory-tool.js';
-// import {createFindKnowledgeTopicsTool} from './implementations/find-knowledge-topics-tool.js'
 import { createGlobFilesTool } from './implementations/glob-files-tool.js';
 import { createGrepContentTool } from './implementations/grep-content-tool.js';
-import { createKillProcessTool } from './implementations/kill-process-tool.js';
 import { createListDirectoryTool } from './implementations/list-directory-tool.js';
-import { createListMemoriesTool } from './implementations/list-memories-tool.js';
 import { createReadFileTool } from './implementations/read-file-tool.js';
-import { createReadMemoryTool } from './implementations/read-memory-tool.js';
-import { createReadTodosTool } from './implementations/read-todos-tool.js';
-import { createSearchHistoryTool } from './implementations/search-history-tool.js';
 import { createSearchKnowledgeService } from './implementations/search-knowledge-service.js';
 import { createSearchKnowledgeTool } from './implementations/search-knowledge-tool.js';
-import { createSpecAnalyzeTool } from './implementations/spec-analyze-tool.js';
 import { createWriteFileTool } from './implementations/write-file-tool.js';
-import { createWriteMemoryTool } from './implementations/write-memory-tool.js';
-import { createWriteTodosTool } from './implementations/write-todos-tool.js';
 import { ToolMarker } from './tool-markers.js';
 /**
  * Helper function to safely retrieve a required service.
@@ -51,24 +35,6 @@ function getRequiredService(service, serviceName) {
  * 3. Add entry to this registry
  */
 export const TOOL_REGISTRY = {
-    [ToolName.BASH_EXEC]: {
-        descriptionFile: 'bash_exec',
-        factory: (services) => createBashExecTool(getRequiredService(services.processService, 'processService')),
-        markers: [ToolMarker.Execution],
-        requiredServices: ['processService'],
-    },
-    [ToolName.BASH_OUTPUT]: {
-        descriptionFile: 'bash_output',
-        factory: (services) => createBashOutputTool(getRequiredService(services.processService, 'processService')),
-        markers: [ToolMarker.Execution, ToolMarker.Optional],
-        requiredServices: ['processService'],
-    },
-    [ToolName.BATCH]: {
-        descriptionFile: 'batch',
-        factory: (services) => createBatchTool(getRequiredService(services.getToolProvider, 'getToolProvider')),
-        markers: [ToolMarker.Execution, ToolMarker.Core],
-        requiredServices: ['getToolProvider'],
-    },
     [ToolName.CODE_EXEC]: {
         descriptionFile: 'code_exec',
         factory({ environmentContext, fileSystemService, sandboxService }) {
@@ -96,13 +62,6 @@ export const TOOL_REGISTRY = {
         markers: [ToolMarker.Execution],
         requiredServices: ['sandboxService', 'fileSystemService'],
     },
-    [ToolName.CREATE_KNOWLEDGE_TOPIC]: {
-        descriptionFile: 'create_knowledge_topic',
-        factory: () => createCreateKnowledgeTopicTool(),
-        markers: [ToolMarker.ContextBuilding],
-        outputGuidance: 'create_knowledge_topic',
-        requiredServices: [], // Uses DirectoryManager for file operations
-    },
     [ToolName.CURATE]: {
         descriptionFile: 'curate',
         factory: () => createCurateTool(),
@@ -110,26 +69,6 @@ export const TOOL_REGISTRY = {
         outputGuidance: 'curate',
         requiredServices: [], // Uses DirectoryManager and MarkdownWriter for file operations
     },
-    [ToolName.DELETE_MEMORY]: {
-        descriptionFile: 'delete_memory',
-        factory: (services) => createDeleteMemoryTool(getRequiredService(services.memoryManager, 'memoryManager')),
-        markers: [ToolMarker.ContextBuilding],
-        outputGuidance: 'delete_memory',
-        requiredServices: ['memoryManager'],
-    },
-    [ToolName.EDIT_FILE]: {
-        descriptionFile: 'edit_file',
-        factory: (services) => createEditFileTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
-        markers: [ToolMarker.Modification],
-        requiredServices: ['fileSystemService'],
-    },
-    [ToolName.EDIT_MEMORY]: {
-        descriptionFile: 'edit_memory',
-        factory: (services) => createEditMemoryTool(getRequiredService(services.memoryManager, 'memoryManager')),
-        markers: [ToolMarker.ContextBuilding],
-        outputGuidance: 'edit_memory',
-        requiredServices: ['memoryManager'],
-    },
     [ToolName.GLOB_FILES]: {
         descriptionFile: 'glob_files',
         factory: (services) => createGlobFilesTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
@@ -142,80 +81,28 @@ export const TOOL_REGISTRY = {
         markers: [ToolMarker.Core, ToolMarker.Discovery],
         requiredServices: ['fileSystemService'],
     },
-    [ToolName.KILL_PROCESS]: {
-        descriptionFile: 'kill_process',
-        factory: (services) => createKillProcessTool(getRequiredService(services.processService, 'processService')),
-        markers: [ToolMarker.Execution, ToolMarker.Optional],
-        requiredServices: ['processService'],
-    },
     [ToolName.LIST_DIRECTORY]: {
         descriptionFile: 'list_directory',
         factory: (services) => createListDirectoryTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
         markers: [ToolMarker.Discovery],
         requiredServices: ['fileSystemService'],
     },
-    [ToolName.LIST_MEMORIES]: {
-        descriptionFile: 'list_memories',
-        factory: (services) => createListMemoriesTool(getRequiredService(services.memoryManager, 'memoryManager')),
-        markers: [ToolMarker.ContextBuilding, ToolMarker.Discovery],
-        outputGuidance: 'list_memories',
-        requiredServices: ['memoryManager'],
-    },
     [ToolName.READ_FILE]: {
         descriptionFile: 'read_file',
         factory: (services) => createReadFileTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
         markers: [ToolMarker.Core, ToolMarker.Discovery],
         requiredServices: ['fileSystemService'],
     },
-    [ToolName.READ_MEMORY]: {
-        descriptionFile: 'read_memory',
-        factory: (services) => createReadMemoryTool(getRequiredService(services.memoryManager, 'memoryManager')),
-        markers: [ToolMarker.ContextBuilding, ToolMarker.Discovery],
-        outputGuidance: 'read_memory',
-        requiredServices: ['memoryManager'],
-    },
-    [ToolName.READ_TODOS]: {
-        descriptionFile: 'read_todos',
-        factory: (services) => createReadTodosTool(getRequiredService(services.todoStorage, 'todoStorage')),
-        markers: [ToolMarker.Planning, ToolMarker.Core],
-        requiredServices: ['todoStorage'],
-    },
-    [ToolName.SEARCH_HISTORY]: {
-        descriptionFile: 'search_history',
-        factory: (_services) => createSearchHistoryTool(),
-        markers: [ToolMarker.ContextBuilding, ToolMarker.Discovery],
-        requiredServices: [], // No services required yet (stub implementation)
-    },
     [ToolName.SEARCH_KNOWLEDGE]: {
         descriptionFile: 'search_knowledge',
         factory: (services) => createSearchKnowledgeTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
         markers: [ToolMarker.ContextBuilding, ToolMarker.Discovery],
         requiredServices: ['fileSystemService'],
     },
-    [ToolName.SPEC_ANALYZE]: {
-        descriptionFile: 'spec_analyze',
-        factory: () => createSpecAnalyzeTool(),
-        markers: [ToolMarker.ContextBuilding],
-        outputGuidance: 'spec_analyze',
-        requiredServices: [], // No services required (validates LLM-detected domains)
-    },
     [ToolName.WRITE_FILE]: {
         descriptionFile: 'write_file',
         factory: (services) => createWriteFileTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
         markers: [ToolMarker.Modification],
         requiredServices: ['fileSystemService'],
     },
-    [ToolName.WRITE_MEMORY]: {
-        descriptionFile: 'write_memory',
-        factory: (services) => createWriteMemoryTool(getRequiredService(services.memoryManager, 'memoryManager')),
-        markers: [ToolMarker.ContextBuilding],
-        outputGuidance: 'write_memory',
-        requiredServices: ['memoryManager'],
-    },
-    [ToolName.WRITE_TODOS]: {
-        descriptionFile: 'write_todos',
-        factory: (services) => createWriteTodosTool(getRequiredService(services.todoStorage, 'todoStorage')),
-        markers: [ToolMarker.Planning, ToolMarker.Core],
-        requiredServices: ['todoStorage'],
-    },
 };

package/dist/agent/resources/prompts/curate-detail-preservation.yml

@@ -0,0 +1,73 @@
+description: "Detail preservation instructions for curate mode"
+prompt: |
+  <CURATE_DETAIL_PRESERVATION>
+  ## Diagram and Visual Content Preservation
+
+  When curating content from files or folders, actively look for and preserve:
+
+  **Diagrams (MUST PRESERVE in narrative.diagrams array):**
+  - Mermaid diagrams (```mermaid ... ```) - store with type: "mermaid"
+  - PlantUML diagrams (@startuml ... @enduml) - store with type: "plantuml"
+  - ASCII art diagrams (box drawings, flow charts using |, -, +, >, arrows) - store with type: "ascii"
+  - Sequence diagrams, state diagrams, class diagrams, ER diagrams - identify the format and store accordingly
+  - ALWAYS preserve diagram content EXACTLY as-is, character for character
+  - NEVER paraphrase or describe a diagram in text instead of storing it
+  - NEVER skip a diagram because "it's too complex" - store it verbatim
+
+  **Tables (MUST PRESERVE):**
+  - Markdown tables - preserve the full table in narrative.structure or narrative.features
+  - Include column headers and ALL rows - do not summarize table content
+  - If a table has 20 rows, store all 20 rows
+
+  **Step-by-step Procedures:**
+  - Numbered instructions - store in narrative.rules with original numbering
+  - Decision trees - store as diagrams (ascii type) or in narrative.structure
+  - Workflows - capture in rawConcept.flow AND as diagrams if visual representation exists
+
+  **API Signatures and Interfaces:**
+  - Function signatures with parameter types - store in narrative.structure
+  - Interface definitions - preserve exact TypeScript/language syntax in snippets
+  - Request/response schemas - store complete schema, not summaries
+
+  **Code Examples:**
+  - Inline code examples from documentation - store in narrative.examples with full code
+  - Configuration examples - preserve exact syntax and values
+  - Command-line examples - store complete commands with flags
+
+  **Detection Heuristics:**
+  - Lines containing box-drawing characters (U+2500-U+257F, or ASCII +--+, |  |) = ASCII diagram
+  - Fenced blocks with language tag "mermaid", "plantuml", "dot", "graphviz" = diagram
+  - Content between @startuml/@enduml = PlantUML diagram
+  - Arrow patterns (-->, ==>, ->, =>), combined with indentation = flow/sequence diagram
+
+  **Storage Rules for Diagrams:**
+  - One diagram per entry in the narrative.diagrams array
+  - Always set the `type` field correctly (mermaid, plantuml, ascii, other)
+  - Use `title` field when the diagram has a caption or label nearby
+  - Example:
+    ```javascript
+    narrative: {
+      diagrams: [
+        {
+          type: "mermaid",
+          title: "Authentication Flow",
+          content: "graph TD\n  A[Request] --> B{Has Token?}\n  B -->|Yes| C[Validate]\n  B -->|No| D[Reject]"
+        }
+      ]
+    }
+    ```
+
+  ## General Detail Preservation
+
+  **Completeness over conciseness:**
+  - If a document lists 15 items, store all 15
+  - If a config file has 30 settings, capture all relevant ones
+  - If there are multiple code examples, store each one
+  - Preserve original formatting, indentation, and structure where possible
+
+  **Do NOT:**
+  - Summarize detailed content into brief descriptions
+  - Pick "representative examples" instead of storing all items
+  - Omit sections because they seem "less important"
+  - Flatten hierarchical content into flat descriptions
+  </CURATE_DETAIL_PRESERVATION>

package/dist/agent/resources/prompts/system-prompt.yml

@@ -345,16 +345,33 @@ prompt: |
   When using the `curate` tool, use this structured format:
 
   **rawConcept** - Essential metadata and technical footprint:
+  - IMPORTANT: Before proceeding, analyze the input content for any file path references (e.g., "implemented in auth.ts", "see config.json", "refer to src/utils/helper.h")
+    - **Language-Specific File Path Handling**:
+      - **TypeScript/TSX ESM**: Import statements use `.js/.jsx` but source files are `.ts/.tsx`
+        - Example: `import {foo} from './bar.js'` → actual file is `bar.ts`
+        - ALWAYS use actual source extension (.ts, .tsx, .d.ts) NOT import extension (.js, .jsx)
+        - When in doubt, verify the .ts/.tsx file exists before assuming .js
+      - **Other Languages** (Python, Java, Go, Rust, C/C++, PHP, Ruby, etc.):
+        - Use the actual file paths as they appear in the filesystem
+        - For languages where imports match file paths (C/C++, PHP, JS), use the import path directly
+        - For languages with module systems (Python, Java, Go, Rust), extract the referenced module file
   - `task`: What is being documented (required - always include this)
   - `changes`: Array of changes in the codebase (e.g., ["Added Redis caching", "Created singleton client"])
-  - `files`: Array of related files (e.g., ["services/auth.ts", "utils/cache.ts"])
+  - `files`: Array of actual source file paths (e.g., ["services/auth.ts", "utils/cache.ts", "include/helper.h"])
+    - Use the file extension that exists in the filesystem
+    - TypeScript ESM: Use .ts/.tsx even when imports show .js/.jsx
+    - All other languages: Use the actual file extension (preserve .h, .cpp, .py, .java, .go, .rs, .php, .rb, etc.)
   - `flow`: The execution flow (e.g., "request -> validate -> cache check -> process -> respond")
   - `timestamp`: When created (ISO 8601 format, e.g., "2025-03-18")
+  - `author`: Author or source attribution (e.g., "meowso", "Security Team") - optional
+  - `patterns`: Array of regex/validation patterns with {pattern, description, flags} - optional
 
   **narrative** - Descriptive and structural context:
   - `structure`: Code structure documentation (describe file organization, class hierarchy, etc.)
   - `dependencies`: Dependency management information (external libs, internal dependencies, initialization order)
   - `features`: Feature documentation (behavior, limitations, edge cases, caching TTLs, etc.)
+  - `rules`: Exact rules, constraints, or guidelines - preserved verbatim from source - optional
+  - `examples`: Concrete examples and use cases - optional
 
   **relations** - Optional cross-references to related topics:
   - Array of related topic paths (e.g., ["@structure/redis/overview.md", "@design/security/token-validation.md"])
@@ -381,12 +398,18 @@ prompt: |
             'src/utils/jwt.ts'
           ],
           flow: 'request -> extract token -> verify JWT -> check blacklist -> attach user -> proceed',
-          timestamp: '2025-01-02'
+          timestamp: '2025-01-02',
+          author: 'Security Team',
+          patterns: [
+            { pattern: '^Bearer\\s+[A-Za-z0-9-._~+/]+=*$', description: 'Validates Bearer token format in Authorization header' }
+          ]
         },
         narrative: {
           structure: 'Authentication is handled by middleware in src/middleware/auth.ts which delegates to TokenService for JWT operations',
           dependencies: 'Uses jsonwebtoken library for JWT operations, Redis for token blacklist with 24h TTL',
-          features: 'Access tokens expire in 15 minutes, refresh tokens in 7 days. Refresh token rotation invalidates old tokens immediately'
+          features: 'Access tokens expire in 15 minutes, refresh tokens in 7 days. Refresh token rotation invalidates old tokens immediately',
+          rules: 'Rule 1: Access tokens must be verified before use\nRule 2: Expired tokens return 401\nRule 3: Refresh tokens can only be used once',
+          examples: 'Example Authorization header: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
         },
         relations: ['@structure/redis/overview.md', '@design/security/token-validation.md']
       },
@@ -416,6 +439,49 @@ prompt: |
   - "The hook system allows registering callbacks for lifecycle events. Register hooks using `HookRegistry.register(hookName, callback)` and trigger them with `HookRegistry.trigger(hookName, context)`. Hooks support async callbacks and are commonly used for: pre/post tool execution, agent lifecycle events, and custom integrations."
   - "Error handling follows a custom error class pattern. All custom errors extend `BaseError` and include: error code, message, context object, and optional cause. Use `ErrorHandler.wrap(fn)` for consistent error boundaries across async operations."
 
+  ### Content Preservation Rules
+
+  When curating content that contains rules, patterns, or exact specifications, **PRESERVE DETAILS** instead of summarizing:
+
+  **PRESERVE VERBATIM:**
+  - Exact rule text and constraint language - DO NOT paraphrase
+  - Regex patterns and validation patterns - include as-is in `patterns` array
+  - Author/source attribution - capture in `author` field
+  - All enumerated items in lists - DO NOT omit any items
+  - Exact configuration values and technical specifications
+  - Metadata like version numbers, dates, identifiers
+
+  **Use appropriate fields:**
+  - `rawConcept.patterns` - for regex, validation patterns, matching rules with exact pattern strings
+  - `narrative.rules` - for exact rule text, constraints, guidelines (preserve verbatim, do not summarize)
+  - `narrative.examples` - for concrete examples and use cases with specific details
+  - `rawConcept.author` - for attribution and source info
+  - `snippets` - for code blocks and larger text excerpts
+
+  **When curating rules/guidelines:**
+  - Include the EXACT rule text in `narrative.rules`, not a summary
+  - Capture ALL rules, not a representative subset
+  - Preserve the original numbering/ordering if present
+  - Keep qualifiers and specific conditions (e.g., "other than what's explicitly requested")
+
+  **When curating patterns:**
+  - Store in `rawConcept.patterns` array with exact pattern string + description
+  - Include regex flags if specified (e.g., "i", "gi")
+  - Do not simplify or modify the pattern
+  - Include ALL patterns, not just examples
+
+  **Examples of GOOD preservation:**
+  - Original: "Rule 3: Never use apologies" → Store exactly: "Rule 3: Never use apologies" in narrative.rules
+  - Original: Has 16 regex patterns → Store all 16 in rawConcept.patterns array
+  - Original: "Author: meowso" → Capture: author: "meowso"
+  - Original: "Make changes file by file and give me a chance to spot mistakes" → Store complete text, not "Enforced file-by-file changes"
+
+  **Examples of BAD summarization (AVOID):**
+  - Original: "Rule 3: Never use apologies" → "Prohibited apologies" ❌
+  - Original: 16 patterns → Store only 3-5 examples ❌
+  - Original: Detailed rule with qualifier → Shortened version without qualifier ❌
+  - Original: 8 use cases → Store only 2 ❌
+
   ### Domain/Topic/Subtopic Context
 
   When creating NEW domains, topics, or subtopics, provide the appropriate context:

package/dist/server/core/domain/knowledge/markdown-writer.d.ts

@@ -1,13 +1,26 @@
 export interface RawConcept {
+    author?: string;
     changes?: string[];
     files?: string[];
     flow?: string;
+    patterns?: Array<{
+        description: string;
+        flags?: string;
+        pattern: string;
+    }>;
     task?: string;
     timestamp?: string;
 }
 export interface Narrative {
     dependencies?: string;
+    diagrams?: Array<{
+        content: string;
+        title?: string;
+        type: string;
+    }>;
+    examples?: string;
     features?: string;
+    rules?: string;
     structure?: string;
 }
 export interface ContextData {