index
Refresh the search index for Claude Code conversations to ensure accurate results. Choose incremental updates for new sessions or full rebuilds when needed.
Instructions
Update the search index with recent Claude Code sessions. Call if search returns stale results or the user asks to refresh the index. Modes: 'incremental' (default, only new/changed), 'full' (delete all and rebuild from scratch), 'cancel' (stop running index).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| project | No | ||
| confirm | No |
Implementation Reference
- src/tools/index-tool.ts:134-264 (handler)Main tool handler function that triggers the background indexing process.
export async function handleIndex( db: Database.Database, params: IndexParams ): Promise<{ content: Array<{ type: string; text: string }> }> { // Full reindex requires explicit confirmation (safety gate) if (params.mode === "full" && !params.confirm) { return { content: [{ type: "text", text: JSON.stringify({ status: "confirmation_required", message: "Full reindex will delete ALL indexed data and rebuild from scratch. This can take several minutes. To proceed, call index with mode 'full' and confirm set to true.", }), }], }; } // Cancel running indexing if (params.mode === "cancel") { if (!progress.running) { return { content: [{ type: "text", text: JSON.stringify({ status: "ok", message: "No indexing in progress." }) }] }; } cancelRequested = true; return { content: [{ type: "text", text: JSON.stringify({ status: "ok", message: "Cancellation requested. Indexing will stop after current session completes." }) }] }; } if (progress.running) { return { content: [{ type: "text", text: JSON.stringify({ status: "already_running", ...getIndexProgress(), elapsed_ms: Date.now() - progress.startedAt, message: `Indexing in progress: ${progress.sessionsIndexed}/${progress.sessionsTotal} sessions. Use list_sessions or search while waiting.`, }), }], }; } const loreDir = process.env.LORE_DIR ?? CONFIG.loreDir; const projectsBaseDir = process.env.CLAUDE_PROJECTS_DIR ?? CONFIG.claudeProjectsDir; if (!acquireLock(loreDir)) { return { content: [{ type: "text", text: JSON.stringify({ status: "locked", message: "Another indexing process is running. Check status with list_sessions.", }), }], }; } // Determine which projects to index: // 1. If params.project specified → only that project (overrides config) // 2. Else if config.indexed_projects is non-empty → only registered projects // 3. Else → nothing (user must register projects first) const allProjects = scanProjects(projectsBaseDir); const userConfig = loadUserConfig(); let projectsToIndex = allProjects; if (params.project) { // Explicit project filter — overrides config projectsToIndex = allProjects.filter( (p) => p.name.toLowerCase().includes(params.project!.toLowerCase()) || p.dirName.toLowerCase().includes(params.project!.toLowerCase()) ); } else if (userConfig.indexed_projects.length > 0) { // Config-based filter const registered = new Set(userConfig.indexed_projects); projectsToIndex = allProjects.filter((p) => registered.has(p.dirName)); } else { // No config, no param — show guidance releaseLock(loreDir); return { content: [{ type: "text", text: JSON.stringify({ status: "no_projects_registered", total_projects_on_disk: allProjects.length, message: "No projects are registered for indexing. Use manage_projects with action 'list' to see available projects, then 'add' to register the ones you want to index.", }), }], }; } let totalSessions = 0; const projectSessions: Array<{ project: typeof allProjects[0]; sessions: ReturnType<typeof scanSessions> }> = []; for (const project of projectsToIndex) { const sessions = scanSessions(project.dirPath); totalSessions += sessions.length; projectSessions.push({ project, sessions }); } // Reset progress progress.running = true; progress.sessionsScanned = 0; progress.sessionsIndexed = 0; progress.sessionsSkipped = 0; progress.sessionsTotal = totalSessions; progress.chunksCreated = 0; progress.currentProject = ""; progress.startedAt = Date.now(); progress.completedAt = null; progress.error = null; progress.skipReasons = { no_parseable_content: 0, empty_file: 0, read_error: 0, no_chunks_after_processing: 0 }; // Return immediately, run indexing in background runIndexInBackground(db, params, projectSessions, loreDir).catch((err) => { progress.error = String(err); progress.running = false; releaseLock(loreDir); }); return { content: [{ type: "text", text: JSON.stringify({ status: "started", sessions_found: totalSessions, projects_found: projectSessions.length, message: `Indexing started for ${totalSessions} sessions across ${projectSessions.length} projects. Use list_sessions to check progress. You can search while indexing proceeds.`, }), }], }; } - src/tools/index-tool.ts:268-442 (handler)The actual background implementation that processes sessions, chunks, and embeddings.
async function runIndexInBackground( db: Database.Database, params: IndexParams, projectSessions: Array<{ project: { dirName: string; dirPath: string; name: string }; sessions: Array<{ sessionId: string; jsonlPath: string; size: number; mtime: number }> }>, loreDir: string, ): Promise<void> { const forceMode = params.mode ?? "incremental"; try { const embedder = await getEmbedder(); for (const { project, sessions } of projectSessions) { progress.currentProject = project.name; const projectId = upsertProject(db, { dir_name: project.dirName, path: project.dirPath, name: project.name, }); for (const sessionInfo of sessions) { // Check for cancellation between sessions if (cancelRequested) { cancelRequested = false; progress.error = "Cancelled by user"; return; } progress.sessionsScanned++; const existingSession = db .prepare("SELECT * FROM sessions WHERE session_id = ?") .get(sessionInfo.sessionId) as SessionRow | undefined; const existingSize = existingSession?.jsonl_size ?? null; const existingMtime = existingSession?.jsonl_mtime ?? null; const existingOffset = existingSession?.indexed_offset ?? 0; let reindexStrategy = needsReindex( sessionInfo, existingSize, existingMtime, existingOffset ); if (forceMode === "full") { reindexStrategy = "full"; } if (reindexStrategy === "skip") { progress.sessionsSkipped++; continue; } const sessionDbId = upsertSession(db, { project_id: projectId, session_id: sessionInfo.sessionId, jsonl_path: sessionInfo.jsonlPath, jsonl_size: sessionInfo.size, jsonl_mtime: sessionInfo.mtime, }); let readOffset = existingOffset; if (reindexStrategy === "full") { deleteSessionChunks(db, sessionDbId); readOffset = 0; } let lines: string[]; try { lines = readJsonlFromOffset(sessionInfo.jsonlPath, readOffset); } catch { progress.sessionsSkipped++; progress.skipReasons.read_error++; continue; } if (lines.length === 0) { progress.sessionsSkipped++; progress.skipReasons.empty_file++; continue; } const records = lines.map((line) => parseLine(line)).filter((r) => r !== null); if (records.length === 0) { progress.sessionsSkipped++; progress.skipReasons.no_parseable_content++; continue; } // Extract metadata let intent: string | null = null; let branch: string | null = null; let model: string | null = null; let startedAt: string | null = null; let endedAt: string | null = null; for (const record of records) { if (record.timestamp) { if (!startedAt) startedAt = record.timestamp; endedAt = record.timestamp; } if (intent === null && record.type === "user" && !record.isToolResult && record.text) { intent = record.text.slice(0, 200); } if (branch === null && record.gitBranch) branch = record.gitBranch; if (model === null && record.model) model = record.model; } const turns = groupIntoLogicalTurns(records); const chunks = chunkTurns(turns, CONFIG.maxChunkTokens, CONFIG.shortTurnThreshold); if (chunks.length === 0) { progress.sessionsSkipped++; progress.skipReasons.no_chunks_after_processing++; continue; } const textsToEmbed = chunks.map((chunk) => `passage: ${chunk.content}`); progress.currentSessionChunks = 0; progress.currentSessionTotal = chunks.length; const embeddings = await embedder.embedBatch(textsToEmbed, (done) => { progress.currentSessionChunks = done; }); let chunkIndexOffset = 0; if (reindexStrategy === "append" && existingSession) { const maxChunkRow = db .prepare("SELECT MAX(chunk_index) as max_idx FROM chunks WHERE session_id = ?") .get(sessionDbId) as { max_idx: number | null }; chunkIndexOffset = (maxChunkRow.max_idx ?? -1) + 1; } const insertAllChunks = db.transaction(() => { for (let i = 0; i < chunks.length; i++) { insertChunkWithVector(db, { session_id: sessionDbId, chunk_index: chunkIndexOffset + i, role: chunks[i].role, content: chunks[i].content, timestamp: chunks[i].timestamp || null, turn_start: chunks[i].turnStart, turn_end: chunks[i].turnEnd, token_count: chunks[i].tokenCount, embedding: embeddings[i], }); progress.chunksCreated++; } }); insertAllChunks(); const newOffset = statSync(sessionInfo.jsonlPath).size; updateSessionMetadata(db, { session_id: sessionDbId, indexed_offset: newOffset, indexed_at: new Date().toISOString(), turn_count: turns.length, started_at: startedAt, ended_at: endedAt, branch, model, intent, jsonl_size: sessionInfo.size, jsonl_mtime: sessionInfo.mtime, }); progress.sessionsIndexed++; } } } finally { progress.running = false; progress.completedAt = Date.now(); releaseLock(loreDir); } } - src/server.ts:66-82 (registration)Tool registration for "index" in the McpServer.
// index tool — description intentionally omits "confirm" param to force user approval for full reindex server.tool( "index", "Update the search index with recent Claude Code sessions. Call if search returns stale results or the user asks to refresh the index. Modes: 'incremental' (default, only new/changed), 'full' (delete all and rebuild from scratch), 'cancel' (stop running index).", { mode: z.enum(["incremental", "full", "cancel"]).optional(), project: z.string().optional(), confirm: z.boolean().optional(), }, async (args): Promise<ToolResult> => { return handleIndex(db, { mode: args.mode, project: args.project, confirm: args.confirm, }); } );