memorix 0.10.0 → 0.10.3

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 (7) hide show
  1. package/README.md +184 -326
  2. package/README.zh-CN.md +136 -340
  3. package/dist/cli/index.js +39936 -37952
  4. package/dist/cli/index.js.map +1 -1
  5. package/dist/index.js +1343 -168
  6. package/dist/index.js.map +1 -1
  7. package/package.json +1 -1
package/README.md CHANGED
@@ -1,458 +1,316 @@
1
1
  <p align="center">
2
- <img src="assets/logo.png" alt="Memorix Logo" width="120">
3
- <h1 align="center">Memorix</h1>
4
- <p align="center"><strong>Cross-Agent Memory Bridge — Your AI never forgets again</strong></p>
5
- <p align="center"><a href="README.zh-CN.md">中文文档</a> | English</p>
6
- <p align="center">
7
- <a href="https://www.npmjs.com/package/memorix"><img src="https://img.shields.io/npm/v/memorix.svg?style=flat-square&color=cb3837" alt="npm version"></a>
8
- <a href="https://www.npmjs.com/package/memorix"><img src="https://img.shields.io/npm/dm/memorix.svg?style=flat-square&color=blue" alt="npm downloads"></a>
9
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green.svg?style=flat-square" alt="License"></a>
10
- <a href="https://github.com/AVIDS2/memorix"><img src="https://img.shields.io/github/stars/AVIDS2/memorix?style=flat-square&color=yellow" alt="GitHub stars"></a>
11
- <img src="https://img.shields.io/badge/tests-509%20passed-brightgreen?style=flat-square" alt="Tests">
12
- </p>
13
- <p align="center">
14
- <img src="https://img.shields.io/badge/Works%20with-Cursor-orange?style=flat-square" alt="Cursor">
15
- <img src="https://img.shields.io/badge/Works%20with-Windsurf-blue?style=flat-square" alt="Windsurf">
16
- <img src="https://img.shields.io/badge/Works%20with-Claude%20Code-purple?style=flat-square" alt="Claude Code">
17
- <img src="https://img.shields.io/badge/Works%20with-Codex-green?style=flat-square" alt="Codex">
18
- <img src="https://img.shields.io/badge/Works%20with-Copilot-lightblue?style=flat-square" alt="Copilot">
19
- <img src="https://img.shields.io/badge/Works%20with-Kiro-red?style=flat-square" alt="Kiro">
20
- <img src="https://img.shields.io/badge/Works%20with-Antigravity-grey?style=flat-square" alt="Antigravity">
21
- <img src="https://img.shields.io/badge/Works%20with-Gemini%20CLI-4285F4?style=flat-square" alt="Gemini CLI">
22
- </p>
23
- <p align="center">
24
- <a href="#%EF%B8%8F-stop-re-explaining-your-project">Why</a> •
25
- <a href="#-get-started-in-30-seconds">Quick Start</a> •
26
- <a href="#-real-world-scenarios">Scenarios</a> •
27
- <a href="#-what-memorix-can-do">Features</a> •
28
- <a href="#-comparison-with-alternatives">Compare</a> •
29
- <a href="docs/SETUP.md">Full Setup Guide</a>
30
- </p>
2
+ <img src="assets/logo.png" alt="Memorix" width="120">
31
3
  </p>
32
4
 
33
- ---
5
+ <h1 align="center">Memorix</h1>
34
6
 
35
- ## ⚠️ Stop Re-Explaining Your Project
7
+ <p align="center">
8
+ <strong>Persistent memory layer for AI coding agents.</strong><br>
9
+ One MCP server. Nine agents. Zero context loss.
10
+ </p>
36
11
 
37
- Your AI assistant forgets everything when you start a new chat. You spend 10 minutes re-explaining your architecture. **Again.** And if you switch from Cursor to Claude Code? Everything is gone. **Again.**
12
+ <p align="center">
13
+ <a href="https://www.npmjs.com/package/memorix"><img src="https://img.shields.io/npm/v/memorix.svg?style=flat-square&color=cb3837" alt="npm"></a>
14
+ <a href="https://www.npmjs.com/package/memorix"><img src="https://img.shields.io/npm/dm/memorix.svg?style=flat-square&color=blue" alt="downloads"></a>
15
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green.svg?style=flat-square" alt="license"></a>
16
+ <a href="https://github.com/AVIDS2/memorix"><img src="https://img.shields.io/github/stars/AVIDS2/memorix?style=flat-square&color=yellow" alt="stars"></a>
17
+ <img src="https://img.shields.io/badge/tests-593%20passed-brightgreen?style=flat-square" alt="tests">
18
+ </p>
38
19
 
39
- | Without Memorix | With Memorix |
40
- |-----------------|--------------|
41
- | **Session 2:** "What's our tech stack?" | **Session 2:** "I remember — Next.js with Prisma and tRPC. What should we build next?" |
42
- | **Switch IDE:** All context lost | **Switch IDE:** Context follows you instantly |
43
- | **New team member's AI:** Starts from zero | **New team member's AI:** Already knows the codebase |
44
- | **After 50 tool calls:** Context explodes, restart needed | **After restart:** Picks up right where you left off |
45
- | **MCP configs:** Copy-paste between 7 IDEs manually | **MCP configs:** One command syncs everything |
20
+ <p align="center">
21
+ <img src="https://img.shields.io/badge/-Cursor-orange?style=flat-square" alt="Cursor">
22
+ <img src="https://img.shields.io/badge/-Windsurf-blue?style=flat-square" alt="Windsurf">
23
+ <img src="https://img.shields.io/badge/-Claude%20Code-purple?style=flat-square" alt="Claude Code">
24
+ <img src="https://img.shields.io/badge/-Codex-green?style=flat-square" alt="Codex">
25
+ <img src="https://img.shields.io/badge/-Copilot-lightblue?style=flat-square" alt="Copilot">
26
+ <img src="https://img.shields.io/badge/-Kiro-red?style=flat-square" alt="Kiro">
27
+ <img src="https://img.shields.io/badge/-Antigravity-grey?style=flat-square" alt="Antigravity">
28
+ <img src="https://img.shields.io/badge/-OpenCode-teal?style=flat-square" alt="OpenCode">
29
+ <img src="https://img.shields.io/badge/-Gemini%20CLI-4285F4?style=flat-square" alt="Gemini CLI">
30
+ </p>
46
31
 
47
- **Memorix solves all of this.** One MCP server. Eight agents. Zero context loss.
32
+ <p align="center">
33
+ <a href="README.zh-CN.md">中文文档</a> ·
34
+ <a href="#quick-start">Quick Start</a> ·
35
+ <a href="#features">Features</a> ·
36
+ <a href="#how-it-works">How It Works</a> ·
37
+ <a href="docs/SETUP.md">Full Setup Guide</a>
38
+ </p>
48
39
 
49
40
  ---
50
41
 
51
- ## ⚡ Get Started in 30 Seconds
42
+ ## Why Memorix?
52
43
 
53
- ### Step 1: Install globally (one-time)
44
+ AI coding agents forget everything between sessions. Switch IDEs and context is gone. Memorix gives every agent a shared, persistent memory — decisions, gotchas, and architecture survive across sessions and tools.
54
45
 
55
- ```bash
56
- npm install -g memorix
46
+ ```
47
+ Session 1 (Cursor): "Use JWT with refresh tokens, 15-min expiry" → stored as 🟤 decision
48
+ Session 2 (Claude Code): "Add login endpoint" → finds the decision → implements correctly
57
49
  ```
58
50
 
59
- > ⚠️ **Do NOT use `npx`** — npx downloads the package every time, which causes MCP server initialization timeout (60s limit). Global install starts instantly.
51
+ No re-explaining. No copy-pasting. No vendor lock-in.
60
52
 
61
- ### Step 2: Add to your agent's MCP config
53
+ ---
62
54
 
63
- <details open>
64
- <summary><strong>Claude Code</strong></summary>
55
+ ## Quick Start
65
56
 
66
- Run in terminal:
67
57
  ```bash
68
- claude mcp add memorix -- memorix serve
58
+ npm install -g memorix
69
59
  ```
70
- Or manually add to `~/.claude.json` (global) or `.claude/settings.json` (project):
60
+
61
+ Add to your agent's MCP config:
62
+
63
+ <details open>
64
+ <summary><strong>Cursor</strong> · <code>.cursor/mcp.json</code></summary>
65
+
71
66
  ```json
72
- {
73
- "mcpServers": {
74
- "memorix": {
75
- "command": "memorix",
76
- "args": ["serve"]
77
- }
78
- }
79
- }
67
+ { "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
80
68
  ```
81
- > **Windows:** `~/.claude.json` is at `C:\Users\<YourUsername>\.claude.json`
82
69
  </details>
83
70
 
84
71
  <details>
85
- <summary><strong>Cursor</strong></summary>
72
+ <summary><strong>Claude Code</strong></summary>
86
73
 
87
- Add to `.cursor/mcp.json` in your project:
88
- ```json
89
- {
90
- "mcpServers": {
91
- "memorix": {
92
- "command": "memorix",
93
- "args": ["serve"]
94
- }
95
- }
96
- }
74
+ ```bash
75
+ claude mcp add memorix -- memorix serve
97
76
  ```
98
77
  </details>
99
78
 
100
79
  <details>
101
- <summary><strong>Windsurf</strong></summary>
80
+ <summary><strong>Windsurf</strong> · <code>~/.codeium/windsurf/mcp_config.json</code></summary>
102
81
 
103
- Add to Windsurf MCP settings (`~/.codeium/windsurf/mcp_config.json`):
104
82
  ```json
105
- {
106
- "mcpServers": {
107
- "memorix": {
108
- "command": "memorix",
109
- "args": ["serve"]
110
- }
111
- }
112
- }
83
+ { "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
113
84
  ```
114
85
  </details>
115
86
 
116
87
  <details>
117
- <summary><strong>VS Code Copilot</strong></summary>
88
+ <summary><strong>VS Code Copilot</strong> · <code>.vscode/mcp.json</code></summary>
118
89
 
119
- Add to `.vscode/mcp.json` in your project:
120
90
  ```json
121
- {
122
- "servers": {
123
- "memorix": {
124
- "command": "memorix",
125
- "args": ["serve"]
126
- }
127
- }
128
- }
91
+ { "servers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
129
92
  ```
130
93
  </details>
131
94
 
132
95
  <details>
133
- <summary><strong>Codex</strong></summary>
96
+ <summary><strong>Codex</strong> · <code>~/.codex/config.toml</code></summary>
134
97
 
135
- Add to `~/.codex/config.toml`:
136
98
  ```toml
137
99
  [mcp_servers.memorix]
138
100
  command = "memorix"
139
101
  args = ["serve"]
140
- startup_timeout_sec = 30 # default is 10s, increase if you see handshake timeouts
141
102
  ```
142
103
  </details>
143
104
 
144
105
  <details>
145
- <summary><strong>Kiro</strong></summary>
106
+ <summary><strong>Kiro</strong> · <code>.kiro/settings/mcp.json</code></summary>
146
107
 
147
- Add to `.kiro/settings/mcp.json` (project) or `~/.kiro/settings/mcp.json` (global):
148
108
  ```json
149
- {
150
- "mcpServers": {
151
- "memorix": {
152
- "command": "memorix",
153
- "args": ["serve"]
154
- }
155
- }
156
- }
109
+ { "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
157
110
  ```
158
111
  </details>
159
112
 
160
113
  <details>
161
- <summary><strong>Antigravity</strong></summary>
114
+ <summary><strong>Antigravity</strong> · <code>~/.gemini/antigravity/mcp_config.json</code></summary>
162
115
 
163
- Add to `~/.gemini/antigravity/mcp_config.json`. Antigravity requires `MEMORIX_PROJECT_ROOT`:
164
116
  ```json
165
- {
166
- "mcpServers": {
167
- "memorix": {
168
- "command": "memorix",
169
- "args": ["serve"],
170
- "env": {
171
- "MEMORIX_PROJECT_ROOT": "E:/your/project/path"
172
- }
173
- }
174
- }
175
- }
117
+ { "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"], "env": { "MEMORIX_PROJECT_ROOT": "/your/project/path" } } } }
176
118
  ```
177
119
  </details>
178
120
 
179
121
  <details>
180
- <summary><strong>Gemini CLI</strong></summary>
122
+ <summary><strong>OpenCode</strong> · <code>~/.config/opencode/config.json</code></summary>
181
123
 
182
- Add to `.gemini/settings.json` (project) or `~/.gemini/settings.json` (global):
183
124
  ```json
184
- {
185
- "mcpServers": {
186
- "memorix": {
187
- "command": "memorix",
188
- "args": ["serve"]
189
- }
190
- }
191
- }
125
+ { "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
192
126
  ```
193
127
  </details>
194
128
 
195
- ### Step 3: Restart your agent — done!
196
-
197
- No API keys. No cloud accounts. No dependencies. Works with any directory (git repo or not).
198
-
199
- > 📖 **Full setup guide for all 8 agents** → [docs/SETUP.md](docs/SETUP.md)
200
-
201
- ### 🔧 Troubleshooting — MCP Connection Issues
202
-
203
- > **⚠️ #1 Mistake: Do NOT manually run `memorix serve` in a terminal.**
204
- > MCP uses **stdio transport** — your IDE (Claude Code, Cursor, etc.) launches memorix as a subprocess automatically. Running it manually in PowerShell/Terminal does nothing for the IDE connection.
129
+ <details>
130
+ <summary><strong>Gemini CLI</strong> · <code>.gemini/settings.json</code></summary>
205
131
 
206
- **Quick diagnostic** — run this first:
207
- ```bash
208
- memorix --version # Should print version number
209
- memorix serve --cwd . # Should show "[memorix] MCP Server running on stdio"
210
- ```
211
- If either fails, follow the table below:
212
-
213
- | Symptom | Cause | Fix |
214
- |---------|-------|-----|
215
- | `memorix · ✗ failed` in IDE | IDE can't find the `memorix` command | Run `npm install -g memorix`. On Windows, **restart your IDE** after install so it picks up the new PATH |
216
- | `MCP server initialization timed out` | Using `npx` (downloads every time) | Switch to global install: `npm install -g memorix`, change config to `"command": "memorix"` |
217
- | Repeated "Reconnected to memorix" then fails | memorix process crashes on startup | Check: 1) Node.js ≥ 18 (`node -v`), 2) open a **real project folder** (not Desktop/Home), 3) set `MEMORIX_PROJECT_ROOT` in MCP config |
218
- | `Cannot start Memorix: no valid project detected` | CWD is a system directory | Open a project folder with code, or add `"env": { "MEMORIX_PROJECT_ROOT": "/path/to/project" }` to your MCP config |
219
- | `memorix: command not found` | npm global bin not in PATH | Run `npm config get prefix` to find install location, add its `bin/` to your system PATH, then restart IDE |
220
- | Works in terminal but not in IDE | IDE uses a different PATH than your shell | **Windows:** restart IDE after `npm install -g`. **macOS/Linux:** ensure `~/.bashrc` or `~/.zshrc` exports the npm global bin path |
221
- | Parameter type errors | Old version or non-Anthropic model quirks | Update: `npm install -g memorix@latest` |
222
-
223
- **Correct config:**
224
132
  ```json
225
- "command": "memorix", "args": ["serve"]
226
- ```
227
-
228
- **❌ Wrong:**
229
- ```
230
- "command": "npx" ← will timeout
231
- "command": "npx -y memorix serve" ← wrong format
232
- "command": "node memorix serve" ← not how it works
233
- ```
234
-
235
- ---
236
-
237
- ## 🔍 Hybrid Search (BM25 + Vector)
238
-
239
- Memorix uses **BM25 fulltext search** by default (powered by [Orama](https://orama.com/)). For better semantic recall, install an optional embedding provider to enable **hybrid search** (60% BM25 + 40% vector similarity):
240
-
241
- ```bash
242
- # Option 1: Pure JS/WASM — works everywhere, no native deps (~22MB model)
243
- npm install -g @huggingface/transformers
244
-
245
- # Option 2: Native ONNX — faster inference, requires C++ build tools
246
- npm install -g fastembed
247
- ```
248
-
249
- Check your search engine status:
250
- ```bash
251
- memorix status # Shows embedding provider and observation count
252
- ```
253
-
254
- When an embedding provider is available, `memorix_search` automatically switches to hybrid mode — no configuration needed. Search quality improves significantly for semantic queries like "how does auth work" vs exact keyword matches.
255
-
256
- ---
257
-
258
- ## 🎬 Real-World Scenarios
259
-
260
- ### Scenario 1: Cross-Session Memory
261
-
262
- ```
263
- Monday morning — You and Cursor discuss auth architecture:
264
- You: "Let's use JWT with refresh tokens, 15-minute expiry"
265
- → Memorix auto-stores this as a 🟤 decision
266
-
267
- Tuesday — New Cursor session:
268
- You: "Add the login endpoint"
269
- → AI calls memorix_search("auth") → finds Monday's decision
270
- → "Got it, I'll implement JWT with 15-min refresh tokens as we decided"
271
- → Zero re-explaining!
272
- ```
273
-
274
- ### Scenario 2: Cross-Agent Collaboration
275
-
276
- ```
277
- You use Windsurf for backend, Claude Code for reviews:
278
-
279
- Windsurf: You fix a tricky race condition in the payment module
280
- → Memorix stores it as a 🟡 problem-solution with the fix details
281
-
282
- Claude Code: "Review the payment module"
283
- → AI calls memorix_search("payment") → finds the race condition fix
284
- → "I see there was a recent race condition fix. Let me verify it's correct..."
285
- → Knowledge transfers seamlessly between agents!
286
- ```
287
-
288
- ### Scenario 3: Gotcha Prevention
289
-
290
- ```
291
- Week 1: You hit a painful Windows path separator bug
292
- → Memorix stores it as a 🔴 gotcha: "Use path.join(), never string concat"
293
-
294
- Week 3: AI is about to write `baseDir + '/' + filename`
295
- → Session-start hook injected the gotcha into context
296
- → AI writes `path.join(baseDir, filename)` instead
297
- → Bug prevented before it happened!
133
+ { "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
298
134
  ```
135
+ </details>
299
136
 
300
- ### Scenario 4: Workspace Sync Across IDEs
137
+ Restart your agent. Done. No API keys, no cloud, no dependencies.
301
138
 
302
- ```
303
- You have 12 MCP servers configured in Cursor.
304
- Now you want to try Kiro.
305
-
306
- You: "Sync my workspace to Kiro"
307
- → memorix_workspace_sync scans Cursor's MCP configs
308
- → Generates Kiro-compatible .kiro/settings/mcp.json
309
- → Also syncs your rules, skills, and workflows
310
- → Kiro is ready in seconds, not hours!
311
- ```
139
+ > **Note:** Do NOT use `npx` — it re-downloads each time and causes MCP timeout. Use global install.
140
+ >
141
+ > 📖 [Full setup guide](docs/SETUP.md) · [Troubleshooting](docs/SETUP.md#troubleshooting)
312
142
 
313
143
  ---
314
144
 
315
- ## 🧠 What Memorix Can Do
145
+ ## Features
316
146
 
317
147
  ### 25 MCP Tools
318
148
 
319
- | Category | Tools | What They Do |
320
- |----------|-------|-------------|
321
- | **Store & Classify** | `memorix_store`, `memorix_suggest_topic_key` | Store memories with 9 types (🔴gotcha 🟤decision 🟡fix ...), dedup via topic keys |
322
- | **Search & Retrieve** | `memorix_search`, `memorix_detail`, `memorix_timeline` | 3-layer progressive disclosure (~10x token savings), temporal queries, chronological context |
323
- | **Sessions** | `memorix_session_start/end/context` | Auto-inject previous session context, save structured summaries |
324
- | **Maintenance** | `memorix_retention`, `memorix_consolidate`, `memorix_export/import` | Decay scoring, merge duplicates, backup & share |
325
- | **Dashboard** | `memorix_dashboard` | Interactive web UI — D3.js knowledge graph, observation browser, retention panel |
326
- | **Workspace Sync** | `memorix_workspace_sync`, `memorix_rules_sync`, `memorix_skills` | Migrate MCP configs across 8 agents, sync rules (`.mdc` ↔ `CLAUDE.md` ↔ `.kiro/steering/`), auto-generate project skills |
327
- | **Knowledge Graph** | `create_entities`, `create_relations`, `add_observations`, `delete_entities`, `delete_observations`, `delete_relations`, `search_nodes`, `open_nodes`, `read_graph` | [MCP Official Memory Server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) compatible — same API, more features |
149
+ | | |
150
+ |---|---|
151
+ | **Memory** | `memorix_store` · `memorix_search` · `memorix_detail` · `memorix_timeline` — 3-layer progressive disclosure with ~10x token savings |
152
+ | **Sessions** | `memorix_session_start` · `memorix_session_end` · `memorix_session_context` — auto-inject previous context on new sessions |
153
+ | **Knowledge Graph** | `create_entities` · `create_relations` · `add_observations` · `search_nodes` · `open_nodes` · `read_graph` — [MCP Official Memory Server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) compatible |
154
+ | **Workspace Sync** | `memorix_workspace_sync` · `memorix_rules_sync` · `memorix_skills` — migrate MCP configs, rules, and skills across 9 agents |
155
+ | **Maintenance** | `memorix_retention` · `memorix_consolidate` · `memorix_export` · `memorix_import` — decay scoring, dedup, backup |
156
+ | **Dashboard** | `memorix_dashboard` — web UI with D3.js knowledge graph, observation browser, retention panel |
328
157
 
329
158
  ### 9 Observation Types
330
159
 
331
- Every memory is classified: 🎯 session-request · 🔴 gotcha · 🟡 problem-solution · 🔵 how-it-works · 🟢 what-changed · 🟣 discovery · 🟠 why-it-exists · 🟤 decision · ⚖️ trade-off
160
+ 🎯 session-request · 🔴 gotcha · 🟡 problem-solution · 🔵 how-it-works · 🟢 what-changed · 🟣 discovery · 🟠 why-it-exists · 🟤 decision · ⚖️ trade-off
332
161
 
333
162
  ### Auto-Memory Hooks
334
163
 
335
164
  ```bash
336
- memorix hooks install # One-command setup
165
+ memorix hooks install
337
166
  ```
338
167
 
339
- Automatically captures decisions, errors, and gotchas from your coding sessions. Detects patterns in English + Chinese, injects high-value memories at session start, with smart filtering (30s cooldown, skips trivial commands).
168
+ Captures decisions, errors, and gotchas automatically. Pattern detection in English + Chinese. Smart filtering (30s cooldown, skips trivial commands). Injects high-value memories at session start.
340
169
 
341
- ---
170
+ ### Hybrid Search
342
171
 
343
- ## 📊 Comparison with Alternatives
344
-
345
- | | [Mem0](https://github.com/mem0ai/mem0) | [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) | [claude-mem](https://github.com/anthropics/claude-code) | **Memorix** |
346
- |---|---|---|---|---|
347
- | **Agents supported** | SDK-based | 13+ (MCP) | Claude Code only | **8 agents (MCP)** |
348
- | **Cross-agent sync** | No | No | No | **Yes (configs, rules, skills, workflows)** |
349
- | **Rules sync** | No | No | No | **Yes (7 formats)** |
350
- | **Skills engine** | No | No | No | **Yes (auto-generated from memory)** |
351
- | **Knowledge graph** | No | Yes | No | **Yes (MCP Official compatible)** |
352
- | **Hybrid search** | No | Yes | No | **Yes (BM25 + vector)** |
353
- | **Token-efficient** | No | No | Yes (3-layer) | **Yes (3-layer progressive disclosure)** |
354
- | **Auto-memory hooks** | No | No | Yes | **Yes (multi-language)** |
355
- | **Memory decay** | No | Yes | No | **Yes (exponential + immunity)** |
356
- | **Visual dashboard** | Cloud UI | Yes | No | **Yes (web UI + D3.js graph)** |
357
- | **Privacy** | Cloud | Local | Local | **100% Local** |
358
- | **Cost** | Per-call API | $0 | $0 | **$0** |
359
- | **Install** | `pip install` | `pip install` | Built into Claude | **`npm i -g memorix`** |
360
-
361
- **Memorix is the only tool that bridges memory AND workspace across agents.**
172
+ BM25 fulltext out of the box (~50MB RAM). Semantic search is **opt-in** — 3 providers:
362
173
 
363
- ---
174
+ ```bash
175
+ # Set in your MCP config env:
176
+ MEMORIX_EMBEDDING=api # ⭐ Recommended — zero local RAM, best quality
177
+ MEMORIX_EMBEDDING=fastembed # Local ONNX (~300MB RAM)
178
+ MEMORIX_EMBEDDING=transformers # Local JS/WASM (~500MB RAM)
179
+ MEMORIX_EMBEDDING=off # Default — BM25 only, minimal resources
180
+ ```
364
181
 
365
- ## 🔮 Optional: Vector Search
182
+ #### API Embedding (Recommended)
366
183
 
367
- Out of the box, Memorix uses BM25 full-text search (already great for code). Add semantic search with one command:
184
+ Works with any OpenAI-compatible endpoint — OpenAI, Qwen, Cohere, 中转站/反代, Ollama:
368
185
 
369
186
  ```bash
370
- # Option A: Native speed (recommended)
371
- npm install -g fastembed
372
-
373
- # Option B: Universal compatibility
374
- npm install -g @huggingface/transformers
187
+ MEMORIX_EMBEDDING=api
188
+ MEMORIX_EMBEDDING_API_KEY=sk-xxx # or reuse OPENAI_API_KEY
189
+ MEMORIX_EMBEDDING_MODEL=text-embedding-3-small # default
190
+ MEMORIX_EMBEDDING_BASE_URL=https://api.openai.com/v1 # optional
191
+ MEMORIX_EMBEDDING_DIMENSIONS=512 # optional dimension shortening
375
192
  ```
376
193
 
377
- With vector search, queries like "authentication" also match memories about "login flow" via semantic similarity. Both run **100% locally** — zero API calls, zero cost.
194
+ **Performance advantages over competitors:**
195
+ - **10K LRU cache + disk persistence** — repeat queries cost $0 and take 0ms
196
+ - **Batch API calls** — up to 2048 texts per request (competitors: 1-by-1)
197
+ - **4x concurrent processing** — parallel batch chunks
198
+ - **Text normalization** — better cache hit rates via whitespace dedup
199
+ - **Debounced disk writes** — 5s coalesce window, not per-call I/O
200
+ - **Zero external dependencies** — no Chroma, no SQLite, just native `fetch`
201
+ - **Smart key fallback** — auto-reuses LLM API key if same provider
378
202
 
379
- ---
203
+ #### Local Embedding
380
204
 
381
- ## 🔒 Project Isolation
205
+ ```bash
206
+ npm install -g fastembed # for MEMORIX_EMBEDDING=fastembed
207
+ npm install -g @huggingface/transformers # for MEMORIX_EMBEDDING=transformers
208
+ ```
382
209
 
383
- - **Auto-detected** — Project identity from `git remote` URL, zero config needed
384
- - **MCP roots fallback** — If `cwd` is not a project (e.g., Antigravity), Memorix tries the [MCP roots protocol](https://modelcontextprotocol.io/docs/concepts/roots) to get your workspace path from the IDE
385
- - **Shared storage, metadata isolation** — All data lives in `~/.memorix/data/`, with `projectId` embedded in each observation. This ensures cross-IDE sharing works even when different IDEs detect different project IDs for the same repo
386
- - **Scoped search** — Defaults to current project; `scope: "global"` to search all
387
- - **Zero cross-contamination** — Search results are filtered by project ID; project A's decisions never appear in project B's searches
210
+ Both run 100% locally. Zero API calls.
388
211
 
389
- **Detection priority:** `--cwd` → `MEMORIX_PROJECT_ROOT` → `INIT_CWD` → `process.cwd()` → MCP roots → error
212
+ ### LLM Enhanced Mode (Optional)
390
213
 
391
- ---
214
+ Enable intelligent memory deduplication and fact extraction with your own API key:
392
215
 
393
- ## ❓ Frequently Asked Questions
216
+ ```bash
217
+ # Set in your MCP config env, or export before starting:
218
+ MEMORIX_LLM_API_KEY=sk-xxx # OpenAI-compatible API key
219
+ MEMORIX_LLM_PROVIDER=openai # openai | anthropic | openrouter
220
+ MEMORIX_LLM_MODEL=gpt-4o-mini # model name
221
+ MEMORIX_LLM_BASE_URL=https://... # custom endpoint (optional)
222
+ ```
394
223
 
395
- **How do I keep context when switching between Cursor and Claude Code?**
396
- Install Memorix in both IDEs. They share the same local memory directory — architecture decisions made in Cursor are instantly searchable in Claude Code. No cloud sync needed.
224
+ Or use existing env vars — Memorix auto-detects:
225
+ - `OPENAI_API_KEY` → OpenAI
226
+ - `ANTHROPIC_API_KEY` → Anthropic
227
+ - `OPENROUTER_API_KEY` → OpenRouter
397
228
 
398
- **How do I prevent my AI from forgetting previous sessions?**
399
- Use `memorix_session_start` at the beginning of each session — it automatically injects previous session summaries and key observations (gotchas, decisions, discoveries). Use `memorix_session_end` to save a structured summary before leaving. All observations persist on disk and are searchable via `memorix_search` anytime.
229
+ **Without LLM**: Free heuristic deduplication (similarity-based)
230
+ **With LLM**: Smart merge, fact extraction, contradiction detection
400
231
 
401
- **How do I sync MCP server configs between IDEs?**
402
- Run `memorix_workspace_sync` with action `"migrate"` and your target IDE. It scans source configs and generates compatible configs for the target — merges, never overwrites.
232
+ ### Interactive CLI
403
233
 
404
- **How do I migrate from Cursor to Windsurf / Kiro / Claude Code?**
405
- Memorix workspace sync migrates MCP configs, agent rules (`.mdc` ↔ `CLAUDE.md` ↔ `.kiro/steering/`), skills, and workflows. One command, seconds to complete.
234
+ ```bash
235
+ memorix # Interactive menu (no args)
236
+ memorix configure # LLM + Embedding provider setup (TUI)
237
+ memorix status # Project info + stats
238
+ memorix dashboard # Web UI at localhost:3210
239
+ memorix hooks install # Auto-capture for IDEs
240
+ ```
406
241
 
407
- **Is there an MCP server for persistent AI coding memory?**
408
- Yes — Memorix is a cross-agent memory MCP server supporting 8 agents with knowledge graph, 3-layer progressive disclosure search, workspace sync, and auto-generated project skills.
242
+ ---
409
243
 
410
- **How is this different from mcp-memory-service?**
411
- Both are great memory servers. Memorix adds: cross-agent workspace sync (MCP configs, rules, skills), auto-generated project skills from memory patterns, 3-layer token-efficient search, and session-start memory injection hooks.
244
+ ## How It Works
412
245
 
413
- **Does it work offline / locally?**
414
- Yes, 100%. All data stored in `~/.memorix/data/`. No cloud, no API keys, no external services. Optional vector search also runs locally via ONNX/WASM.
246
+ ```
247
+ ┌─────────┐ ┌───────────┐ ┌────────────┐ ┌───────┐ ┌──────────┐
248
+ │ Cursor │ │ Claude │ │ Windsurf │ │ Codex │ │ +4 more │
249
+ │ │ │ Code │ │ │ │ │ │ │
250
+ └────┬────┘ └─────┬─────┘ └─────┬──────┘ └───┬───┘ └────┬─────┘
251
+ │ │ │ │ │
252
+ └─────────────┴──────┬───────┴──────────────┴───────────┘
253
+ │ MCP (stdio)
254
+ ┌──────┴──────┐
255
+ │ Memorix │
256
+ │ MCP Server │
257
+ └──────┬──────┘
258
+ │
259
+ ┌───────────────┼───────────────┐
260
+ │ │ │
261
+ ┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐
262
+ │ Orama │ │ Knowledge │ │ Rules & │
263
+ │ Search │ │ Graph │ │ Workspace │
264
+ │ (BM25+Vec) │ │ (Entities) │ │ Sync │
265
+ └─────────────┘ └─────────────┘ └─────────────┘
266
+ │
267
+ ~/.memorix/data/
268
+ (100% local, per-project isolation)
269
+ ```
415
270
 
416
- > 📖 For AI systems: see [`llms.txt`](llms.txt) and [`llms-full.txt`](llms-full.txt) for machine-readable project documentation.
271
+ - **Project isolation** — auto-detected from `git remote`, scoped search by default
272
+ - **Shared storage** — all agents read/write the same `~/.memorix/data/`, cross-IDE by design
273
+ - **Token efficient** — 3-layer progressive disclosure: search → timeline → detail
417
274
 
418
275
  ---
419
276
 
420
- ## 🧑‍💻 Development
277
+ ## Development
421
278
 
422
279
  ```bash
423
280
  git clone https://github.com/AVIDS2/memorix.git
424
- cd memorix
425
- npm install
281
+ cd memorix && npm install
426
282
 
427
- npm run dev # tsup watch mode
428
- npm test # vitest (509 tests)
429
- npm run lint # TypeScript type check
430
- npm run build # Production build
283
+ npm run dev # watch mode
284
+ npm test # 593 tests
285
+ npm run build # production build
431
286
  ```
432
287
 
433
- > 📚 **Documentation:** [Architecture](docs/ARCHITECTURE.md) • [API Reference](docs/API_REFERENCE.md) • [Modules](docs/MODULES.md) • [Design Decisions](docs/DESIGN_DECISIONS.md) • [Setup Guide](docs/SETUP.md) • [Known Issues](docs/KNOWN_ISSUES_AND_ROADMAP.md)
288
+ 📚 [Architecture](docs/ARCHITECTURE.md) · [API Reference](docs/API_REFERENCE.md) · [Modules](docs/MODULES.md) · [Design Decisions](docs/DESIGN_DECISIONS.md)
289
+
290
+ > For AI systems: [`llms.txt`](llms.txt) · [`llms-full.txt`](llms-full.txt)
434
291
 
435
292
  ---
436
293
 
437
- ## 🙏 Acknowledgements
294
+ ## Acknowledgements
438
295
 
439
- Memorix stands on the shoulders of these excellent projects:
296
+ Built on ideas from [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service), [MemCP](https://github.com/maydali28/memcp), [claude-mem](https://github.com/anthropics/claude-code), and [Mem0](https://github.com/mem0ai/mem0).
440
297
 
441
- - [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) — Hybrid search, exponential decay, access tracking
442
- - [MemCP](https://github.com/maydali28/memcp) — MAGMA 4-graph, entity extraction, retention lifecycle
443
- - [claude-mem](https://github.com/anthropics/claude-code) — 3-layer Progressive Disclosure
444
- - [Mem0](https://github.com/mem0ai/mem0) — Memory layer architecture patterns
298
+ ## Star History
445
299
 
446
- ---
300
+ <a href="https://star-history.com/#AVIDS2/memorix&Date">
301
+ <picture>
302
+ <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=AVIDS2/memorix&type=Date&theme=dark" />
303
+ <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=AVIDS2/memorix&type=Date" />
304
+ <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=AVIDS2/memorix&type=Date" width="600" />
305
+ </picture>
306
+ </a>
447
307
 
448
- ## 📄 License
308
+ ## License
449
309
 
450
- Apache 2.0 — see [LICENSE](LICENSE)
310
+ [Apache 2.0](LICENSE)
451
311
 
452
312
  ---
453
313
 
454
314
  <p align="center">
455
- <strong>Made with ❤️ by <a href="https://github.com/AVIDS2">AVIDS2</a></strong>
456
- <br>
457
- <sub>If Memorix helps your workflow, consider giving it a ⭐ on GitHub!</sub>
315
+ <sub>Built by <a href="https://github.com/AVIDS2">AVIDS2</a> · Star ⭐ if it helps your workflow</sub>
458
316
  </p>