Memorix

Cross-Agent Memory Bridge — Your AI never forgets again

中文文档 | English

Why • Quick Start • Scenarios • Features • Compare • Full Setup Guide

---

😤 Stop Re-Explaining Your Project

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.

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

Memorix solves all of this. One MCP server. Eight agents. Zero context loss.

---

⚡ Get Started in 30 Seconds

Step 1: Install globally (one-time)

npm install -g memorix

⚠️ Do NOT use npx — npx downloads the package every time, which causes MCP server initialization timeout (60s limit). Global install starts instantly.

Step 2: Add to your agent's MCP config

Claude Code

Run in terminal:

claude mcp add memorix -- memorix serve

Or manually add to ~/.claude.json:

{
  "mcpServers": {
    "memorix": {
      "command": "memorix",
      "args": ["serve"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "memorix": {
      "command": "memorix",
      "args": ["serve"]
    }
  }
}

Windsurf

Add to Windsurf MCP settings (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "memorix": {
      "command": "memorix",
      "args": ["serve"]
    }
  }
}

VS Code Copilot / Codex / Kiro

Same format — add to the agent's MCP config file:

{
  "mcpServers": {
    "memorix": {
      "command": "memorix",
      "args": ["serve"]
    }
  }
}

Antigravity / Gemini CLI

Add to .gemini/settings.json (project) or ~/.gemini/settings.json (global):

{
  "mcpServers": {
    "memorix": {
      "command": "memorix",
      "args": ["serve"]
    }
  }
}

Antigravity IDE only: Antigravity uses its own install path as CWD. You must add:

{
  "mcpServers": {
    "memorix": {
      "command": "memorix",
      "args": ["serve"],
      "env": {
        "MEMORIX_PROJECT_ROOT": "E:/your/project/path"
      }
    }
  }
}

Gemini CLI reads MCP config from the same path. Hooks are automatically installed to .gemini/settings.json.

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

🔧 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.

Quick diagnostic — run this first:

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 .claude.json config:

{
  "mcpServers": {
    "memorix": {
      "command": "memorix",
      "args": ["serve"]
    }
  }
}

❌ Wrong — do NOT use any of these:

"command": "npx"                    ← will timeout
"command": "npx -y memorix serve"   ← wrong format
"command": "node memorix serve"     ← not how it works

---

🎬 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!

Scenario 4: Workspace Sync Across IDEs

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!

---

🧠 What Memorix Can Do

24 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, search_nodes, read_graph	MCP Official Memory Server compatible — same API, more features

9 Observation Types

Every memory is classified: 🎯 session-request · 🔴 gotcha · 🟡 problem-solution · 🔵 how-it-works · 🟢 what-changed · 🟣 discovery · 🟠 why-it-exists · 🟤 decision · ⚖️ trade-off

Auto-Memory Hooks

memorix hooks install    # One-command setup

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	mcp-memory-service	claude-mem	Memorix
Agents supported	SDK-based	13+ (MCP)	Claude Code only	7 IDEs (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.

---

🔮 Optional: Vector Search

Out of the box, Memorix uses BM25 full-text search (already great for code). Add semantic search with one command:

# Option A: Native speed (recommended)
npm install -g fastembed

# Option B: Universal compatibility
npm install -g @huggingface/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.

---

🔒 Project Isolation

• 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 to get your workspace path from the IDE
• Per-project storage — ~/.memorix/data/<owner--repo>/ per project
• Scoped search — Defaults to current project; scope: "global" to search all
• Zero cross-contamination — Project A's decisions never leak into project B

Detection priority: --cwd → MEMORIX_PROJECT_ROOT → INIT_CWD → process.cwd() → MCP roots → error

---

❓ 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 7 IDEs 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 and llms-full.txt for machine-readable project documentation.

---

🧑‍💻 Development

git clone https://github.com/AVIDS2/memorix.git
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

📚 Documentation: Architecture • API Reference • Modules • Design Decisions • Setup Guide • Known Issues

---

🙏 Acknowledgements

Memorix stands on the shoulders of these excellent projects:

• mcp-memory-service — Hybrid search, exponential decay, access tracking
• MemCP — MAGMA 4-graph, entity extraction, retention lifecycle
• claude-mem — 3-layer Progressive Disclosure
• Mem0 — Memory layer architecture patterns

---

📄 License

Apache 2.0 — see LICENSE

---

Made with ❤️ by AVIDS2
_{If Memorix helps your workflow, consider giving it a ⭐ on GitHub!}