memtrace 0.1.28 → 0.1.29

package/README.md

@@ -35,12 +35,12 @@ That's it. Claude picks up the skills and MCP tools automatically.
 
 ## Why Memtrace Exists
 
-Static code graphs exist. Tools like GitNexus and CodeGrapherContext build AST-based graphs with symbol relationships — and they're useful. But they solve one dimension: *what exists right now*.
+Good code intelligence tools already exist. GitNexus and CodeGrapherContext build AST-based graphs with symbol relationships, and they work well for understanding what's in your codebase *right now*.
 
-Memtrace is a **bi-temporal episodic structural knowledge graph**. It adds two dimensions no other code intelligence tool has:
+Memtrace is a **bi-temporal episodic structural knowledge graph**. It builds on that same AST foundation and adds two dimensions:
 
 - **Temporal memory** — every symbol carries its full version history. Agents can reason about *what changed*, *when it changed*, and *how the architecture evolved* — not just what exists today. Six scoring algorithms (impact, novelty, recency, directional, compound, overview) let agents ask different temporal questions.
-- **Cross-service API topology** — Memtrace maps HTTP call graphs between repositories, detecting which services call which endpoints. No other code grapher does inter-service relationship mapping.
+- **Cross-service API topology** — Memtrace maps HTTP call graphs between repositories, detecting which services call which endpoints across your architecture.
 
 On top of that, the structural layer is comprehensive:
 
@@ -48,7 +48,7 @@ On top of that, the structural layer is comprehensive:
 - **Relationships are edges** — `CALLS`, `IMPLEMENTS`, `IMPORTS`, `EXPORTS`, `CONTAINS`
 - **Community detection** — Louvain algorithm identifies architectural modules automatically
 - **Hybrid search** — Tantivy BM25 + vector embeddings + Reciprocal Rank Fusion, all on top of the graph
-- **Rust-native** — compiled binary, no Python/JS runtime overhead, single-digit millisecond queries
+- **Rust-native** — compiled binary, no Python/JS runtime overhead, sub-15ms average query latency
 
 The agent doesn't just search your code. It *remembers* it.
 
@@ -58,15 +58,15 @@ All benchmarks run on the same machine, same codebase, same queries. No cherry-p
 
 ### Does it find the right thing?
 
-<img alt="Search accuracy: Memtrace 83.5% vs Vector RAG 25.8%" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/search-accuracy.svg" width="720"/>
+<img alt="Search accuracy: Memtrace 97.3% vs ChromaDB 89.6% vs GitNexus 12.8%" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/search-accuracy.svg" width="720"/>
 
 ### How fast?
 
-<img alt="Search latency: Memtrace 4.6ms vs GitNexus 220ms vs CodeGrapher 466.7ms" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/search-latency.svg" width="720"/>
+<img alt="Search latency: Memtrace 13.4ms vs ChromaDB 60.6ms vs GitNexus 172.7ms vs CodeGrapher 510.5ms" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/search-latency.svg" width="720"/>
 
 ### How much context does it save?
 
-<img alt="Token usage: Memtrace 284K vs Vector RAG 2.4M — 88.2% reduction" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/token-context.svg" width="720"/>
+<img alt="Token usage: Memtrace 319K vs ChromaDB 1.91M — 83% reduction" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/token-context.svg" width="720"/>
 
 ### How long to set up?
 
@@ -77,15 +77,15 @@ All benchmarks run on the same machine, same codebase, same queries. No cherry-p
 
 <br/>
 
-Mem0 and Graphiti are excellent conversational memory engines for tracking entity knowledge (e.g. `User -> Likes -> Apples`). They are **architecturally unsuited for code intelligence** because they require LLM inference to build their graphs.
+Mem0 and Graphiti are strong conversational memory engines designed for tracking entity knowledge (e.g. `User -> Likes -> Apples`). They excel at that. For code intelligence specifically, the tradeoff is that they rely on LLM inference to build their graphs — which adds cost and time when processing thousands of source files.
 
-**Graphiti** processes data through `add_episode()`, which triggers multiple LLM calls per episode — entity extraction, relationship resolution, deduplication. At ~50 episodes/minute ([source](https://github.com/getzep/graphiti)), ingesting 1,500 code files takes **1–2 hours**. Every episode costs LLM tokens.
+**Graphiti** processes data through `add_episode()`, which triggers multiple LLM calls per episode — entity extraction, relationship resolution, deduplication. At ~50 episodes/minute ([source](https://github.com/getzep/graphiti)), ingesting 1,500 code files takes **1–2 hours**.
 
-**Mem0** processes data through `client.add()`, which queues async LLM extraction and conflict resolution per memory item ([source](https://mem0.ai)). Bulk ingestion with `infer=True` (default) means every file passes through an LLM distillation pipeline. Throughput is bounded by your LLM provider's rate limits.
+**Mem0** processes data through `client.add()`, which queues async LLM extraction and conflict resolution per memory item ([source](https://mem0.ai)). Bulk ingestion with `infer=True` (default) means every file passes through an LLM pipeline. Throughput is bounded by your LLM provider's rate limits.
 
-**Both** accumulate $10–50+ in API costs because they use LLMs to *guess* code relationships rather than parsing them deterministically.
+**Both** accumulate $10–50+ in API costs for large codebases because every relationship is inferred rather than parsed.
 
-**Memtrace indexes 1,500 files in 1.2–1.8 seconds for $0.00** — no LLM calls, no API costs, no rate limits. Native Tree-sitter AST parsers resolve deterministic symbol references (`CALLS`, `IMPLEMENTS`, `IMPORTS`) locally.
+**Memtrace takes a different approach:** it indexes 1,500 files in 1.2–1.8 seconds for $0.00 — no LLM calls, no API costs, no rate limits. Native Tree-sitter AST parsers resolve deterministic symbol references (`CALLS`, `IMPLEMENTS`, `IMPORTS`) locally. The tradeoff is that Memtrace is purpose-built for code — it doesn't handle conversational entity memory the way Mem0 and Graphiti do.
 
 </details>
 
@@ -94,7 +94,7 @@ Mem0 and Graphiti are excellent conversational memory engines for tracking entit
 
 <br/>
 
-GitNexus and CodeGrapherContext both build AST-based code graphs with structural relationships — they're real tools solving real problems. Here's what Memtrace adds:
+GitNexus and CodeGrapherContext both build AST-based code graphs with structural relationships — solid tools in the same space. Memtrace shares that foundation and extends it with temporal memory, API topology, and a Rust runtime:
 
 | Capability | Memtrace | GitNexus | CodeGrapher |
 |:-----------|:---------|:---------|:------------|
@@ -105,10 +105,14 @@ GitNexus and CodeGrapherContext both build AST-based code graphs with structural
 | Community detection (Louvain) | **Yes** | Yes | No |
 | Hybrid search (BM25 + vector + RRF) | **Yes — Tantivy + embeddings** | No | BM25 + optional embeddings |
 | Language | **Rust (compiled binary)** | JavaScript | Python |
-| Query latency (1K queries) | **4.6 ms avg** | 220 ms avg | 466.7 ms avg |
-| Index time (1,500 files) | **1.5 sec** | 10.5 sec | 3.5 min |
+| Search accuracy (1K queries) | **97.3%** | 12.8% | 0%* |
+| Query latency (1K queries) | **13.4 ms avg** | 172.7 ms avg | 510.5 ms avg |
+| Tokens per query | **319 avg** | 254 avg | 23 avg |
+| Index time (1,500 files) | **1.5 sec** | 10.5 sec | ~3.5 min |
 
-The speed difference comes from Rust vs. interpreted runtimes, and Memgraph's Bolt protocol vs. HTTP/embedding pipelines. The feature difference is temporal memory and API topology — dimensions that don't exist in static-snapshot graphs.
+*CGC's 0% reflects an output format mismatch — it returns symbol names without file paths, so our Acc@1 evaluator can't match them. CGC likely finds relevant symbols; the metric just can't confirm it. All numbers from [live benchmark](https://github.com/syncable-dev/memtrace-public/tree/main/benchmarks) on the same machine, same codebase, same 1,000 queries.
+
+The latency difference is primarily Rust vs. interpreted runtimes, and Memgraph's Bolt protocol vs. HTTP/embedding pipelines. The feature difference is temporal memory and API topology — dimensions Memtrace adds on top of the shared AST-graph foundation.
 
 </details>
 
@@ -205,11 +209,28 @@ Six scoring algorithms for different temporal questions:
 
 Uses **Structural Significance Budgeting** to surface the minimum set of changes covering ≥80% of total significance.
 
+## Compatibility
+
+| Editor / Agent | MCP Tools (25+) | Skills (12) | Install |
+|:---------------|:---------------:|:-----------:|:--------|
+| **Claude Code** | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
+| **Claude Desktop** | ✅ | ✅ | Automatic — shared with Claude Code |
+| **Cursor** | ✅ | Coming soon | Add MCP server manually |
+| **Windsurf** | ✅ | Coming soon | Add MCP server manually |
+| **VS Code (Copilot)** | ✅ | — | Add MCP server manually |
+| **Cline / Roo Code** | ✅ | — | Add MCP server manually |
+| **Codex CLI** | ✅ | Coming soon | Add MCP server manually |
+| **Any MCP client** | ✅ | — | Add MCP server manually |
+
+> **MCP tools** work with any editor or agent that supports the [Model Context Protocol](https://modelcontextprotocol.io). **Skills** are Claude-specific workflow prompts that teach the agent *how* to chain tools — they require Claude Code or Claude Desktop.
+
 ## Setup
 
-### Claude Code
+### Claude Code + Claude Desktop
+
+`npm install -g memtrace` handles everything automatically — binary, 12 skills, MCP server, plugin, and marketplace all register in one command for both Claude Code and Claude Desktop.
 
-`npm install -g memtrace` handles everything automatically. For manual setup:
+For manual setup:
 
 ```bash
 claude plugin marketplace add syncable-dev/memtrace
@@ -217,9 +238,9 @@ claude plugin install memtrace-skills@memtrace --scope user
 claude mcp add memtrace -- memtrace mcp -e MEMGRAPH_URL=bolt://localhost:7687
 ```
 
-### Claude Desktop
+### Other Editors (Cursor, Windsurf, VS Code, Cline)
 
-Skills and plugins are shared between Claude Code and Claude Desktop — both activate after `npm install -g memtrace`. Add the MCP server to `claude_desktop_config.json`:
+After `npm install -g memtrace`, add the MCP server to your editor's config:
 
 ```json
 {
@@ -233,6 +254,18 @@ Skills and plugins are shared between Claude Code and Claude Desktop — both ac
 }
 ```
 
+<details>
+<summary>Config file locations by editor</summary>
+
+| Editor | Config file |
+|:-------|:------------|
+| **Cursor** | `.cursor/mcp.json` in your project root |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
+| **VS Code (Copilot)** | `.vscode/mcp.json` in your project root |
+| **Cline** | Cline MCP settings in the extension panel |
+
+</details>
+
 ### Uninstall
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",

package/skills/commands/memtrace-cochange.md

@@ -0,0 +1,73 @@
+---
+name: memtrace-cochange
+description: "Use when the user asks what tends to change together with a symbol, what other code moves when this moves, historical coupling, blast awareness before modifying a symbol, or wants to find hidden dependencies not visible in the call graph"
+allowed-tools:
+  - mcp__memtrace__get_cochange_context
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__get_impact
+user-invocable: true
+---
+
+## Overview
+
+Find symbols that historically co-change with a target symbol — ranked by co-occurrence frequency across all episodes. This surfaces **behavioral coupling** that the static call graph cannot see.
+
+`get_impact` answers "who calls this?" (structural).
+`get_cochange_context` answers "what always moves when this moves?" (historical).
+
+They are complementary. A symbol with no direct callers can still have strong cochange partners if it's always modified alongside another in every commit.
+
+## Steps
+
+### 1. Identify the target symbol
+
+Use `find_symbol` if you need the exact name. The tool matches by `name` field.
+
+### 2. Call `get_cochange_context`
+
+```
+get_cochange_context(
+  repo_id: "...",
+  symbol: "execute",    // exact symbol name
+  limit: 20             // default 20, increase for broader view
+)
+```
+
+### 3. Interpret results
+
+The response contains `cochanges[]`, each with:
+- `name` — symbol name
+- `kind` — Function / Method / Class / Struct
+- `file_path` — where it lives
+- `cochange_count` — how many episodes it shared with the target
+
+```
+High cochange_count = strong historical coupling
+→ If you modify the target, you will likely need to touch this too
+→ Or it may be the real root cause you should investigate first
+```
+
+### 4. Cross-reference with call graph
+
+For the top cochange partners, optionally run `get_impact` to see if the coupling is also structural:
+
+| Structural coupling | Historical coupling | Interpretation |
+|---|---|---|
+| Yes | Yes | Core architectural dependency — highest risk |
+| No | Yes | Hidden coupling — only visible through history |
+| Yes | No | Called frequently but changed independently — lower risk |
+
+## When to Use
+
+- **Before modifying a symbol** — get blast awareness beyond what `get_impact` shows
+- **Incident investigation** — when `get_impact` doesn't explain the blast radius, check cochange history
+- **Code review** — verify that a PR touched all historically-coupled partners
+- **Refactoring** — discover implicit coupling before extracting a module
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Only using `get_impact` for blast radius | Structural coupling misses behavioral coupling — always pair with cochange |
+| Ignoring low-`in_degree` cochange partners | A rarely-called utility with high cochange_count is a strong coupling signal |
+| Using cochange as a dependency map | It's not a dependency graph — it's a change correlation. Two symbols can cochange without any direct relationship. |

package/skills/commands/memtrace-evolution.md

@@ -6,6 +6,7 @@ allowed-tools:
   - mcp__memtrace__get_timeline
   - mcp__memtrace__detect_changes
   - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__get_changes_since
 user-invocable: true
 ---
 
@@ -109,6 +110,17 @@ compound = 0.50×rank(impact) + 0.35×rank(novel) + 0.15×rank(recent)
 - Impact-dominant but boosted by novelty and recency
 - Best default when you don't have a specific hypothesis
 
+## Auto-overview Safety
+
+If a time window produces more than 500 candidates and mode is not `overview`, the query **automatically downgrades to overview mode** and returns `auto_overview: true`. This prevents timeouts on wide windows. When you see `auto_overview: true`:
+- Narrow the window, OR
+- Switch to `get_changes_since` (which handles this automatically), OR
+- Use the `by_module` rollup to identify the specific area and query a tighter window
+
+## Session-Aware Alternative
+
+If you're resuming work after a break and don't know the right `from` timestamp, use `get_changes_since` instead — it accepts a `last_episode_id` anchor and never requires timestamp guessing.
+
 ## Common Mistakes
 
 | Mistake | Reality |
@@ -117,3 +129,4 @@ compound = 0.50×rank(impact) + 0.35×rank(novel) + 0.15×rank(recent)
 | Ignoring `budget_exhausted` flag | If true, there are more significant changes beyond what was returned — narrow the time window or use module rollup |
 | Not checking `by_module` first | Module rollup is never truncated — scan it to identify which areas changed before diving into symbol-level |
 | Using `recent` without setting `to` | The `to` timestamp is the reference point for proximity weighting — set it to the incident/event time |
+| Guessing timestamps when resuming work | Use `get_changes_since` with a stored `session_anchor` instead — exact episode boundary, no guessing |

package/skills/workflows/memtrace-episode-replay.md

@@ -0,0 +1,100 @@
+---
+name: memtrace-episode-replay
+description: "Use when an agent needs to understand why code looks the way it does, replay implementation steps between commits, find what was tried and reverted, understand a colleague's (or your past self's) reasoning, or avoid repeating a previously-abandoned approach"
+allowed-tools:
+  - mcp__memtrace__get_episode_replay
+  - mcp__memtrace__get_timeline
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## Overview
+
+Replay the sub-commit implementation narrative for any symbol. Between any two commits, Memtrace recorded every file save as a `working_tree` episode. This tool surfaces that sequence — the attempts, the reversions, the iterative refinements — not just the final committed state.
+
+**Git shows A→B. Episode replay shows every step in between.**
+
+This is the only tool that can answer: "why does this code look like this?" without relying on commit messages or comments.
+
+## Steps
+
+### 1. Identify the symbol and time window
+
+Use `find_symbol` to get the exact symbol name if needed. Determine the window:
+- `from` — when to start (e.g. a few days before a confusing commit)
+- `to` — when to end (usually the commit timestamp or now)
+
+If you don't know the window, call `get_timeline` first to find when the symbol changed.
+
+### 2. Call `get_episode_replay`
+
+```
+get_episode_replay(
+  repo_id: "...",
+  symbol: "execute",
+  from: "2026-04-10T00:00:00Z",
+  to:   "2026-04-13T00:00:00Z",
+  include_working_tree: true,   // false = commits only
+  compress: true                // collapse identical-hash runs
+)
+```
+
+### 3. Read the narrative_hint sequence
+
+Each episode has a `narrative_hint` — derived automatically from AST hash patterns:
+
+| Hint | What it means |
+|---|---|
+| `committed` | A real git commit — the "public record" checkpoint |
+| `pre_commit_finalization` | Last working_tree save before a commit — the final draft |
+| `iterative_refinement` | 3+ consecutive working_tree saves — active development in progress |
+| `attempted_and_reverted` | Hash returned to a prior state — something was tried and backed out |
+| `no_change` | File was saved but this symbol didn't change |
+| `working_tree_save` | A single file save with structural changes |
+
+### 4. Reconstruct the implementation story
+
+Read the sequence like a narrative:
+
+```
+committed              ← "here's where we started"
+working_tree_save      ← "first attempt"
+iterative_refinement   ← "refining the approach"
+attempted_and_reverted ← "tried X, it was wrong, backed out"
+pre_commit_finalization← "final version before commit"
+committed              ← "here's what shipped"
+```
+
+The gap between `committed` entries is the implementation story.
+
+### 5. Identify what to act on
+
+| Pattern | Implication |
+|---|---|
+| `attempted_and_reverted` appears | There was a tried-and-abandoned approach — understand why before trying similar |
+| Multiple `iterative_refinement` clusters | The author was unsure — this area may need extra care |
+| No working_tree episodes (commits only) | Code was written elsewhere or pasted in — less implementation history available |
+| Very short episode sequence | Straightforward change — low implementation complexity |
+
+## When to Use
+
+- **Before modifying unfamiliar code** — understand the intent, not just the current state
+- **Post-session debugging** — replay what was tried during a broken session
+- **Code review** — understand the reasoning behind non-obvious implementations
+- **Avoiding dead ends** — check if the approach you're about to try was already attempted and reverted
+
+## Compression
+
+With `compress: true` (default), consecutive episodes with identical `ast_hash` are collapsed to first+last of the run. Cosmetic saves and whitespace-only edits are filtered out. Only structurally significant transitions are shown.
+
+With `compress: false`, every single save is shown — useful when you want to see exact timing between saves.
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Only reading the final committed code | The commit shows *what*, the episode replay shows *why* — always check both for unfamiliar code |
+| Ignoring `attempted_and_reverted` hints | These are the most valuable entries — they represent knowledge about what doesn't work |
+| Using `include_working_tree: false` by default | Commits-only loses all the sub-commit narrative — only use this if you explicitly want commit-level granularity |
+| Large windows with compress off | Very long histories produce noise; use `compress: true` unless you need exact save-by-save granularity |

package/skills/workflows/memtrace-incident-investigation.md

@@ -11,6 +11,8 @@ allowed-tools:
   - mcp__memtrace__find_symbol
   - mcp__memtrace__analyze_relationships
   - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__get_cochange_context
+  - mcp__memtrace__get_episode_replay
 user-invocable: true
 ---
 
@@ -75,6 +77,21 @@ Call `get_evolution` with mode `directional` to separate:
 - **Removed symbols** — deleted code (potential missing functionality)
 - **Modified symbols** — changed behaviour (potential regressions)
 
+### 8. Check historical coupling (cochange)
+
+For the primary suspect, call `get_cochange_context`:
+- Which symbols historically co-change with this one?
+- If the blast radius from `get_impact` doesn't explain the failure area, check cochange partners — the coupling may be behavioral, not structural.
+
+**Decision:** If a cochange partner is in the failure area but has no direct call relationship to the suspect, it's a hidden dependency — investigate both.
+
+### 9. Replay the sub-commit implementation history (if needed)
+
+If the suspect's commit history doesn't explain the intent, call `get_episode_replay`:
+- What was tried before the final committed state?
+- Was any approach attempted and reverted in the same session?
+- The `attempted_and_reverted` hint often explains why seemingly-correct code was changed to something subtler.
+
 ## Report: Root Cause Analysis
 
 1. **Incident Timeline** — when it started, what was observed
@@ -86,13 +103,15 @@ Call `get_evolution` with mode `directional` to separate:
 
 ## Algorithm Selection Guide for Incidents
 
-| Phase | Mode | Why |
-|-------|------|-----|
-| Initial triage | `recent` | Time-weighted ranking surfaces changes near the incident |
-| Anomaly detection | `novel` | Catches unexpected changes to stable code |
-| Scope assessment | `impact` | Ranks by structural significance (blast radius) |
-| Direction analysis | `directional` | Separates added/removed/modified |
-| Quick summary | `overview` | Fast module-level scan before deep-diving |
+| Phase | Tool / Mode | Why |
+|-------|-------------|-----|
+| Initial triage | `get_evolution` `recent` | Time-weighted ranking surfaces changes near the incident |
+| Anomaly detection | `get_evolution` `novel` | Catches unexpected changes to stable code |
+| Scope assessment | `get_impact` | Ranks by structural significance (blast radius) |
+| Hidden coupling | `get_cochange_context` | Surfaces behavioral coupling not in the call graph |
+| Direction analysis | `get_evolution` `directional` | Separates added/removed/modified |
+| Sub-commit intent | `get_episode_replay` | Reveals what was tried before the committed state |
+| Quick summary | `get_evolution` `overview` | Fast module-level scan before deep-diving |
 
 ## Common Mistakes
 
@@ -102,3 +121,5 @@ Call `get_evolution` with mode `directional` to separate:
 | Only looking at the most recent commit | The root cause may be from an earlier change whose effects were delayed |
 | Ignoring `novel` mode | Unexpected changes to stable code are often the root cause |
 | Not checking blast radius overlap | A change is only a suspect if its blast radius reaches the failure area |
+| Stopping at call graph analysis | `get_cochange_context` finds hidden coupling — symbols that move together without calling each other |
+| Reading only committed code | `get_episode_replay` reveals tried-and-reverted approaches that explain the current implementation |

package/skills/workflows/memtrace-session-continuity.md

@@ -0,0 +1,98 @@
+---
+name: memtrace-session-continuity
+description: "Use at the start of any session to check what changed since last time, when resuming work after a break, when an agent needs to orient itself without guessing timestamps, or when asked 'what changed while I was away'"
+allowed-tools:
+  - mcp__memtrace__get_changes_since
+  - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__get_evolution
+user-invocable: true
+---
+
+## Overview
+
+Session continuity for agents. Instead of guessing a time window and blindly running `get_evolution`, pass a `session_anchor` from your last session and get back exactly what changed — nothing more. The response returns a new anchor to persist for next time.
+
+**Core principle:** Agents track a cursor, not a clock. Never guess timestamps.
+
+## Steps
+
+### 1. Find or bootstrap the session anchor
+
+Look for a stored `session_anchor` from your last session:
+
+```json
+{
+  "last_episode_id": "ep_abc123",
+  "last_reference_time": "2026-04-13T10:43:00Z"
+}
+```
+
+If you have no anchor yet (first run), call `list_indexed_repositories`. Each repo now includes `last_episode_id`, `last_episode_time`, and `last_episode_type` — use `last_episode_id` as your bootstrap anchor.
+
+### 2. Call `get_changes_since`
+
+```
+get_changes_since(
+  repo_id: "...",
+  last_episode_id: "ep_abc123"      // preferred — exact episode boundary
+  // OR
+  last_reference_time: "2026-04-13T10:43:00Z"   // fallback
+)
+```
+
+### 3. Interpret the response
+
+| `status` | Meaning | Action |
+|---|---|---|
+| `no_changes` | Nothing changed since your anchor | Safe to proceed; store new anchor |
+| `changes_detected` | Full symbol-level delta returned | Review `modified[]`, `added[]`, `removed[]` |
+| `changes_detected_overview` | >500 candidates — module rollup only | Check `by_module` for affected areas |
+| `error` | Bad anchor or unknown episode | Fall back to `last_reference_time` or re-index |
+
+### 4. Decide whether changes are relevant
+
+```
+changes_detected
+├── Check modified[]/added[]/removed[] — do any overlap with your current task?
+│   ├── YES → understand what changed before proceeding
+│   └── NO  → safe to continue, update anchor
+
+changes_detected_overview (large window)
+├── Check by_module — does any changed module overlap with your task area?
+│   ├── YES → get_evolution(mode: compound) scoped to that window for detail
+│   └── NO  → ignore, update anchor
+```
+
+### 5. Always persist the returned anchor
+
+Every response includes a new `session_anchor`. Store it for next session:
+
+```json
+{
+  "session_anchor": {
+    "last_episode_id": "ep_xyz789",
+    "last_reference_time": "2026-04-13T14:22:00Z"
+  }
+}
+```
+
+## Auto-mode Selection
+
+`get_changes_since` automatically picks the right mode so it never crashes:
+
+| Candidate count | Mode selected | What you get |
+|---|---|---|
+| 0 | — | `no_changes` immediately |
+| 1–499 | `compound` | Full symbol scoring |
+| 500+ | `overview` | Module rollup only |
+
+`candidate_count` in the response tells you what was found before selection.
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Using `get_evolution` with a guessed timestamp | `get_changes_since` uses an exact episode boundary — no guessing, no over-fetching |
+| Discarding the returned `session_anchor` | Without it, next session reverts to timestamp guessing |
+| Treating `changes_detected_overview` as too large to act on | `by_module` is complete — it tells you exactly which areas changed even in large windows |
+| Calling this tool repeatedly within one session | Call once at session start; use the returned evolution result for the rest of the session |