How Rocky Works

The pipeline at a glance

Rocky doesn’t extract topics one commit at a time. It batches diffs across a whole working session, pairs them with the Claude Code transcript and a cached project summary, and produces rich nodes with a question bank (~4 implication-grounded Q+A+clue triples each) — driven by an agent already sitting in your editor.

The motivation: a single commit message like “feat: rotate refresh tokens” is too thin a context to ground good questions in. By batching at session end, the extractor has the project summary, the actual diffs, and the agent’s reasoning trail. And by running inside Claude Code itself rather than shelling out to a local Ollama on every Stop event, the per-turn latency drops to zero — the heavy step only happens when you ask for it.

The legacy Stop-hook → Ollama path still ships and is opt-in via rocky install stop. It runs after every Claude turn and is useful if you don’t keep a Claude session open the whole day. The skill-driven default is faster and produces sharper extraction because it sees the full transcript at once.

Inspecting what was generated

The web UI is the canonical viewer — see Quick Start → Step 3 for screenshots of each tab. The Knowledge Map shows the topic graph; the Review Queue surfaces what’s most overdue; the Saga tab is a cinematic timelapse of the graph growing.

Cross-project dedup

When the checkpoint skill extracts topics, it’s fed the global topic list (across every project Rocky knows about) and asked to reuse exact names where a new finding is semantically equivalent. The result: a topic like Token Rotation lives as one node with a repos[] array that accumulates as the same idea reappears in another codebase.

▸ refactor: surface is_rotated helper for refresh token reuse checks
  ◇ Token Rotation (existing — encounter +1, repos: [taskify, home-bank])

Done. 0 new topic(s), 1 encounter update(s).

The web UI’s Project field on a topic shows everywhere it’s appeared. Layer-2 (semantic dedup via embeddings + cosine, beyond today’s lexical Jaccard) is on the backlog.

How the PKG classifies topics

Every topic has a recall score: recall_now = retrievability × mastery.

• Retrievability (R) — FSRS freshness from spaced repetition. Decays with time since the last review. Decays slower when stability is high (you’ve demonstrated solid understanding).
• Mastery (M) — mean of the last 3 review scores (default 0.5 if you’ve never been quizzed). Captures how well you’ve actually been answering, not just how recently.

Recall lifecycle:

1. Topic created → stability set by kind (Concept 4.0, Pattern 2.5, Implementation 1.5), mastery defaults to 0.5
2. Topic reviewed → score 0.0 to 1.0 is recorded. Stability rises if score ≥ 0.65; it floors at 1.0 + difficulty bumps if score < 0.4. The new score replaces the oldest in the last-3 mastery window.
3. Over time → R decays. M is sticky until you take another quiz.
4. Classification:
   • recall ≥ 0.6 → Known — skipped automatically
   • 0.3 ≤ recall < 0.6 → Fading — surfaced as a review candidate
   • recall < 0.3 → Gap — full Socratic Q&A from the question bank

The multiplicative model is the point: a freshly-reviewed topic where you got the question wrong (R high, M low) is still a gap. Freshness alone doesn’t count as knowing.

Domain taxonomy

Every topic is assigned to one of 13 domains when it’s first extracted. Domains group topics in the PKG into subfolders and are used for Obsidian graph view clustering.

Use rocky classify to assign domains to any older topics that predate this feature.