memorix

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:

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

claude mcp add memorix -- memorix serve

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

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

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

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

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

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

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

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

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)

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

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:

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:

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:

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:

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