session_health_check

Run integrity checks on agent memory to identify and repair issues like missing embeddings, duplicate entries, orphaned handoffs, and stale rollups.

Instructions

Run integrity checks on the agent's memory (like fsck for filesystems). Scans for missing embeddings, duplicate entries, orphaned handoffs, and stale rollups.\n\nChecks performed:\n1. Missing embeddings — entries that can't be found via semantic search\n2. Duplicate entries — near-identical summaries wasting context tokens\n3. Orphaned handoffs — handoff state with no backing ledger entries\n4. Stale rollups — compaction artifacts with no archived originals\n\nUse auto_fix=true to automatically repair missing embeddings and clean up orphans.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`auto_fix`	No	If true, automatically repair issues (backfill embeddings, remove orphaned handoffs). Default: false.

Implementation Reference

src/tools/sessionMemoryHandlers.ts:1267-1330 (handler)

The primary handler implementation for 'session_health_check', which coordinates fetching stats, running the health check logic, and performing auto-fixes.

export async function sessionHealthCheckHandler(args: unknown) {
  // Validate input arguments
  if (!isSessionHealthCheckArgs(args)) {
    return {
      content: [{ type: "text", text: "Error: Invalid arguments." }],
      isError: true,
    };
  }

  const autoFix = args.auto_fix || false;  // default: read-only scan

  console.error("[Health Check] Running fsck (auto_fix=" + autoFix + ")");

  try {
    // Get the storage backend (SQLite or Supabase)
    const storage = await getStorage();

    // Step 1: Fetch raw health statistics from the database
    const stats = await storage.getHealthStats(PRISM_USER_ID);

    // Step 2: Run all 4 checks in the pure-JS engine
    const report: HealthReport = runHealthCheck(stats);

    // Step 3: If auto_fix is true, repair what we can
    let fixedCount = 0;
    if (autoFix && report.issues.length > 0) {
      const embeddingIssue = report.issues.find(
        i => i.check === "missing_embeddings"
      );
      if (embeddingIssue && embeddingIssue.count > 0) {
        console.error(
          "[Health Check] Auto-fixing " + embeddingIssue.count + " missing embeddings..."
        );
        try {
          await backfillEmbeddingsHandler({ dry_run: false, limit: 50 });
          fixedCount += embeddingIssue.count;
          console.error("[Health Check] Backfill complete.");
        } catch (err) {
          console.error("[Health Check] Backfill failed: " + err);
        }
      }
    }

    // Step 4 (v2.3.0): Run prompt injection security scan
    // Uses Gemini to screen latest context for system override attempts
    let securityResult: SecurityScanResult = { safe: true };
    try {
      // Build context string from recent summaries for security scanning
      const contextForScan = stats.activeLedgerSummaries
        .slice(0, 10)                             // last 10 summaries
        .map(s => s.summary)                      // extract text
        .join("\n");                               // combine into one string
      securityResult = await scanForPromptInjection(contextForScan);
    } catch (err) {
      console.error("[Health Check] Security scan failed (non-fatal): " + err);
    }

    // Step 5: Format the report into a readable MCP response
    const statusEmoji = {
      healthy: "✅",
      degraded: "⚠️",
      unhealthy: "🔴",
    }[report.status];

src/tools/sessionMemoryDefinitions.ts:601-620 (schema)

MCP tool definition for 'session_health_check', including the schema and documentation.

export const SESSION_HEALTH_CHECK_TOOL: Tool = {
  name: "session_health_check",
  description:
    "Run integrity checks on the agent's memory (like fsck for filesystems). " +
    "Scans for missing embeddings, duplicate entries, orphaned handoffs, and stale rollups.\\n\\n" +
    "Checks performed:\\n" +
    "1. **Missing embeddings** — entries that can't be found via semantic search\\n" +
    "2. **Duplicate entries** — near-identical summaries wasting context tokens\\n" +
    "3. **Orphaned handoffs** — handoff state with no backing ledger entries\\n" +
    "4. **Stale rollups** — compaction artifacts with no archived originals\\n\\n" +
    "Use auto_fix=true to automatically repair missing embeddings and clean up orphans.",
  inputSchema: {
    type: "object",
    properties: {
      auto_fix: {
        type: "boolean",
        description:
          "If true, automatically repair issues (backfill embeddings, remove orphaned handoffs). Default: false.",
      },
    },

Prism MCP