claude-eidetic 0.1.0 → 0.1.2

package/dist/tool-schemas.d.ts

@@ -43,7 +43,7 @@ export declare const TOOL_DEFINITIONS: readonly [{
     };
 }, {
     readonly name: "search_code";
-    readonly description: "Search the indexed codebase using natural language queries.\n\nProvide either `path` (absolute) or `project` (name). Use `list_indexed` to see registered projects.\n\nWhen to Use:\n- Code search: Find specific functions, classes, or implementations\n- Context-aware assistance: Gather relevant code context before making changes\n- Issue identification: Locate problematic code sections or bugs\n- Code review: Understand existing implementations and patterns\n- Refactoring: Find all related code pieces that need to be updated\n- Feature development: Understand existing architecture and similar implementations\n- Duplicate detection: Identify redundant or duplicated code patterns\n\nIf the codebase is not indexed, this tool will return a clear error message indicating that indexing is required first.";
+    readonly description: "Search the indexed codebase using natural language queries.\nPrefer over Grep for conceptual/semantic queries — returns ~20 tokens/result vs ~100+ for Grep.\nTry before launching an Explore agent — faster and cheaper for understanding code.\n\nProvide either `path` (absolute) or `project` (name). Use `list_indexed` to see registered projects.\n\nWhen to Use:\n- Code search: Find specific functions, classes, or implementations\n- Context-aware assistance: Gather relevant code context before making changes\n- Issue identification: Locate problematic code sections or bugs\n- Code review: Understand existing implementations and patterns\n- Refactoring: Find all related code pieces that need to be updated\n- Feature development: Understand existing architecture and similar implementations\n- Duplicate detection: Identify redundant or duplicated code patterns\n\nIf the codebase is not indexed, this tool will return a clear error message indicating that indexing is required first.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -123,6 +123,256 @@ export declare const TOOL_DEFINITIONS: readonly [{
         readonly properties: {};
         readonly required: readonly [];
     };
+}, {
+    readonly name: "cleanup_vectors";
+    readonly description: "Remove orphaned vectors for files that no longer exist on disk. Lightweight alternative to re-indexing — no embedding cost.\n\nProvide either `path` (absolute) or `project` (name). Use `list_indexed` to see registered projects.\n\nUse `dryRun=true` first to preview which files would be cleaned without making any changes.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "Absolute path to the codebase directory.";
+            };
+            readonly project: {
+                readonly type: "string";
+                readonly description: "Project name (resolves via registry). Use list_indexed to see registered projects.";
+            };
+            readonly dryRun: {
+                readonly type: "boolean";
+                readonly description: "List files that would be cleaned without actually deleting any vectors.";
+                readonly default: false;
+            };
+        };
+        readonly required: readonly [];
+    };
+}, {
+    readonly name: "index_document";
+    readonly description: "Cache external documentation (from query-docs, WebFetch, etc.) for cheap semantic search later.\n\nAfter fetching documentation from an external source, call this tool to store it. Subsequent queries about the same library will use search_documents (~20 tokens/result) instead of re-fetching (~5K+ tokens).\n\nThe content is split into chunks, embedded, and stored in a vector collection grouped by library. A TTL tracks staleness — stale docs still return results but are flagged.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly content: {
+                readonly type: "string";
+                readonly description: "The full text content of the documentation to cache.";
+            };
+            readonly source: {
+                readonly type: "string";
+                readonly description: "Source URL or identifier (e.g., \"https://docs.langfuse.com/guides/evaluators\" or \"context7:langfuse/hooks\").";
+            };
+            readonly library: {
+                readonly type: "string";
+                readonly description: "Library name (e.g., \"react\", \"langfuse\"). Used for collection grouping.";
+            };
+            readonly topic: {
+                readonly type: "string";
+                readonly description: "Topic within the library (e.g., \"hooks\", \"evaluators\").";
+            };
+            readonly ttlDays: {
+                readonly type: "number";
+                readonly description: "Days before the cached content is considered stale.";
+                readonly default: 7;
+            };
+        };
+        readonly required: readonly ["content", "source", "library", "topic"];
+    };
+}, {
+    readonly name: "search_documents";
+    readonly description: "Search cached documentation using natural language queries.\n\nReturns results from previously cached documentation (via index_document). Much cheaper than re-fetching docs (~20 tokens/result vs ~5K+ tokens/fetch).\n\nIf a specific library is provided, searches only that library's collection. Otherwise searches across all cached documentation. Results include staleness indicators.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "Natural language query to search cached documentation.";
+            };
+            readonly library: {
+                readonly type: "string";
+                readonly description: "Optional: limit search to a specific library (e.g., \"langfuse\"). Omit to search all cached docs.";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Maximum number of results to return.";
+                readonly default: 5;
+                readonly maximum: 20;
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+}, {
+    readonly name: "read_file";
+    readonly description: "Read a file and return raw content without line-number overhead (~15-20% fewer tokens than built-in Read for code, more for short-line files).\n\nUse offset and limit to page through large files. Add lineNumbers=true only when you need line references for editing.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "Absolute file path to read.";
+            };
+            readonly offset: {
+                readonly type: "number";
+                readonly description: "1-based line number to start reading from.";
+                readonly default: 1;
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Maximum number of lines to return.";
+                readonly default: 5000;
+                readonly maximum: 10000;
+            };
+            readonly lineNumbers: {
+                readonly type: "boolean";
+                readonly description: "Prefix each line with its line number. Only enable when you need line references for editing.";
+                readonly default: false;
+            };
+        };
+        readonly required: readonly ["path"];
+    };
+}, {
+    readonly name: "add_memory";
+    readonly description: "Extract and store developer knowledge from text. Uses LLM to identify facts about coding style, tools, architecture, conventions, debugging insights, and workflow preferences. Automatically deduplicates against existing memories.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly content: {
+                readonly type: "string";
+                readonly description: "Text containing developer knowledge to extract and store (conversation snippets, notes, preferences).";
+            };
+            readonly source: {
+                readonly type: "string";
+                readonly description: "Optional source identifier (e.g., \"conversation\", \"claude-code\", \"user-note\").";
+            };
+        };
+        readonly required: readonly ["content"];
+    };
+}, {
+    readonly name: "search_memory";
+    readonly description: "Search stored developer memories using natural language. Returns semantically similar memories ranked by relevance.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "Natural language query to search memories.";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Maximum number of results.";
+                readonly default: 10;
+                readonly maximum: 50;
+            };
+            readonly category: {
+                readonly type: "string";
+                readonly description: "Filter by category: coding_style, tools, architecture, conventions, debugging, workflow, preferences.";
+                readonly enum: readonly ["coding_style", "tools", "architecture", "conventions", "debugging", "workflow", "preferences"];
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+}, {
+    readonly name: "list_memories";
+    readonly description: "List all stored developer memories, optionally filtered by category.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly category: {
+                readonly type: "string";
+                readonly description: "Filter by category: coding_style, tools, architecture, conventions, debugging, workflow, preferences.";
+                readonly enum: readonly ["coding_style", "tools", "architecture", "conventions", "debugging", "workflow", "preferences"];
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Maximum number of memories to return.";
+                readonly default: 50;
+                readonly maximum: 100;
+            };
+        };
+        readonly required: readonly [];
+    };
+}, {
+    readonly name: "delete_memory";
+    readonly description: "Delete a specific memory by its ID.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly id: {
+                readonly type: "string";
+                readonly description: "The UUID of the memory to delete.";
+            };
+        };
+        readonly required: readonly ["id"];
+    };
+}, {
+    readonly name: "memory_history";
+    readonly description: "View the change history for a specific memory (additions, updates, deletions).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly id: {
+                readonly type: "string";
+                readonly description: "The UUID of the memory to view history for.";
+            };
+        };
+        readonly required: readonly ["id"];
+    };
+}, {
+    readonly name: "browse_structure";
+    readonly description: "Show a condensed structural map of the indexed codebase — classes, functions, methods with signatures, grouped by file.\nPrefer over Glob + Read cascades for understanding architecture — one call vs many.\n\nProvide either `path` (absolute) or `project` (name). Use `list_indexed` to see registered projects.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "Absolute path to the codebase directory.";
+            };
+            readonly project: {
+                readonly type: "string";
+                readonly description: "Project name (resolves via registry). Use list_indexed to see registered projects.";
+            };
+            readonly pathFilter: {
+                readonly type: "string";
+                readonly description: "Glob pattern to filter by file path (e.g., \"src/core/**\", \"**/*.ts\").";
+            };
+            readonly kind: {
+                readonly type: "string";
+                readonly description: "Filter by symbol kind: function, class, interface, method, type, enum, etc.";
+            };
+            readonly maxTokens: {
+                readonly type: "number";
+                readonly description: "Approximate token budget for the output (1 token ≈ 4 chars). Default: 4000.";
+                readonly default: 4000;
+            };
+        };
+        readonly required: readonly [];
+    };
+}, {
+    readonly name: "list_symbols";
+    readonly description: "List symbols (functions, classes, methods, etc.) from the indexed codebase as a compact table. Supports filtering by name, kind, or path.\n\nProvide either `path` (absolute) or `project` (name). Use `list_indexed` to see registered projects.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "Absolute path to the codebase directory.";
+            };
+            readonly project: {
+                readonly type: "string";
+                readonly description: "Project name (resolves via registry). Use list_indexed to see registered projects.";
+            };
+            readonly pathFilter: {
+                readonly type: "string";
+                readonly description: "Glob pattern to filter by file path (e.g., \"src/core/**\").";
+            };
+            readonly kind: {
+                readonly type: "string";
+                readonly description: "Filter by symbol kind: function, class, interface, method, type, enum, etc.";
+            };
+            readonly nameFilter: {
+                readonly type: "string";
+                readonly description: "Substring filter on symbol name (case-insensitive).";
+            };
+        };
+        readonly required: readonly [];
+    };
 }, {
     readonly name: "__IMPORTANT";
     readonly description: "Workflow guidance for efficient code search. ALWAYS index before searching. Use project names after first index. Use extensionFilter to narrow results.";

package/dist/tool-schemas.js

@@ -1,3 +1,31 @@
+const READ_FILE_DESCRIPTION = `\
+Read a file and return raw content without line-number overhead (~15-20% fewer tokens than built-in Read for code, more for short-line files).
+
+Use offset and limit to page through large files. \
+Add lineNumbers=true only when you need line references for editing.`;
+const INDEX_DOCUMENT_DESCRIPTION = `\
+Cache external documentation (from query-docs, WebFetch, etc.) for cheap semantic search later.
+
+After fetching documentation from an external source, call this tool to store it. \
+Subsequent queries about the same library will use search_documents (~20 tokens/result) \
+instead of re-fetching (~5K+ tokens).
+
+The content is split into chunks, embedded, and stored in a vector collection grouped by library. \
+A TTL tracks staleness — stale docs still return results but are flagged.`;
+const SEARCH_DOCUMENTS_DESCRIPTION = `\
+Search cached documentation using natural language queries.
+
+Returns results from previously cached documentation (via index_document). \
+Much cheaper than re-fetching docs (~20 tokens/result vs ~5K+ tokens/fetch).
+
+If a specific library is provided, searches only that library's collection. \
+Otherwise searches across all cached documentation. Results include staleness indicators.`;
+const CLEANUP_DESCRIPTION = `\
+Remove orphaned vectors for files that no longer exist on disk. Lightweight alternative to re-indexing — no embedding cost.
+
+Provide either \`path\` (absolute) or \`project\` (name). Use \`list_indexed\` to see registered projects.
+
+Use \`dryRun=true\` first to preview which files would be cleaned without making any changes.`;
 const INDEX_DESCRIPTION = `\
 Index a codebase directory to enable semantic search using a configurable code splitter.
 
@@ -10,6 +38,8 @@ Usage Guidance:
 you MUST prompt the user to confirm whether to proceed with a force index.`;
 const SEARCH_DESCRIPTION = `\
 Search the indexed codebase using natural language queries.
+Prefer over Grep for conceptual/semantic queries — returns ~20 tokens/result vs ~100+ for Grep.
+Try before launching an Explore agent — faster and cheaper for understanding code.
 
 Provide either \`path\` (absolute) or \`project\` (name). Use \`list_indexed\` to see registered projects.
 
@@ -149,6 +179,283 @@ export const TOOL_DEFINITIONS = [
             required: [],
         },
     },
+    {
+        name: 'cleanup_vectors',
+        description: CLEANUP_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute path to the codebase directory.',
+                },
+                project: {
+                    type: 'string',
+                    description: 'Project name (resolves via registry). Use list_indexed to see registered projects.',
+                },
+                dryRun: {
+                    type: 'boolean',
+                    description: 'List files that would be cleaned without actually deleting any vectors.',
+                    default: false,
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'index_document',
+        description: INDEX_DOCUMENT_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                content: {
+                    type: 'string',
+                    description: 'The full text content of the documentation to cache.',
+                },
+                source: {
+                    type: 'string',
+                    description: 'Source URL or identifier (e.g., "https://docs.langfuse.com/guides/evaluators" or "context7:langfuse/hooks").',
+                },
+                library: {
+                    type: 'string',
+                    description: 'Library name (e.g., "react", "langfuse"). Used for collection grouping.',
+                },
+                topic: {
+                    type: 'string',
+                    description: 'Topic within the library (e.g., "hooks", "evaluators").',
+                },
+                ttlDays: {
+                    type: 'number',
+                    description: 'Days before the cached content is considered stale.',
+                    default: 7,
+                },
+            },
+            required: ['content', 'source', 'library', 'topic'],
+        },
+    },
+    {
+        name: 'search_documents',
+        description: SEARCH_DOCUMENTS_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Natural language query to search cached documentation.',
+                },
+                library: {
+                    type: 'string',
+                    description: 'Optional: limit search to a specific library (e.g., "langfuse"). Omit to search all cached docs.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of results to return.',
+                    default: 5,
+                    maximum: 20,
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'read_file',
+        description: READ_FILE_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute file path to read.',
+                },
+                offset: {
+                    type: 'number',
+                    description: '1-based line number to start reading from.',
+                    default: 1,
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of lines to return.',
+                    default: 5000,
+                    maximum: 10000,
+                },
+                lineNumbers: {
+                    type: 'boolean',
+                    description: 'Prefix each line with its line number. Only enable when you need line references for editing.',
+                    default: false,
+                },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'add_memory',
+        description: 'Extract and store developer knowledge from text. Uses LLM to identify facts about coding style, tools, architecture, conventions, debugging insights, and workflow preferences. Automatically deduplicates against existing memories.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                content: {
+                    type: 'string',
+                    description: 'Text containing developer knowledge to extract and store (conversation snippets, notes, preferences).',
+                },
+                source: {
+                    type: 'string',
+                    description: 'Optional source identifier (e.g., "conversation", "claude-code", "user-note").',
+                },
+            },
+            required: ['content'],
+        },
+    },
+    {
+        name: 'search_memory',
+        description: 'Search stored developer memories using natural language. Returns semantically similar memories ranked by relevance.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Natural language query to search memories.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of results.',
+                    default: 10,
+                    maximum: 50,
+                },
+                category: {
+                    type: 'string',
+                    description: 'Filter by category: coding_style, tools, architecture, conventions, debugging, workflow, preferences.',
+                    enum: [
+                        'coding_style',
+                        'tools',
+                        'architecture',
+                        'conventions',
+                        'debugging',
+                        'workflow',
+                        'preferences',
+                    ],
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'list_memories',
+        description: 'List all stored developer memories, optionally filtered by category.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                category: {
+                    type: 'string',
+                    description: 'Filter by category: coding_style, tools, architecture, conventions, debugging, workflow, preferences.',
+                    enum: [
+                        'coding_style',
+                        'tools',
+                        'architecture',
+                        'conventions',
+                        'debugging',
+                        'workflow',
+                        'preferences',
+                    ],
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of memories to return.',
+                    default: 50,
+                    maximum: 100,
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'delete_memory',
+        description: 'Delete a specific memory by its ID.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'The UUID of the memory to delete.',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'memory_history',
+        description: 'View the change history for a specific memory (additions, updates, deletions).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'The UUID of the memory to view history for.',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'browse_structure',
+        description: 'Show a condensed structural map of the indexed codebase — classes, functions, methods with signatures, grouped by file.\nPrefer over Glob + Read cascades for understanding architecture — one call vs many.\n\nProvide either `path` (absolute) or `project` (name). Use `list_indexed` to see registered projects.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute path to the codebase directory.',
+                },
+                project: {
+                    type: 'string',
+                    description: 'Project name (resolves via registry). Use list_indexed to see registered projects.',
+                },
+                pathFilter: {
+                    type: 'string',
+                    description: 'Glob pattern to filter by file path (e.g., "src/core/**", "**/*.ts").',
+                },
+                kind: {
+                    type: 'string',
+                    description: 'Filter by symbol kind: function, class, interface, method, type, enum, etc.',
+                },
+                maxTokens: {
+                    type: 'number',
+                    description: 'Approximate token budget for the output (1 token ≈ 4 chars). Default: 4000.',
+                    default: 4000,
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'list_symbols',
+        description: 'List symbols (functions, classes, methods, etc.) from the indexed codebase as a compact table. Supports filtering by name, kind, or path.\n\nProvide either `path` (absolute) or `project` (name). Use `list_indexed` to see registered projects.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute path to the codebase directory.',
+                },
+                project: {
+                    type: 'string',
+                    description: 'Project name (resolves via registry). Use list_indexed to see registered projects.',
+                },
+                pathFilter: {
+                    type: 'string',
+                    description: 'Glob pattern to filter by file path (e.g., "src/core/**").',
+                },
+                kind: {
+                    type: 'string',
+                    description: 'Filter by symbol kind: function, class, interface, method, type, enum, etc.',
+                },
+                nameFilter: {
+                    type: 'string',
+                    description: 'Substring filter on symbol name (case-insensitive).',
+                },
+            },
+            required: [],
+        },
+    },
     {
         name: '__IMPORTANT',
         description: 'Workflow guidance for efficient code search. ALWAYS index before searching. Use project names after first index. Use extensionFilter to narrow results.',

package/dist/tools.d.ts

@@ -1,11 +1,14 @@
 import { StateManager } from './state/snapshot.js';
 import type { Embedding } from './embedding/types.js';
 import type { VectorDB } from './vectordb/types.js';
+import type { MemoryStore } from './memory/store.js';
 export declare class ToolHandlers {
     private embedding;
     private vectordb;
     private state;
+    private memoryStore;
     constructor(embedding: Embedding, vectordb: VectorDB, state: StateManager);
+    setMemoryStore(store: MemoryStore): void;
     handleIndexCodebase(args: Record<string, unknown>): Promise<{
         content: {
             type: string;
@@ -36,5 +39,71 @@ export declare class ToolHandlers {
             text: string;
         }[];
     }>;
+    handleCleanupVectors(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleIndexDocument(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleSearchDocuments(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleAddMemory(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleSearchMemory(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleListMemories(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleDeleteMemory(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleMemoryHistory(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleBrowseStructure(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleListSymbols(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
 }
+export declare function handleReadFile(args: Record<string, unknown>): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;
 //# sourceMappingURL=tools.d.ts.map