---
title: analyst
description: Cost tracking and pattern analysis agent — tracks token usage, extracts patterns, and maintains institutional memory across sessions.
---

# analyst

The analyst is your institutional memory keeper. It tracks what every session costs, extracts patterns from recurring issues, and maintains a growing body of lessons learned. Over time, it identifies cost optimizations and proposes improvements to project configuration — always as recommendations, never applied automatically.

## Cognitive Framing

> *"Track everything, learn from everything, auto-apply nothing."*

The analyst operates at Phase 0 (session start — loads context) and Phase 6 (Reflect — records data). It is the terminal agent in the pipeline — after it completes, no further routing occurs. Its most important rule is that it proposes changes but never applies them automatically.

## Key Facts

| | |
|---|---|
| **Type** | Core |
| **Phase** | 0 (Orient), 6 (Reflect) |
| **Auto-activates** | Session start and session end |
| **Owns** | `.claude/memory/` (cost-log.json, patterns.json, lessons.md) |
| **Never does** | Write code, auto-apply configuration changes |

## When to Use

- At **session start** — the analyst loads prior context from memory files automatically.
- At **session end** — the analyst records session cost data, extracts patterns, and updates lessons learned.
- When you want a **cost report** via `/mk:budget` — shows spending by task, agent, model tier, and time period.
- When you want to understand **recurring patterns** across sessions.

## Key Capabilities

- **Token usage tracking** — records task name, model used, tokens consumed, estimated cost, and timestamp in `.claude/memory/cost-log.json` for every session.
- **Cost reporting** — generates cost reports via `/mk:budget` showing spend breakdowns by task, agent, model tier, and time period.
- **Pattern extraction** — identifies recurring issues, common solutions, and frequently needed refactors from session data and records them in `.claude/memory/patterns.json`.
- **Lessons learned** — maintains actionable lessons in `.claude/memory/lessons.md` documenting what worked, what did not, and what to do differently.
- **Configuration recommendations** — proposes `CLAUDE.md` updates every 10 sessions based on accumulated patterns. These are always proposals for human review, never auto-applied.
- **Cost optimization** — identifies tasks consistently over-classified to expensive model tiers and recommends routing adjustments.

## Behavioral Checklist

- [x] Records token usage and cost data for every session
- [x] Generates cost reports on `/mk:budget` request
- [x] Extracts patterns from recurring issues across sessions
- [x] Maintains lessons learned with actionable takeaways
- [x] Proposes `CLAUDE.md` updates every 10 sessions — never auto-applies
- [x] Identifies cost optimization opportunities
- [x] Confirms pipeline complete as the terminal agent
- [x] Never writes production code or test code

## Common Use Cases

| Scenario | What the analyst does |
|---|---|
| End of session | Records cost data, extracts patterns, updates lessons learned |
| `/mk:budget` request | Generates cost report showing spend by task, agent, model tier, and time period |
| Recurring test failures | Identifies the pattern across sessions and documents it for future reference |
| Over-classified tasks | Detects that "simple config changes" are consistently routed as Complex and recommends adjustment |
| Every 10th session | Proposes `CLAUDE.md` updates based on accumulated patterns for human review |

## Pro Tips

### Use Budget Reports to Catch Classification Drift

If your cost reports show that a large percentage of tasks are classified as Complex (and using the most expensive models), it may indicate that the orchestrator's classification rules need adjustment. The analyst's cost optimization recommendations help identify where routing changes can reduce costs without sacrificing quality.

### Review Lessons Learned Periodically

The lessons in `.claude/memory/lessons.md` accumulate over time and become increasingly valuable. Periodically reviewing them helps identify systemic issues — patterns that a single session might miss but that become obvious when viewed across many sessions.

## Key Takeaway

The analyst builds institutional memory that makes every future session smarter. By tracking costs, extracting patterns, and maintaining lessons learned, it ensures that mistakes are not repeated and optimizations compound over time — all without ever making changes automatically.

## Related Agents

- **[documenter](/reference/agents/documenter)** — hands off to the analyst as the final step in the Phase 6 reflect sequence
- **[orchestrator](/reference/agents/orchestrator)** — receives cost anomaly reports and routing adjustment recommendations
- **[journal-writer](/reference/agents/journal-writer)** — journal entries feed into the analyst's pattern extraction
