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. Seven agents. Zero context loss.

---

⚡ Get Started in 30 Seconds

Add this to your agent's MCP config file, restart — done:

{
  "mcpServers": {
    "memorix": {
      "command": "npx",
      "args": ["-y", "memorix@latest", "serve"]
    }
  }
}

📖 Where is my config file? → Full setup guide for all 7 agents Windsurf • Cursor • Claude Code • Codex • VS Code Copilot • Kiro • Antigravity

That's it. No API keys. No cloud accounts. No dependencies. Just works.

⚠️ Antigravity users: extra config required

Antigravity sets its working directory to its own install path (e.g., G:\Antigravity) instead of your project directory, and does not support the MCP roots protocol. You must add MEMORIX_PROJECT_ROOT:

{
  "mcpServers": {
    "memorix": {
      "command": "npx",
      "args": ["-y", "memorix@latest", "serve"],
      "env": {
        "MEMORIX_PROJECT_ROOT": "E:/your/project/path"
      }
    }
  }
}

You'll need to update MEMORIX_PROJECT_ROOT when switching projects. All other IDEs work without this.

---

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

Scenario 5: Auto-Generated Project Skills

After 2 weeks of development, you have 50+ observations:
  - 8 gotchas about Windows path issues
  - 5 decisions about the auth module
  - 3 problem-solutions for database migrations

  You: "Generate project skills"
  → memorix_skills clusters observations by entity
  → Auto-generates SKILL.md files:
    - "auth-module-guide.md" — JWT setup, refresh flow, common pitfalls
    - "database-migrations.md" — Prisma patterns, rollback strategies
  → Syncs skills to any agent: Cursor, Claude Code, Kiro...
  → New team members' AI instantly knows your project's patterns!

Scenario 6: Session Lifecycle (v0.8.0)

Morning — Start a new session in Windsurf:
  → memorix_session_start auto-injects:
    📋 Previous Session: "Implemented JWT auth middleware"
    🔴 JWT tokens expire silently (gotcha)
    🟤 Use Docker for deployment (decision)
  → AI instantly knows what you did yesterday!

Evening — End the session:
  → memorix_session_end saves structured summary
  → Next session (any agent!) gets this context automatically

Scenario 7: Topic Key Upsert — No More Duplicates (v0.8.0)

You update your architecture decision 3 times over a week:

  Day 1: memorix_store(topicKey="architecture/auth-model", ...)
  → Creates observation #42 (rev 1)

  Day 3: memorix_store(topicKey="architecture/auth-model", ...)
  → Updates #42 in-place (rev 2) — NOT a new #43!

  Day 5: memorix_store(topicKey="architecture/auth-model", ...)
  → Updates #42 again (rev 3)

  Result: 1 observation with latest content, not 3 duplicates!

---

🧠 What Memorix Can Do

Smart Memory (24 MCP Tools)

What You Say	What Memorix Does
"Remember this architecture decision"	memorix_store — Classifies as 🟤 decision, extracts entities, creates graph relations, auto-associates session
"What did we decide about auth?"	memorix_search → memorix_detail — 3-layer progressive disclosure, ~10x token savings
"What auth decisions last week?"	memorix_search with since/until — Temporal queries with date range filtering
"What happened around that bug fix?"	memorix_timeline — Shows chronological context before/after
"Show me the knowledge graph"	memorix_dashboard — Opens interactive web UI with D3.js graph + sessions panel
"Which memories are getting stale?"	memorix_retention — Exponential decay scores, identifies archive candidates
"Start a new session"	memorix_session_start — Tracks session lifecycle, auto-injects previous session summaries + key memories
"End this session"	memorix_session_end — Saves structured summary (Goal/Discoveries/Accomplished/Files) for next session
"What did we do last session?"	memorix_session_context — Retrieves session history and key observations
"Suggest a topic key for this"	memorix_suggest_topic_key — Generates stable keys for deduplication (e.g. architecture/auth-model)
"Clean up duplicate memories"	memorix_consolidate — Find & merge similar observations by text similarity, preserving all facts
"Export this project's memories"	memorix_export — JSON (importable) or Markdown (human-readable for PRs/docs)
"Import memories from teammate"	memorix_import — Restore from JSON export, re-assigns IDs, deduplicates by topicKey

Cross-Agent Workspace Sync

What You Say	What Memorix Does
"Sync my MCP servers to Kiro"	memorix_workspace_sync — Migrates configs, merges (never overwrites)
"Check my agent rules"	memorix_rules_sync — Scans 7 agents, deduplicates, detects conflicts
"Generate rules for Cursor"	memorix_rules_sync — Cross-format conversion (.mdc ↔ CLAUDE.md ↔ .kiro/steering/)
"Generate project skills"	memorix_skills — Creates SKILL.md from observation patterns
"Inject the auth skill"	memorix_skills — Returns skill content directly into agent context

Knowledge Graph (MCP Official Compatible)

Tool	What It Does
create_entities	Build your project's knowledge graph
create_relations	Connect entities with typed edges (causes, fixes, depends_on)
add_observations	Attach observations to entities
search_nodes / open_nodes	Query the graph
read_graph	Export full graph for visualization

Drop-in compatible with MCP Official Memory Server — same API, more features.

9 Observation Types

Every memory is classified for intelligent retrieval:

Icon	Type	When To Use
🎯	session-request	Original task/goal for this session
🔴	gotcha	Critical pitfall — "Never do X because Y"
🟡	problem-solution	Bug fix with root cause and solution
🔵	how-it-works	Technical explanation of a system
🟢	what-changed	Code/config change record
🟣	discovery	New insight or finding
🟠	why-it-exists	Rationale behind a design choice
🟤	decision	Architecture/design decision
⚖️	trade-off	Compromise with pros/cons

Visual Dashboard

Run memorix_dashboard to open a web UI at http://localhost:3210:

• Interactive Knowledge Graph — D3.js force-directed visualization of entities and relations
• Observation Browser — Filter by type, search with highlighting, expand/collapse details
• Retention Panel — See which memories are active, stale, or candidates for archival
• Project Switcher — View any project's data without switching IDEs
• Batch Cleanup — Auto-detect and bulk-delete low-quality observations
• Light/Dark Theme — Premium glassmorphism design, bilingual (EN/中文)

Auto-Memory Hooks

Memorix can automatically capture decisions, errors, and gotchas from your coding sessions:

memorix hooks install    # One-command setup

• Implicit Memory — Detects patterns like "I decided to...", "The bug was caused by...", "Never use X"
• Session Start Injection — Loads recent high-value memories into agent context automatically
• Multi-Language — English + Chinese keyword matching
• Smart Filtering — 30s cooldown, skips trivial commands (ls, cat, pwd)

---

📊 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	npx memorix serve

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 (422 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!}