Coverage Heatmap

The coverage heatmap visualizes which parts of your codebase have the highest concentration of learned observations, helping you identify where your agents are acquiring knowledge and where gaps may exist.

What It Shows

Each row represents a directory or module path extracted from your observations' metadata. The bar width shows the count of observations in that location, relative to others.

Example:

/src/lib/workflows/          ████████████ 145
/src/components/factory/     ████████ 98
/src/lib/memory/             ██████ 72
/src/app/api/                ████ 51
/src/lib/cedal/              ██ 19

How Directories Are Extracted

Primary source: metadata.file_path (if your agents record file paths)
Secondary source: metadata.module (for non-file observations, e.g., "request-routing")
Fallback: (unknown) or (root) if neither is present

The directory is computed by removing the filename (everything after the last /), so src/lib/memory/retrieval.ts becomes src/lib/memory/.

Interpreting Coverage

High Coverage Areas

Indicate where agents are actively learning
May reflect high complexity or frequent changes in those areas
Good candidates for cross-project knowledge transfer (if those patterns are generic)

Low or Zero Coverage

May indicate:
- Those code areas are stable and infrequently modified
- Agents don't have permission to observe those areas
- Work doesn't flow through those paths often
- Opportunity to increase agent scope or add manual observations

Coverage vs Success

High observation density does not guarantee success. Use the coverage heatmap alongside:

Trends - to see if observations are recent or stale
Drift Alerts - to check consistency
Feedback Impact - to see if observations improve outcomes

Time Range Impact

The heatmap respects your selected time window (7d, 30d, 90d). A longer window shows cumulative density over time; a shorter window shows recent focus areas.

Viewing the Heatmap

The heatmap appears on the Memory Dashboard in the top-left panel, alongside the trends chart. It updates when you:

Change the time range
Change the project scope
Click the Refresh button

Common Patterns

Pattern	Interpretation
Top 5 directories account for >70% of observations	Concentration in a few high-value areas (often expected)
New directory suddenly appears at top	Recent refactor or new feature area; agents learning about new subsystem
Directory drops to zero after being high	Area may be complete/frozen, or agents lost access/scope
Flat distribution across many directories	Wide knowledge spread; good for generalist understanding

API Reference

Endpoint: GET /api/memory/analytics/coverage

Query Parameters:

projectId (optional) - Filter to a specific project
since (optional) - ISO-8601 date lower bound (default: 30 days ago)

Response:

{
  rows: Array<{
    directory: string  // Directory path (e.g., "/src/lib/memory/")
    count: number      // Observation count
  }>
  totalObservations: number  // Sum of all row counts
  projectId: string | null   // Project filter applied
  since: string              // ISO-8601 date of lower bound
}

Example:

curl -X GET "https://api.rensei.ai/api/memory/analytics/coverage?projectId=proj_abc&since=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer rsk_..."

Response:

{
  "rows": [
    {"directory": "/src/lib/workflows/", "count": 145},
    {"directory": "/src/components/factory/", "count": 98}
  ],
  "totalObservations": 243,
  "projectId": "proj_abc",
  "since": "2026-05-01T00:00:00Z"
}

Limits

Maximum 200 directories returned (sorted by count descending)
Directories with <1 observation are excluded
Time range is capped at query execution time (no future predictions)

On this page