memtrace 0.1.51 → 0.2.1

package/README.md

@@ -48,29 +48,33 @@ On top of that, the structural layer is comprehensive:
 - **Relationships are edges** — `CALLS`, `IMPLEMENTS`, `IMPORTS`, `EXPORTS`, `CONTAINS`
 - **Community detection** — Louvain algorithm identifies architectural modules automatically
 - **Hybrid search** — Tantivy BM25 + vector embeddings + Reciprocal Rank Fusion, all on top of the graph
-- **Rust-native** — compiled binary, no Python/JS runtime overhead, sub-15ms average query latency
+- **Rust-native** — compiled binary, no Python/JS runtime overhead, sub-8ms average query latency
 
 The agent doesn't just search your code. It *remembers* it.
 
 ## Benchmarks
 
-All benchmarks run on the same machine, same codebase, same queries. No cherry-picking.
+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).
 
-### Does it find the right thing?
+<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"/>
 
-<img alt="Search accuracy: Memtrace 97.3% vs ChromaDB 89.6% vs GitNexus 12.8%" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/search-accuracy.svg" width="720"/>
+### Results (1,000 Python symbol-lookup queries on mempalace)
 
-### How fast?
+| Tool | Coverage | Acc@1 | Acc@5 | Acc@10 | Avg lat | Tokens |
+|:-----|---------:|------:|------:|-------:|--------:|-------:|
+| **Memtrace** (ArcadeDB) | **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 |
 
-<img alt="Search latency: Memtrace 13.4ms vs ChromaDB 60.6ms vs GitNexus 172.7ms vs CodeGrapher 510.5ms" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/search-latency.svg" width="720"/>
+**What the numbers say, read fairly:**
 
-### How much context does it save?
+- **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.
 
-<img alt="Token usage: Memtrace 319K vs ChromaDB 1.91M — 83% reduction" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/token-context.svg" width="720"/>
-
-### How long to set up?
-
-<img alt="Indexing: Memtrace 1.5s vs Graphiti 6h vs Mem0 31m" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/indexing-speed.svg" width="720"/>
+**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.
 
 <details>
 <summary><strong>Memtrace vs. general memory systems (Mem0, Graphiti)</strong></summary>
@@ -85,7 +89,7 @@ Mem0 and Graphiti are strong conversational memory engines designed for tracking
 
 **Both** accumulate $10–50+ in API costs for large codebases because every relationship is inferred rather than parsed.
 
-**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.
+**Memtrace takes a different approach:** it indexes files in ~4 seconds for $0.00 — no LLM calls, no API costs, no rate limits. Native Tree-sitter AST parsers resolve deterministic symbol references (`CALLS`, `IMPLEMENTS`, `IMPORTS`) locally. The tradeoff is that Memtrace is purpose-built for code — it doesn't handle conversational entity memory the way Mem0 and Graphiti do.
 
 </details>
 
@@ -105,14 +109,16 @@ GitNexus and CodeGrapherContext both build AST-based code graphs with structural
 | Community detection (Louvain) | **Yes** | Yes | No |
 | Hybrid search (BM25 + vector + RRF) | **Yes — Tantivy + embeddings** | No | BM25 + optional embeddings |
 | Language | **Rust (compiled binary)** | JavaScript | Python |
-| Search accuracy (1K queries) | **97.3%** | 12.8% | 0%* |
-| Query latency (1K queries) | **13.4 ms avg** | 172.7 ms avg | 510.5 ms avg |
-| Tokens per query | **319 avg** | 254 avg | 23 avg |
-| Index time (1,500 files) | **1.5 sec** | 10.5 sec | ~3.5 min |
+| 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 real work + ~3 s Docker / Bolt / schema DDL startup on first run) | ~6 sec | ~1 sec (cached) |
 
-*CGC's 0% reflects an output format mismatch — it returns symbol names without file paths, so our Acc@1 evaluator can't match them. CGC likely finds relevant symbols; the metric just can't confirm it. All numbers from [live benchmark](https://github.com/syncable-dev/memtrace-public/tree/main/benchmarks) on the same machine, same codebase, same 1,000 queries.
+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.
 
-The latency difference is primarily Rust vs. interpreted runtimes, and Memgraph's Bolt protocol vs. HTTP/embedding pipelines. The feature difference is temporal memory and API topology — dimensions Memtrace adds on top of the shared AST-graph foundation.
+The latency difference is primarily Rust vs. interpreted runtimes, and ArcadeDB's Graph-OLAP engine (native CSR projections, PageRank/betweenness as in-database procedures) vs. HTTP/embedding pipelines. The feature difference is temporal memory and API topology — dimensions Memtrace adds on top of the shared AST-graph foundation.
 
 </details>
 
@@ -235,7 +241,7 @@ For manual setup:
 ```bash
 claude plugin marketplace add syncable-dev/memtrace
 claude plugin install memtrace-skills@memtrace --scope user
-claude mcp add memtrace -- memtrace mcp -e MEMGRAPH_URL=bolt://localhost:7687
+claude mcp add memtrace -- memtrace mcp -e MEMTRACE_ARCADEDB_BOLT_URL=bolt://localhost:7687
 ```
 
 ### Other Editors (Cursor, Windsurf, VS Code, Cline)
@@ -248,7 +254,7 @@ After `npm install -g memtrace`, add the MCP server to your editor's config:
     "memtrace": {
       "command": "memtrace",
       "args": ["mcp"],
-      "env": { "MEMGRAPH_URL": "bolt://localhost:7687" }
+      "env": { "MEMTRACE_ARCADEDB_BOLT_URL": "bolt://localhost:7687" }
     }
   }
 }

package/installer/dist/transformers/claude.js

@@ -17,7 +17,7 @@ async function tryMcpAddJson(memtraceBinary) {
     const config = JSON.stringify({
         command: memtraceBinary,
         args: ['mcp'],
-        env: { MEMGRAPH_URL: 'bolt://localhost:7687' },
+        env: { MEMTRACE_ARCADEDB_BOLT_URL: 'bolt://localhost:7687' },
     });
     // Shell-quote the JSON. Use single quotes; escape any embedded single quote.
     const escaped = config.replace(/'/g, `'\\''`);
@@ -151,7 +151,7 @@ export function registerMcpInSettingsAt(settingsPath, memtraceBinary) {
     settings.mcpServers['memtrace'] = {
         command: memtraceBinary,
         args: ['mcp'],
-        env: { MEMGRAPH_URL: 'bolt://localhost:7687' },
+        env: { MEMTRACE_ARCADEDB_BOLT_URL: 'bolt://localhost:7687' },
     };
     writeJsonAtomic(settingsPath, settings);
     return { registered: true };
@@ -325,7 +325,7 @@ function writeClaudeLocalMcp(mcpPath, binary) {
     cfg.mcpServers['memtrace'] = {
         command: binary,
         args: ['mcp'],
-        env: { MEMGRAPH_URL: 'bolt://localhost:7687' },
+        env: { MEMTRACE_ARCADEDB_BOLT_URL: 'bolt://localhost:7687' },
     };
     writeJsonAtomic(mcpPath, cfg);
     return true;

package/installer/dist/transformers/cursor.js

@@ -30,7 +30,7 @@ export function registerCursorMcpAt(mcpFile, binary) {
     cfg.mcpServers['memtrace'] = {
         command: binary,
         args: ['mcp'],
-        env: { MEMGRAPH_URL: 'bolt://localhost:7687' },
+        env: { MEMTRACE_ARCADEDB_BOLT_URL: 'bolt://localhost:7687' },
     };
     writeJsonAtomic(mcpFile, cfg);
     return { registered: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.1.51",
+  "version": "0.2.1",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",
@@ -36,9 +36,9 @@
     "fs-extra": "^11.0.0"
   },
   "optionalDependencies": {
-    "@memtrace/darwin-arm64": "0.1.51",
-    "@memtrace/linux-x64": "0.1.51",
-    "@memtrace/win32-x64": "0.1.51"
+    "@memtrace/darwin-arm64": "0.2.1",
+    "@memtrace/linux-x64": "0.2.1",
+    "@memtrace/win32-x64": "0.2.1"
   },
   "engines": {
     "node": ">=18"

package/skills/commands/memtrace-graph.md

@@ -20,7 +20,7 @@ Graph algorithms that reveal the structural architecture of a codebase — commu
 | Tool | Purpose |
 |------|---------|
 | `find_bridge_symbols` | Architectural chokepoints — symbols that connect otherwise-separate modules |
-| `find_central_symbols` | Most important symbols by PageRank or degree centrality |
+| `find_central_symbols` | Most important symbols (PageRank via ArcadeDB `algo.pagerank`) |
 | `list_communities` | Louvain-detected logical modules/services |
 | `list_processes` | Execution flows: HTTP handlers, background jobs, CLI commands, event handlers |
 | `get_process_flow` | Trace a single process step-by-step |
@@ -67,7 +67,8 @@ Use `find_central_symbols` to identify the most important symbols:
 - `repo_id` — string, required.
 - `branch` — string, optional. Defaults to `"main"`.
 - `limit` — **integer**, optional. How many to return. Default `20`, capped at `100`.
-- `algorithm` — string, optional. `"pagerank"` (default, via MAGE — falls back to degree if unavailable) or `"degree"` (simple in-degree count, no MAGE required).
+
+Returns the top-N symbols ranked by **PageRank** (ArcadeDB's native `algo.pagerank` procedure). Filters the global run to Function/Method/Class/Interface/Struct in the requested repo + branch. Falls back to in-degree centrality only if the native procedure isn't registered on the connected ArcadeDB build.
 
 ### 3. Find architectural chokepoints
 
@@ -81,6 +82,8 @@ Use `find_bridge_symbols` to find symbols that, if removed, would disconnect par
 - `branch` — string, optional. Defaults to `"main"`.
 - `limit` — **integer**, optional. Default `15`, capped at `50`.
 
+Ranks symbols by **betweenness centrality** (ArcadeDB's native `algo.betweenness` with `normalized: true`) — how many shortest paths between other symbols pass through each one. Falls back to an in-degree × out-degree heuristic only if the native procedure isn't registered.
+
 ### 4. Trace execution flows
 
 Use `list_processes` to see all entry points (HTTP handlers, background jobs, CLI commands, event handlers).
@@ -111,7 +114,7 @@ Use `execute_cypher` for advanced graph queries not covered by built-in tools. T
 | Question | Tool |
 |----------|------|
 | "What are the main modules?" | `list_communities` |
-| "What are the most important functions?" | `find_central_symbols` with method=pagerank |
+| "What are the most important functions?" | `find_central_symbols` (PageRank, native) |
 | "Where are the bottlenecks?" | `find_bridge_symbols` |
 | "How does a request flow through the system?" | `list_processes` → `get_process_flow` |
 | "What's the entry point for feature X?" | `list_processes`, then filter by name |

package/skills/workflows/memtrace-codebase-exploration.md

@@ -50,7 +50,7 @@ Each community represents a cohesive module — these are the "areas" of the cod
 
 ### 4. Find the most important symbols
 
-Call `find_central_symbols` with `method: "pagerank"` and `limit: 15`.
+Call `find_central_symbols` with `limit: 15`. It ranks symbols by PageRank (ArcadeDB's native `algo.pagerank`) — no extra parameter needed.
 
 These are the symbols that the rest of the codebase depends on most heavily. They form the "skeleton" of the architecture.