memtrace 0.1.20 → 0.1.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +145 -117
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -1,91 +1,134 @@
1
1
  <p align="center">
2
- <img src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/logo.svg" alt="Memtrace" width="120" height="120" />
2
+ <img src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/logo.svg" alt="Memtrace" width="100" height="100" />
3
3
  </p>
4
4
 
5
5
  <h1 align="center">Memtrace</h1>
6
6
 
7
7
  <p align="center">
8
- <strong>Code intelligence graph for AI agents</strong><br/>
9
- Structural search · Relationship analysis · Temporal evolution · Architectural understanding
8
+ <strong>The persistent memory layer for coding agents.</strong><br/>
9
+ A bi-temporal, episodic, structural knowledge graph — built from AST, not guesswork.
10
10
  </p>
11
11
 
12
12
  <p align="center">
13
13
  <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>
14
- <a href="https://www.npmjs.com/package/memtrace"><img src="https://img.shields.io/npm/dm/memtrace?style=flat-square&color=0A1628&label=downloads" alt="npm downloads" /></a>
15
- <a href="https://github.com/syncable-dev/memtrace-public/stargazers"><img src="https://img.shields.io/github/stars/syncable-dev/memtrace-public?style=flat-square&color=00D4B8" alt="GitHub stars" /></a>
16
- <a href="https://github.com/syncable-dev/memtrace-public/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-FSL--1.1--MIT-0A1628?style=flat-square" alt="license" /></a>
14
+ <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>
17
15
  <a href="https://memtrace.dev"><img src="https://img.shields.io/badge/docs-memtrace.dev-00D4B8?style=flat-square" alt="docs" /></a>
18
16
  </p>
19
17
 
20
- <p align="center">
21
- <a href="#quick-start">Quick Start</a> ·
22
- <a href="#skills">Skills</a> ·
23
- <a href="#mcp-tools">MCP Tools</a> ·
24
- <a href="#evolution-engine">Evolution Engine</a> ·
25
- <a href="#claude-code-setup">Claude Code</a> ·
26
- <a href="#claude-desktop-setup">Claude Desktop</a>
27
- </p>
28
-
29
18
  ---
30
19
 
31
- Memtrace is an MCP server that builds a **persistent knowledge graph** from your codebase. It parses source files, resolves cross-file relationships, detects API endpoints, runs community detection, and embeds all symbols for semantic search — then exposes 25+ tools via the [Model Context Protocol](https://modelcontextprotocol.io) so AI agents can explore, analyze, and reason about your code structurally.
20
+ 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.
32
21
 
33
- ## Quick Start
22
+ 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.
34
23
 
35
24
  ```bash
36
- # Install (binary + skills + MCP server — all in one)
37
- npm install -g memtrace
25
+ npm install -g memtrace # binary + 12 skills + MCP server — one command
26
+ memtrace start # launches the graph database
27
+ memtrace index . # indexes your codebase in seconds
28
+ ```
38
29
 
39
- # Start the graph database
40
- memtrace start
30
+ That's it. Claude picks up the skills and MCP tools automatically.
41
31
 
42
- # Index your project
43
- memtrace index /path/to/your/project
44
- ```
32
+ ---
33
+
34
+ ## Why Memtrace Exists
35
+
36
+ Static code graphs exist. Tools like GitNexus and CodeGrapherContext build AST-based graphs with symbol relationships — and they're useful. But they solve one dimension: *what exists right now*.
37
+
38
+ Memtrace is a **bi-temporal episodic structural knowledge graph**. It adds two dimensions no other code intelligence tool has:
39
+
40
+ - **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.
41
+ - **Cross-service API topology** — Memtrace maps HTTP call graphs between repositories, detecting which services call which endpoints. No other code grapher does inter-service relationship mapping.
42
+
43
+ On top of that, the structural layer is comprehensive:
44
+
45
+ - **Symbols are nodes** — functions, classes, interfaces, types, endpoints
46
+ - **Relationships are edges** — `CALLS`, `IMPLEMENTS`, `IMPORTS`, `EXPORTS`, `CONTAINS`
47
+ - **Community detection** — Louvain algorithm identifies architectural modules automatically
48
+ - **Hybrid search** — Tantivy BM25 + vector embeddings + Reciprocal Rank Fusion, all on top of the graph
49
+ - **Rust-native** — compiled binary, no Python/JS runtime overhead, single-digit millisecond queries
50
+
51
+ The agent doesn't just search your code. It *remembers* it.
52
+
53
+ ## Benchmarks
54
+
55
+ All benchmarks run on the same machine, same codebase, same queries. No cherry-picking.
45
56
 
46
- That's it. The installer handles everything:
57
+ ### Does it find the right thing?
47
58
 
48
- | Step | What happens |
49
- |------|-------------|
50
- | **Binary** | Platform-specific native binary installed via npm |
51
- | **Skills** | 12 AI agent skills written to `~/.claude/skills/` and plugin cache |
52
- | **Plugin** | `memtrace-skills@memtrace` enabled in `~/.claude/settings.json` |
53
- | **Marketplace** | GitHub marketplace registered for auto-updates |
54
- | **MCP Server** | `memtrace mcp` registered in `mcpServers` |
59
+ <picture>
60
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/search-accuracy.svg"/>
61
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/search-accuracy.svg"/>
62
+ <img alt="Search accuracy: Memtrace 83.5% vs Vector RAG 25.8%" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/search-accuracy.svg" width="720"/>
63
+ </picture>
55
64
 
56
- > **Zero configuration required** — just install and start exploring your codebase with Claude.
65
+ ### How fast?
57
66
 
58
- ## Skills
67
+ <picture>
68
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/search-latency.svg"/>
69
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/search-latency.svg"/>
70
+ <img alt="Search latency: Memtrace 4.6ms vs GitNexus 220ms vs CodeGrapher 466.7ms" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/search-latency.svg" width="720"/>
71
+ </picture>
59
72
 
60
- Memtrace ships with **12 skills** that teach Claude _how_ to use the knowledge graph. Skills fire automatically based on what you ask.
73
+ ### How much context does it save?
74
+
75
+ <picture>
76
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/token-context.svg"/>
77
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/token-context.svg"/>
78
+ <img alt="Token usage: Memtrace 284K vs Vector RAG 2.4M — 88.2% reduction" src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/token-context.svg" width="720"/>
79
+ </picture>
80
+
81
+ ### How long to set up?
82
+
83
+ <picture>
84
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/indexing-speed.svg"/>
85
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/benchmarks/indexing-speed.svg"/>
86
+ <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"/>
87
+ </picture>
88
+
89
+ <details>
90
+ <summary><strong>Memtrace vs. general memory systems (Mem0, Graphiti)</strong></summary>
91
+
92
+ <br/>
93
+
94
+ 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.
95
+
96
+ **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**. Every episode costs LLM tokens.
97
+
98
+ **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 distillation pipeline. Throughput is bounded by your LLM provider's rate limits.
99
+
100
+ **Both** accumulate $10–50+ in API costs because they use LLMs to *guess* code relationships rather than parsing them deterministically.
101
+
102
+ **Memtrace 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.
103
+
104
+ </details>
105
+
106
+ <details>
107
+ <summary><strong>Memtrace vs. code graphers (GitNexus, CodeGrapherContext)</strong></summary>
61
108
 
62
- ### Command Skills
109
+ <br/>
63
110
 
64
- | Skill | Triggers when you say... |
65
- |:------|:------------------------|
66
- | `memtrace-index` | _"index this project"_, _"set up code intelligence"_, _"parse this codebase"_ |
67
- | `memtrace-search` | _"find this function"_, _"where is X defined"_, _"search for authentication logic"_ |
68
- | `memtrace-relationships` | _"who calls this"_, _"what does this function call"_, _"show class hierarchy"_ |
69
- | `memtrace-evolution` | _"what changed this week"_, _"how did this evolve"_, _"what's different since Monday"_ |
70
- | `memtrace-impact` | _"what will break if I change this"_, _"blast radius"_, _"risk assessment"_ |
71
- | `memtrace-quality` | _"find dead code"_, _"complexity hotspots"_, _"code smells"_ |
72
- | `memtrace-graph` | _"show me the architecture"_, _"find bottlenecks"_, _"most important functions"_ |
73
- | `memtrace-api-topology` | _"list API endpoints"_, _"service dependencies"_, _"who calls this API"_ |
111
+ GitNexus and CodeGrapherContext both build AST-based code graphs with structural relationships — they're real tools solving real problems. Here's what Memtrace adds:
74
112
 
75
- ### Workflow Skills
113
+ | Capability | Memtrace | GitNexus | CodeGrapher |
114
+ |:-----------|:---------|:---------|:------------|
115
+ | AST-based graph | Yes | Yes | Yes |
116
+ | Structural relationships (CALLS, IMPLEMENTS, IMPORTS) | Yes | Yes | Yes |
117
+ | Bi-temporal version history per symbol | **Yes — 6 scoring modes** | Git-diff only | No |
118
+ | Cross-service HTTP API topology | **Yes** | No | No |
119
+ | Community detection (Louvain) | **Yes** | Yes | No |
120
+ | Hybrid search (BM25 + vector + RRF) | **Yes — Tantivy + embeddings** | No | BM25 + optional embeddings |
121
+ | Language | **Rust (compiled binary)** | JavaScript | Python |
122
+ | Query latency (1K queries) | **4.6 ms avg** | 220 ms avg | 466.7 ms avg |
123
+ | Index time (1,500 files) | **1.5 sec** | 10.5 sec | 3.5 min |
76
124
 
77
- Multi-step orchestrations that chain tools together with decision logic:
125
+ The speed difference comes from Rust vs. interpreted runtimes, and Memgraph's Bolt protocol vs. HTTP/embedding pipelines. The feature difference is temporal memory and API topology — dimensions that don't exist in static-snapshot graphs.
78
126
 
79
- | Skill | Triggers when you say... |
80
- |:------|:------------------------|
81
- | `memtrace-codebase-exploration` | _"explore this codebase"_, _"I'm new to this project"_, _"give me an overview"_ |
82
- | `memtrace-change-impact-analysis` | _"what will break if I refactor this"_, _"pre-change risk assessment"_ |
83
- | `memtrace-incident-investigation` | _"something broke"_, _"root cause analysis"_, _"what went wrong"_ |
84
- | `memtrace-refactoring-guide` | _"help me refactor"_, _"reduce complexity"_, _"clean up tech debt"_ |
127
+ </details>
85
128
 
86
- ## MCP Tools
129
+ ## 25+ MCP Tools
87
130
 
88
- 25+ tools exposed via the Model Context Protocol:
131
+ Memtrace exposes a full structural toolkit via the [Model Context Protocol](https://modelcontextprotocol.io):
89
132
 
90
133
  <table>
91
134
  <tr>
@@ -113,7 +156,7 @@ Multi-step orchestrations that chain tools together with decision logic:
113
156
  <td width="50%" valign="top">
114
157
 
115
158
  **Temporal Analysis**
116
- - `get_evolution` — 6 scoring modes (see below)
159
+ - `get_evolution` — 6 scoring modes (compound, impact, novel, recent, directional, overview)
117
160
  - `get_timeline` — full symbol version history
118
161
  - `detect_changes` — diff-based impact scope
119
162
 
@@ -137,73 +180,60 @@ Multi-step orchestrations that chain tools together with decision logic:
137
180
  </tr>
138
181
  </table>
139
182
 
140
- ## Evolution Engine
141
-
142
- The temporal analysis engine implements **six distinct scoring algorithms** — choose the right one for the question you're asking:
183
+ ## 12 Agent Skills
143
184
 
144
- | Mode | Formula | Best for |
145
- |:-----|:--------|:---------|
146
- | **`compound`** | `0.50 × rank(impact) + 0.35 × rank(novel) + 0.15 × rank(recent)` | General-purpose _"what changed?"_ |
147
- | **`impact`** | `sig(n) = in_degree^0.7 × (1 + out_degree)^0.3` | _"What broke?"_ — largest blast radius |
148
- | **`novel`** | `surprise(n) = (1 + in_degree) / (1 + change_freq_90d)` | _"What's unexpected?"_ — anomaly detection |
149
- | **`recent`** | `impact × exp(−0.5 × Δhours)` | _"What changed near the incident?"_ |
150
- | **`directional`** | Asymmetric: added → out_degree, removed → in_degree | _"What was added vs removed?"_ |
151
- | **`overview`** | Module-level rollup only | Quick summary, no per-symbol scoring |
185
+ Memtrace ships skills that teach Claude *how* to use the graph. They fire automatically based on what you ask — no prompt engineering required.
152
186
 
153
- Uses **Structural Significance Budgeting (SSB)** to select the minimum set of changes covering ≥80% of total significance — surfaces what matters without drowning you in noise.
187
+ | | Skill | You say... |
188
+ |:--|:------|:-----------|
189
+ | **Search** | `memtrace-search` | _"find this function"_, _"where is X defined"_ |
190
+ | **Relationships** | `memtrace-relationships` | _"who calls this"_, _"show class hierarchy"_ |
191
+ | **Evolution** | `memtrace-evolution` | _"what changed this week"_, _"how did this evolve"_ |
192
+ | **Impact** | `memtrace-impact` | _"what breaks if I change this"_, _"blast radius"_ |
193
+ | **Quality** | `memtrace-quality` | _"find dead code"_, _"complexity hotspots"_ |
194
+ | **Architecture** | `memtrace-graph` | _"show me the architecture"_, _"find bottlenecks"_ |
195
+ | **APIs** | `memtrace-api-topology` | _"list API endpoints"_, _"service dependencies"_ |
196
+ | **Index** | `memtrace-index` | _"index this project"_, _"parse this codebase"_ |
154
197
 
155
- ## Claude Code Setup
198
+ Plus **4 workflow skills** that chain multiple tools with decision logic:
156
199
 
157
- `npm install -g memtrace` handles everything. For manual setup:
200
+ | Skill | You say... |
201
+ |:------|:-----------|
202
+ | `memtrace-codebase-exploration` | _"I'm new to this project"_, _"give me an overview"_ |
203
+ | `memtrace-change-impact-analysis` | _"what will break if I refactor this"_ |
204
+ | `memtrace-incident-investigation` | _"something broke"_, _"root cause analysis"_ |
205
+ | `memtrace-refactoring-guide` | _"help me refactor"_, _"clean up tech debt"_ |
158
206
 
159
- ```bash
160
- # 1. Register the marketplace
161
- claude plugin marketplace add syncable-dev/memtrace
207
+ ## Temporal Engine
162
208
 
163
- # 2. Install the skills plugin
164
- claude plugin install memtrace-skills@memtrace --scope user
209
+ Six scoring algorithms for different temporal questions:
165
210
 
166
- # 3. Register the MCP server
167
- claude mcp add memtrace -- memtrace mcp -e MEMGRAPH_URL=bolt://localhost:7687
168
- ```
211
+ | Mode | Best for |
212
+ |:-----|:---------|
213
+ | **`compound`** | General-purpose _"what changed?"_ — weighted blend of impact, novelty, recency |
214
+ | **`impact`** | _"What broke?"_ — ranks by blast radius (`in_degree^0.7 × (1 + out_degree)^0.3`) |
215
+ | **`novel`** | _"What's unexpected?"_ — anomaly detection via surprise scoring |
216
+ | **`recent`** | _"What changed near the incident?"_ — exponential time decay |
217
+ | **`directional`** | _"What was added vs removed?"_ — asymmetric scoring |
218
+ | **`overview`** | Quick module-level summary |
169
219
 
170
- <details>
171
- <summary><strong>What this writes to <code>~/.claude/settings.json</code></strong></summary>
220
+ Uses **Structural Significance Budgeting** to surface the minimum set of changes covering ≥80% of total significance.
172
221
 
173
- ```json
174
- {
175
- "mcpServers": {
176
- "memtrace": {
177
- "command": "memtrace",
178
- "args": ["mcp"],
179
- "env": { "MEMGRAPH_URL": "bolt://localhost:7687" }
180
- }
181
- },
182
- "enabledPlugins": {
183
- "memtrace-skills@memtrace": true
184
- },
185
- "extraKnownMarketplaces": {
186
- "memtrace": {
187
- "source": { "source": "github", "repo": "syncable-dev/memtrace" }
188
- }
189
- }
190
- }
191
- ```
222
+ ## Setup
192
223
 
193
- </details>
224
+ ### Claude Code
194
225
 
195
- ### Installing skills separately
226
+ `npm install -g memtrace` handles everything automatically. For manual setup:
196
227
 
197
228
  ```bash
198
- npx memtrace-skills install # install skills + register MCP
199
- npx memtrace-skills uninstall # remove everything
229
+ claude plugin marketplace add syncable-dev/memtrace
230
+ claude plugin install memtrace-skills@memtrace --scope user
231
+ claude mcp add memtrace -- memtrace mcp -e MEMGRAPH_URL=bolt://localhost:7687
200
232
  ```
201
233
 
202
- ## Claude Desktop Setup
234
+ ### Claude Desktop
203
235
 
204
- Skills are installed to `~/.claude/skills/` which is shared between Claude Code and Claude Desktop — both pick up skills automatically after `npm install -g memtrace`.
205
-
206
- Add the MCP server to your `claude_desktop_config.json`:
236
+ Skills and plugins are shared between Claude Code and Claude Desktop — both activate after `npm install -g memtrace`. Add the MCP server to `claude_desktop_config.json`:
207
237
 
208
238
  ```json
209
239
  {
@@ -217,7 +247,7 @@ Add the MCP server to your `claude_desktop_config.json`:
217
247
  }
218
248
  ```
219
249
 
220
- ## Supported Languages
250
+ ## Languages
221
251
 
222
252
  Rust · Go · TypeScript · JavaScript · Python · Java · C · C++ · C# · Swift · Kotlin · Ruby · PHP · Dart · Scala · Perl — and more via Tree-sitter.
223
253
 
@@ -225,18 +255,16 @@ Rust · Go · TypeScript · JavaScript · Python · Java · C · C++ · C# · Sw
225
255
 
226
256
  | Dependency | Purpose |
227
257
  |:-----------|:--------|
228
- | **Memgraph** | Knowledge graph backend — auto-managed via `memtrace start` |
258
+ | **Memgraph** | Graph database — auto-managed via `memtrace start` |
229
259
  | **Node.js ≥ 18** | npm installation |
230
260
  | **Git** | Temporal analysis (commit history) |
231
261
 
232
- ## Links
233
-
234
- - [Documentation](https://memtrace.dev)
235
- - [npm Package](https://www.npmjs.com/package/memtrace)
236
- - [Report an Issue](https://github.com/syncable-dev/memtrace/issues)
262
+ <br/>
237
263
 
238
- ---
264
+ <p align="center">
265
+ <a href="https://memtrace.dev">Documentation</a> · <a href="https://www.npmjs.com/package/memtrace">npm</a> · <a href="https://github.com/syncable-dev/memtrace-public/issues">Issues</a>
266
+ </p>
239
267
 
240
268
  <p align="center">
241
- <sub>Built by <a href="https://syncable.dev">Syncable</a> · Licensed under <a href="LICENSE">FSL-1.1-MIT</a></sub>
269
+ <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>
242
270
  </p>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "memtrace",
3
- "version": "0.1.20",
3
+ "version": "0.1.23",
4
4
  "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
5
5
  "keywords": [
6
6
  "mcp",
@@ -14,9 +14,9 @@
14
14
  "homepage": "https://memtrace.dev",
15
15
  "repository": {
16
16
  "type": "git",
17
- "url": "https://github.com/syncable-dev/memtrace"
17
+ "url": "https://github.com/syncable-dev/memtrace-public"
18
18
  },
19
- "license": "FSL-1.1-MIT",
19
+ "license": "SEE LICENSE IN LICENSE",
20
20
  "bin": {
21
21
  "memtrace": "bin/memtrace.js"
22
22
  },
@@ -29,9 +29,9 @@
29
29
  "postinstall": "node install.js"
30
30
  },
31
31
  "optionalDependencies": {
32
- "@memtrace/darwin-arm64": "0.1.20",
33
- "@memtrace/linux-x64": "0.1.20",
34
- "@memtrace/win32-x64": "0.1.20"
32
+ "@memtrace/darwin-arm64": "0.1.0",
33
+ "@memtrace/linux-x64": "0.1.0",
34
+ "@memtrace/win32-x64": "0.1.0"
35
35
  },
36
36
  "engines": {
37
37
  "node": ">=18"