lore

Instructions

Implementation Reference

• src/tools/status.ts:6-69 (handler)

  The handleStatus function implements the core logic for the "status" tool, retrieving indexing progress and database statistics.

  export async function handleStatus(
    db: Database.Database
  ): Promise<{ content: Array<{ type: string; text: string }> }> {
    const progress = getIndexProgress();
  
    const totalSessions = (db.prepare("SELECT COUNT(*) as c FROM sessions").get() as any).c;
    const indexedSessions = (db.prepare("SELECT COUNT(*) as c FROM sessions WHERE indexed_at IS NOT NULL").get() as any).c;
    const totalChunks = (db.prepare("SELECT COUNT(*) as c FROM chunks").get() as any).c;
  
    let dbSizeMb = 0;
    try {
      dbSizeMb = Math.round(statSync(CONFIG.dbPath).size / 1024 / 1024 * 10) / 10;
    } catch { /* db might not exist yet */ }
  
    const result: any = {
      indexing: progress.running
        ? (() => {
            const elapsed = Date.now() - progress.startedAt;
            // ETA based on chunks processed (more accurate than session count)
            const totalChunksProcessed = progress.chunksCreated + progress.currentSessionChunks;
            const chunksPerMs = totalChunksProcessed > 0 ? totalChunksProcessed / elapsed : 0;
            // Estimate remaining: current session remaining + unprocessed sessions (estimate avg chunks/session)
            const currentRemaining = progress.currentSessionTotal - progress.currentSessionChunks;
            const processedSessions = progress.sessionsIndexed + progress.sessionsSkipped;
            const remainingSessions = progress.sessionsTotal - processedSessions - 1; // -1 for current
            const avgChunksPerSession = processedSessions > 0 ? progress.chunksCreated / Math.max(progress.sessionsIndexed, 1) : 0;
            const estimatedRemainingChunks = currentRemaining + (remainingSessions * avgChunksPerSession);
            const etaMs = chunksPerMs > 0 ? Math.round(estimatedRemainingChunks / chunksPerMs) : null;
            const etaStr = etaMs !== null
              ? etaMs < 60000 ? `${Math.round(etaMs / 1000)}s` : `${Math.round(etaMs / 60000)}m`
              : "calculating...";
            return {
              status: "running",
              progress: `${progress.sessionsIndexed}/${progress.sessionsTotal} sessions`,
              current_project: progress.currentProject,
              current_session: progress.currentSessionTotal > 0
                ? `embedding ${progress.currentSessionChunks}/${progress.currentSessionTotal} chunks`
                : undefined,
              chunks_created: progress.chunksCreated,
              elapsed_ms: elapsed,
              eta: etaStr,
            };
          })()
        : progress.completedAt
          ? {
              status: "idle",
              last_run: `${progress.sessionsIndexed} sessions indexed, ${progress.sessionsSkipped} skipped, ${progress.chunksCreated} chunks in ${progress.completedAt - progress.startedAt}ms`,
              error: progress.error,
              ...(progress.sessionsSkipped > 0 ? { skip_reasons: progress.skipReasons } : {}),
            }
          : { status: "never_run" },
      db: {
        total_sessions: totalSessions,
        indexed_sessions: indexedSessions,
        empty_sessions: (db.prepare("SELECT COUNT(*) as c FROM sessions s WHERE NOT EXISTS (SELECT 1 FROM chunks c WHERE c.session_id = s.id)").get() as any).c,
        total_chunks: totalChunks,
        size_mb: dbSizeMb,
      },
    };
  
    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }

• src/server.ts:118-126 (registration)

  The "status" tool is registered here with the MCP server using the handleStatus function as its handler.

  // status tool
  server.tool(
    "status",
    "Check the health and progress of lore indexing. Shows indexing status, session counts, DB size. Use this to monitor indexing progress after calling index.",
    {},
    async (): Promise<ToolResult> => {
      return handleStatus(db);
    }
  );