memtrace 0.8.8 → 0.8.10

package/pi-package/skills/references/mcp-parameters.md

@@ -0,0 +1,358 @@
+# Memtrace MCP tool parameters — authoritative reference
+
+This file is the single source of truth for the name, type, required-ness,
+default, and constraint of every argument accepted by every Memtrace tool.
+It's generated from the underlying MCP server's `tools/list` schema. If
+you're wondering what to pass to a tool, check this table; if the live tool
+rejects a call, the validator error message here explains why.
+
+> **Naming note:** the Memtrace Pi extension registers every Memtrace MCP
+> tool as a native Pi tool named `memtrace_<name>` (e.g. the MCP tool
+> `get_impact` becomes the Pi tool `memtrace_get_impact`). This reference
+> uses the bare MCP name (`get_impact`) for every heading; prefix it with
+> `memtrace_` when calling the tool from Pi.
+
+## Zeroth rule — JSON types are strict
+
+The MCP validator does not coerce. `limit: "10"` is a type error even
+though "10" parses as a number. Rejection surfaces as:
+
+```
+MCP error -32602: invalid type: string "10", expected usize
+```
+
+Pass JSON numbers as numbers, booleans as booleans, strings as strings,
+arrays as arrays. No quoting numbers, no `"true"` for booleans.
+
+```json
+// CORRECT
+{ "repo_id": "my-repo", "depth": 3, "fuzzy": true, "include_tests": false }
+
+// WRONG — every one of these fails validation
+{ "repo_id": my-repo, "depth": "3", "fuzzy": "true", "include_tests": 0 }
+```
+
+## Conventions that appear across tools
+
+| Param | Type | Meaning |
+|---|---|---|
+| `repo_id` | string | Repository identifier from `list_indexed_repositories` (usually the repo folder name) |
+| `branch` *or* `branch_name` | string | Git branch. Default `"main"` across every tool. Both spellings occur historically — use whichever the specific tool's schema says |
+| `limit` | integer | Cap on returned results. Always a JSON number, never a string |
+| `depth` | integer | Graph traversal hops. 1–5 is reasonable; >8 explodes on wide graphs |
+| `target` / `symbol` | string | Symbol **name** for graph tools — `get_impact`/`analyze_relationships` use `target`; `get_symbol_context` uses `symbol` |
+| `from` / `to` / `since` / `until` | string | e.g. `"90d ago"`, `"2026-04-17T13:00:00Z"`, `"yesterday"` — relative strings work for temporal tools. **Never `days` on `get_evolution`.** |
+
+## Search & discovery
+
+### `find_code`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `query` | string | yes | — | Natural-language text |
+| `repo_id` | string | no | all repos | Scope to one repo |
+| `file_path` | string | no | — | Path substring filter |
+| `limit` | integer | no | `20` | Max 100 |
+| `as_of` | string | no | now | Time-travel search |
+| `include_diagnostics` | boolean | no | `false` | Include `id`, `score` in results |
+
+No `kind` param — use `find_symbol(kind=...)` instead.
+
+### `find_symbol`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `name` | string | yes | — | Exact or partial identifier |
+| `fuzzy` | boolean | no | `false` | Exact-match today; field kept for API parity |
+| `edit_distance` | integer | no | `2` | Max 2. Only used when `fuzzy: true` |
+| `repo_id` | string | no | all repos | |
+| `kind` | string | no | — | Same enum as `find_code` |
+| `file_path` | string | no | — | |
+| `limit` | integer | no | `10` | Capped at `50` |
+
+### `get_source_window`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `file_path` | string | yes | — | Use the path returned by Memtrace search/context tools |
+| `repo_id` | string | no | — | Helps resolve repo-relative and repo-prefixed paths |
+| `start_line` | integer | no | `1` | 1-based line number from a Memtrace result |
+| `end_line` | integer | no | `start_line` | 1-based line number from a Memtrace result |
+| `before_lines` | integer | no | `8` | Context before the span |
+| `after_lines` | integer | no | `24` | Context after the span |
+| `max_lines` | integer | no | `120` | Hard-capped at `400` |
+
+### `list_indexed_repositories`
+No parameters. Call once at session start to get `repo_id` values.
+
+## Relationships
+
+### `get_symbol_context`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+| `symbol` | string | yes | — |
+| `file_path` | string | no | — |
+| `branch` | string | no | `"main"` |
+| `as_of` | string | no | now |
+| `view` | string | no | `"live"` |
+
+Returns: symbol, callers, callees, type_references, community, processes, api_callers_cross_repo.
+
+### `analyze_relationships`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `target` | string | yes | — | Symbol name |
+| `query_type` | string enum | yes | — | `find_callers` \| `find_callees` \| `class_hierarchy` \| `overrides` \| `imports` \| `exporters` \| `type_usages` |
+| `depth` | integer | no | `3` | Max 10 |
+| `file_path` | string | no | — | Disambiguation hint |
+
+## Impact
+
+### `get_impact`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `target` | string | yes | — | Symbol name |
+| `direction` | string enum | no | `"both"` | `"upstream"` \| `"downstream"` \| `"both"` |
+| `depth` | integer | no | `5` | Max 15 |
+| `as_of` | string | no | now | |
+
+### `detect_changes`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `diff` | string | no ‡ | — | Unified git diff text |
+| `changed_files` | array of string | no ‡ | — | Alternative to `diff` |
+| `branch` | string | no | `"main"` | |
+
+‡ Exactly one of `diff` or `changed_files` must be provided.
+
+## Temporal
+
+### `get_evolution`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `from` | string | yes | — | Start of window. RFC3339, ISO date, epoch, or relative (`"7d ago"`, `"yesterday"`). **Never pass `days`.** |
+| `to` | string | no | now | End of window |
+| `mode` | string enum | no | `"recent"` | `"recent"` \| `"compound"` \| `"summary"` \| `"overview"` (alias for `summary`) |
+| `target` | string | no | — | Symbol name or file path substring scope |
+| `branch` | string | no | any branch | |
+| `file_path` | string | no | — | **`recent` mode only** — substring match on `touched_files` |
+| `kind` | string | no | — | **`recent` mode only** — `"git_commit"` or `"working_tree"` |
+| `limit` | integer | no | `100` | **`recent` mode only** — page size; `0` = server cap |
+| `cursor` | integer | no | `0` | **`recent` mode only** — pagination offset |
+
+**Response by mode:**
+- `recent` → `episodes[]`, `totals`, `page` (with `next_cursor`)
+- `compound` → `totals`, `top_changed_files`, `top_touched_symbols`
+- `summary` / `overview` → `totals`, `first_episode`, `last_episode`
+
+Modes **`impact`**, **`novel`**, **`directional`** are **not implemented**.
+
+### `get_timeline`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `scope_path` | string | yes | — | e.g. `"AuthService::validateToken"` |
+| `file_path` | string | yes | — | Containing file |
+| `branch` | string | no | `"main"` | |
+
+### `get_episode_replay`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `episode_id` | string | † | — | Episode UUID — preferred when known |
+| `repo_id` | string | † | — | Required with `episode_index` when `episode_id` omitted |
+| `episode_index` | integer | † | — | 0 = newest episode |
+| `branch` | string | no | any branch | Used with `episode_index` |
+| `symbol` | string | no | — | Optional filter — scope to one symbol |
+| `kind` | string | no | — | e.g. `Function`, `CALLS` — narrow large commits |
+| `file_path` | string | no | — | Substring filter on record paths |
+| `limit` | integer | no | `200` | Page size per bucket; `0` = no pagination |
+| `cursor` | integer | no | `0` | Pagination offset |
+| `mode` | string | no | default | `"graph_summary"` for digest on large commits |
+| `compress` | boolean | no | `true` | Collapse identical-hash modifications |
+
+† Supply `episode_id`, OR `repo_id` + `episode_index`.
+
+### `get_changes_since`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `since` | string | yes | — | Cutoff timestamp. Same formats as `get_evolution.from`. **Not** `last_episode_id`. |
+| `until` | string | no | now | Optional upper bound |
+| `branch` | string | no | any branch | |
+
+Returns `episodes[]` with per-episode change counts and `totals`. Store `until` (or latest episode `reference_time`) as the next session's `since` value.
+
+### `get_cochange_context`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `target` | string | yes | — | Symbol name or file path |
+| `window_days` | integer | no | `30` | Lookback from `as_of` |
+| `as_of` | string | no | now | Window anchor |
+| `branch` | string | no | any branch | |
+| `limit` | integer | no | `10` | Max cochanged files returned |
+
+Returns `cochanged_files[]` with `file_path`, `cochange_count`, `last_cochanged_at`.
+
+## Graph algorithms
+
+### `find_central_symbols`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `branch` | string | no | any branch | |
+| `kinds` | array of string | no | Function/Method/Class/… | |
+| `limit` | integer | no | `25` | Max 100. Always PageRank — no `method` param. |
+
+### `find_bridge_symbols`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `branch` | string | no | `"main"` | |
+| `limit` | integer | no | `15` | Max 50 |
+
+### `list_communities`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `branch` | string | no | `"main"` | |
+| `min_size` | integer | no | `3` | |
+| `limit` | integer | no | `50` | Max 200 |
+
+### `list_processes`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+| `branch` | string | no | `"main"` |
+| `limit` | integer | no | `50` |
+
+### `get_process_flow`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+| `process` | string | yes | — |
+| `branch` | string | no | `"main"` |
+
+### `find_dependency_path`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `source` | string | yes | — | Start symbol name |
+| `target` | string | yes | — | End symbol name |
+| `max_depth` | integer | no | `20` | Max 20 |
+| `edge_type` | string | no | calls+refs+… | Comma-separated or alias |
+
+## Quality
+
+### `get_repository_stats`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+| `branch` | string | no | `"main"` |
+
+### `find_dead_code`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `branch` | string | no | `"main"` | |
+| `include_tests` | boolean | no | `false` | |
+| `limit` | integer | no | `50` | |
+| `kinds` | array of string | no | all | Filter, e.g. `["Function","Method"]` |
+
+### `find_most_complex_functions`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+| `branch` | string | no | `"main"` |
+| `top_n` | integer | no | `20` |
+| `kinds` | array of string | no | Function+Method |
+
+### `calculate_cyclomatic_complexity`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+| `target` | string | yes | — |
+
+## API topology
+
+### `find_api_endpoints`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | The service that handles these endpoints |
+| `method` | string | no | — | HTTP method filter, e.g. `"GET"` |
+| `path_contains` | string | no | — | Substring filter, e.g. `"/users"` |
+| `branch` | string | no | `"main"` | |
+| `limit` | integer | no | `50` | |
+
+### `find_api_calls`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | The service making the calls |
+| `method` | string | no | — | |
+| `path_contains` | string | no | — | |
+| `branch` | string | no | `"main"` | |
+| `limit` | integer | no | `50` | |
+
+### `get_api_topology`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `min_confidence` | number (float) | no | `0.7` | 0.0–1.0 — threshold for cross-repo HTTP edges |
+| `include_external` | boolean | no | `false` | Include calls to services outside indexed repos |
+| `repo_id` | string | no | — | Omit for full cross-service topology |
+
+### `link_repositories`
+Connects already-indexed repos so `get_api_topology` can stitch their HTTP graphs. Parameters vary — see the `link_repositories` tool schema via `memtrace_status` / the live `tools/list` result.
+
+## Indexing
+
+### `index_directory`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `path` | string | yes | — | Absolute path to the repo root |
+| `repo_id` | string | no | directory name | |
+| `branch` | string | no | `"main"` | |
+| `incremental` | boolean | no | `false` | Re-index only changed files |
+| `clear_existing` | boolean | no | `false` | Wipe before indexing |
+| `skip_embed` | boolean | no | `false` | Skip the embedding stage |
+
+### `check_job_status`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `job_id` | string (UUID) | yes | — |
+
+### `delete_repository`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+
+### `watch_directory`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `path` | string | yes | — |
+| `repo_id` | string | yes | — |
+| `branch` | string | no | `"main"` |
+
+### `unwatch_directory`
+| Field | Type | Required |
+|---|---|---|
+| `path` | string | yes |
+
+### `list_watched_paths`
+No parameters. Returns `{ watches: [{ path, repo_id, branch, started_at, origin }], count }`.
+
+## Style
+
+### `get_style_fingerprint`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `file_path` | string | no | — | Scope the empirical sample to one file's language/area |
+
+## When this file is wrong
+
+It's drift-prone; tool schemas evolve with the Memtrace server. If a live
+tool call rejects with `-32602`, trust the error message and the live
+`tools/list` schema (call `memtrace_status`, then inspect the registered
+tool's parameters) over this doc.

package/pi-package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["extension/**/*.ts"]
+}