claude-eidetic 0.1.4 → 2026.304.1730

package/README.md

@@ -1,5 +1,10 @@
-# claude-eidetic
-
+```
+┌─────────────────────────────────────────────┐
+│  ╔═╗╦╔╦╗╔═╗╔╦╗╦╔═╗                         │
+│  ║╣ ║ ║║║╣  ║ ║║    semantic code search    │
+│  ╚═╝╩═╩╝╚═╝ ╩ ╩╚═╝  for Claude Code        │
+└─────────────────────────────────────────────┘
+```
 
 [![tests](https://img.shields.io/github/actions/workflow/status/eidetics/claude-eidetic/ci.yml?style=flat-square&label=tests)](https://github.com/eidetics/claude-eidetic/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/claude-eidetic)](https://www.npmjs.com/package/claude-eidetic)
@@ -9,7 +14,7 @@ Semantic code search, persistent memory, and session continuity for Claude Code.
 
 ---
 
-## 🚀 Quick Start
+## Quick Start
 
 ```bash
 claude plugin install eidetics/claude-eidetic
@@ -28,9 +33,9 @@ search_code("how does authentication work")
 
 ---
 
-## ✨ Features
+## Features
 
-### 🔍 Semantic Code Search
+### Semantic Code Search
 
 **Find code by meaning, not keywords.** Search across your entire codebase with natural language, returning the most relevant functions and classes, not a list of files to read.
 
@@ -40,7 +45,7 @@ search_code("authentication middleware", extensionFilter=[".ts"])
 search_code(project="backend", query="auth flow")
 ```
 
-### 🏗️ Architecture at a Glance
+### Architecture at a Glance
 
 **Get every class, function, and method in one call.** `browse_structure` returns a condensed map of your codebase with signatures, grouped by file, replacing a Glob + Read cascade with a single tool call.
 
@@ -49,7 +54,7 @@ browse_structure(path="/my/project", kind="class")
 list_symbols(path="/my/project", nameFilter="handle")
 ```
 
-### 📚 Documentation Cache
+### Documentation Cache
 
 **Fetch docs once, search them forever.** Cache external documentation as searchable embeddings. Retrieve relevant passages instantly, far cheaper than re-fetching the same page each session.
 
@@ -58,7 +63,7 @@ index_document(content=..., library="react", topic="hooks", source="https://..."
 search_documents("React useCallback dependencies", library="react")
 ```
 
-### 🧠 Persistent Memory
+### Persistent Memory
 
 **Claude remembers your preferences between sessions.** `add_memory` uses an LLM to extract structured facts from conversation text (coding style, architecture decisions, debugging insights) and deduplicates them semantically. Not a static config file you forget to update.
 
@@ -67,11 +72,11 @@ add_memory("Always use absolute imports, never relative")
 search_memory("how does this team handle errors")
 ```
 
-### 🔄 Session Continuity
+### Session Continuity
 
 **Every session picks up where the last one left off.** When a session ends (or context compacts mid-session), Eidetic automatically writes a structured note capturing files changed, tasks, commands, and decisions. `/catchup` at the start of a new session reconstructs exactly where you were. No user action required.
 
-### 👻 Invisible Optimizations
+### Invisible Optimizations
 
 Eight hook events fire automatically, nudging toward cheaper tools, redirecting file reads for 15-20% token savings, tracking changed files, and saving session state on exit.
 
@@ -93,7 +98,7 @@ Eight hook events fire automatically, nudging toward cheaper tools, redirecting
 
 ---
 
-## 🗺️ When to Use What
+## When to Use What
 
 | Need | Use | Notes |
 |---|---|---|
@@ -107,7 +112,7 @@ Eight hook events fire automatically, nudging toward cheaper tools, redirecting
 
 ---
 
-## 📖 Skills Reference
+## Skills Reference
 
 | Skill | What it does |
 |---|---|
@@ -120,7 +125,7 @@ Eight hook events fire automatically, nudging toward cheaper tools, redirecting
 ---
 
 <details>
-<summary><strong>🔥 Why does this exist? (The Problem)</strong></summary>
+<summary><strong>Why does this exist? (The Problem)</strong></summary>
 
 Every new Claude Code session starts cold. You re-explain the architecture. You re-fetch the same docs. Claude reads the same files repeatedly, burning tokens just to get back to where you were.
 
@@ -135,7 +140,7 @@ Every new Claude Code session starts cold. You re-explain the architecture. You
 
 ---
 
-## 📦 Installation
+## Installation
 
 ### Plugin (recommended)
 
@@ -145,6 +150,9 @@ claude plugin install eidetics/claude-eidetic
 
 The plugin auto-starts the MCP server, installs skills, and configures hooks.
 
+<details>
+<summary><strong>Alternative installation methods</strong></summary>
+
 ### npx (manual MCP config)
 
 Add to your `.mcp.json`:
@@ -177,6 +185,8 @@ cd claude-eidetic
 npm install && npx tsc && npm start
 ```
 
+</details>
+
 ### Requirements
 
 - Node.js >= 20.0.0
@@ -186,7 +196,7 @@ npm install && npx tsc && npm start
 
 ---
 
-## ⚙️ Configuration
+## Configuration
 
 All configuration is via environment variables. No config files.
 
@@ -223,10 +233,57 @@ export MEMORY_LLM_PROVIDER=ollama
 
 ---
 
+## Troubleshooting
+
+### `OPENAI_API_KEY` not set
+
+Eidetic needs an embedding API key. Set it in your shell profile:
+
+```bash
+export OPENAI_API_KEY=sk-...   # macOS/Linux
+setx OPENAI_API_KEY sk-...     # Windows
+```
+
+Or use Ollama for free local embeddings: `export EMBEDDING_PROVIDER=ollama`
+
+### Docker not installed (Qdrant can't auto-provision)
+
+Eidetic auto-provisions Qdrant via Docker. If Docker isn't installed:
+- **Option A:** Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and retry
+- **Option B:** Run Qdrant manually and set `QDRANT_URL` to point to it
+
+### Qdrant unreachable at custom URL
+
+If you set `QDRANT_URL` to a remote instance, verify it's reachable:
+
+```bash
+curl http://your-qdrant-host:6333/healthz
+```
+
+### Tree-sitter native build fails on Windows
+
+Tree-sitter requires C/C++ build tools. Install them:
+
+```bash
+npm install -g windows-build-tools   # or install Visual Studio Build Tools
+```
+
+If the build still fails, Eidetic falls back to line-based chunking (works, but less precise).
+
+### Ollama model not pulled
+
+If using `EMBEDDING_PROVIDER=ollama`, ensure the model is available:
+
+```bash
+ollama pull nomic-embed-text
+```
+
+---
+
 <details>
-<summary><strong>🔧 Tool Reference</strong></summary>
+<summary><strong>Tool Reference</strong></summary>
 
-### 🔍 Code Search
+### Code Search
 
 | Tool | Description |
 |---|---|
@@ -239,20 +296,20 @@ export MEMORY_LLM_PROVIDER=ollama
 | `browse_structure` | Condensed structural map: classes, functions, methods with signatures, grouped by file. |
 | `list_symbols` | Compact symbol table with name/kind/file/line. Supports name, kind, and path filters. |
 
-### 📄 File Reading
+### File Reading
 
 | Tool | Description |
 |---|---|
 | `read_file` | Read file without line-number overhead. Cheaper than built-in Read for code files. |
 
-### 📚 Documentation Cache
+### Documentation Cache
 
 | Tool | Description |
 |---|---|
 | `index_document` | Cache external documentation for semantic search. Supports TTL for staleness tracking. |
 | `search_documents` | Search cached docs. Far cheaper than re-fetching the same page. |
 
-### 🧠 Memory
+### Memory
 
 | Tool | Description |
 |---|---|
@@ -266,7 +323,7 @@ export MEMORY_LLM_PROVIDER=ollama
 
 ---
 
-## 🌐 Supported Languages
+## Supported Languages
 
 **AST-aware** (functions and classes chunked intact):
 
@@ -298,7 +355,7 @@ export MEMORY_LLM_PROVIDER=ollama
 
 ---
 
-## 🛠️ Development
+## Development
 
 ```bash
 npm install && npx tsc    # install and build
@@ -313,12 +370,12 @@ Scopes: `embedding`, `vectordb`, `splitter`, `indexer`, `mcp`, `infra`, `config`
 
 ---
 
-## 🙏 Acknowledgements
+## Acknowledgements
 
 Heavily inspired by [mem0](https://github.com/mem0ai/mem0), [claude-mem](https://github.com/thedotmack/claude-mem), and [claude-context](https://github.com/zilliztech/claude-context). Documentation retrieval powered by [context7](https://github.com/upstash/context7).
 
 ---
 
-## 📄 License
+## License
 
 MIT

package/dist/build-info.d.ts

@@ -0,0 +1,3 @@
+export declare const BUILD_VERSION: "2026.304.1730";
+export declare const BUILD_TIMESTAMP: "2026-03-04T17:30:09.498Z";
+//# sourceMappingURL=build-info.d.ts.map

package/dist/build-info.js

@@ -0,0 +1,4 @@
+// Auto-generated by scripts/generate-build-info.ts — do not edit
+export const BUILD_VERSION = '2026.304.1730';
+export const BUILD_TIMESTAMP = '2026-03-04T17:30:09.498Z';
+//# sourceMappingURL=build-info.js.map

package/dist/config.d.ts

@@ -15,6 +15,9 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     eideticDataDir: z.ZodDefault<z.ZodString>;
     customExtensions: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], unknown>;
     customIgnorePatterns: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], unknown>;
+    raptorEnabled: z.ZodEffects<z.ZodDefault<z.ZodBoolean>, boolean, unknown>;
+    raptorTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    raptorLlmModel: z.ZodDefault<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     embeddingProvider: "openai" | "ollama" | "local";
     openaiApiKey: string;
@@ -27,6 +30,9 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     eideticDataDir: string;
     customExtensions: string[];
     customIgnorePatterns: string[];
+    raptorEnabled: boolean;
+    raptorTimeoutMs: number;
+    raptorLlmModel: string;
     openaiBaseUrl?: string | undefined;
     embeddingModel?: string | undefined;
     qdrantApiKey?: string | undefined;
@@ -47,6 +53,9 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     eideticDataDir?: string | undefined;
     customExtensions?: unknown;
     customIgnorePatterns?: unknown;
+    raptorEnabled?: unknown;
+    raptorTimeoutMs?: number | undefined;
+    raptorLlmModel?: string | undefined;
 }>, {
     embeddingModel: string;
     embeddingProvider: "openai" | "ollama" | "local";
@@ -60,6 +69,9 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     eideticDataDir: string;
     customExtensions: string[];
     customIgnorePatterns: string[];
+    raptorEnabled: boolean;
+    raptorTimeoutMs: number;
+    raptorLlmModel: string;
     openaiBaseUrl?: string | undefined;
     qdrantApiKey?: string | undefined;
     milvusToken?: string | undefined;
@@ -79,6 +91,9 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     eideticDataDir?: string | undefined;
     customExtensions?: unknown;
     customIgnorePatterns?: unknown;
+    raptorEnabled?: unknown;
+    raptorTimeoutMs?: number | undefined;
+    raptorLlmModel?: string | undefined;
 }>;
 export type Config = z.infer<typeof configSchema>;
 export declare function loadConfig(): Config;

package/dist/config.js

@@ -19,6 +19,9 @@ const configSchema = z
     eideticDataDir: z.string().default(path.join(os.homedir(), '.eidetic')),
     customExtensions: z.preprocess((val) => (typeof val === 'string' ? JSON.parse(val) : val), z.array(z.string()).default([])),
     customIgnorePatterns: z.preprocess((val) => (typeof val === 'string' ? JSON.parse(val) : val), z.array(z.string()).default([])),
+    raptorEnabled: z.preprocess((val) => (val === 'false' ? false : val === 'true' ? true : val), z.boolean().default(true)),
+    raptorTimeoutMs: z.coerce.number().int().min(1000).default(60000),
+    raptorLlmModel: z.string().default('gpt-4o-mini'),
 })
     .transform((cfg) => ({
     ...cfg,
@@ -31,19 +34,22 @@ export function loadConfig() {
     const raw = {
         embeddingProvider: process.env.EMBEDDING_PROVIDER,
         openaiApiKey: (process.env.OPENAI_API_KEY ?? '').trim().replace(/^["']|["']$/g, ''),
-        openaiBaseUrl: process.env.OPENAI_BASE_URL || undefined,
+        openaiBaseUrl: process.env.OPENAI_BASE_URL?.trim() ?? undefined,
         ollamaBaseUrl: process.env.OLLAMA_BASE_URL,
-        embeddingModel: process.env.EMBEDDING_MODEL || undefined,
+        embeddingModel: process.env.EMBEDDING_MODEL?.trim() ?? undefined,
         embeddingBatchSize: process.env.EMBEDDING_BATCH_SIZE,
         indexingConcurrency: process.env.INDEXING_CONCURRENCY,
         qdrantUrl: process.env.QDRANT_URL,
-        qdrantApiKey: process.env.QDRANT_API_KEY?.trim().replace(/^["']|["']$/g, '') || undefined,
+        qdrantApiKey: process.env.QDRANT_API_KEY?.trim().replace(/^["']|["']$/g, '') ?? undefined,
         vectordbProvider: process.env.VECTORDB_PROVIDER,
         milvusAddress: process.env.MILVUS_ADDRESS,
-        milvusToken: process.env.MILVUS_TOKEN?.trim().replace(/^["']|["']$/g, '') || undefined,
+        milvusToken: process.env.MILVUS_TOKEN?.trim().replace(/^["']|["']$/g, '') ?? undefined,
         eideticDataDir: process.env.EIDETIC_DATA_DIR,
         customExtensions: process.env.CUSTOM_EXTENSIONS,
         customIgnorePatterns: process.env.CUSTOM_IGNORE_PATTERNS,
+        raptorEnabled: process.env.RAPTOR_ENABLED,
+        raptorTimeoutMs: process.env.RAPTOR_TIMEOUT_MS,
+        raptorLlmModel: process.env.RAPTOR_LLM_MODEL,
     };
     const result = configSchema.safeParse(raw);
     if (!result.success) {

package/dist/core/global-concepts.d.ts

@@ -0,0 +1,8 @@
+import type { Embedding } from '../embedding/types.js';
+import type { VectorDB } from '../vectordb/types.js';
+/**
+ * Replicate knowledge summaries from a project's knowledge collection
+ * to the global concepts collection, tagged with the project name.
+ */
+export declare function replicateToGlobalConcepts(project: string, knowledgeCollectionName: string, embedding: Embedding, vectordb: VectorDB): Promise<number>;
+//# sourceMappingURL=global-concepts.d.ts.map

package/dist/core/global-concepts.js

@@ -0,0 +1,38 @@
+import { randomUUID } from 'node:crypto';
+import { globalConceptsCollectionName } from '../paths.js';
+/**
+ * Replicate knowledge summaries from a project's knowledge collection
+ * to the global concepts collection, tagged with the project name.
+ */
+export async function replicateToGlobalConcepts(project, knowledgeCollectionName, embedding, vectordb) {
+    const globalCol = globalConceptsCollectionName();
+    // Ensure global collection exists
+    if (!(await vectordb.hasCollection(globalCol))) {
+        await vectordb.createCollection(globalCol, embedding.dimension);
+    }
+    // Scroll all knowledge points
+    const points = await vectordb.scrollAll(knowledgeCollectionName);
+    if (points.length === 0)
+        return 0;
+    // Clean up stale entries for this project
+    await vectordb.deleteByFilter(globalCol, { project });
+    // Upsert knowledge points into global collection
+    let replicated = 0;
+    for (const point of points) {
+        const id = randomUUID();
+        await vectordb.updatePoint(globalCol, id, point.vector, {
+            ...point.payload,
+            content: typeof point.payload.content === 'string' ? point.payload.content : '',
+            relativePath: id,
+            startLine: 0,
+            endLine: 0,
+            fileExtension: 'knowledge',
+            language: 'summary',
+            project,
+            source: 'raptor',
+        });
+        replicated++;
+    }
+    return replicated;
+}
+//# sourceMappingURL=global-concepts.js.map

package/dist/core/indexer.js

@@ -158,8 +158,20 @@ export async function indexCodebase(rootPath, embedding, vectordb, force = false
         await vectordb.insert(collectionName, documents);
         processedChunks += batch.length;
     }
-    onProgress?.(98, 'Saving snapshot...');
+    onProgress?.(95, 'Saving snapshot...');
     saveSnapshot(normalizedPath, currentSnapshot);
+    // Run RAPTOR knowledge generation (non-fatal)
+    if (config.raptorEnabled) {
+        try {
+            onProgress?.(97, 'Generating knowledge summaries...');
+            const projectName = path.basename(normalizedPath);
+            const { runRaptor } = await import('./raptor.js');
+            await runRaptor(projectName, collectionName, embedding, vectordb);
+        }
+        catch (err) {
+            console.warn(`RAPTOR knowledge generation failed (non-fatal): ${String(err)}`);
+        }
+    }
     onProgress?.(100, 'Done');
     return {
         totalFiles: filePaths.length,

package/dist/core/raptor-cache.d.ts

@@ -0,0 +1,6 @@
+export declare function getCachedSummary(clusterHash: string): string | null;
+export declare function setCachedSummary(clusterHash: string, summary: string, project: string, level?: number): void;
+export declare function clearProjectCache(project: string): void;
+/** Reset the module-level DB connection (for testing). */
+export declare function _resetDb(): void;
+//# sourceMappingURL=raptor-cache.d.ts.map

package/dist/core/raptor-cache.js

@@ -0,0 +1,45 @@
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { getRaptorDbPath } from '../paths.js';
+let db = null;
+function getDb() {
+    if (db)
+        return db;
+    const dbPath = getRaptorDbPath();
+    mkdirSync(dirname(dbPath), { recursive: true });
+    db = new Database(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS raptor_clusters (
+      cluster_hash TEXT PRIMARY KEY,
+      summary TEXT NOT NULL,
+      project TEXT NOT NULL,
+      level INTEGER NOT NULL DEFAULT 0,
+      updated_at TEXT NOT NULL
+    )
+  `);
+    return db;
+}
+export function getCachedSummary(clusterHash) {
+    const row = getDb()
+        .prepare('SELECT summary FROM raptor_clusters WHERE cluster_hash = ?')
+        .get(clusterHash);
+    return row?.summary ?? null;
+}
+export function setCachedSummary(clusterHash, summary, project, level = 0) {
+    getDb()
+        .prepare('INSERT OR REPLACE INTO raptor_clusters (cluster_hash, summary, project, level, updated_at) VALUES (?, ?, ?, ?, ?)')
+        .run(clusterHash, summary, project, level, new Date().toISOString());
+}
+export function clearProjectCache(project) {
+    getDb().prepare('DELETE FROM raptor_clusters WHERE project = ?').run(project);
+}
+/** Reset the module-level DB connection (for testing). */
+export function _resetDb() {
+    if (db) {
+        db.close();
+        db = null;
+    }
+}
+//# sourceMappingURL=raptor-cache.js.map

package/dist/core/raptor.d.ts

@@ -0,0 +1,31 @@
+import type { Embedding } from '../embedding/types.js';
+import type { VectorDB } from '../vectordb/types.js';
+export interface RaptorResult {
+    clustersProcessed: number;
+    summariesGenerated: number;
+    cached: number;
+    timedOut: boolean;
+}
+interface Point {
+    id: string | number;
+    vector: number[];
+    content: string;
+}
+/**
+ * Run RAPTOR knowledge generation: cluster code chunks, summarize each cluster,
+ * store summaries in the knowledge collection.
+ */
+export declare function runRaptor(project: string, codeCollectionName: string, embedding: Embedding, vectordb: VectorDB, options?: {
+    timeoutMs?: number;
+    llmModel?: string;
+    summarize?: LlmSummarizer;
+}): Promise<RaptorResult>;
+export type LlmSummarizer = (content: string, model: string, apiKey: string) => Promise<string>;
+/**
+ * K-means clustering (Lloyd's algorithm).
+ * Returns an array of clusters, each containing the points assigned to it.
+ */
+export declare function kMeans(points: Point[], k: number, maxIter?: number): Point[][];
+export declare function clusterHash(memberIds: string[]): string;
+export {};
+//# sourceMappingURL=raptor.d.ts.map