MCP 服务器

memorix

Cross-agent memory bridge for AI coding assistants. Persistent knowledge graph shared across 10 IDEs (Cursor, Windsurf, Claude Code, Codex, Copilot, Kiro, Antigravity, OpenCode, Trae, Gemini CLI) via MCP. 22 tools including team collaboration, auto-cleanup, mini-skills, session management, and workspace sync. 100% local, zero API keys required.

README

<h1 align="center">Memorix</h1>

Persistent memory layer for AI coding agents. One MCP server. Ten agents. Zero context loss.

v1.0 Stable | 22 MCP tools | Auto-cleanup | Multi-agent collaboration | 10 IDEs supported

<a href="README.zh-CN.md">中文文档</a> · <a href="#quick-start">Quick Start</a> · <a href="#features">Features</a> · <a href="#architecture">Architecture</a> · <a href="docs/SETUP.md">Setup Guide</a>

Introduction

AI coding agents lose all context between sessions. Switch IDEs and previous decisions, debugging history, and architectural knowledge are gone. Memorix provides a shared, persistent memory layer across agents and sessions — storing decisions, gotchas, and project knowledge that any agent can retrieve instantly.

Session 1 (Cursor):      "Use JWT with refresh tokens, 15-min expiry"  → stored as decision
Session 2 (Claude Code): "Add login endpoint"  → retrieves the decision → implements correctly

No re-explaining. No copy-pasting. No vendor lock-in.

Core Capabilities

Cross-Agent Memory: All agents share the same memory store. Store in Cursor, retrieve in Claude Code.
Multi-Agent Collaboration: Team tools for agent coordination — join/leave, file locks, task boards, and cross-IDE messaging via shared team-state.json.
Auto-Cleanup on Startup: Background retention archiving and intelligent deduplication (LLM or heuristic) run automatically — zero manual maintenance.
Dual-Mode Quality: Free heuristic engine for basic dedup; optional LLM mode for intelligent compression, reranking, and conflict resolution.
3-Layer Progressive Disclosure: Search returns compact indices (~50 tokens/result), timeline shows chronological context, detail provides full content. ~10x token savings over full-text retrieval.
Mini-Skills: Promote high-value observations to permanent skills that auto-inject at every session start. Critical knowledge never decays.
Auto-Memory Hooks: Automatically capture decisions, errors, and gotchas from IDE tool calls. Pattern detection in English and Chinese.
Knowledge Graph: Entity-relation model compatible with MCP Official Memory Server. Auto-creates relations from entity extraction.

Quick Start

npm install -g memorix

Add to your agent's MCP config:

<details open> <summary>Cursor · <code>.cursor/mcp.json</code></summary>

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

</details>

<details> <summary>Claude Code</summary>

claude mcp add memorix -- memorix serve

</details>

<details> <summary>Windsurf · <code>~/.codeium/windsurf/mcp_config.json</code></summary>

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

</details>

<details> <summary>VS Code Copilot · <code>.vscode/mcp.json</code></summary>

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

</details>

<details> <summary>Codex · <code>~/.codex/config.toml</code></summary>

[mcp_servers.memorix]
command = "memorix"
args = ["serve"]

</details>

<details> <summary>Kiro · <code>.kiro/settings/mcp.json</code></summary>

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

</details>

<details> <summary>Antigravity · <code>~/.gemini/antigravity/mcp_config.json</code></summary>

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

</details>

<details> <summary>OpenCode · <code>~/.config/opencode/config.json</code></summary>

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

</details>

<details> <summary>Trae · <code>~/%APPDATA%/Trae/User/mcp.json</code></summary>

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

</details>

<details> <summary>Gemini CLI · <code>.gemini/settings.json</code></summary>

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

</details>

Restart your agent. No API keys required. No cloud. No external dependencies.

Auto-update: Memorix checks for updates on startup (once per 24h) and self-updates in the background.

Note: Do not use npx — it re-downloads on each invocation and causes MCP timeout. Use global install.

Full setup guide · Troubleshooting

Features

22 MCP Tools (Default)

Category	Tools
Memory	`memorix_store` · `memorix_search` · `memorix_detail` · `memorix_timeline` · `memorix_resolve` · `memorix_deduplicate` · `memorix_suggest_topic_key`
Sessions	`memorix_session_start` · `memorix_session_end` · `memorix_session_context`
Skills	`memorix_skills` · `memorix_promote`
Workspace	`memorix_workspace_sync` · `memorix_rules_sync`
Maintenance	`memorix_retention` · `memorix_consolidate` · `memorix_transfer`
Team	`team_manage` · `team_file_lock` · `team_task` · `team_message`
Dashboard	`memorix_dashboard`

<details> <summary>+9 Optional: Knowledge Graph tools (enable in <code>~/.memorix/settings.json</code>)</summary>

create_entities · create_relations · add_observations · delete_entities · delete_observations · delete_relations · search_nodes · open_nodes · read_graph

Enable with: { "knowledgeGraph": true } in ~/.memorix/settings.json </details>

Observation Types

Nine structured types for classifying stored knowledge:

session-request · gotcha · problem-solution · how-it-works · what-changed · discovery · why-it-exists · decision · trade-off

Hybrid Search

BM25 fulltext search works out of the box with minimal resources (~50MB RAM). Semantic vector search is opt-in with three provider options:

Provider	Configuration	Resources	Quality
API (recommended)	`MEMORIX_EMBEDDING=api`	Zero local RAM	Highest
fastembed	`MEMORIX_EMBEDDING=fastembed`	~300MB RAM	High
transformers	`MEMORIX_EMBEDDING=transformers`	~500MB RAM	High
Off (default)	`MEMORIX_EMBEDDING=off`	~50MB RAM	BM25 only

API embedding works with any OpenAI-compatible endpoint — OpenAI, Qwen/DashScope, OpenRouter, Ollama, or any proxy:

MEMORIX_EMBEDDING=api
MEMORIX_EMBEDDING_API_KEY=sk-xxx
MEMORIX_EMBEDDING_MODEL=text-embedding-3-small
MEMORIX_EMBEDDING_BASE_URL=https://api.openai.com/v1    # optional
MEMORIX_EMBEDDING_DIMENSIONS=512                         # optional

Embedding infrastructure includes 10K LRU cache with disk persistence, batch API calls (up to 2048 texts per request), parallel processing (4 concurrent chunks), and text normalization for improved cache hit rates. Zero external dependencies — no Chroma, no SQLite.

For local embedding:

npm install -g fastembed                     # ONNX runtime
npm install -g @huggingface/transformers     # JS/WASM runtime

LLM Enhanced Mode

Optional LLM integration that significantly improves memory quality. Three capabilities layered on top of the base search:

Capability	Description	Measured Impact
Narrative Compression	Compresses verbose observations before storage, preserving all technical facts	27% token reduction (up to 44% on narrative-heavy content)
Search Reranking	LLM reranks search results by semantic relevance to the current query	60% of queries improved, 0% degraded
Compact on Write	Detects duplicates and conflicts at write time; merges, updates, or skips as appropriate	Prevents redundant storage, resolves contradictions

Smart filtering ensures LLM calls are only made when beneficial — structured content like commands and file paths is bypassed automatically.

MEMORIX_LLM_API_KEY=sk-xxx
MEMORIX_LLM_PROVIDER=openai          # openai | anthropic | openrouter | custom
MEMORIX_LLM_MODEL=gpt-4.1-nano       # any chat completion model
MEMORIX_LLM_BASE_URL=https://...     # custom endpoint (optional)

Memorix auto-detects existing environment variables:

Variable	Provider
`OPENAI_API_KEY`	OpenAI
`ANTHROPIC_API_KEY`	Anthropic
`OPENROUTER_API_KEY`	OpenRouter

Without LLM: Free heuristic deduplication (similarity-based rules). With LLM: Intelligent compression, contextual reranking, contradiction detection, and fact extraction.

Mini-Skills

Promote high-value observations to permanent skills using memorix_promote. Mini-skills are:

Permanent — exempt from retention decay, never archived
Auto-injected — loaded into context at every memorix_session_start
Project-scoped — isolated per project, no cross-project pollution

Use this for critical knowledge that must survive indefinitely: deployment procedures, architectural constraints, recurring gotchas.

Team Collaboration

Multiple agents working in the same workspace can coordinate via 4 team tools:

Tool	Actions	Purpose
`team_manage`	join, leave, status	Agent registry — see who's active
`team_file_lock`	lock, unlock, status	Advisory file locks to prevent conflicts
`team_task`	create, claim, complete, list	Shared task board with dependencies
`team_message`	send, broadcast, inbox	Direct and broadcast messaging

State is persisted to team-state.json and shared across all IDE processes. See TEAM.md for the full protocol.

Auto-Memory Hooks

memorix hooks install

Captures decisions, errors, and gotchas automatically from IDE tool calls. Pattern detection supports English and Chinese. Smart filtering applies 30-second cooldown and skips trivial commands. High-value memories are injected at session start.

Interactive CLI

memorix              # Interactive menu
memorix configure    # LLM + Embedding provider setup
memorix status       # Project info and statistics
memorix dashboard    # Web UI at localhost:3210
memorix hooks install # Install auto-capture for IDEs

Architecture

graph TB
    A["Cursor · Claude Code · Windsurf · Codex · +6 more"]
    A -->|MCP stdio| Core
    Core["Memorix MCP Server\n22 Default Tools · Auto-Hooks · Auto-Cleanup"]
    Core --> Search["Search Pipeline\nBM25 + Vector + Rerank"]
    Core --> Team["Team Collab\nAgents · Tasks · Locks · Msgs"]
    Core --> Sync["Rules & Workspace Sync\n10 Adapters"]
    Core --> Cleanup["Auto-Cleanup\nRetention + LLM Dedup"]
    Core --> KG["Knowledge Graph\nEntities · Relations"]
    Search --> Disk["~/.memorix/data/\nobservations · sessions · mini-skills · team-state · entities · relations"]
    Team --> Disk
    KG --> Disk

Search Pipeline

Three-stage retrieval with progressive quality enhancement:

Stage 1:  Orama (BM25 + Vector Hybrid)  →  Top-N candidates
Stage 2:  LLM Reranking (optional)      →  Reordered by semantic relevance
Stage 3:  Recency + Project Affinity    →  Final scored results

Write Pipeline

Input  →  LLM Compression (optional)  →  Compact on Write (dedup/merge)  →  Store + Index

Key Design Decisions

Project isolation: Auto-detected from git remote. Scoped search by default.
Shared storage: All agents read/write ~/.memorix/data/. Cross-IDE by design.
Token efficiency: 3-layer progressive disclosure (search, timeline, detail). ~10x savings.
Graceful degradation: Every LLM and embedding feature is optional. Core functionality requires zero configuration.

Development

git clone https://github.com/AVIDS2/memorix.git
cd memorix && npm install

npm run dev       # watch mode
npm test          # 753 tests
npm run build     # production build

Architecture · API Reference · Modules · Design Decisions

For AI agents: llms.txt · llms-full.txt

Acknowledgements

Built on ideas from mcp-memory-service, MemCP, claude-mem, and Mem0.

Star History

License

Apache 2.0

memorix

README

Introduction

Core Capabilities

Quick Start

Features

22 MCP Tools (Default)

Observation Types

Hybrid Search

LLM Enhanced Mode

Mini-Skills

Team Collaboration

Auto-Memory Hooks

Interactive CLI

Architecture

Search Pipeline

Write Pipeline

Key Design Decisions

Development

Acknowledgements

Star History

License

推荐服务器