memtrace 0.7.25 → 0.8.1

package/install.js

@@ -114,15 +114,18 @@ function platformPackageName(key) {
 }
 
 // npm only restores the executable bit for files declared in the platform
-// package's `bin` map (`memtrace`). `memcore-server` is shipped alongside it
-// WITHOUT a bin entry, so if the published tarball carries mode 644 (the
-// v0.6.16/v0.6.17 releases did — GitHub's artifact transfer strips modes),
-// `memtrace start` fails to spawn the sidecar with EACCES. Re-assert the bit
-// on every resolution so broken installs self-repair on the next run.
+// package's `bin` map (`memtrace`). The sidecars — `memcore-server` (code graph)
+// and, when bundled, `memcortex-daemon` + `memcortex-mcp` (Cortex decision
+// memory) — ship alongside it WITHOUT a bin entry, so if the published tarball
+// carries mode 644 (the v0.6.16/v0.6.17 releases did — GitHub's artifact
+// transfer strips modes), `memtrace start` fails to spawn the sidecar with
+// EACCES. Re-assert the bit on every resolution so broken installs self-repair
+// on the next run. Names not present in a given release are skipped (existsSync),
+// so listing the Cortex sidecars here is safe before they are bundled.
 function ensureExecutableBits(binaryPath) {
   if (os.platform() === "win32") return;
   const dir = path.dirname(binaryPath);
-  for (const name of ["memtrace", "memcore-server"]) {
+  for (const name of ["memtrace", "memcore-server", "memcortex-daemon", "memcortex-mcp"]) {
     const candidate = path.join(dir, name);
     try {
       if (fs.existsSync(candidate)) fs.chmodSync(candidate, 0o755);

package/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace-skills",
-  "version": "0.7.25",
+  "version": "0.8.1",
   "description": "Memtrace skills for AI coding agents — codebase exploration, temporal evolution, impact analysis, and more.",
   "type": "module",
   "bin": {

package/installer/skills/commands/memtrace-api-topology.md

@@ -1,65 +1,62 @@
 ---
 name: memtrace-api-topology
-description: "Always use for API endpoint, HTTP route, fetch/client call, REST surface, service dependency, cross-repo dependency, or API topology questions in source code. Do not use Grep, Glob, rg, find, or manual file search for routes or HTTP calls; Memtrace maps endpoints and call edges from the indexed AST graph."
+description: "Map API endpoints, outbound HTTP calls, and cross-repo service topology in indexed source code. Use when the user asks about API endpoints, HTTP routes, fetch/client calls, REST surface, service dependencies, cross-repo dependencies, or API topology. Do not use Grep, Glob, rg, find, or manual file search for routes or HTTP calls; Memtrace maps endpoints and call edges from the indexed AST graph."
 allowed-tools:
   - mcp__memtrace__get_api_topology
   - mcp__memtrace__find_api_endpoints
   - mcp__memtrace__find_api_calls
   - mcp__memtrace__get_symbol_context
   - mcp__memtrace__link_repositories
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
 ---
 
 ## Overview
 
-Map the HTTP API surface of a codebase — exposed endpoints, outbound HTTP calls, and cross-repo service-to-service dependency graphs. Supports auto-detection for Express, Encore, NestJS, Axum, FastAPI, Flask, Gin, Spring Boot, and more.
+Map HTTP API surface — endpoints, outbound calls, cross-repo topology.
 
 ## Quick Reference
 
-| Tool | Purpose |
-|------|---------|
-| `find_api_endpoints` | All exposed HTTP endpoints (GET /users, POST /orders, etc.) |
-| `find_api_calls` | All outbound HTTP calls (fetch, axios, reqwest, etc.) |
-| `get_api_topology` | Cross-repo call graph: which service calls which endpoint |
-| `link_repositories` | Manually link repos for cross-repo edge detection |
-
-> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+| Tool | Required | Key optional |
+|------|----------|--------------|
+| `find_api_endpoints` | `repo_id` | `method`, `path_contains`, `limit`, `branch` |
+| `find_api_calls` | `repo_id` | `method`, `path_contains`, `limit`, `branch` |
+| `get_api_topology` | — | `repo_id`, `min_confidence`, `include_external` |
 
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
 ## Steps
 
-### 1. Discover endpoints
-
-Use `find_api_endpoints`:
-- `repo_id` — required
-- Returns: method, path, handler function, framework detected
-
-### 2. Discover outbound calls
+### 1–3. Endpoints, calls, topology
 
-Use `find_api_calls`:
-- `repo_id` — required
-- Returns: target URL/path, HTTP method, calling function, library used (fetch, axios, reqwest, etc.)
+```json
+{ "repo_id": "memdb" }
+{ "repo_id": "memdb", "method": "GET", "path_contains": "/users" }
+{ "min_confidence": 0.7 }
+```
 
-### 3. Map service topology
+### 4. Deep-dive an endpoint handler
 
-Use `get_api_topology` to see the cross-repo HTTP call graph:
-- Which services call which endpoints
-- Confidence scores for each detected link
-- Service-to-service dependency direction
+Use handler **symbol name** — not symbol ID:
 
-**Prerequisite:** Multiple repos must be indexed. If cross-repo links aren't appearing, use `link_repositories` to explicitly connect them.
+```json
+{ "repo_id": "memdb", "symbol": "handleGetUsers" }
+```
 
-### 4. Deep-dive into an endpoint
+## Output
 
-For any specific endpoint, use `get_symbol_context` with the endpoint's symbol ID to see:
-- Which internal functions handle the request
-- Which processes (execution flows) include this endpoint
-- Which external services call this endpoint
+| Result | Carries |
+|--------|---------|
+| Endpoint entry (`find_api_endpoints`) | HTTP method, route path, handler symbol name (feed to `get_symbol_context` as `symbol`) |
+| Call entry (`find_api_calls`) | HTTP method, target path, calling symbol |
+| Topology edge (`get_api_topology`) | caller repo → handler repo, confidence 0.0–1.0 (edges below `min_confidence` dropped) |
 
 ## Common Mistakes
 
 | Mistake | Reality |
 |---------|---------|
-| Expecting cross-repo links with only one repo indexed | Index ALL related services first; cross-repo HTTP edges are linked automatically after indexing |
-| Missing endpoints from custom frameworks | Memtrace auto-detects major frameworks; for custom routers, the endpoints may appear as regular functions |
-| Not using `link_repositories` | If auto-linking missed a connection, use this to manually establish cross-repo edges |
+| `get_symbol_context(symbol_id=...)` | Use **`symbol`** (name) + `repo_id` |
+| Cross-repo links with one repo indexed | Index all services; use `link_repositories` if needed |

package/installer/skills/commands/memtrace-cochange.md

@@ -1,66 +1,93 @@
 ---
 name: memtrace-cochange
-description: "Always use for historical coupling, co-change, what changes with this, hidden dependency, or what else needs to move questions for source code. Do not use git log, git diff, Grep, or manual file search to correlate changes; Memtrace queries co-change and temporal graph data directly."
+description: "Find files that historically co-change with a target symbol or file, ranked by co-occurrence across git episodes. Use when the user asks about historical coupling, co-change, what changes with this, hidden dependencies, or what else needs to move for source code. Do not use git log, git diff, Grep, or manual file search to correlate changes; Memtrace queries co-change and temporal graph data directly."
 allowed-tools:
   - mcp__memtrace__get_cochange_context
   - mcp__memtrace__find_symbol
   - mcp__memtrace__get_impact
+  - mcp__memtrace__replay_history
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 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.
+Find **files** that historically co-change with a target symbol or file path — ranked by co-occurrence frequency across git episodes. Surfaces **behavioral coupling** 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.
+`get_cochange_context` answers "what files always move when this moves?" (historical, file-level).
+
+They are complementary. A file with no call-graph edges to the target can still be a strong cochange partner if it's always modified alongside it in every commit.
+
+> **Parameter types:** Numbers (`limit`, `window_days`, etc.) must be JSON numbers — not strings.
+
+## Required parameters
+
+| Parameter | Required | Default | Notes |
+|---|---|---|---|
+| `repo_id` | yes | — | |
+| `target` | yes | — | Symbol name **or** file path substring — **not** `symbol` |
+| `limit` | no | **10** | Max cochanged files returned |
+| `window_days` | no | **30** | Lookback from `as_of` |
+| `as_of` | no | now | Window anchor |
+| `branch` | no | any branch | |
+
+```json
+{
+  "repo_id": "memdb",
+  "target": "execute",
+  "limit": 10,
+  "window_days": 30
+}
+```
 
-> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
+## Output
+
+```json
+{
+  "cochanged_files": [
+    {
+      "file_path": "src/order/types.rs",
+      "cochange_count": 8,
+      "last_cochanged_at": "2026-04-13T10:43:00Z"
+    }
+  ],
+  "target_files": ["src/order/service.rs"]
+}
+```
 
+There is **no** `cochanges[]` with symbol names — results are **file-level**.
 
 ## Steps
 
-### 1. Identify the target symbol
+### 1. Identify the target
 
-Use `find_symbol` if you need the exact name. The tool matches by `name` field.
+Use `find_symbol` if needed. Pass the symbol **`name`** or a **`file_path`** as `target`.
 
 ### 2. Call `get_cochange_context`
 
-```
-get_cochange_context(
-  repo_id: "...",
-  symbol: "execute",    // exact symbol name
-  limit: 20             // default 20, increase for broader view
-)
-```
+See required parameters above.
 
 ### 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
-```
+High `cochange_count` on a file → strong historical coupling. When you modify the target, review those files too — even without direct call-graph edges.
 
 ### 4. Cross-reference with call graph
 
-For the top cochange partners, optionally run `get_impact` to see if the coupling is also structural:
+For symbols in cochanged files, optionally run `get_impact(target=...)`:
 
 | 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 |
+| Yes | Yes | Core dependency — highest risk |
+| No | Yes | Hidden coupling — history-only |
+| Yes | No | Called often but changed independently |
 
-## When to Use
+## Use Cases
 
 - **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
@@ -72,5 +99,9 @@ For the top cochange partners, optionally run `get_impact` to see if the couplin
 | 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. |
+| Ignoring cochanged files with no call-graph edges | A rarely-called file with high `cochange_count` is a strong coupling signal |
+| Using cochange as a dependency map | It's a change correlation, not a dependency graph — files can cochange without any direct relationship |
+| Passing `symbol:` | Required param is **`target`** |
+| Expecting `cochanges[]` with symbol names | Response is **`cochanged_files[]`** (file paths) |
+| Using `limit: 20` as default | API default is **10** |
+| Empty results with 0 git episodes | Run `replay_history` during indexing to populate co-change data |

package/installer/skills/commands/memtrace-daily.md

@@ -0,0 +1,73 @@
+---
+name: memtrace-daily
+description: "Orient at the start of a coding session, review what recently changed in a repository, and self-audit after completing work. Use when the user wants the daily briefing (what changed in the last 24h with complexity deltas), hotspots (complexity × churn refactor priorities), or a session review (clean/review/risky verdicts per editing session). For catching up after time away or resuming a prior session, use memtrace-session-continuity; daily is the last-24h briefing + hotspots + self-audit. Do not reconstruct recent activity from git log; Memtrace diffs the graph at save granularity."
+allowed-tools:
+  - mcp__memtrace__get_daily_briefing
+  - mcp__memtrace__find_hotspots
+  - mcp__memtrace__review_agent_sessions
+  - mcp__memtrace__preflight_check
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+user-invocable: true
+---
+
+## Overview
+
+Session bookends: orient before you start, audit before you finish. All
+three tools read the bi-temporal version history — every save is a change
+event with complexity deltas, so "what happened" includes "did it make the
+code better or worse".
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `get_daily_briefing` | Last 24h diffed at graph level: changed functions with complexity deltas, new functions, new endpoints, per-module distribution |
+| `find_hotspots` | Functions ranked by complexity × recent changes — the ordered refactor priority list |
+| `review_agent_sessions` | Editing sessions clustered by actor, judged clean / review / risky |
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+> (`window_hours`, `window_days`, `top_n`) must be JSON numbers.
+
+## Steps
+
+### 1. Orient at session start
+
+`get_daily_briefing` with `repo_id`. Read the summary first:
+- `net_cyclomatic_delta` positive → recent work added complexity; check
+  whether your task touches the same area before piling on.
+- `changed` rows with large positive deltas → recently-destabilised code;
+  prefer `preflight_check` before editing anything in that list.
+
+### 2. When the task is refactoring or cleanup
+
+`find_hotspots` — work the list top-down. A hotspot you simplify pays off
+on every future change; a complex-but-untouched function can wait.
+
+### 3. Self-audit before declaring work done
+
+`review_agent_sessions` and find YOUR session (newest, your agent id):
+- `clean` — done; state the verdict in your summary.
+- `review` — re-read your top_changes rows; justify each complexity
+  increase or simplify it.
+- `risky` — do not hand off yet. You added >30 net cyclomatic or touched
+  a >50-complexity function; extract helpers / flatten nesting first,
+  then re-run the review.
+
+## The standard a session should meet
+
+Net complexity delta ≤ 0 unless the task genuinely required new branching
+(new feature with new cases). "I left the code simpler than I found it"
+is verifiable here — verify it.
+
+## Output
+
+| Tool | Returns |
+|------|---------|
+| `get_daily_briefing` | summary with `net_cyclomatic_delta`; `changed` rows (function + complexity delta); new functions, new endpoints, per-module distribution |
+| `find_hotspots` | ranked list of functions scored by complexity × recent changes |
+| `review_agent_sessions` | per-session verdict (`clean` / `review` / `risky`) with `top_changes` rows and net cyclomatic delta |

package/installer/skills/commands/memtrace-decision-recall.md

@@ -0,0 +1,91 @@
+---
+name: memtrace-decision-recall
+description: "Recall ranked decisions, bans, and conventions from Cortex decision memory by free-text query. Use when the user asks what was decided, what was chosen or rejected, whether there's a convention/ban/policy on something, or before re-picking a library, pattern, or approach that may already be settled. Do not reconstruct past decisions from git log or guesswork. To verify whether a known decision held, use memtrace-intent-verification; for symbol-scoped decision lineage/contracts, use memtrace-provenance."
+allowed-tools:
+  - mcp__memtrace__recall_decision
+  - mcp__memtrace__verify_intent
+  - mcp__memtrace__get_arc
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+## Overview
+
+`recall_decision` is the **free-text entry point** to decision memory. Given a query,
+it returns the statistically-ranked set of decisions/conversations that bear on it —
+including **bans** ("never use X", "don't do Y"), which are recorded as decisions.
+Use it before re-litigating a settled choice or contradicting a convention.
+
+This is the one decision-memory tool that takes plain text. The ranked decisions it
+returns carry the `decision_id`s the other tools (`verify_intent`, `get_arc`) need.
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `recall_decision` | Ranked decisions/bans for a free-text query (the entry point) |
+| `verify_intent` | Given a returned `decision_id` — did it still hold? (see `memtrace-intent-verification`) |
+| `get_arc` | Given a returned `decision_id` — what implemented it? (see `memtrace-intent-verification`) |
+
+> **Honesty contract:** an empty or unknown query returns an explicit **CannotProve**,
+> never a fabricated decision. CannotProve means "no recorded decision on this" — it is
+> *unknown*, not *approved*. Don't treat it as a green light.
+
+## Steps
+
+### 1. Query in the user's own terms
+
+`recall_decision(query)` — `query` is free text. Use the noun phrase of the thing in
+question: a library (`"redis vs in-memory cache"`), a pattern (`"error handling
+strategy"`), a subsystem (`"auth tokens"`), or the exact thing you're about to do.
+
+### 2. Read the ranked result
+
+Results come back ranked (lexical + semantic lanes, RRF-fused) with an `id`, a
+`kind`, and a score per hit. **`decision`-kind hits are ranked first**; lower-ranked
+`conversation` hits are supporting context (the verbatim turns around the decision).
+For anything you mean to chain (step 4), use a hit whose `kind` is `decision` — its
+`id` is the `decision_id` the other tools require.
+
+### 3. Act on what's there
+
+| Result | Action |
+|---|---|
+| A matching decision | Honor it. Quote it back to the user before doing anything that contradicts it. |
+| A **ban** ("never/don't …") | Do **not** reintroduce the banned approach without explicit user sign-off. |
+| Several competing/old hits | Run `verify_intent(decision_id)` on the top one to see if it still holds before relying on it. |
+| **CannotProve** | No recorded decision. Don't invent one — fall back to `memtrace-first` and/or ask the user. |
+
+### 4. Chain into the id-based tools when you need more
+
+The `id` of a `kind: "decision"` hit feeds `verify_intent` (did it hold?) and
+`get_arc` (what implemented it?). Don't pass a `conversation` hit's id — those tools
+require a Decision node and will honestly return CannotProve. See
+`memtrace-intent-verification`.
+
+## Decision Points
+
+| Situation | Action |
+|-----------|--------|
+| About to choose a library/pattern/approach | `recall_decision` FIRST — you may be undoing a deliberate choice or ban |
+| User asks "did we decide X?" / "what's our convention on Y?" | `recall_decision("X" / "Y")` |
+| You suspect a "don't do this" rule exists | `recall_decision` — bans are decisions and will surface |
+| Recall returns a decision you're about to contradict | Surface it to the user verbatim; don't silently override |
+| Recall returns CannotProve | Treat as unknown, not approval; do not fabricate a rationale |
+
+## Output
+
+`recall_decision` returns ranked hits — `kind: "decision"` first, `conversation` hits below as supporting context — or an explicit **CannotProve**:
+
+```json
+[
+  { "id": "…", "kind": "decision", "score": 0.91 },
+  { "id": "…", "kind": "conversation", "score": 0.44 }
+]
+```
+
+Only a `decision`-kind hit's `id` is a `decision_id` usable with `verify_intent` / `get_arc`. An empty or unknown query returns CannotProve, never fabricated hits.