memtrace 0.7.24 → 0.8.0

package/README.md

@@ -1,383 +1,305 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/logo.svg" alt="Memtrace" width="100" height="100" />
-</p>
+# Memtrace
 
-<h1 align="center">Memtrace</h1>
+Code intelligence graph — an MCP server that builds a persistent knowledge graph from your codebase, enabling structural search, relationship analysis, temporal evolution tracking, and architectural understanding.
 
-<p align="center">
-  <strong>The persistent memory layer for coding agents.</strong><br/>
-  A bi-temporal, episodic, structural knowledge graph — built from AST, not guesswork.
-</p>
+## Quick Start
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/memtrace"><img src="https://img.shields.io/npm/v/memtrace?style=flat-square&color=00D4B8&label=npm" alt="npm version" /></a>
-  <a href="https://github.com/syncable-dev/memtrace-public/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Proprietary%20EULA-0A1628?style=flat-square" alt="license" /></a>
-  <a href="https://memtrace.io"><img src="https://img.shields.io/badge/docs-memtrace.io-00D4B8?style=flat-square" alt="docs" /></a>
-</p>
+Run once without installing anything globally:
 
-> **Early Access** — Memtrace is under active development. Core indexing and structural search are stable. Temporal features (evolution scoring, timeline replay) are functional but may have rough edges. [Report issues here.](https://github.com/syncable-dev/memtrace-public/issues)
-
----
-
-Memtrace gives coding agents something they've never had: **structural memory**. Not vector similarity. Not semantic chunking. A real knowledge graph compiled from your codebase's AST — where every function, class, interface, and API endpoint exists as a node with deterministic, typed relationships.
+```bash
+npx memtrace@latest start
+```
 
-Index once. Every agent query after that resolves through graph traversal — callers, callees, implementations, imports, blast radius, temporal evolution — in milliseconds, with zero token waste.
+Or pin Memtrace to one project so teammates use the same CLI version:
 
 ```bash
-npm install -g memtrace    # binary + 18 skills + MCP server — one command
-memtrace start             # launches the graph database and auto-indexes the current project
+npm install --save-dev memtrace
+npx memtrace start
 ```
 
-That's it. Run `memtrace start` from your project root — it spins up the graph database and kicks off indexing automatically. Claude, Cursor, Codex, Windsurf, VS Code/Copilot, Hermes, OpenCode, and Kiro pick up the skills/guidance and MCP tools automatically.
+Global install is still supported when you want the `memtrace` command available everywhere:
 
----
+```bash
+npm install -g memtrace
 
-## Why Memtrace Exists
+memtrace start
 
-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*.
+# Index your project
+memtrace index /path/to/your/project
 
-Memtrace is a **bi-temporal episodic structural knowledge graph**. It builds on that same AST foundation and adds two dimensions:
+# Start the MCP server (for direct use)
+memtrace mcp
+```
 
-- **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 across your architecture.
+After `npm install -g memtrace`, the installer automatically:
 
-On top of that, the structural layer is comprehensive:
+1. Installs the platform-specific memtrace binary
+2. Installs 18 Memtrace skills/workflows, or the provider's nearest native equivalent
+3. Registers the memtrace MCP server for supported agents
+4. Registers the `memtrace` marketplace from the public HTTPS Git source in `~/.claude/settings.json` for Claude auto-updates
+5. Enables the `memtrace-skills@memtrace` Claude plugin in `enabledPlugins`
+6. Attempts `claude plugin marketplace add` + `claude plugin install` via CLI if available
 
-- **Symbols are nodes** — functions, classes, interfaces, types, endpoints
-- **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, sub-8ms average query latency
+Skills are bundled inside the npm package — no network fetch needed during install. The GitHub marketplace registration enables Claude to discover plugin updates automatically.
 
-The agent doesn't just search your code. It *remembers* it.
+**No manual configuration needed** for Claude, Cursor, Codex, Windsurf, VS Code/Copilot, Hermes, OpenCode, or Kiro — just install or run with `npx`, then start exploring your codebase with your agent.
 
-## Benchmarks
+## Claude Code Setup
 
-All four systems run on the same machine, same mempalace checkout, same 1,000 queries, same evaluator. Ground truth is extracted by Python's stdlib `ast` module — **not** from any tool's index — so no system gets a home-field advantage. Full reproduction scripts and raw results: [`benchmarks/fair/`](https://github.com/syncable-dev/memtrace-public/tree/main/benchmarks/fair).
+The `npm install -g memtrace` command handles everything automatically. It registers the marketplace, installs the plugin, adds the MCP server, and writes skills to `~/.claude/skills/`.
 
-<img alt="Benchmark overview: Memtrace 96.7% Acc@1, 100% Acc@10, 9.16ms latency, 195 tokens — vs ChromaDB, GitNexus, CodeGrapher" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/benchmark-overview.svg" width="720"/>
+If you need to set it up manually, run these three commands:
 
-### Results (1,000 Python symbol-lookup queries on mempalace)
+```bash
+# 1. Register the memtrace marketplace (tells Claude where to find plugin updates)
+claude plugin marketplace add https://github.com/syncable-dev/memtrace-public.git
 
-| Tool | Coverage | Acc@1 | Acc@5 | Acc@10 | Avg lat | Tokens |
-|:-----|---------:|------:|------:|-------:|--------:|-------:|
-| **Memtrace** (MemDB) | **100.0%** | **96.7%** | **100.0%** | **100.0%** | **9.16 ms** | 195 |
-| ChromaDB (all-MiniLM-L6-v2)     | 100.0%  | 62.3% | 86.1% | 87.9%  |  58.5 ms |  1,937 |
-| GitNexus (eval-server)          |  99.5%  | 27.1% | 89.7% | 89.9%  | 191.2 ms |    213 |
-| CodeGrapherContext (CLI)        |  67.2%  |  6.4% | 66.4% | 66.7%  | 1627.2 ms |    221 |
+# 2. Install the skills plugin (writes skills + enables them)
+claude plugin install memtrace-skills@memtrace --scope user
 
-**What the numbers say, read fairly:**
+# 3. Register the MCP server (gives Claude access to memtrace tools)
+claude mcp add memtrace -- memtrace mcp
+```
 
-- **Memtrace** is exact-symbol lookup's sweet spot: 100% coverage, rank-1 hit in 96.7% of queries, and the correct file is in the top-10 every single time. 9 ms per query, 195 tokens per response.
-- **ChromaDB** shows what semantic embeddings look like for this workload — 88% top-10 but rank-1 is probabilistic, and the response is 10× larger because it returns 800-char chunks rather than symbol metadata.
-- **GitNexus** finds the right file 90% of the time — its response leads with execution *flows*, pushing standalone definitions down the list, which costs it rank-1 but not top-10.
-- **CodeGrapherContext**'s 67.2% coverage means its parser extracted two-thirds of the symbols Python's AST finds. Among symbols it did index, top-10 hit rate is excellent (~99%). Latency is dominated by CLI re-initialising FalkorDB per call.
+This writes three things to `~/.claude/settings.json`:
 
-**Where each tool shines** — this benchmark measures exact-symbol lookup only. Different workloads produce different rankings: ChromaDB wins on natural-language queries, GitNexus on execution-flow traces, Memtrace on exact lookup / typo tolerance / temporal queries / cross-service API topology. See [`benchmarks/fair/README.md`](https://github.com/syncable-dev/memtrace-public/tree/main/benchmarks/fair/README.md) for a per-workload breakdown.
+```json
+{
+  "mcpServers": {
+    "memtrace": {
+      "command": "memtrace",
+      "args": ["mcp"]
+    }
+  },
+  "enabledPlugins": {
+    "memtrace-skills@memtrace": true
+  },
+  "extraKnownMarketplaces": {
+    "memtrace": {
+      "source": {
+        "source": "git",
+        "url": "https://github.com/syncable-dev/memtrace-public.git"
+      }
+    }
+  }
+}
+```
 
-<details>
-<summary><strong>Memtrace vs. general memory systems (Mem0, Graphiti)</strong></summary>
+The `enabledPlugins` key activates the skill plugin. The `extraKnownMarketplaces` key registers the HTTPS Git marketplace so Claude can auto-discover updates. Skills are cached at `~/.claude/plugins/cache/memtrace/memtrace-skills/<version>/skills/` and also written to `~/.claude/skills/` for broader compatibility.
 
-<br/>
+## Supported Agent Integrations
 
-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.
+`npm install -g memtrace` runs `memtrace-skills install` after the binary is installed. By default it configures every supported agent it can safely write to:
 
-**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**.
+| Agent / Editor | Skills or Guidance Written | MCP Config Written |
+|:---------------|:---------------------------|:-------------------|
+| **Claude Code** | `~/.claude/skills/` and Claude plugin cache | `~/.claude/settings.json` |
+| **Claude Desktop** | Uses the same `~/.claude/skills/` files | Add `claude_desktop_config.json` manually if needed |
+| **Cursor** | `~/.cursor/skills/` | `~/.cursor/mcp.json` |
+| **Codex** | `~/.agents/skills/` | `~/.codex/config.toml` |
+| **Windsurf** | `~/.codeium/windsurf/skills/` | `~/.codeium/windsurf/mcp_config.json` |
+| **VS Code / Copilot** | `~/.copilot/skills/` | VS Code user `mcp.json` |
+| **Hermes** | `~/.hermes/skills/` | `~/.hermes/config.yaml` |
+| **OpenCode** | `~/.config/opencode/skills/` | `~/.config/opencode/opencode.json` |
+| **Kiro** | `~/.kiro/steering/` auto steering files | `~/.kiro/settings/mcp.json` |
 
-**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.
+Limit the install to one or more agents:
 
-**Both** accumulate $10–50+ in API costs for large codebases because every relationship is inferred rather than parsed.
+```bash
+npx memtrace-skills install --only claude,cursor,codex,windsurf,vscode,hermes,opencode,kiro
+```
 
-**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.
+Install project-local config where the provider supports it:
 
-</details>
+```bash
+npx memtrace-skills install --only claude,cursor,codex,vscode,opencode,kiro --local
+```
 
-<details>
-<summary><strong>Memtrace vs. code graphers (GitNexus, CodeGrapherContext)</strong></summary>
+Project-local paths include `.claude/skills`, `.mcp.json`, `.cursor/skills`, `.cursor/mcp.json`, `.agents/skills`, `.codex/config.toml`, `.github/skills`, `.opencode/skills`, `.kiro/steering`, `.vscode/mcp.json`, `opencode.json`, and `.kiro/settings/mcp.json`. Windsurf MCP and Hermes skills/MCP are user-level by their current config models, so local installs write the user-level config and print a warning.
 
-<br/>
+### Skills (Installed Automatically)
 
-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:
+Memtrace ships with 18 skills that teach agents how to use the knowledge graph effectively:
 
-| Capability | Memtrace | GitNexus | CodeGrapher |
-|:-----------|:---------|:---------|:------------|
-| AST-based graph | Yes | Yes | Yes |
-| Structural relationships (CALLS, IMPLEMENTS, IMPORTS) | Yes | Yes | Yes |
-| Bi-temporal version history per symbol | **Yes — 6 scoring modes** | Git-diff only | No |
-| Cross-service HTTP API topology | **Yes** | No | No |
-| Community detection (Louvain) | **Yes** | Yes | No |
-| Hybrid search (BM25 + vector + RRF) | **Yes — Tantivy + embeddings** | No | BM25 + optional embeddings |
-| Language | **Rust (compiled binary)** | JavaScript | Python |
-| Coverage (1K queries) | **100%** | 99.5% | 67.2% |
-| Acc@1 (1K queries) | **96.7%** | 27.1% | 6.4% |
-| Acc@10 (1K queries) | **100%** | 89.9% | 66.7% |
-| Query latency (1K queries) | **9.16 ms avg** | 191.2 ms avg | 1627.2 ms avg |
-| Tokens per query | **195 avg** | 213 avg | 221 avg |
-| Index time (~250 files / 2.3K nodes / 5.8K edges) | **~4 sec** (≈500 ms of graph work plus first-run local engine warmup) | ~6 sec | ~1 sec (cached) |
+**Command Skills** (single-tool wrappers with usage guidance):
 
-All numbers from [the fair benchmark](https://github.com/syncable-dev/memtrace-public/tree/main/benchmarks/fair) on the same machine, same mempalace checkout, same 1,000 queries. Ground truth is extracted by Python's stdlib `ast` — not from any tool's index — so no system is advantaged in the dataset itself.
+| Skill | Triggers on |
+|-------|-------------|
+| `memtrace-index` | "index this project", "set up code intelligence", "parse this codebase" |
+| `memtrace-search` | "find this function", "where is X defined", "search for Y" |
+| `memtrace-relationships` | "who calls this", "what does this call", "show class hierarchy" |
+| `memtrace-evolution` | "what changed", "how did this evolve", "what's different since last week" |
+| `memtrace-impact` | "what will break if I change this", "blast radius", "risk assessment" |
+| `memtrace-quality` | "find dead code", "complexity hotspots", "code smells" |
+| `memtrace-graph` | "show architecture", "find bottlenecks", "important functions" |
+| `memtrace-api-topology` | "list API endpoints", "service dependencies", "who calls this API" |
+| `memtrace-cochange` | "what changes with this", "hidden coupling", "historical dependency" |
 
-The latency difference is primarily Rust vs. interpreted runtimes, and MemDB's embedded native graph engine (in-process Node/Edge storage, bi-temporal predicates resolved at the storage layer, vector + lexical indexes co-located) vs. HTTP/embedding pipelines. The feature difference is temporal memory and API topology — dimensions Memtrace adds on top of the shared AST-graph foundation.
+**Workflow Skills** (multi-step orchestrations):
 
-</details>
+| Skill | Triggers on |
+|-------|-------------|
+| `memtrace-codebase-exploration` | "explore this codebase", "I'm new to this project", "give me an overview" |
+| `memtrace-change-impact-analysis` | "what will break if I refactor this", "pre-change risk assessment" |
+| `memtrace-code-review` | "review this PR", "post Memtrace review", "GitHub PR review" |
+| `memtrace-incident-investigation` | "something broke", "root cause analysis", "what went wrong" |
+| `memtrace-refactoring-guide` | "help me refactor", "reduce complexity", "clean up tech debt" |
+| `memtrace-first` | "use Memtrace before file search", "source-code discovery policy" |
+| `memtrace-continuous-memory` | "watch this repo", "keep the graph fresh while editing" |
+| `memtrace-episode-replay` | "why does this code look this way", "replay implementation attempts" |
+| `memtrace-session-continuity` | "continue", "catch me up", "what changed while away" |
 
-## 25+ MCP Tools
+### Installing Skills Separately
 
-Memtrace exposes a full structural toolkit via the [Model Context Protocol](https://modelcontextprotocol.io):
+If you installed memtrace via cargo or the skills weren't installed:
 
-<table>
-<tr>
-<td width="50%" valign="top">
+```bash
+npx memtrace-skills install
+```
 
-**Search & Discovery**
-- `find_code` — hybrid BM25 + semantic search with RRF
-- `find_symbol` — exact/fuzzy name match with Levenshtein
+To remove skills:
+
+```bash
+npx memtrace-skills uninstall
+```
 
-**Relationships**
-- `analyze_relationships` — callers, callees, hierarchy, imports
-- `get_symbol_context` — 360° view in one call
+## Claude Desktop Setup
 
-**Impact Analysis**
-- `get_impact` — blast radius with risk rating
-- `detect_changes` — diff-to-symbols scope mapping
+Skills are installed to `~/.claude/skills/` which is shared between Claude Code and Claude Desktop — both pick up memtrace skills after `npm install -g memtrace`.
 
-**Code Quality**
-- `find_dead_code` — zero-caller detection
-- `find_most_complex_functions` — complexity hotspots
-- `calculate_cyclomatic_complexity` — per-symbol scoring
-- `get_repository_stats` — repo-wide metrics
+The plugin is enabled via `~/.claude/settings.json` (the `enabledPlugins` and `extraKnownMarketplaces` keys written by the installer), which is also shared.
 
-</td>
-<td width="50%" valign="top">
+The only additional step for Claude Desktop is adding the MCP server to `claude_desktop_config.json`:
 
-**Temporal Analysis**
-- `get_evolution` — 6 scoring modes (compound, impact, novel, recent, directional, overview)
-- `get_timeline` — full symbol version history
-- `detect_changes` — diff-based impact scope
+```json
+{
+  "mcpServers": {
+    "memtrace": {
+      "command": "memtrace",
+      "args": ["mcp"]
+    }
+  }
+}
+```
 
-**Graph Algorithms**
-- `find_bridge_symbols` — betweenness centrality
-- `find_central_symbols` — PageRank / degree
-- `list_communities` — Louvain module detection
-- `list_processes` / `get_process_flow` — execution tracing
+After that, Claude Desktop has both the skills (how to use memtrace) and the MCP tools (the actual capabilities).
 
-**API Topology**
-- `get_api_topology` — cross-repo HTTP call graph
-- `find_api_endpoints` — all exposed routes
-- `find_api_calls` — all outbound HTTP calls
+## MCP Tools
 
-**Indexing & Watch**
-- `index_directory` — parse, resolve, embed
-- `watch_directory` — live incremental re-indexing
-- `execute_cypher` — direct graph queries
+Memtrace exposes 25+ tools via the MCP protocol:
 
-</td>
-</tr>
-</table>
+**Indexing:** `index_directory`, `list_indexed_repositories`, `delete_repository`, `check_job_status`, `list_jobs`
 
-## 18 Agent Skills
+**Search:** `find_code` (hybrid BM25 + semantic), `find_symbol` (exact/fuzzy name match)
 
-Memtrace ships skills that teach agents *how* to use the graph. They fire automatically based on what you ask — no prompt engineering required.
+**Relationships:** `analyze_relationships` (callers, callees, hierarchy, imports), `get_symbol_context` (360° view)
 
-| | Skill | You say... |
-|:--|:------|:-----------|
-| **Search** | `memtrace-search` | _"find this function"_, _"where is X defined"_ |
-| **Relationships** | `memtrace-relationships` | _"who calls this"_, _"show class hierarchy"_ |
-| **Evolution** | `memtrace-evolution` | _"what changed this week"_, _"how did this evolve"_ |
-| **Impact** | `memtrace-impact` | _"what breaks if I change this"_, _"blast radius"_ |
-| **Quality** | `memtrace-quality` | _"find dead code"_, _"complexity hotspots"_ |
-| **Architecture** | `memtrace-graph` | _"show me the architecture"_, _"find bottlenecks"_ |
-| **APIs** | `memtrace-api-topology` | _"list API endpoints"_, _"service dependencies"_ |
-| **Index** | `memtrace-index` | _"index this project"_, _"parse this codebase"_ |
-| **Co-change** | `memtrace-cochange` | _"what else changes with this"_, _"hidden coupling"_ |
-
-Plus **9 workflow skills** that chain multiple tools with decision logic:
-
-| Skill | You say... |
-|:------|:-----------|
-| `memtrace-codebase-exploration` | _"I'm new to this project"_, _"give me an overview"_ |
-| `memtrace-change-impact-analysis` | _"what will break if I refactor this"_ |
-| `memtrace-code-review` | _"review this PR"_, _"post Memtrace review"_ |
-| `memtrace-incident-investigation` | _"something broke"_, _"root cause analysis"_ |
-| `memtrace-refactoring-guide` | _"help me refactor"_, _"clean up tech debt"_ |
-| `memtrace-first` | _"use Memtrace before file search"_ |
-| `memtrace-continuous-memory` | _"watch this repo"_, _"keep the graph fresh"_ |
-| `memtrace-episode-replay` | _"why does this code look this way"_ |
-| `memtrace-session-continuity` | _"continue"_, _"catch me up"_ |
-
-## Temporal Engine
-
-Six scoring algorithms for different temporal questions:
-
-| Mode | Best for |
-|:-----|:---------|
-| **`compound`** | General-purpose _"what changed?"_ — weighted blend of impact, novelty, recency |
-| **`impact`** | _"What broke?"_ — ranks by blast radius (`in_degree^0.7 × (1 + out_degree)^0.3`) |
-| **`novel`** | _"What's unexpected?"_ — anomaly detection via surprise scoring |
-| **`recent`** | _"What changed near the incident?"_ — exponential time decay |
-| **`directional`** | _"What was added vs removed?"_ — asymmetric scoring |
-| **`overview`** | Quick module-level summary |
-
-Uses **Structural Significance Budgeting** to surface the minimum set of changes covering ≥80% of total significance.
-
-## Compatibility
-
-| Editor / Agent | MCP Tools (25+) | Skills / Guidance | Install |
-|:---------------|:---------------:|:-----------:|:--------|
-| **Claude Code** | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
-| **Claude Desktop** | ✅ | ✅ | Automatic — shared with Claude Code |
-| **Cursor** (v2.4+) | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
-| **Codex CLI** | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
-| **Windsurf** | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
-| **VS Code (Copilot)** | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
-| **Hermes** | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
-| **OpenCode** | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
-| **Kiro** | ✅ | Steering | `npm install -g memtrace` — fully automatic |
-| **Cline / Roo Code** | ✅ | — | 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 workflow prompts that teach the agent *how* to chain tools. Kiro does not use `SKILL.md`, so Memtrace writes equivalent auto steering files instead.
-
-## Setup
-
-### Claude Code + Claude Desktop
-
-`npm install -g memtrace` handles everything automatically — binary, 18 skills, MCP server, plugin, and marketplace all register in one command for both Claude Code and Claude Desktop.
-
-For manual setup:
+**Impact:** `get_impact` (blast radius), `detect_changes` (diff-based scope)
 
-```bash
-claude plugin marketplace add https://github.com/syncable-dev/memtrace-public.git
-claude plugin install memtrace-skills@memtrace --scope user
-claude mcp add memtrace -- memtrace mcp
-```
+**Temporal:** `get_evolution` (modes: `recent`, `compound`, `summary`, `overview`), `get_timeline`, `get_changes_since`, `get_episode_replay`, `get_cochange_context`
 
-### Cursor
+**Quality:** `find_dead_code`, `calculate_cyclomatic_complexity`, `find_most_complex_functions`, `get_repository_stats`
 
-Cursor **v2.4+** supports Agent Skills natively, and `npm install -g memtrace` handles everything automatically — no separate Cursor plugin is needed because Cursor reads the same `SKILL.md` format as Claude.
+**Graph Algorithms:** `find_bridge_symbols` (betweenness centrality), `find_central_symbols` (PageRank), `list_communities` (Louvain), `list_processes`, `get_process_flow`
 
-What the installer writes:
-- **MCP server** → `~/.cursor/mcp.json` (global — works in every project you open)
-- **18 skills/workflows** → `~/.cursor/skills/memtrace-*/SKILL.md`
+**API Topology:** `get_api_topology`, `find_api_endpoints`, `find_api_calls`, `link_repositories`
 
-For a **project-local** install (so the skills travel with your repo and teammates get them on clone), run inside the project:
+**Watch:** `watch_directory` (live incremental re-indexing), `list_watched_paths`
 
-```bash
-npx memtrace-skills install --only cursor --local
-```
+**Low-level:** `execute_cypher` (read-only Cypher queries)
 
-### Codex, Windsurf, VS Code, Hermes, OpenCode, and Kiro
+## `get_evolution` modes
 
-The installer also writes skills/guidance and MCP configuration for the newer agent surfaces:
+| Mode | Use case |
+|------|----------|
+| `recent` | Per-episode changelog (default); supports `file_path`, `kind`, pagination |
+| `compound` | Top changed files + top touched symbols |
+| `summary` / `overview` | Totals + first/last episode metadata |
 
-| Agent | Global skills / guidance | Global MCP config | Project-local support |
-|:------|:-------------------------|:------------------|:----------------------|
-| **Codex** | `~/.agents/skills/` | `~/.codex/config.toml` | `.agents/skills/`, `.codex/config.toml` |
-| **Windsurf** | `~/.codeium/windsurf/skills/` | `~/.codeium/windsurf/mcp_config.json` | `.windsurf/skills/`; MCP remains user-level |
-| **VS Code / Copilot** | `~/.copilot/skills/` | VS Code user `mcp.json` | `.github/skills/`, `.vscode/mcp.json` |
-| **Hermes** | `~/.hermes/skills/` | `~/.hermes/config.yaml` | user-level only |
-| **OpenCode** | `~/.config/opencode/skills/` | `~/.config/opencode/opencode.json` | `.opencode/skills/`, `opencode.json` |
-| **Kiro** | `~/.kiro/steering/` | `~/.kiro/settings/mcp.json` | `.kiro/steering/`, `.kiro/settings/mcp.json` |
+Requires `repo_id` + `from` (e.g. `"90d ago"`). Never pass `days`.
 
-Install only selected integrations:
+## Performance Benchmarking
 
-```bash
-npx memtrace-skills install --only codex,windsurf,vscode,hermes,opencode,kiro
-```
+All benchmarks below were measured live on the same machine, same codebase ([mempalace](https://github.com/mempalace/mempalace)), same 1,000 queries. Every system ran in its recommended production mode — no mocking, no hardcoded numbers. Raw results and reproduction scripts are in [`benchmarks/`](benchmarks/).
 
-Install project-local config where supported:
+### Search Accuracy & Latency (1,000 queries)
 
-```bash
-npx memtrace-skills install --only codex,vscode,opencode,kiro --local
-```
+| System | Accuracy (Acc@1) | Avg Latency | P95 Latency | Avg Tokens/Query | n |
+|:-------|:-----------------|:------------|:------------|:-----------------|:--|
+| **Memtrace** | **97.3%** | **13.4 ms** | **16.5 ms** | **319** | 1,000 |
+| ChromaDB | 89.6% | 60.6 ms | 76.8 ms | 1,912 | 1,000 |
+| GitNexus | 12.8% | 172.7 ms | 221.5 ms | 254 | 1,000 |
+| CodeGrapherContext | 0.0%† | 510.5 ms | 753.5 ms | 23 | 50 |
 
-### Other MCP Clients
+> [!IMPORTANT]
+> **Understanding the Accuracy Scores:** This benchmark measures **Structural Location Precision** (finding the exact file path). 
+> - **Memtrace** is optimized for "Sniper" lookups—returning the exact file and line for every symbol.
+> - **GitNexus** and **CGC** optimize for "Discovery"—returning symbol names or execution flows which often omit the direct file path in their CLI outputs. Their lower scores reflect a **design mismatch with this specific automated test**, not necessarily a failure of their underlying search engine.
 
-For Cline, Roo Code, or any client that only needs MCP tools, add this server manually:
+**Methodology:** 1,000 unique symbols sampled from the indexed graph. Accuracy = "expected file path appears in response." Latency = wall-clock `time.time()` including protocol overhead. 
+- † CGC's CLI returns names without paths, resulting in 0% in this specific validation script. 
+- GitNexus returns "Flow" stories; our script only credits results where a path is explicitly present.
 
-```json
-{
-  "mcpServers": {
-    "memtrace": {
-      "command": "memtrace",
-      "args": ["mcp"]
-    }
-  }
-}
-```
+### Token Reduction (Context Window Efficiency)
 
-<details>
-<summary>Config file locations by editor</summary>
+Over 1,000 queries, total tokens injected into the agent's context window:
 
-| Editor | Config file |
-|:-------|:------------|
-| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
-| **VS Code (Copilot)** | `.vscode/mcp.json` in your project root |
-| **Codex** | `~/.codex/config.toml` or `.codex/config.toml` |
-| **Hermes** | `~/.hermes/config.yaml` |
-| **OpenCode** | `~/.config/opencode/opencode.json` or project `opencode.json` |
-| **Kiro** | `~/.kiro/settings/mcp.json` or `.kiro/settings/mcp.json` |
-| **Cline** | Cline MCP settings in the extension panel |
+| System | Avg Tokens/Query | Total Tokens (1K queries) | Reduction vs ChromaDB |
+|:-------|:-----------------|:--------------------------|:----------------------|
+| **Memtrace** | **319** | **318,876** | **83.3% fewer tokens** |
+| ChromaDB (Sentence Transformers) | 1,912 | 1,911,500 | — (baseline) |
+| GitNexus | 254 | 254,416 | 86.7%† |
 
-</details>
+> † GitNexus returns fewer tokens than Memtrace — but with only 12.8% accuracy. Compact results that point to the wrong files waste the agent's reasoning budget. **Memtrace returns compact *and* accurate context.**
 
-### Uninstall
+**Why this matters:** Every token in the agent's context window costs inference time and money. ChromaDB dumps 10 chunks of ~800 characters per query regardless of relevance. Memtrace returns only the matching symbol's structural block — the exact function, class, or interface the agent asked for. Over a coding session with hundreds of queries, this is the difference between staying within context limits and hitting token ceilings that force expensive re-summarization.
 
-```bash
-memtrace uninstall              # removes skills, MCP server, plugin, and settings
-npm uninstall -g memtrace       # removes the binary
-```
+### Memtrace vs. General Memory Systems (Mem0, Graphiti)
+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.
 
-Already ran `npm uninstall` first? The cleanup script is persisted at `~/.memtrace/uninstall.js`:
+**Why they can't index codebases:**
+- **Graphiti** processes data through `add_episode()`, which triggers multiple LLM calls per episode (entity extraction, relationship resolution, deduplication). At its documented default throughput of ~50 episodes/minute ([source](https://github.com/getzep/graphiti)), ingesting 1,500 code files would take **30+ minutes** — and each file may chunk into multiple episodes, pushing real-world times to **1–2 hours**. Every episode costs LLM tokens.
+- **Mem0** processes data through `client.add()`, which queues asynchronous LLM extraction and conflict resolution per memory item ([source](https://mem0.ai)). Bulk code ingestion with `infer=True` (default) means every file passes through an LLM distillation pipeline. Throughput is bounded entirely by your LLM provider's rate limits.
+- **Both** accumulate significant API costs ($10–50+ depending on model and file count) because they use LLMs to *guess* code relationships rather than parsing them deterministically.
 
-```bash
-node ~/.memtrace/uninstall.js
-```
+**Memtrace indexes 1,500 files in 1.2–1.8 seconds for $0.00** — no LLM calls, no API costs, no rate limits. It compiles native Tree-sitter AST parsers and resolves deterministic symbol references (`CALLS`, `IMPLEMENTS`, `IMPORTS`) locally.
 
-### A note on install
+## Requirements
 
-`npm install -g memtrace` ships a small main package + a platform-specific binary (one of `@memtrace/darwin-arm64`, `@memtrace/linux-x64`, or `@memtrace/win32-x64`) that npm picks automatically.
+- **Node.js ≥ 18** — for npm installation
+- **Git** — for temporal analysis (commit history)
+- **MemDB** — bundled graph + vector backend used by the CLI; no Docker required for normal Memtrace usage
 
-Most setups just work. If `memtrace start` ever says **"Could not find binary for your platform"**, any of these will fix it:
+## Development
 
 ```bash
-# Option 1 — re-run install, asking npm to keep optional deps
-npm install -g memtrace --include=optional
+# Build from source
+cargo build --release --bin memtrace
 
-# Option 2 — refresh from latest
-memtrace install                  # built-in self-update
-# or:
-npm install -g memtrace@latest --force
+# Run the MCP server
+cargo run --release --bin memtrace -- mcp
 
-# Option 3 — install the platform binary directly (Apple Silicon shown — swap for your platform)
-npm install -g @memtrace/darwin-arm64
+# Run the local runtime without Docker
+cargo run --release --bin memtrace -- start --headless
 ```
 
-This typically only happens on machines where npm is configured to skip optional dependencies (some corporate npmrc setups, certain CI caches). Postinstall self-heals on most installs; the options above cover the rest.
+## Workspace-local data (`.memdb/`)
 
-## Languages
+The MemDB on-disk index lives in a workspace-local directory by default — `./.memdb/` relative to where you ran `memtrace start` or `memtrace index`. Each repository owns its own data dir, the dir is fully self-contained, and copying the workspace preserves the index.
 
-Rust · Go · TypeScript · JavaScript · Python · Java · C · C++ · C# · Swift · Kotlin · Ruby · PHP · Dart · Scala · Perl — and more via Tree-sitter.
+Add `.memdb/` to your project's `.gitignore` so the index doesn't end up in a commit:
 
-## Requirements
+```gitignore
+# Memtrace MemDB on-disk index
+.memdb/
+```
 
-Memtrace does parsing, graph construction, and embedding generation locally. Expect the first index to use noticeable CPU and memory; follow-up queries and incremental indexing are much lighter.
+If you previously ran Memtrace with the legacy global default (`/tmp/memdb-memtrace`), the binary will print a one-line migration notice on next boot. Copy or symlink the legacy directory to `./.memdb` to keep your indexed graphs, or run `memtrace reset` to start fresh.
 
-| Requirement | Minimum | Recommended |
-|:------------|:--------|:------------|
-| **CPU** | 4 cores | 8+ cores for large monorepos |
-| **Memory** | 8 GB RAM | 16–32 GB RAM |
-| **Disk** | 5 GB free | 10–20 GB free for large repositories |
-| **GPU** | Not required | Not required |
-| **Node.js** | ≥ 18 | Current LTS |
-| **Git** | Required for temporal analysis | Full repository history for best results |
+Override the location with `MEMTRACE_MEMDB_DATA_DIR=/path/to/your/data-dir` if you need a custom path (CI caches, shared volumes, etc).
 
-<br/>
+## License
 
-<p align="center">
-  <a href="https://memtrace.io">Documentation</a> · <a href="https://www.npmjs.com/package/memtrace">npm</a> · <a href="https://github.com/syncable-dev/memtrace-public/issues">Issues</a>
-</p>
+Proprietary EULA — Free to use. See [LICENSE](https://github.com/syncable-dev/memtrace-public/blob/main/LICENSE).
 
-<p align="center">
-  <sub>Built by <a href="https://syncable.dev">Syncable</a> · <a href="https://github.com/syncable-dev/memtrace-public/blob/main/LICENSE">Proprietary EULA</a> · Free to use</sub>
-</p>
+<!-- Memtrace contributor attribution smoke: 2026-05-23 -->