Skip to content

api-examples.md

Latest commit

 

History

History
1523 lines (1411 loc) · 32.9 KB

api-examples.md

File metadata and controls

1523 lines (1411 loc) · 32.9 KB
Raw

CORTEXA Daemon API Examples (Copy/Paste JSON)

These are practical request/response examples for every currently exposed daemon endpoint.

← Back to README

Base URL and auth

  • Base URL (default): http://localhost:4312
  • If CORTEXA_DAEMON_TOKEN is configured, send one of:
    • x-cortexa-token: <token>
    • Authorization: Bearer <token>

All examples below use JSON request bodies for POST routes.

API surface map

flowchart TD
  H[Health and metrics]
  C[Core routes]
  X[CX-LINK routes]
  M[Compaction routes]
  S[Session-resurrection routes]

  H --> C
  C --> X
  X --> M
  X --> S
Loading
Group Representative routes Typical use
Health GET /health, GET /metrics uptime checks and telemetry scraping
Core /ingest, /query, /context, /evolve ingestion, retrieval, context compile, progression
CX-LINK /cxlink/context, /cxlink/query, /cxlink/plan, /cxlink/llm/status, /cxlink/agent/* protocol envelopes and orchestration
Compaction /cxlink/compaction/* stats, audit, dashboard, self-healing control
Session resurrection /cxlink/session-resurrection/* scheduler status and manual trigger

1) Health

GET /health

Response

{
  "ok": true,
  "service": "cortexa-daemon",
  "ts": 1713432172123,
  "uptimeMs": 23567,
  "selfHealing": {
    "enabled": true,
    "started": true,
    "running": false,
    "nextRunAt": 1713433972123,
    "lastScheduledDelayMs": 1805421,
    "consecutiveFailures": 0,
    "lastOutcome": "dry-run-only",
    "runCount": 14,
    "slo": {
      "generatedAt": 1713432172123,
      "windows": [
        {
          "windowMinutes": 60,
          "windowMs": 3600000,
          "sinceMs": 1713428572123,
          "total": 3,
          "applied": 1,
          "dryRunOnly": 2,
          "skipped": 0,
          "error": 0,
          "successRate": 1,
          "errorRate": 0,
          "applyRate": 0.3333
        }
      ]
    }
  },
  "sessionResurrection": {
    "enabled": true,
    "started": true,
    "running": false,
    "nextRunAt": 1713433072123,
    "lastScheduledDelayMs": 901234,
    "consecutiveFailures": 0,
    "lastOutcome": "indexed",
    "runCount": 9,
    "slo": {
      "generatedAt": 1713432172123,
      "windows": [
        {
          "windowMinutes": 60,
          "windowMs": 3600000,
          "sinceMs": 1713428572123,
          "total": 2,
          "indexed": 2,
          "applied": 0,
          "skipped": 0,
          "error": 0,
          "successRate": 1,
          "errorRate": 0,
          "applyRate": 0,
          "indexRate": 1
        }
      ]
    }
  }
}

2) Core routes

POST /ingest

Notes:

  • path is required.
  • projectId is optional; when omitted, it is inferred from the provided path.
  • includeChats defaults to false for API calls unless provided.
  • skipUnchanged defaults to true for API calls.
  • if includeChats=true and chatRoot is omitted, transcript discovery scopes to matching workspace storage first, then falls back to broader roots.
  • if cortexa.policy.json exists in the project root, ingestion applies it automatically.
  • set policyPath to override the default policy file location.

Request

{
  "path": "C:/Users/ayana/Projects/Cortexta",
  "branch": "feature/auth-refactor",
  "includeChats": true,
  "skipUnchanged": true,
  "maxFiles": 3000,
  "maxChatFiles": 500,
  "policyPath": "C:/Users/ayana/Projects/Cortexta/cortexa.policy.json"
}

Response

{
  "ok": true,
  "route": "ingest",
  "result": {
    "filesScanned": 714,
    "codeFilesSkippedUnchanged": 312,
    "chatFilesScanned": 18,
    "chatFilesSkippedUnchanged": 11,
    "codeChunks": 1910,
    "chatTurns": 220,
    "memoriesStored": 2130,
    "staleMemoriesRemoved": 41,
    "staleCodeMemoriesRemoved": 19,
    "staleChatMemoriesRemoved": 22,
    "skipUnchanged": true,
    "ingestVersion": "ingest-v2",
    "errors": []
  }
}

POST /query

Request

{
  "query": "how is compaction dashboard built?",
  "projectId": "cortexta",
  "branch": "feature/auth-refactor",
  "topK": 5,
  "minScore": 0.55,
  "asOf": 1713432172000
}

Response

{
  "ok": true,
  "route": "query",
  "count": 1,
  "results": [
    {
      "id": "code_4b132f3a5b4f0f5dc7ab9123",
      "logicalId": "code_4b132f3a5b4f0f5dc7ab9123",
      "projectId": "cortexta",
      "branch": "feature/auth-refactor",
      "kind": "code_entity",
      "sourceType": "code",
      "title": "Compaction dashboard aggregation",
      "summary": "Builds global and per-project trend payload.",
      "content": "export function getMemoryCompactionDashboard(...) { ... }",
      "tags": [
        "typescript",
        "file:core/mempalace/memory.service.ts"
      ],
      "importance": 0.72,
      "confidence": 0.7,
      "createdAt": 1713431111000,
      "lastAccessedAt": 1713432111000,
      "sourceRef": "core/mempalace/memory.service.ts",
      "copilotContent": "getMemoryCompactionDashboard aggregates current stats, trend snapshots and project risk.",
      "score": 0.8934,
      "similarity": 0.82,
      "recency": 0.9912
    }
  ],
  "suggestion": {
    "query": "how is compaction dashboard built?",
    "projectId": "cortexta",
    "branch": "feature/auth-refactor",
    "intent": {
      "category": "general",
      "confidence": 0.45,
      "matchedKeywords": []
    },
    "recommendedTopK": 12,
    "recommendedMaxTokens": 4200,
    "recommendedScope": "project + memory + retrieval",
    "recommendedConstraints": [
      "prefer high-confidence memories",
      "keep context concise"
    ],
    "reason": "No dominant intent detected. Using balanced context defaults."
  }
}

POST /context

Request

{
  "query": "add a new risk dimension to compaction dashboard",
  "projectId": "cortexta",
  "branch": "release/next",
  "asOf": 1713432172000,
  "maxTokens": 4096,
  "topK": 12,
  "proactive": true,
  "constraints": [
    "preserve existing API schema",
    "add integration tests"
  ],
  "scope": "core/mempalace"
}

Response

{
  "ok": true,
  "route": "context",
  "context": "### Objective\nAdd a new risk dimension ...",
  "tokens": 1328,
  "memoriesUsed": 8,
  "dropped": 4,
  "suggestion": {
    "intent": {
      "category": "feature",
      "confidence": 0.72,
      "matchedKeywords": [
        "\\badd\\b",
        "\\bfeature\\b"
      ]
    },
    "recommendedTopK": 13,
    "recommendedMaxTokens": 4800,
    "recommendedScope": "requirements + touched modules",
    "recommendedConstraints": [
      "identify dependencies",
      "capture migration impacts"
    ]
  }
}

POST /context/suggest

Notes:

  • Generates proactive intent suggestions for the query.
  • Set warmup=true to also return compiled context using suggested defaults.
  • When daemon stream subscribers are connected, proactive suggestion flows may emit contextSuggested events.

Request

{
  "query": "investigate failing auth integration test",
  "projectId": "cortexta",
  "branch": "ops/hotfix",
  "warmup": true,
  "topK": 16,
  "maxTokens": 5600
}

Response

{
  "ok": true,
  "route": "context/suggest",
  "warmup": true,
  "suggestion": {
    "intent": {
      "category": "debugging",
      "confidence": 0.86,
      "matchedKeywords": [
        "\\bfail(?:ed|ing)?\\b"
      ]
    },
    "recommendedTopK": 16,
    "recommendedMaxTokens": 5600,
    "recommendedScope": "runtime + diagnostics + memory",
    "recommendedConstraints": [
      "prioritize failure context",
      "prefer latest affected entities"
    ],
    "reason": "Detected debugging intent from query signals; proactively tuned context packing."
  },
  "warmedContext": {
    "context": "### Objective\nInvestigate failing auth integration test ...",
    "tokens": 1492,
    "memoriesUsed": 10,
    "dropped": 2
  }
}

POST /evolve

Notes:

  • If text is omitted, the route uses consolidate mode (existing batch consolidation behavior).
  • If text is provided, the route uses progression mode and returns progression stage telemetry.
  • POST /evolve/progression is a strict alias for progression mode and requires text.

Request

{
  "projectId": "cortexta",
  "dryRun": false,
  "limit": 500
}

Response

{
  "ok": true,
  "route": "evolve",
  "dryRun": false,
  "sourceCount": 500,
  "evolvedCount": 438,
  "removed": 62,
  "persistedCount": 438
}

Request (progression mode)

{
  "projectId": "cortexta",
  "text": "upgrade memory evolution progression telemetry",
  "context": "operator-triggered daemon cycle",
  "dryRun": true
}

Response (progression mode)

{
  "ok": true,
  "route": "evolve",
  "mode": "progression",
  "projectId": "cortexta",
  "dryRun": true,
  "stored": true,
  "persisted": false,
  "action": "store",
  "reason": "fallback-heuristic",
  "atomId": "mem_n4yk3x8z",
  "progression": {
    "proposedCandidates": 1,
    "reviewedCandidates": 1,
    "selectedCandidateIndex": 0,
    "selectedScore": 0.6934,
    "merged": false,
    "neighborCount": 3,
    "promoted": false,
    "archived": false,
    "stages": [
      {
        "stage": "propose",
        "ok": true,
        "detail": "writer-produced-1-candidate(s)",
        "at": 1713433000000
      },
      {
        "stage": "review",
        "ok": true,
        "detail": "selected-candidate-0-action-store",
        "at": 1713433000005
      },
      {
        "stage": "consolidate",
        "ok": true,
        "detail": "no-consolidation-required",
        "at": 1713433000007
      },
      {
        "stage": "archivist",
        "ok": true,
        "detail": "decay=1 promote=false archive=false",
        "at": 1713433000008
      },
      {
        "stage": "persist",
        "ok": true,
        "detail": "upserted",
        "at": 1713433000009
      }
    ]
  }
}

POST /evolve/progression

Notes:

  • Strict progression endpoint alias.
  • Requires text; missing text returns 400 with {"ok":false,"error":"Missing required field: text"}.

Request

{
  "projectId": "cortexta",
  "text": "upgrade memory evolution progression telemetry",
  "context": "operator-triggered daemon cycle",
  "dryRun": true
}

Response

{
  "ok": true,
  "route": "evolve/progression",
  "mode": "progression",
  "projectId": "cortexta",
  "dryRun": true,
  "stored": true,
  "persisted": false,
  "action": "store",
  "reason": "fallback-heuristic",
  "atomId": "mem_n4yk3x8z",
  "progression": {
    "proposedCandidates": 1,
    "reviewedCandidates": 1,
    "selectedCandidateIndex": 0,
    "selectedScore": 0.6934,
    "merged": false,
    "neighborCount": 3,
    "promoted": false,
    "archived": false,
    "stages": [
      {
        "stage": "propose",
        "ok": true,
        "detail": "writer-produced-1-candidate(s)",
        "at": 1713433000000
      }
    ]
  }
}

3) CX-LINK routes

POST /cxlink/context

Request

{
  "query": "wire compaction stats into a dashboard widget",
  "agent": "cli",
  "projectId": "cortexta",
  "branch": "release/next",
  "asOf": 1713432172000,
  "topK": 12,
  "minScore": 0.5
}

Response

{
  "ok": true,
  "route": "cxlink/context",
  "agent": "cli",
  "branch": "release/next",
  "asOf": 1713432172000,
  "tokens": 944,
  "memoryHealth": {
    "projectId": "cortexta",
    "totalRows": 4200,
    "compactionRate": 0.81,
    "savedPercent": 74.2,
    "anomalyTotal": 0,
    "status": "healthy",
    "recommendation": "Memory quality is healthy. Keep regular ingestion and dashboard snapshots running."
  },
  "context": "# Context\n- ...",
  "cxf": "intent: wire compaction stats into a dashboard widget\nscope: project + memory + retrieval",
  "envelope": "# Context\n- ...\n\n[CONTEXT_STATS]\ntokens=944 atoms=12 dropped=3\n\n[USER_QUERY]\nwire compaction stats into a dashboard widget"
}

POST /cxlink/query

Request

{
  "query": "memory backfill behavior",
  "agent": "cli",
  "projectId": "cortexta",
  "branch": "release/next",
  "asOf": 1713432172000,
  "topK": 6,
  "minScore": 0.5
}

Response

{
  "ok": true,
  "route": "cxlink/query",
  "query": "memory backfill behavior",
  "branch": "release/next",
  "asOf": 1713432172000,
  "count": 1,
  "memoryHealth": {
    "projectId": "cortexta",
    "totalRows": 4200,
    "compactionRate": 0.81,
    "savedPercent": 74.2,
    "anomalyTotal": 0,
    "status": "healthy",
    "recommendation": "Memory quality is healthy. Keep regular ingestion and dashboard snapshots running."
  },
  "results": [
    {
      "id": "code_2f8f4dbeacbd7e6bc8d9a111",
      "projectId": "cortexta",
      "kind": "code_entity",
      "sourceType": "code",
      "title": "backfillMemoryCompaction",
      "summary": "Dry-run/apply compaction over recent rows.",
      "content": "export function backfillMemoryCompaction(...) { ... }",
      "tags": [
        "typescript",
        "file:core/mempalace/memory.service.ts"
      ],
      "importance": 0.72,
      "confidence": 0.7,
      "createdAt": 1713430001000,
      "lastAccessedAt": 1713432001000,
      "sourceRef": "core/mempalace/memory.service.ts",
      "copilotContent": "Scans rows, skips already compacted entries, and reports scanned/eligible/compacted/savedChars.",
      "score": 0.8755,
      "similarity": 0.81,
      "recency": 0.9901
    }
  ],
  "cxf": "intent: memory backfill behavior\nscope: project + memory + retrieval",
  "envelope": "# Context\n- ...\n\n[CONTEXT_STATS]\ntokens=611 atoms=6 dropped=0\n\n[USER_QUERY]\nmemory backfill behavior"
}

POST /cxlink/plan

Request

{
  "query": "introduce retention alerting for compaction anomalies",
  "agent": "cli",
  "projectId": "cortexta",
  "branch": "release/next",
  "asOf": 1713432172000,
  "topK": 8,
  "minScore": 0.45
}

Response

{
  "ok": true,
  "route": "cxlink/plan",
  "query": "introduce retention alerting for compaction anomalies",
  "agent": "cli",
  "branch": "release/next",
  "asOf": 1713432172000,
  "tokens": 702,
  "memoryHealth": {
    "projectId": "cortexta",
    "totalRows": 4200,
    "compactionRate": 0.81,
    "savedPercent": 74.2,
    "anomalyTotal": 0,
    "status": "healthy",
    "recommendation": "Memory quality is healthy. Keep regular ingestion and dashboard snapshots running."
  },
  "steps": [
    {
      "id": 1,
      "title": "Confirm objective and constraints",
      "detail": "Clarify the primary goal for: introduce retention alerting for compaction anomalies"
    },
    {
      "id": 2,
      "title": "Collect relevant context",
      "detail": "Review top-ranked memory/code entities and extract high-confidence facts."
    },
    {
      "id": 3,
      "title": "Execute change in bounded increments",
      "detail": "Apply updates in small steps, validate after each change, and track regressions early."
    },
    {
      "id": 4,
      "title": "Verify and summarize",
      "detail": "Run validation checks, capture outcomes, and document follow-up actions."
    }
  ],
  "cxf": "intent: introduce retention alerting for compaction anomalies\nscope: project + memory + retrieval",
  "envelope": "# Context\n- ...\n\n[CONTEXT_STATS]\ntokens=702 atoms=8 dropped=2\n\n[USER_QUERY]\nintroduce retention alerting for compaction anomalies"
}

POST /cxlink/llm/status

Request

{}

Response

{
  "ok": true,
  "route": "cxlink/llm/status",
  "status": {
    "mode": "auto",
    "strictRemote": true,
    "effectiveTimeoutMs": 60000,
    "effectiveJsonMaxTokens": 160,
    "serviceUrl": "http://127.0.0.1:8000",
    "serviceReachable": false,
    "modelPathDetected": "data/llm/cortexa-mini-llm.q8.json",
    "lastSuccessAt": 1713433000000,
    "lastError": "Qwen service request failed (503): {\"error\":\"service_unavailable\"}",
    "diagnosticHints": [
      "Qwen service is not reachable at http://127.0.0.1:8000.",
      "Strict remote is enabled; auto mode will not fall back to mini-local on Qwen failure."
    ]
  }
}

POST /cxlink/agent/list

Request

{}

Response

{
  "ok": true,
  "route": "cxlink/agent/list",
  "count": 10,
  "agents": [
    {
      "id": "planner",
      "description": "Planning agent that produces structured strategies, risks, and constraints.",
      "family": "heuristic",
      "mutation": false
    },
    {
      "id": "multi_agent_loop",
      "description": "Blueprint loop that composes planner + writer + critic + refactor outputs.",
      "family": "orchestrator",
      "mutation": true
    }
  ]
}

POST /cxlink/agent/run

Notes:

  • Successful runs emit daemon stream event type agentStatus.

Request

{
  "projectId": "cortexta",
  "branch": "feature/agents",
  "agent": "multi_agent_loop",
  "text": "integrate planner and refactor outputs into cxlink orchestration",
  "dryRun": true,
  "topK": 8,
  "maxChars": 1200
}

Response

{
  "ok": true,
  "route": "cxlink/agent/run",
  "agent": "multi_agent_loop",
  "projectId": "cortexta",
  "branch": "feature/agents",
  "dryRun": true,
  "result": {
    "agent": "multi_agent_loop",
    "plan": {
      "intent": "feature"
    },
    "writer": {
      "candidateCount": 1
    },
    "critic": {
      "selectedAction": "store"
    },
    "refactor": {
      "actionCount": 3
    }
  },
  "streamEvent": {
    "payload": {
      "eventType": "agentStatus"
    }
  }
}

POST /cxlink/branch/list

Request

{
  "projectId": "cortexta"
}

Response

{
  "ok": true,
  "route": "cxlink/branch/list",
  "projectId": "cortexta",
  "branches": [
    {
      "id": "mem_branch_42f8f3d7f10f97d4ef9f8191",
      "projectId": "cortexta",
      "branch": "main",
      "createdAt": 1713430000000,
      "updatedAt": 1713433000000
    },
    {
      "id": "mem_branch_117d2de0e6a99f1cbf9bc3ba",
      "projectId": "cortexta",
      "branch": "feature/auth-refactor",
      "parentBranch": "main",
      "forkedFromCommit": "commit-main-001",
      "createdAt": 1713432000000,
      "updatedAt": 1713433000000
    }
  ]
}

POST /cxlink/branch/create

Request

{
  "projectId": "cortexta",
  "branch": "release/next",
  "fromBranch": "feature/auth-refactor",
  "forkedFromCommit": "commit-feature-012"
}

Response

{
  "ok": true,
  "route": "cxlink/branch/create",
  "created": {
    "id": "mem_branch_8113968d6c1ded8f42fe5fb1",
    "projectId": "cortexta",
    "branch": "release/next",
    "parentBranch": "feature/auth-refactor",
    "forkedFromCommit": "commit-feature-012",
    "createdAt": 1713433200000,
    "updatedAt": 1713433200000
  }
}

POST /cxlink/branch/merge

Request

{
  "projectId": "cortexta",
  "sourceBranch": "feature/auth-refactor",
  "targetBranch": "release/next",
  "strategy": "source-wins"
}

Response

{
  "ok": true,
  "route": "cxlink/branch/merge",
  "result": {
    "projectId": "cortexta",
    "sourceBranch": "feature/auth-refactor",
    "targetBranch": "release/next",
    "strategy": "source-wins",
    "mergedRows": 7,
    "appliedUpserts": 5,
    "appliedDeletes": 1,
    "skipped": 1,
    "completedAt": 1713433500000
  }
}

POST /cxlink/branch/switch

Notes:

  • Successful switches emit daemon stream event type branchSwitched.

Request

{
  "projectId": "cortexta",
  "fromBranch": "release/next",
  "toBranch": "ops/hotfix",
  "reason": "incident-response"
}

Response

{
  "ok": true,
  "route": "cxlink/branch/switch",
  "switched": {
    "projectId": "cortexta",
    "fromBranch": "release/next",
    "toBranch": "ops/hotfix",
    "reason": "incident-response"
  },
  "streamEvent": {
    "payload": {
      "eventType": "branchSwitched"
    }
  }
}

POST /cxlink/temporal/query

Request

{
  "query": "auth guard",
  "projectId": "cortexta",
  "branch": "feature/auth-refactor",
  "asOf": 1713432800000,
  "topK": 8,
  "minScore": 0.4
}

Response

{
  "ok": true,
  "route": "cxlink/temporal/query",
  "query": "auth guard",
  "projectId": "cortexta",
  "branch": "feature/auth-refactor",
  "asOf": 1713432800000,
  "count": 1,
  "results": [
    {
      "logicalId": "memory.feature.auth.guard",
      "title": "Auth guard feature branch",
      "score": 0.913,
      "branch": "feature/auth-refactor"
    }
  ]
}

POST /cxlink/temporal/diff

Request

{
  "projectId": "cortexta",
  "branch": "feature/auth-refactor",
  "from": 1713432000000,
  "to": 1713434000000,
  "limit": 50
}

Response

{
  "ok": true,
  "route": "cxlink/temporal/diff",
  "diff": {
    "projectId": "cortexta",
    "branch": "feature/auth-refactor",
    "from": 1713432000000,
    "to": 1713434000000,
    "totals": {
      "added": 1,
      "removed": 1,
      "modified": 2
    },
    "items": [
      {
        "logicalId": "memory.feature.auth.guard",
        "changeType": "modified",
        "title": "Auth guard feature branch"
      }
    ]
  }
}

4) Compaction routes

POST /cxlink/compaction/stats

Request

{
  "projectId": "cortexta"
}

Response

{
  "ok": true,
  "route": "cxlink/compaction/stats",
  "stats": {
    "projectId": "cortexta",
    "totalRows": 1500,
    "compactedRows": 1200,
    "plainRows": 300,
    "storedChars": 500000,
    "originalChars": 2000000,
    "savedChars": 1500000,
    "savedPercent": 75,
    "compactionRate": 0.8,
    "averageCompressionRatio": 0.25,
    "integrityAnomalies": {
      "invalidChecksum": 0,
      "decodeError": 0,
      "total": 0
    }
  }
}

POST /cxlink/compaction/backfill

Request

{
  "projectId": "cortexta",
  "limit": 5000,
  "dryRun": false
}

Response

{
  "ok": true,
  "route": "cxlink/compaction/backfill",
  "result": {
    "projectId": "cortexta",
    "dryRun": false,
    "scanned": 5000,
    "eligible": 1200,
    "compacted": 1200,
    "skipped": 3800,
    "savedChars": 450000
  }
}

POST /cxlink/compaction/dashboard

Request

{
  "projectId": "cortexta",
  "lookbackDays": 30,
  "maxTrendPoints": 120,
  "maxProjects": 50,
  "persistSnapshot": true,
  "perProjectSnapshotLimit": 25,
  "snapshotRetentionDays": 180
}

Response

{
  "ok": true,
  "route": "cxlink/compaction/dashboard",
  "dashboard": {
    "generatedAt": 1713430000000,
    "lookbackDays": 30,
    "scopedProjectId": "cortexta",
    "current": {
      "projectId": "cortexta",
      "totalRows": 1500,
      "compactedRows": 1200,
      "plainRows": 300,
      "storedChars": 500000,
      "originalChars": 2000000,
      "savedChars": 1500000,
      "savedPercent": 75,
      "compactionRate": 0.8,
      "averageCompressionRatio": 0.25,
      "integrityAnomalies": {
        "invalidChecksum": 0,
        "decodeError": 0,
        "total": 0
      }
    },
    "trend": {
      "global": [
        {
          "createdAt": 1713343600000,
          "totalRows": 1400,
          "compactedRows": 1000,
          "plainRows": 400,
          "storedChars": 520000,
          "originalChars": 2000000,
          "savedChars": 1480000,
          "savedPercent": 74,
          "compactionRate": 0.7143,
          "invalidChecksum": 0,
          "decodeError": 0,
          "integrityAnomalyTotal": 0
        },
        {
          "createdAt": 1713430000000,
          "totalRows": 1500,
          "compactedRows": 1200,
          "plainRows": 300,
          "storedChars": 500000,
          "originalChars": 2000000,
          "savedChars": 1500000,
          "savedPercent": 75,
          "compactionRate": 0.8,
          "invalidChecksum": 0,
          "decodeError": 0,
          "integrityAnomalyTotal": 0
        }
      ],
      "scopedProject": [
        {
          "projectId": "cortexta",
          "createdAt": 1713430000000,
          "totalRows": 1500,
          "compactedRows": 1200,
          "plainRows": 300,
          "storedChars": 500000,
          "originalChars": 2000000,
          "savedChars": 1500000,
          "savedPercent": 75,
          "compactionRate": 0.8,
          "invalidChecksum": 0,
          "decodeError": 0,
          "integrityAnomalyTotal": 0
        }
      ]
    },
    "perProject": [
      {
        "projectId": "cortexta",
        "stats": {
          "projectId": "cortexta",
          "totalRows": 1500,
          "compactedRows": 1200,
          "plainRows": 300,
          "storedChars": 500000,
          "originalChars": 2000000,
          "savedChars": 1500000,
          "savedPercent": 75,
          "compactionRate": 0.8,
          "averageCompressionRatio": 0.25,
          "integrityAnomalies": {
            "invalidChecksum": 0,
            "decodeError": 0,
            "total": 0
          }
        },
        "lastAccessedAt": 1713425000000,
        "riskLevel": "healthy"
      }
    ],
    "integrityAnomalies": {
      "invalidChecksum": 0,
      "decodeError": 0,
      "total": 0
    },
    "totals": {
      "projectCount": 1,
      "projectsWithAnomalies": 0,
      "projectsMostlyCompacted": 1
    }
  }
}

POST /cxlink/compaction/audit

Request

{
  "projectId": "cortexta",
  "limit": 5000,
  "maxIssues": 10
}

Response

{
  "ok": true,
  "route": "cxlink/compaction/audit",
  "report": {
    "projectId": "cortexta",
    "scannedRows": 5000,
    "compactedRows": 4100,
    "plainRows": 900,
    "validCompactedRows": 4098,
    "anomalies": {
      "invalidChecksum": 1,
      "decodeError": 1,
      "total": 2
    },
    "anomalyRate": 0.0005,
    "compactionOpportunityRate": 0.18,
    "issueSamples": [
      {
        "id": "cmp_integrity_anomaly_1",
        "projectId": "cortexta",
        "kind": "code_entity",
        "sourceType": "manual",
        "title": "Integrity anomaly sample",
        "integrity": "invalid_checksum",
        "preview": "Tampered compact row for anomaly accounting.",
        "storedChars": 321,
        "originalChars": 1280,
        "savedChars": 959,
        "lastAccessedAt": 1713431000000
      }
    ],
    "recommendations": [
      "Integrity anomalies detected. Inspect issue samples and re-ingest affected sources to restore full resurrection fidelity."
    ]
  }
}

POST /cxlink/compaction/self-heal/status

Request

{}

Response

{
  "ok": true,
  "route": "cxlink/compaction/self-heal/status",
  "status": {
    "enabled": true,
    "started": true,
    "running": false,
    "nextRunAt": 1713433972123,
    "lastScheduledDelayMs": 1805421,
    "consecutiveFailures": 0,
    "runCount": 14,
    "config": {
      "enabled": true,
      "projectId": "cortexta",
      "intervalMs": 1800000,
      "jitterMs": 60000,
      "runOnStart": true,
      "auditLimit": 5000,
      "auditMaxIssues": 20,
      "backfillLimit": 5000,
      "applyEnabled": true,
      "maxAllowedAnomalies": 0,
      "minCompactionOpportunityRate": 0.2,
      "minDryRunCompactedRows": 50,
      "maxApplyRows": 2000,
      "applyWindowStartHour": 1,
      "applyWindowEndHour": 5,
      "historyLimit": 50,
      "persistHistory": true,
      "persistedHistoryLimit": 2000,
      "backoffEnabled": true,
      "backoffMultiplier": 2,
      "maxBackoffIntervalMs": 21600000,
      "sloWindowsMinutes": [
        60,
        1440,
        10080
      ]
    },
    "lastRun": {
      "runId": "selfheal_m14a2f_9",
      "trigger": "scheduled",
      "dryRunOnly": false,
      "startedAt": 1713432100000,
      "completedAt": 1713432100190,
      "durationMs": 190,
      "outcome": "dry-run-only",
      "decision": {
        "allowApply": false,
        "applyLimit": 2000,
        "reasons": [
          "Compaction opportunity below threshold (0.1200 < 0.2000)."
        ]
      }
    },
    "recentRuns": [],
    "slo": {
      "generatedAt": 1713433972123,
      "windows": [
        {
          "windowMinutes": 60,
          "windowMs": 3600000,
          "sinceMs": 1713430372123,
          "total": 2,
          "applied": 0,
          "dryRunOnly": 2,
          "skipped": 0,
          "error": 0,
          "successRate": 1,
          "errorRate": 0,
          "applyRate": 0
        }
      ]
    }
  }
}

POST /cxlink/compaction/self-heal/trigger

Request

{
  "reason": "nightly-ops-check",
  "dryRunOnly": true
}

Response

{
  "ok": true,
  "route": "cxlink/compaction/self-heal/trigger",
  "report": {
    "runId": "selfheal_m14a2f_a",
    "trigger": "manual",
    "reason": "nightly-ops-check",
    "dryRunOnly": true,
    "startedAt": 1713432200000,
    "completedAt": 1713432200181,
    "durationMs": 181,
    "outcome": "dry-run-only",
    "decision": {
      "allowApply": false,
      "applyLimit": 2000,
      "reasons": [
        "Manual dry-run only mode requested.",
        "Apply mode is disabled by configuration."
      ]
    },
    "audit": {
      "scannedRows": 5000,
      "compactedRows": 4100,
      "plainRows": 900,
      "anomalies": {
        "invalidChecksum": 0,
        "decodeError": 0,
        "total": 0
      },
      "anomalyRate": 0,
      "compactionOpportunityRate": 0.18,
      "recommendationCount": 1
    },
    "dryRunBackfill": {
      "projectId": "cortexta",
      "dryRun": true,
      "scanned": 5000,
      "eligible": 900,
      "compacted": 900,
      "skipped": 4100,
      "savedChars": 350000
    }
  },
  "status": {
    "runCount": 15
  }
}

5) Session-resurrection routes

POST /cxlink/session-resurrection/status

Request

{}

Response

{
  "ok": true,
  "route": "cxlink/session-resurrection/status",
  "status": {
    "enabled": true,
    "started": true,
    "running": false,
    "nextRunAt": 1713433072123,
    "lastScheduledDelayMs": 901234,
    "consecutiveFailures": 0,
    "runCount": 9,
    "config": {
      "projectPath": "C:/Users/ayana/Projects/Cortexta",
      "projectId": "cortexta",
      "branch": "main",
      "includeChats": true,
      "skipUnchanged": true,
      "graphIndexLookbackHours": 336,
      "graphIndexLimit": 5000,
      "graphSnapshotLimit": 5000,
      "applyEnabled": false,
      "backoffEnabled": true,
      "sloWindowsMinutes": [60, 1440, 10080]
    },
    "lastRun": {
      "runId": "sessres_m14a2f_9",
      "trigger": "scheduled",
      "dryRunOnly": false,
      "outcome": "indexed",
      "durationMs": 226,
      "ingestion": {
        "filesScanned": 714,
        "chatFilesScanned": 18,
        "memoriesStored": 2130
      },
      "graphIndex": {
        "nodesUpserted": 482,
        "edgesUpserted": 903,
        "sessionNodes": 27,
        "temporalNodes": 12,
        "chatToCodeEdges": 154
      }
    },
    "recentRuns": [],
    "slo": {
      "generatedAt": 1713432172123,
      "windows": [
        {
          "windowMinutes": 60,
          "windowMs": 3600000,
          "sinceMs": 1713428572123,
          "total": 2,
          "indexed": 2,
          "applied": 0,
          "skipped": 0,
          "error": 0,
          "successRate": 1,
          "errorRate": 0,
          "applyRate": 0,
          "indexRate": 1
        }
      ]
    }
  }
}

POST /cxlink/session-resurrection/trigger

Notes:

  • Successful manual triggers emit daemon stream event type sessionResurrectionStatus.

Request

{
  "reason": "ops-manual-check",
  "dryRunOnly": true,
  "includeChats": false,
  "projectPath": "C:/Users/ayana/Projects/Cortexta"
}

Response

{
  "ok": true,
  "route": "cxlink/session-resurrection/trigger",
  "report": {
    "runId": "sessres_m14a2f_a",
    "trigger": "manual",
    "reason": "ops-manual-check",
    "dryRunOnly": true,
    "projectId": "cortexta",
    "branch": "main",
    "outcome": "indexed",
    "durationMs": 244,
    "decision": {
      "allowApply": false,
      "applyLimit": 2000,
      "reasons": [
        "Manual dry-run only mode requested.",
        "Apply mode is disabled by configuration."
      ]
    },
    "ingestion": {
      "filesScanned": 714,
      "chatFilesScanned": 0,
      "memoriesStored": 1876
    },
    "graphIndex": {
      "nodesUpserted": 463,
      "edgesUpserted": 852,
      "sessionNodes": 24,
      "temporalNodes": 11,
      "chatToCodeEdges": 121
    },
    "audit": {
      "scannedRows": 5000,
      "compactedRows": 4100,
      "plainRows": 900,
      "anomalies": {
        "invalidChecksum": 0,
        "decodeError": 0,
        "total": 0
      },
      "anomalyRate": 0,
      "compactionOpportunityRate": 0.18,
      "recommendationCount": 1
    }
  },
  "status": {
    "runCount": 10
  },
  "streamEvent": {
    "payload": {
      "eventType": "sessionResurrectionStatus"
    }
  }
}

Common error responses

Missing required field

{
  "ok": false,
  "error": "Missing required field: query"
}

Invalid token

{
  "ok": false,
  "error": "unauthorized"
}