lore

Instructions

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,
      });
    }
  );