memtrace 0.7.25 → 0.8.0

package/skills/workflows/memtrace-continuous-memory.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-continuous-memory
-description: "Always use when the user asks to keep Memtrace fresh while editing, watch a repo, enable live or incremental indexing, set up always-on memory, or make just-saved source code queryable immediately. Do not fall back to repeated Grep or manual rescans; configure Memtrace watching."
+description: "Keep the Memtrace index fresh while editing by watching a repo for live, incremental re-indexing. Use when the user asks to keep Memtrace fresh while editing, watch a repo, enable live or incremental indexing, set up always-on memory (meaning Memtrace index watching, not generic agent memory), or make just-saved source code queryable immediately. Do not fall back to repeated Grep or manual rescans; configure Memtrace watching."
 allowed-tools:
   - mcp__memtrace__watch_directory
   - mcp__memtrace__list_watched_paths
@@ -8,97 +8,95 @@ allowed-tools:
   - mcp__memtrace__index_directory
   - mcp__memtrace__list_indexed_repositories
   - mcp__memtrace__check_job_status
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
 ---
 
 ## Overview
 
-Memtrace keeps the knowledge graph live as you edit. Once you call `watch_directory`, every save runs through the **incremental indexing fast-path** — a notify-based file watcher debounces saves, the indexer re-parses only the touched files, and the engine commits the delta in a single WAL transaction. Steady-state latency is **~80 ms from save to queryable** on a typical project.
+Keep the knowledge graph live while editing. `watch_directory` triggers incremental re-indexing on file saves (~80 ms typical latency after debounce).
 
-This is what makes "session continuity" actually work: by the time you ask `find_symbol` after a save, the new symbol is already in the graph.
+## Required parameters — `watch_directory`
+
+| Param | Required | Notes |
+|---|---|---|
+| `path` | yes | Absolute directory path |
+| `repo_id` | yes | Must already be indexed |
+| `branch` | no | default `"main"` |
+
+```json
+{ "path": "/abs/path/to/repo", "repo_id": "memdb" }
+```
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
 ## Steps
 
-### 1. Confirm the repo is indexed
+### 1. Confirm indexed
 
 ```
-mcp__memtrace__list_indexed_repositories
+list_indexed_repositories()
 ```
 
-If the repo isn't there, run `index_directory` first. The watcher requires an existing repo_id — it never bootstraps from scratch.
+Run `index_directory` first if missing (poll `check_job_status`; stop after ~5 minutes and report the job id — see memtrace-index).
 
 ### 2. Start watching
 
-```
-mcp__memtrace__watch_directory(
-  path: "/abs/path/to/repo"
-)
-```
-
-The tool registers a `notify` watcher on the directory tree, debounces save bursts (so a `:wq` that touches a swap file doesn't trigger twice), and routes deltas through the indexer's incremental fast-path. Returns immediately — watching runs in the background.
+See JSON above. Returns immediately; watcher runs in background.
 
-### 3. Confirm it's live
+### 3. Confirm active watches
 
 ```
-mcp__memtrace__list_watched_paths
+list_watched_paths()
 ```
 
-Each entry shows the watched root, the bound repo_id, and the last delta's `persist_ms`.
+Response shape: see [Output](#output).
 
-### 4. Edit normally — Memtrace catches up
+### 4. Edit normally
 
-After every save the watcher emits a `labels_updated` WebSocket event:
+Next `find_symbol` / `get_symbol_context` call sees saved changes after debounce (~500 ms) + incremental persist (~80 ms).
 
-```json
-{
-  "event":           "labels_updated",
-  "repo_id":         "demo",
-  "nodes_changed":   12,
-  "persist_ms":      78,
-  "timestamp":       "2026-04-27T10:42:13Z"
-}
-```
+### 5. Stop watching (kill switch)
 
-Dashboards and IDE plugins subscribe to this on `/ws` and refresh themselves. As an agent you don't have to listen — your next `find_symbol` / `find_code` / `get_symbol_context` call will see the new state automatically.
+`unwatch_directory`:
 
-### 5. Stop watching
-
-```
-mcp__memtrace__unwatch_directory(path: "/abs/path/to/repo")
+```json
+{ "path": "/abs/path/to/repo" }
 ```
 
 Idempotent — unwatching an already-unwatched path is a no-op.
 
-## When to Use
+## Latency expectations
 
-- **Long sessions on the same repo** — keeps `get_symbol_context` accurate without rerunning `index_directory`
-- **Pair programming with an IDE plugin** — the dashboard's WebSocket subscription auto-refreshes panels
-- **Demo / live coding** — every save reflects in the graph within 80–150 ms
-- **Long-running agents** — instead of polling `index_directory`, the watcher pushes deltas
-
-## When NOT to Use
+| Stage | Typical |
+|---|---|
+| Debounce | **500 ms** (MCP schema) |
+| Incremental persist | ~80 ms |
+| Save → queryable | ~80–150 ms after debounce |
 
-- **One-shot batch edits** — running `index_directory --incremental` at the end is cheaper than spinning up a watcher
-- **Generated / build output trees** — exclude paths under `target/`, `dist/`, `node_modules/` (the watcher honours common ignore patterns but a noisy build can still saturate the debounce queue)
-- **CI / containerised runs** — file events are unreliable across container boundaries; index explicitly instead
+## Output
 
-## Latency Expectations
+`watch_directory` returns an immediate acknowledgment; the watcher runs in the background. `list_watched_paths` returns:
 
-| Operation | Typical wall time |
-|---|---|
-| File save → watcher fires | < 5 ms |
-| Debounce window | 50 ms |
-| Incremental parse + delta persist | ~80 ms |
-| `labels_updated` broadcast | < 1 ms after persist |
-| Total: save → queryable | ~80–150 ms |
+```json
+{
+  "watches": [
+    { "path": "...", "repo_id": "...", "branch": "...", "started_at": "...", "origin": "..." }
+  ],
+  "count": 1
+}
+```
 
-If you see `persist_ms` consistently above 500 ms, the saved files are larger than expected (e.g., generated bundles) — narrow the watch root or add ignore patterns.
+There is **no `persist_ms`** field in this response.
 
 ## Common Mistakes
 
 | Mistake | Reality |
-|---|---|
-| Calling `watch_directory` on an unindexed repo | Returns an error — run `index_directory` first |
-| Watching `node_modules/` or `target/` | Saturates the watcher with build noise — point at the source root only |
-| Polling `find_symbol` every second to "wait" for indexing | Subscribe to the `labels_updated` WS event, or just call once after the save — the delta is already there |
-| Forgetting to `unwatch_directory` between sessions | Watchers are per-process; restarting `memtrace start` wipes them, but for hosted instances unwatching cleanly avoids leaks |
+|---------|---------|
+| `watch_directory(path=...)` without `repo_id` | **Both required** |
+| Watching unindexed repo | Index first |
+| Expecting `persist_ms` from `list_watched_paths` | Field not in MCP response |
+| Debounce "50 ms" | Schema documents **500 ms** |

package/skills/workflows/memtrace-decision-memory.md

@@ -0,0 +1,139 @@
+---
+name: memtrace-decision-memory
+description: "Check Cortex decision memory — the umbrella entry point for decision recall, provenance (why is this here), intent verification, and governing contracts. Use before assuming WHY code exists, before making a choice that may contradict a past one, or before deleting/rewriting code that looks odd or redundant. Route: free-text what-was-decided → memtrace-decision-recall; why does this symbol exist / what constrains it → memtrace-provenance; did the decision hold → memtrace-intent-verification. Do not guess rationale from the diff or git log; Cortex remembers the decision, the ban, and whether it still holds."
+allowed-tools:
+  - mcp__memtrace__recall_decision
+  - mcp__memtrace__why_is_this_here
+  - mcp__memtrace__verify_intent
+  - mcp__memtrace__get_arc
+  - mcp__memtrace__governing_contracts
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+# Decision Memory First
+
+## The Iron Law
+
+```
+BEFORE you assume why code exists, contradict a convention, re-pick a settled
+choice, or delete code that "looks unused/weird" → CHECK DECISION MEMORY.
+
+recall_decision(free-text)  →  what did we decide / ban about X?
+why_is_this_here(symbol_id) →  what decision put this here?
+verify_intent(decision_id)  →  did that decision still hold, or was it violated?
+get_arc(decision_id)        →  what episodes implemented it?
+governing_contracts(sym_id) →  what constraints bind this symbol?
+```
+
+This is the **rationale layer** of the codebase. `memtrace-first` answers *what the
+code is and how it's wired* (symbols, calls, git, blast radius). Decision memory
+answers *why it is the way it is, what we already decided, and whether that decision
+still holds* — extracted from real coding conversations and decisions, not the AST.
+
+The graph can tell you a function exists and who calls it. Only decision memory can
+tell you that three weeks ago you **banned** the approach you're about to reintroduce.
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
+## The honesty contract — read this first
+
+These five tools are **deterministic, zero-LLM**. Every call returns a labeled
+**Verdict / Evidence / CannotProve** answer carrying its FactStatus and proof path.
+**No tool ever fabricates an answer.**
+
+| Answer | What it means | What you must NOT do |
+|---|---|---|
+| **Verdict + Evidence** (Observed / DeterministicallyDerived / StatisticallyRanked) | A recorded decision/provenance backs this | — |
+| **CannotProve** | No recorded decision governs this | Do **not** read it as "safe / approved / unconstrained." It means *unknown*, not *permitted*. Fall back to `memtrace-first` + asking the user. |
+
+`CannotProve` is a real, trustworthy answer ("memory has nothing on this"), not a
+failure and not a green light. Never invent a rationale to fill the gap.
+
+## Server check (once per session)
+
+These tools are served by the **`memcortex`** MCP server (decision memory), separate
+from the `memtrace` code-graph server. If `recall_decision` isn't available, decision
+memory isn't wired in this environment — say so and use `memtrace-first` instead;
+don't fabricate decisions.
+
+## The decision rule
+
+| What you're about to do / be asked | Right tool | Sub-skill |
+|---|---|---|
+| "Did we already decide/choose/reject X?" "What's our convention on Y?" | `recall_decision("X")` | `memtrace-decision-recall` |
+| "Is there a ban / a 'don't do this' on Z?" | `recall_decision("Z")` — bans surface as decisions | `memtrace-decision-recall` |
+| About to re-pick a library/pattern/approach | `recall_decision` FIRST — don't re-litigate a settled call | `memtrace-decision-recall` |
+| "Why is this code here?" "Why is it done this odd way?" | `why_is_this_here(symbol_id)` | `memtrace-provenance` |
+| About to delete/refactor code that looks unused or strange | `why_is_this_here` + `governing_contracts` before touching it | `memtrace-provenance` |
+| "What rules/contracts constrain this symbol?" | `governing_contracts(symbol_id)` | `memtrace-provenance` |
+| "Did decision D actually hold, or did we drift?" | `verify_intent(decision_id)` | `memtrace-intent-verification` |
+| "What commits/episodes implemented decision D?" | `get_arc(decision_id)` | `memtrace-intent-verification` |
+
+## How the tools chain (ids come from recall, not from names)
+
+Only `recall_decision` takes free text. The other four take **numeric node ids**
+(`decision_id` / `symbol_id`, uint64). The normal flow is:
+
+```
+recall_decision("auth strategy")
+        │  returns ranked hits, decisions first: [{ id, kind: "decision", ... }]
+        │  (pick a kind:"decision" hit; conversation hits are context, not chainable)
+        ├─► verify_intent(decision_id)   did it hold?
+        └─► get_arc(decision_id)         what implemented it?
+
+why_is_this_here(symbol_id)
+        │  returns the governing decision lineage for a symbol
+        └─► verify_intent(that decision_id)   is that rationale still valid?
+```
+
+`symbol_id` comes from a prior recall/arc result or the Cortex view — **if you only
+have a name or a free-text question, start with `recall_decision`.** Do not invent ids.
+
+## Standard workflows
+
+### "Why does this code exist / can I delete it?"
+1. `why_is_this_here(symbol_id)` → the governing decision, if any
+2. `governing_contracts(symbol_id)` → constraints that must survive a rewrite
+3. If a decision governs it → `verify_intent(decision_id)` to see if it still holds
+4. **CannotProve on all three ≠ safe to delete** — confirm with `memtrace-impact` (blast radius) and the user
+
+### "Should I do X?" (about to make a choice)
+1. `recall_decision("X")` → did we already decide or ban this?
+2. If a prior decision exists → `verify_intent(decision_id)` → is it still in force?
+3. Honor a held decision; only revisit a `ViolatedAt`/superseded one — and say so explicitly
+
+### "Did we follow through on decision D?"
+1. `verify_intent(decision_id)` → Held | ViolatedAt | CannotProve
+2. `get_arc(decision_id)` → the episodes that implemented (or should have) it
+
+## Red flags — STOP, check decision memory
+
+| Thought | Reality |
+|---|---|
+| "This code looks unused, I'll delete it" | `why_is_this_here` first — a decision may govern it; deletion may reopen a closed issue |
+| "I'll just use library/pattern X" | `recall_decision("X")` — you may be undoing a deliberate ban |
+| "The diff/git log will tell me why" | Git shows *what changed*, not *what was decided or rejected*. Decision memory has the rationale and the bans. |
+| "CannotProve, so it's fine/approved" | CannotProve = unknown, not approved. Don't treat absence of a record as permission. |
+| "I'll guess the rationale from the code" | Don't fabricate a why. Return what the tool proves, or say it's unknown. |
+
+## Skill priority
+
+This is a **process skill** — it runs alongside `memtrace-first` before
+implementation. Use `memtrace-first` for *what/where/impact* (code graph); use
+decision memory for *why/whether-it-held* (rationale). When both apply, decision
+memory gates the intent, the code graph gates the mechanics.
+
+## Output
+
+The routing outcome: which sibling skill/tool to invoke, and the evidence to quote.
+
+```
+Ask:    "Should I switch to library X?"
+Route:  recall_decision("library X")   →  memtrace-decision-recall
+Hit:    { id: 4217, kind: "decision", ... }   (a ban exists)
+Next:   verify_intent(4217)            →  memtrace-intent-verification
+Quote:  Verdict + Evidence (FactStatus, proof path) — or CannotProve = unknown, not permission
+```

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

@@ -1,100 +1,124 @@
 ---
 name: memtrace-episode-replay
-description: "Always use to replay source-code evolution, understand why code looks this way, inspect implementation attempts, reversions, past reasoning, or abandoned approaches across commits and working-tree episodes. Do not use git log, git diff, Grep, or manual history reconstruction; Memtrace has episodic symbol replay."
+description: "Replay the graph diff of one episode — a single git commit or working-tree save — to inspect what it changed: added/modified/removed symbols and edges. Use when the user asks what one commit or save changed in the graph, why code looks this way, or wants to inspect implementation attempts, reversions, past reasoning, or abandoned approaches across commits and working-tree episodes. Do not use git log or Grep for graph-level episode diffs; Memtrace replays indexed episode records. Do NOT use for module-level summaries or date-range change history — use memtrace-evolution."
 allowed-tools:
   - mcp__memtrace__get_episode_replay
+  - mcp__memtrace__get_evolution
   - mcp__memtrace__get_timeline
-  - mcp__memtrace__find_symbol
-  - mcp__memtrace__list_indexed_repositories
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 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.
+Replay the graph diff for **one episode** (a single git commit or working-tree save). Shows which nodes/edges were added, modified, or removed in that episode — not a multi-episode time-range narrative.
 
-**Git shows A→B. Episode replay shows every step in between.**
+Use `get_evolution(mode: "recent")` to **find** episode IDs and timestamps, then drill into a specific episode with this tool.
 
-This is the only tool that can answer: "why does this code look like this?" without relying on commit messages or comments.
+## Episode selector — pick one
 
-## Steps
+| Approach | Parameters |
+|---|---|
+| Known episode UUID | `episode_id` |
+| Newest episode in repo | `repo_id` + `episode_index: 0` |
+| Nth newest | `repo_id` + `episode_index: N` |
 
-### 1. Identify the symbol and time window
+**There is no `from` / `to` / `include_working_tree` on this tool.**
 
-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)
+## Optional filters (large commits)
 
-If you don't know the window, call `get_timeline` first to find when the symbol changed.
+| Param | Purpose |
+|---|---|
+| `symbol` | Scope to one symbol name |
+| `file_path` | Substring filter on record paths |
+| `kind` | e.g. `"Function"`, `"CALLS"` |
+| `mode` | `"graph_summary"` for digest on huge commits |
+| `compress` | default `true` — collapse identical-hash modifications |
+| `limit` / `cursor` | Pagination per bucket (default limit 200) |
 
-### 2. Call `get_episode_replay`
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
-```
-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
-)
-```
+## Steps
 
-### 3. Read the narrative_hint sequence
+### 1. Find the episode to inspect
 
-Each episode has a `narrative_hint` — derived automatically from AST hash patterns:
+From `get_evolution`:
 
-| 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 |
+```json
+{ "repo_id": "memdb", "from": "7d ago", "mode": "recent", "limit": 20 }
+```
 
-### 4. Reconstruct the implementation story
+Each entry has `episode` metadata including `id` (use as `episode_id`) and `reference_time`.
 
-Read the sequence like a narrative:
+Or use `episode_index: 0` for the newest episode without knowing the UUID.
 
-```
-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"
-```
+### 2. Call `get_episode_replay`
 
-The gap between `committed` entries is the implementation story.
+By episode UUID:
+
+```json
+{
+  "episode_id": "550e8400-e29b-41d4-a716-446655440000",
+  "symbol": "execute",
+  "file_path": "src/order/service.rs",
+  "kind": "Function",
+  "compress": true,
+  "limit": 200
+}
+```
 
-### 5. Identify what to act on
+Newest episode, summary first on large commits:
 
-| 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 |
+```json
+{
+  "repo_id": "memdb",
+  "episode_index": 0,
+  "mode": "graph_summary"
+}
+```
 
-## When to Use
+### 3. Interpret the response
 
-- **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
+| Field | Meaning |
+|---|---|
+| `found` | `false` if episode missing — check `_note` |
+| `totals` | Counts: `nodes_added/modified/removed`, `edges_*` |
+| `nodes_added[]` etc. | Per-record diffs (paginated) |
+| `page.next_cursor` | More records remain — pass as `cursor` |
+
+For symbol history **across many episodes**, use `get_timeline` instead:
+
+```json
+{
+  "repo_id": "memdb",
+  "scope_path": "OrderService.execute",
+  "file_path": "src/order/service.rs"
+}
+```
 
-## Compression
+## Output
 
-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.
+`get_episode_replay` returns the buckets interpreted in step 3:
 
-With `compress: false`, every single save is shown — useful when you want to see exact timing between saves.
+```json
+{
+  "found": true,
+  "totals": { "nodes_added": 3, "nodes_modified": 12, "nodes_removed": 1, "edges_added": 7, "edges_removed": 2 },
+  "nodes_added": [ /* per-record diffs, paginated per bucket */ ],
+  "nodes_modified": [ /* … */ ],
+  "edges_removed": [ /* … */ ],
+  "page": { "next_cursor": 200 }
+}
+```
 
 ## 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 |
+| Passing `from` / `to` time window | Not supported — one episode per call |
+| Expecting `narrative_hint` / `attempted_and_reverted` | Not in API — inspect added/modified/removed buckets |
+| Unfiltered replay on 10k-symbol commits | Use `kind`, `file_path`, `symbol`, or `mode: "graph_summary"` first |
+| Using this for "what changed last week?" or module summaries | Use memtrace-evolution — `get_evolution(from=..., mode: recent)` — to list episodes |

package/skills/workflows/memtrace-first.md

@@ -1,6 +1,35 @@
 ---
 name: memtrace-first
-description: "Always use first for indexed source-code repos before searching files, reading code for discovery, debugging, tracing flows, finding implementations, understanding behavior, or answering how code works. Do not use Grep, Glob, rg, find, or manual file browsing for code discovery when Memtrace is indexed. Zero results, missing languages, or partial-looking stats are not permission to grep; diagnose/reindex with Memtrace."
+description: "Route code discovery, debugging, flow tracing, and how-code-works questions in indexed source-code repos to Memtrace graph tools. Use first — before searching files, reading code for discovery, debugging, tracing flows, finding implementations, understanding behavior, or answering how code works. Do not use Grep, Glob, rg, find, or manual file browsing for code discovery when Memtrace is indexed. Zero results, missing languages, or partial-looking stats are not permission to grep; diagnose/reindex with Memtrace."
+allowed-tools:
+  - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__index_directory
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__find_code
+  - mcp__memtrace__get_symbol_context
+  - mcp__memtrace__get_impact
+  - mcp__memtrace__analyze_relationships
+  - mcp__memtrace__get_process_flow
+  - mcp__memtrace__list_communities
+  - mcp__memtrace__find_central_symbols
+  - mcp__memtrace__find_api_endpoints
+  - mcp__memtrace__find_api_calls
+  - mcp__memtrace__get_service_diagram
+  - mcp__memtrace__get_api_topology
+  - mcp__memtrace__find_dependency_path
+  - mcp__memtrace__get_cochange_context
+  - mcp__memtrace__get_evolution
+  - mcp__memtrace__get_changes_since
+  - mcp__memtrace__get_style_fingerprint
+  - mcp__memtrace__find_most_complex_functions
+  - mcp__memtrace__get_source_window
+  - Read
+  - Grep
+  - Glob
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 ---
 
 # Memtrace First
@@ -19,7 +48,7 @@ the whole file when Memtrace has given you exact lines.
 
 Memtrace is the **memory layer** of the codebase, not a search engine that returns code. It has the full knowledge graph — every symbol, call, import, community, process, and API — with a time dimension. The point is to navigate that graph: who calls this, what's the blast radius, when did this change, what community is it part of. File tools are blind to all of that.
 
-**97% better accuracy. 83% fewer wasted tokens. No exceptions for what's in the graph.**
+**No exceptions for what's in the graph.**
 
 ## Value Tracking
 
@@ -68,13 +97,13 @@ For everything else inside the indexed repo, memtrace is the right tool.
 | Question Claude is asking | Right tool |
 |---|---|
 | "Where is symbol `foo` defined?" | `find_symbol(name="foo")` → then `get_symbol_context` for callers/callees/community, NOT a source read unless you're editing. |
-| "What calls `foo`?" | `get_symbol_context(name="foo")` → callers with file:line each. |
+| "What calls `foo`?" | `get_symbol_context(repo_id, symbol="foo")` → callers with file:line. |
 | "How does authentication work?" | `find_code(query="authentication")` → `get_symbol_context` on the top hit, NOT a source read. |
 | "Find behavior X" with multi-word phrase (3+ words) | `find_code(verbatim)` first; if low confidence, fan out with identifier-shaped reshapes (camelCase / snake_case). |
 | "Find the function that uses `STRIPE_KEY_FOO_BAR`" | `find_code(query="STRIPE_KEY_FOO_BAR")` → semantic finds it inside any embedded body. |
 | "Where's that error message `'connection refused for tenant'`?" | `find_code(query="connection refused for tenant")` → semantic catches it. |
-| "What breaks if I change `foo`?" | `get_impact(name="foo")` → blast radius with file:line. |
-| "What changed in `auth.ts` last week?" | `get_evolution(file_path="auth.ts", from="7d ago")`. |
+| "What breaks if I change `foo`?" | `get_impact(repo_id, target="foo")` → blast radius. |
+| "What changed in `auth.ts` last week?" | `get_evolution(repo_id, from="7d ago", mode="recent", file_path="auth.ts")`. |
 | "List all `*.test.ts` files." | `Glob` (file inventory, not symbol search). |
 | "Find this string in my `.env`." | `Grep` (non-source artifact). |
 | "I'm about to edit `foo` — show me its source." | Bounded `Read(file_path, offset=start_line, limit=end_line-start_line+8)`, or `get_source_window` if your harness lacks bounded reads. Never whole-file. |
@@ -89,9 +118,18 @@ All memtrace MCP tools are **strictly typed**. Pass JSON numbers (not strings) f
 | `limit`, `min_size`, `depth`, `max_depth`, `last_n` | `limit: 20` | `limit: "20"` |
 | `repo_id`, `branch`, `name`, `symbol_name`, `query` | `repo_id: "my-repo"` | `repo_id: my-repo` (unquoted) |
 | `fuzzy`, `include_tests`, `invalidate` | `fuzzy: true` | `fuzzy: "true"` |
+| `get_evolution.from` | `from: "90d ago"` | `days: 90` (wrong param — use `from`, not `days`) |
+| `get_changes_since.since` | `since: "2026-04-13T10:43:00Z"` | `last_episode_id: "..."` (wrong param) |
+| `get_impact.target` / `get_symbol_context.symbol` | `target: "foo"` / `symbol: "foo"` | `symbol_id: "..."` (wrong — use name) |
+| `find_most_complex_functions` | `top_n: 10` | `limit: 10` (wrong param name) |
+| `get_cochange_context` | `target: "execute"` | `symbol: "execute"` (wrong param name) |
 
 If you see `failed to deserialize parameters: invalid type: string "N", expected usize`, remove the quotes from the number and retry.
 
+If you see `missing field 'from'`, you called `get_evolution` without `from` — pass e.g. `"90d ago"`, never `days`.
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
 ## Check Indexing First (Once Per Session)
 
 ```
@@ -136,8 +174,8 @@ If not indexed → offer to index with `mcp__memtrace__index_directory`, then fo
 1. `find_symbol` → locate the broken thing
 2. `get_symbol_context` → understand its role
 3. `get_impact` → blast radius (what else breaks)
-4. `get_evolution` → what changed recently (mode: `recent`)
-5. `get_changes_since` → confirm timing vs incident
+4. `get_evolution(from=<lookback>, mode: recent)` → per-episode changelog near the incident
+5. `get_changes_since(since=<anchor>)` → catch-up since last session (requires stored `since` timestamp)
 
 ### "Where is X defined / called?"
 1. `find_symbol` with `fuzzy: true`
@@ -192,3 +230,21 @@ When this skill applies, it overrides default file-search behavior. Use the spec
 - Incident investigation → `memtrace-incident-investigation`
 - Architecture overview → `memtrace-codebase-exploration`
 - Refactoring → `memtrace-refactoring-guide`
+
+## Output
+
+`find_symbol` / `find_code` return ranked symbol entries (`score` only with `include_diagnostics: true`):
+
+```json
+{ "name": "handleAuth", "kind": "Function", "file_path": "src/auth.ts",
+  "start_line": 42, "end_line": 87 }
+```
+
+`get_symbol_context` returns the graph neighborhood: `symbol`, `callers`, `callees`, `type_references`, `community`, `processes`, `api_callers_cross_repo`. Feed `start_line`/`end_line` into a bounded `Read` or `get_source_window` — never a whole-file read.
+
+## Success criteria
+
+- The answer is grounded in Memtrace graph results (search hit → `get_symbol_context` / `get_impact`), not file-tool discovery.
+- Grep/Glob/Read appear only via the documented narrow exceptions (non-source artifacts, paths outside every indexed root, file inventory, bounded span reads).
+- Zero-result queries were diagnosed (`list_indexed_repositories` → broaden → reindex), not bypassed to grep.
+- Any source read was bounded to the span Memtrace returned.