npm - memorix - Versions diffs - 0.9.37 → 0.10.2 - Mend

memorix 0.9.37 → 0.10.2

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

package/README.md CHANGED Viewed

@@ -1,458 +1,271 @@
 <p align="center">
-  <img src="assets/logo.png" alt="Memorix Logo" width="120">
-  <h1 align="center">Memorix</h1>
-  <p align="center"><strong>Cross-Agent Memory Bridge — Your AI never forgets again</strong></p>
-  <p align="center"><a href="README.zh-CN.md">中文文档</a> | English</p>
-  <p align="center">
-    <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>
-    <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>
-    <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green.svg?style=flat-square" alt="License"></a>
-    <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>
-    <img src="https://img.shields.io/badge/tests-509%20passed-brightgreen?style=flat-square" alt="Tests">
-  </p>
-  <p align="center">
-    <img src="https://img.shields.io/badge/Works%20with-Cursor-orange?style=flat-square" alt="Cursor">
-    <img src="https://img.shields.io/badge/Works%20with-Windsurf-blue?style=flat-square" alt="Windsurf">
-    <img src="https://img.shields.io/badge/Works%20with-Claude%20Code-purple?style=flat-square" alt="Claude Code">
-    <img src="https://img.shields.io/badge/Works%20with-Codex-green?style=flat-square" alt="Codex">
-    <img src="https://img.shields.io/badge/Works%20with-Copilot-lightblue?style=flat-square" alt="Copilot">
-    <img src="https://img.shields.io/badge/Works%20with-Kiro-red?style=flat-square" alt="Kiro">
-    <img src="https://img.shields.io/badge/Works%20with-Antigravity-grey?style=flat-square" alt="Antigravity">
-    <img src="https://img.shields.io/badge/Works%20with-Gemini%20CLI-4285F4?style=flat-square" alt="Gemini CLI">
-  </p>
-  <p align="center">
-    <a href="#%EF%B8%8F-stop-re-explaining-your-project">Why</a> •
-    <a href="#-get-started-in-30-seconds">Quick Start</a> •
-    <a href="#-real-world-scenarios">Scenarios</a> •
-    <a href="#-what-memorix-can-do">Features</a> •
-    <a href="#-comparison-with-alternatives">Compare</a> •
-    <a href="docs/SETUP.md">Full Setup Guide</a>
-  </p>
+  <img src="assets/logo.png" alt="Memorix" width="120">
 </p>
----
+<h1 align="center">Memorix</h1>
-## ⚠️ Stop Re-Explaining Your Project
+<p align="center">
+  <strong>Persistent memory layer for AI coding agents.</strong><br>
+  One MCP server. Nine agents. Zero context loss.
+</p>
-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.**
+<p align="center">
+  <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>
+  <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>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green.svg?style=flat-square" alt="license"></a>
+  <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>
+  <img src="https://img.shields.io/badge/tests-534%20passed-brightgreen?style=flat-square" alt="tests">
+</p>
-| Without Memorix | With Memorix |
-|-----------------|--------------|
-| **Session 2:** "What's our tech stack?" | **Session 2:** "I remember — Next.js with Prisma and tRPC. What should we build next?" |
-| **Switch IDE:** All context lost | **Switch IDE:** Context follows you instantly |
-| **New team member's AI:** Starts from zero | **New team member's AI:** Already knows the codebase |
-| **After 50 tool calls:** Context explodes, restart needed | **After restart:** Picks up right where you left off |
-| **MCP configs:** Copy-paste between 7 IDEs manually | **MCP configs:** One command syncs everything |
+<p align="center">
+  <img src="https://img.shields.io/badge/-Cursor-orange?style=flat-square" alt="Cursor">
+  <img src="https://img.shields.io/badge/-Windsurf-blue?style=flat-square" alt="Windsurf">
+  <img src="https://img.shields.io/badge/-Claude%20Code-purple?style=flat-square" alt="Claude Code">
+  <img src="https://img.shields.io/badge/-Codex-green?style=flat-square" alt="Codex">
+  <img src="https://img.shields.io/badge/-Copilot-lightblue?style=flat-square" alt="Copilot">
+  <img src="https://img.shields.io/badge/-Kiro-red?style=flat-square" alt="Kiro">
+  <img src="https://img.shields.io/badge/-Antigravity-grey?style=flat-square" alt="Antigravity">
+  <img src="https://img.shields.io/badge/-OpenCode-teal?style=flat-square" alt="OpenCode">
+  <img src="https://img.shields.io/badge/-Gemini%20CLI-4285F4?style=flat-square" alt="Gemini CLI">
+</p>
-**Memorix solves all of this.** One MCP server. Eight agents. Zero context loss.
+<p align="center">
+  <a href="README.zh-CN.md">中文文档</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#features">Features</a> ·
+  <a href="#how-it-works">How It Works</a> ·
+  <a href="docs/SETUP.md">Full Setup Guide</a>
+</p>
 ---
-## ⚡ Get Started in 30 Seconds
+## Why Memorix?
-### Step 1: Install globally (one-time)
+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.
-```bash
-npm install -g memorix
+```
+Session 1 (Cursor):  "Use JWT with refresh tokens, 15-min expiry"  → stored as 🟤 decision
+Session 2 (Claude Code):  "Add login endpoint"  → finds the decision → implements correctly
 ```
-> ⚠️ **Do NOT use `npx`** — npx downloads the package every time, which causes MCP server initialization timeout (60s limit). Global install starts instantly.
+No re-explaining. No copy-pasting. No vendor lock-in.
-### Step 2: Add to your agent's MCP config
+---
-<details open>
-<summary><strong>Claude Code</strong></summary>
+## Quick Start
-Run in terminal:
 ```bash
-claude mcp add memorix -- memorix serve
+npm install -g memorix
 ```
-Or manually add to `~/.claude.json` (global) or `.claude/settings.json` (project):
+Add to your agent's MCP config:
+<details open>
+<summary><strong>Cursor</strong> · <code>.cursor/mcp.json</code></summary>
 ```json
-{
-  "mcpServers": {
-    "memorix": {
-      "command": "memorix",
-      "args": ["serve"]
-    }
-  }
-}
+{ "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
 ```
-> **Windows:** `~/.claude.json` is at `C:\Users\<YourUsername>\.claude.json`
 </details>
 <details>
-<summary><strong>Cursor</strong></summary>
+<summary><strong>Claude Code</strong></summary>
-Add to `.cursor/mcp.json` in your project:
-```json
-{
-  "mcpServers": {
-    "memorix": {
-      "command": "memorix",
-      "args": ["serve"]
-    }
-  }
-}
+```bash
+claude mcp add memorix -- memorix serve
 ```
 </details>
 <details>
-<summary><strong>Windsurf</strong></summary>
+<summary><strong>Windsurf</strong> · <code>~/.codeium/windsurf/mcp_config.json</code></summary>
-Add to Windsurf MCP settings (`~/.codeium/windsurf/mcp_config.json`):
 ```json
-{
-  "mcpServers": {
-    "memorix": {
-      "command": "memorix",
-      "args": ["serve"]
-    }
-  }
-}
+{ "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
 ```
 </details>
 <details>
-<summary><strong>VS Code Copilot</strong></summary>
+<summary><strong>VS Code Copilot</strong> · <code>.vscode/mcp.json</code></summary>
-Add to `.vscode/mcp.json` in your project:
 ```json
-{
-  "servers": {
-    "memorix": {
-      "command": "memorix",
-      "args": ["serve"]
-    }
-  }
-}
+{ "servers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
 ```
 </details>
 <details>
-<summary><strong>Codex</strong></summary>
+<summary><strong>Codex</strong> · <code>~/.codex/config.toml</code></summary>
-Add to `~/.codex/config.toml`:
 ```toml
 [mcp_servers.memorix]
 command = "memorix"
 args = ["serve"]
-startup_timeout_sec = 30  # default is 10s, increase if you see handshake timeouts
 ```
 </details>
 <details>
-<summary><strong>Kiro</strong></summary>
+<summary><strong>Kiro</strong> · <code>.kiro/settings/mcp.json</code></summary>
-Add to `.kiro/settings/mcp.json` (project) or `~/.kiro/settings/mcp.json` (global):
 ```json
-{
-  "mcpServers": {
-    "memorix": {
-      "command": "memorix",
-      "args": ["serve"]
-    }
-  }
-}
+{ "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
 ```
 </details>
 <details>
-<summary><strong>Antigravity</strong></summary>
+<summary><strong>Antigravity</strong> · <code>~/.gemini/antigravity/mcp_config.json</code></summary>
-Add to `~/.gemini/antigravity/mcp_config.json`. Antigravity requires `MEMORIX_PROJECT_ROOT`:
 ```json
-{
-  "mcpServers": {
-    "memorix": {
-      "command": "memorix",
-      "args": ["serve"],
-      "env": {
-        "MEMORIX_PROJECT_ROOT": "E:/your/project/path"
-      }
-    }
-  }
-}
+{ "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"], "env": { "MEMORIX_PROJECT_ROOT": "/your/project/path" } } } }
 ```
 </details>
 <details>
-<summary><strong>Gemini CLI</strong></summary>
+<summary><strong>OpenCode</strong> · <code>~/.config/opencode/config.json</code></summary>
-Add to `.gemini/settings.json` (project) or `~/.gemini/settings.json` (global):
 ```json
-{
-  "mcpServers": {
-    "memorix": {
-      "command": "memorix",
-      "args": ["serve"]
-    }
-  }
-}
+{ "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
 ```
 </details>
-### Step 3: Restart your agent — done!
-No API keys. No cloud accounts. No dependencies. Works with any directory (git repo or not).
-> 📖 **Full setup guide for all 8 agents** → [docs/SETUP.md](docs/SETUP.md)
-### 🔧 Troubleshooting — MCP Connection Issues
-> **⚠️ #1 Mistake: Do NOT manually run `memorix serve` in a terminal.**
-> 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.
+<details>
+<summary><strong>Gemini CLI</strong> · <code>.gemini/settings.json</code></summary>
-**Quick diagnostic** — run this first:
-```bash
-memorix --version       # Should print version number
-memorix serve --cwd .   # Should show "[memorix] MCP Server running on stdio"
-```
-If either fails, follow the table below:
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| `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 |
-| `MCP server initialization timed out` | Using `npx` (downloads every time) | Switch to global install: `npm install -g memorix`, change config to `"command": "memorix"` |
-| 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 |
-| `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 |
-| `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 |
-| 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 |
-| Parameter type errors | Old version or non-Anthropic model quirks | Update: `npm install -g memorix@latest` |
-**Correct config:**
 ```json
-"command": "memorix", "args": ["serve"]
-```
-**❌ Wrong:**
-```
-"command": "npx"                    ← will timeout
-"command": "npx -y memorix serve"   ← wrong format
-"command": "node memorix serve"     ← not how it works
-```
----
-## 🔍 Hybrid Search (BM25 + Vector)
-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):
-```bash
-# Option 1: Pure JS/WASM — works everywhere, no native deps (~22MB model)
-npm install -g @huggingface/transformers
-# Option 2: Native ONNX — faster inference, requires C++ build tools
-npm install -g fastembed
-```
-Check your search engine status:
-```bash
-memorix status   # Shows embedding provider and observation count
-```
-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.
----
-## 🎬 Real-World Scenarios
-### Scenario 1: Cross-Session Memory
-```
-Monday morning — You and Cursor discuss auth architecture:
-  You: "Let's use JWT with refresh tokens, 15-minute expiry"
-  → Memorix auto-stores this as a 🟤 decision
-Tuesday — New Cursor session:
-  You: "Add the login endpoint"
-  → AI calls memorix_search("auth") → finds Monday's decision
-  → "Got it, I'll implement JWT with 15-min refresh tokens as we decided"
-  → Zero re-explaining!
-```
-### Scenario 2: Cross-Agent Collaboration
-```
-You use Windsurf for backend, Claude Code for reviews:
-  Windsurf: You fix a tricky race condition in the payment module
-  → Memorix stores it as a 🟡 problem-solution with the fix details
-  Claude Code: "Review the payment module"
-  → AI calls memorix_search("payment") → finds the race condition fix
-  → "I see there was a recent race condition fix. Let me verify it's correct..."
-  → Knowledge transfers seamlessly between agents!
-```
-### Scenario 3: Gotcha Prevention
-```
-Week 1: You hit a painful Windows path separator bug
-  → Memorix stores it as a 🔴 gotcha: "Use path.join(), never string concat"
-Week 3: AI is about to write `baseDir + '/' + filename`
-  → Session-start hook injected the gotcha into context
-  → AI writes `path.join(baseDir, filename)` instead
-  → Bug prevented before it happened!
+{ "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
 ```
+</details>
-### Scenario 4: Workspace Sync Across IDEs
+Restart your agent. Done. No API keys, no cloud, no dependencies.
-```
-You have 12 MCP servers configured in Cursor.
-Now you want to try Kiro.
-  You: "Sync my workspace to Kiro"
-  → memorix_workspace_sync scans Cursor's MCP configs
-  → Generates Kiro-compatible .kiro/settings/mcp.json
-  → Also syncs your rules, skills, and workflows
-  → Kiro is ready in seconds, not hours!
-```
+> **Note:** Do NOT use `npx` — it re-downloads each time and causes MCP timeout. Use global install.
+>
+> 📖 [Full setup guide](docs/SETUP.md) · [Troubleshooting](docs/SETUP.md#troubleshooting)
 ---
-## 🧠 What Memorix Can Do
+## Features
 ### 25 MCP Tools
-| Category | Tools | What They Do |
-|----------|-------|-------------|
-| **Store & Classify** | `memorix_store`, `memorix_suggest_topic_key` | Store memories with 9 types (🔴gotcha 🟤decision 🟡fix ...), dedup via topic keys |
-| **Search & Retrieve** | `memorix_search`, `memorix_detail`, `memorix_timeline` | 3-layer progressive disclosure (~10x token savings), temporal queries, chronological context |
-| **Sessions** | `memorix_session_start/end/context` | Auto-inject previous session context, save structured summaries |
-| **Maintenance** | `memorix_retention`, `memorix_consolidate`, `memorix_export/import` | Decay scoring, merge duplicates, backup & share |
-| **Dashboard** | `memorix_dashboard` | Interactive web UI — D3.js knowledge graph, observation browser, retention panel |
-| **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 |
-| **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 |
+| | |
+|---|---|
+| **Memory** | `memorix_store` · `memorix_search` · `memorix_detail` · `memorix_timeline` — 3-layer progressive disclosure with ~10x token savings |
+| **Sessions** | `memorix_session_start` · `memorix_session_end` · `memorix_session_context` — auto-inject previous context on new sessions |
+| **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 |
+| **Workspace Sync** | `memorix_workspace_sync` · `memorix_rules_sync` · `memorix_skills` — migrate MCP configs, rules, and skills across 9 agents |
+| **Maintenance** | `memorix_retention` · `memorix_consolidate` · `memorix_export` · `memorix_import` — decay scoring, dedup, backup |
+| **Dashboard** | `memorix_dashboard` — web UI with D3.js knowledge graph, observation browser, retention panel |
 ### 9 Observation Types
-Every memory is classified: 🎯 session-request · 🔴 gotcha · 🟡 problem-solution · 🔵 how-it-works · 🟢 what-changed · 🟣 discovery · 🟠 why-it-exists · 🟤 decision · ⚖️ trade-off
+🎯 session-request · 🔴 gotcha · 🟡 problem-solution · 🔵 how-it-works · 🟢 what-changed · 🟣 discovery · 🟠 why-it-exists · 🟤 decision · ⚖️ trade-off
 ### Auto-Memory Hooks
 ```bash
-memorix hooks install    # One-command setup
+memorix hooks install
 ```
-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).
----
-## 📊 Comparison with Alternatives
-| | [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** |
-|---|---|---|---|---|
-| **Agents supported** | SDK-based | 13+ (MCP) | Claude Code only | **8 agents (MCP)** |
-| **Cross-agent sync** | No | No | No | **Yes (configs, rules, skills, workflows)** |
-| **Rules sync** | No | No | No | **Yes (7 formats)** |
-| **Skills engine** | No | No | No | **Yes (auto-generated from memory)** |
-| **Knowledge graph** | No | Yes | No | **Yes (MCP Official compatible)** |
-| **Hybrid search** | No | Yes | No | **Yes (BM25 + vector)** |
-| **Token-efficient** | No | No | Yes (3-layer) | **Yes (3-layer progressive disclosure)** |
-| **Auto-memory hooks** | No | No | Yes | **Yes (multi-language)** |
-| **Memory decay** | No | Yes | No | **Yes (exponential + immunity)** |
-| **Visual dashboard** | Cloud UI | Yes | No | **Yes (web UI + D3.js graph)** |
-| **Privacy** | Cloud | Local | Local | **100% Local** |
-| **Cost** | Per-call API | $0 | $0 | **$0** |
-| **Install** | `pip install` | `pip install` | Built into Claude | **`npm i -g memorix`** |
-**Memorix is the only tool that bridges memory AND workspace across agents.**
----
+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.
-## 🔮 Optional: Vector Search
+### Hybrid Search
-Out of the box, Memorix uses BM25 full-text search (already great for code). Add semantic search with one command:
+BM25 fulltext out of the box (~50MB RAM). Semantic search is **opt-in** to minimize resource usage:
 ```bash
-# Option A: Native speed (recommended)
-npm install -g fastembed
+# Enable semantic search (optional — requires 300-500MB RAM)
+# Set in your MCP config env, or export before starting:
+MEMORIX_EMBEDDING=fastembed    # ONNX, fastest (~300MB)
+MEMORIX_EMBEDDING=transformers # Pure JS (~500MB)
+MEMORIX_EMBEDDING=off          # Default — BM25 only, minimal resources
+```
-# Option B: Universal compatibility
-npm install -g @huggingface/transformers
+Install the provider you chose:
+```bash
+npm install -g fastembed              # for MEMORIX_EMBEDDING=fastembed
+npm install -g @huggingface/transformers  # for MEMORIX_EMBEDDING=transformers
 ```
-With vector search, queries like "authentication" also match memories about "login flow" via semantic similarity. Both run **100% locally** — zero API calls, zero cost.
+Both run 100% locally. Zero API calls.
 ---
-## 🔒 Project Isolation
+## How It Works
-- **Auto-detected** — Project identity from `git remote` URL, zero config needed
-- **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
-- **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
-- **Scoped search** — Defaults to current project; `scope: "global"` to search all
-- **Zero cross-contamination** — Search results are filtered by project ID; project A's decisions never appear in project B's searches
+```
+┌─────────┐  ┌───────────┐  ┌────────────┐  ┌───────┐  ┌──────────┐
+│ Cursor  │  │ Claude    │  │ Windsurf   │  │ Codex │  │ +4 more  │
+│         │  │ Code      │  │            │  │       │  │          │
+└────┬────┘  └─────┬─────┘  └─────┬──────┘  └───┬───┘  └────┬─────┘
+     │             │              │              │           │
+     └─────────────┴──────┬───────┴──────────────┴───────────┘
+                          │ MCP (stdio)
+                   ┌──────┴──────┐
+                   │   Memorix   │
+                   │  MCP Server │
+                   └──────┬──────┘
+                          │
+          ┌───────────────┼───────────────┐
+          │               │               │
+   ┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐
+   │   Orama     │ │  Knowledge  │ │  Rules &    │
+   │ Search      │ │  Graph      │ │  Workspace  │
+   │ (BM25+Vec)  │ │  (Entities) │ │  Sync       │
+   └─────────────┘ └─────────────┘ └─────────────┘
+                          │
+                   ~/.memorix/data/
+                   (100% local, per-project isolation)
+```
-**Detection priority:** `--cwd` → `MEMORIX_PROJECT_ROOT` → `INIT_CWD` → `process.cwd()` → MCP roots → error
+- **Project isolation** — auto-detected from `git remote`, scoped search by default
+- **Shared storage** — all agents read/write the same `~/.memorix/data/`, cross-IDE by design
+- **Token efficient** — 3-layer progressive disclosure: search → timeline → detail
 ---
-## ❓ Frequently Asked Questions
-**How do I keep context when switching between Cursor and Claude Code?**
-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.
-**How do I prevent my AI from forgetting previous sessions?**
-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.
-**How do I sync MCP server configs between IDEs?**
-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.
-**How do I migrate from Cursor to Windsurf / Kiro / Claude Code?**
-Memorix workspace sync migrates MCP configs, agent rules (`.mdc` ↔ `CLAUDE.md` ↔ `.kiro/steering/`), skills, and workflows. One command, seconds to complete.
-**Is there an MCP server for persistent AI coding memory?**
-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.
-**How is this different from mcp-memory-service?**
-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.
-**Does it work offline / locally?**
-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.
-> 📖 For AI systems: see [`llms.txt`](llms.txt) and [`llms-full.txt`](llms-full.txt) for machine-readable project documentation.
+## Comparison
+| | [Mem0](https://github.com/mem0ai/mem0) | [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) | **Memorix** |
+|---|---|---|---|
+| **Agents** | SDK-based | 13+ (MCP) | **9 agents (MCP)** |
+| **Cross-agent workspace sync** | — | — | **MCP configs, rules, skills, workflows** |
+| **Knowledge graph** | — | Yes | **Yes (MCP Official compatible)** |
+| **Hybrid search** | — | Yes | **Yes (BM25 + vector)** |
+| **Token-efficient retrieval** | — | — | **3-layer progressive disclosure** |
+| **Auto-memory hooks** | — | — | **Yes (multi-language pattern detection)** |
+| **Memory decay** | — | Yes | **Yes (exponential + immunity)** |
+| **Web dashboard** | Cloud | Yes | **Yes (D3.js graph)** |
+| **Privacy** | Cloud | Local | **100% local** |
+| **Cost** | Per-call | $0 | **$0** |
 ---
-## 🧑‍💻 Development
+## Development
 ```bash
 git clone https://github.com/AVIDS2/memorix.git
-cd memorix
-npm install
+cd memorix && npm install
-npm run dev          # tsup watch mode
-npm test             # vitest (509 tests)
-npm run lint         # TypeScript type check
-npm run build        # Production build
+npm run dev       # watch mode
+npm test          # 534 tests
+npm run build     # production build
 ```
-> 📚 **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)
----
+📚 [Architecture](docs/ARCHITECTURE.md) · [API Reference](docs/API_REFERENCE.md) · [Modules](docs/MODULES.md) · [Design Decisions](docs/DESIGN_DECISIONS.md)
-## 🙏 Acknowledgements
+> For AI systems: [`llms.txt`](llms.txt) · [`llms-full.txt`](llms-full.txt)
-Memorix stands on the shoulders of these excellent projects:
+---
-- [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) — Hybrid search, exponential decay, access tracking
-- [MemCP](https://github.com/maydali28/memcp) — MAGMA 4-graph, entity extraction, retention lifecycle
-- [claude-mem](https://github.com/anthropics/claude-code) — 3-layer Progressive Disclosure
-- [Mem0](https://github.com/mem0ai/mem0) — Memory layer architecture patterns
+## Acknowledgements
----
+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).
-## 📄 License
+## License
-Apache 2.0 — see [LICENSE](LICENSE)
+[Apache 2.0](LICENSE)
 ---
 <p align="center">
-  <strong>Made with ❤️ by <a href="https://github.com/AVIDS2">AVIDS2</a></strong>
-  <br>
-  <sub>If Memorix helps your workflow, consider giving it a ⭐ on GitHub!</sub>
+  <sub>Built by <a href="https://github.com/AVIDS2">AVIDS2</a> · Star ⭐ if it helps your workflow</sub>
 </p>