Open-source cross-agent memory layer for coding agents.
Tiered MCP support across Cursor, Claude Code, Codex, Windsurf, Gemini CLI, GitHub Copilot, Kiro, OpenCode, Antigravity, Trae, and other MCP-compatible clients.
Using Memorix through Cursor, Windsurf, Claude Code, Codex, or another AI coding agent? Read the Agent Operator Playbook for the agent-facing install, MCP, hook, and troubleshooting rules.
What Is Memorix?
Memorix is a local-first memory control plane for coding agents.
It keeps project memory, reasoning context, Git-derived facts, and optional autonomous-agent state in one place so you can continue work across IDEs, sessions, terminals, and agent runs without losing project truth.
For most users, the default path is simple: use the local TUI/CLI or connect one IDE over stdio MCP. Treat HTTP as the shared-control-plane mode you opt into when you specifically want one long-lived background service, shared MCP access, or a live dashboard endpoint.
Why Memorix
Most coding agents remember only the current thread. Memorix gives them a shared, persistent memory layer across IDEs, sessions, and projects.
memorix orchestrate runs a structured coordination loop — plan → parallel execution → verify → fix → review — with capability routing and worktree isolation
📋 Session Lifecycle
Session start/end with handoff summaries, watermark tracking (new memories since last session), cross-session context recovery
🎯 Project Skills
Auto-generate SKILL.md from memory patterns; promote observations to permanent mini-skills injected at session start
📊 Dashboard
Local web UI for browsing memories, Git history, sessions, and read-only autonomous agent team state
🔒 Local & Private
SQLite as canonical store, Orama for search, no cloud dependency — everything stays on your machine
Supported Clients
Tier
Clients
★ Core
Claude Code, Cursor, Windsurf
◆ Extended
GitHub Copilot, Kiro, Codex
○ Community
Gemini CLI, OpenCode, Antigravity, Trae
Core = full hook integration + tested MCP + rules sync. Extended = hook integration with platform caveats. Community = best-effort hooks, community-reported compatibility.
If a client can speak MCP and launch a local command or HTTP endpoint, it can usually connect to Memorix even if it is not in the list above yet.
Quick Start
Install globally:
npm install -g memorix
Initialize Memorix config:
memorix init
memorix init lets you choose between Global defaults and Project config.
Memorix uses two files with two roles:
memorix.yml for behavior and project settings
.env for secrets such as API keys
Then pick the path that matches what you want to do:
You want
Run
Best for
Interactive terminal workbench
memorix
Default starting point for local search, chat, memory capture, and diagnostics
Quick MCP setup inside one IDE
memorix serve
Default MCP path for Cursor, Claude Code, Codex, Windsurf, Gemini CLI, and other stdio clients
Dashboard + shared HTTP MCP in the background
memorix background start
A long-lived shared control plane for multiple clients and a live dashboard endpoint
Foreground HTTP mode for debugging or a custom port
memorix serve-http --port 3211
Manual supervision, debugging, custom launch control
Most users should choose one of the first two options above. Move to HTTP only when you intentionally want one shared background service, multi-client MCP access, or a live dashboard endpoint.
Common paths:
Goal
Use
Why
Work directly in the terminal
memorix or memorix <command>
CLI/TUI is the primary product surface.
Connect an IDE or coding agent over MCP
memorix serve first; HTTP + memorix_session_start when needed
Start a lightweight memory session without joining Agent Team by default.
Run autonomous multi-agent execution
memorix orchestrate
Structured plan → spawn → verify → fix → review loop with CLI agents.
Watch project memory and agent state in the browser
memorix dashboard
Standalone read-mostly dashboard for memory, sessions, and autonomous agent team state.
Companion commands: memorix background status|logs|stop. For multi-workspace HTTP sessions, bind with memorix_session_start(projectRoot=...).
Running memorix without arguments opens an interactive fullscreen terminal UI (requires a TTY). Use it for chat with project memory, search, quick memory capture, diagnostics, background service control, dashboard launch, and IDE setup. Press /help inside the TUI for the current command list.
In 1.0.9 the TUI is organized as a knowledge workbench with Home, Knowledge, Memory, Workbench, and Graph tabs. It can browse the generated Knowledge Base, inspect memory detail, jump between wiki refs and source observations, view the text Knowledge Graph, and keep chatting after answers without leaving the terminal.
Single-shot chat (no TUI): memorix ask "your question".
Operator CLI
Memorix exposes a CLI-first operator surface. Use it when you want to inspect or control the current project directly from a terminal. MCP remains the integration layer for IDEs and agents.
memorix session start --agent codex-main --agentType codex
memorix memory search --query "docker control plane"
memorix reasoning search --query "why sqlite"
memorix retention status
memorix team status
memorix task list
memorix audit project
memorix sync workspace --action scan
The CLI is intentionally task-shaped, not a 1:1 mirror of MCP tool names. Native capabilities are available through these namespaces: session, memory, reasoning, retention, formation, audit, transfer, skills, team, task, message, lock, handoff, poll, sync, ingest. MCP stays available for IDEs, agents, and optional graph-compatibility tools.
Docker
Memorix now includes an official Docker path for the HTTP control plane.
Quick start:
docker compose up --build -d
Then connect to:
dashboard: http://localhost:3211
MCP: http://localhost:3211/mcp
health: http://localhost:3211/health
Important: Docker support is for serve-http, not memorix serve. Project-scoped Git/config behavior only works when the container can see the repositories it is asked to bind.
The per-client examples below show the simplest stdio shape. If you prefer the shared HTTP control plane, keep the generic HTTP block above and use the client-specific variants in docs/SETUP.md.
When multiple HTTP sessions are open at once, each session should bind itself with memorix_session_start(projectRoot=...) before using project-scoped memory tools.
HTTP MCP sessions idle out after 30 minutes by default. If your client does not automatically recover from stale HTTP session IDs, set a longer timeout before starting the control plane:
Shared memory means stored memories are searchable across clients bound to the same Git project. It does not mean every chat message is mirrored automatically. For support/debugging, memorix receipt --json and memorix doctor --receipt show project identity, write/search counts, and hashed IDs without raw prompts or memory text.
Agent Team is not the normal memory startup path and it is not a chat room between IDE windows. Join only when you need tasks, handoff messages, locks, or a structured autonomous-agent/subagent workflow. For real multi-agent execution, prefer:
memorix orchestrate --goal "Add user authentication" --agents claude-code,cursor,codex
Resource Profile
Memorix is designed to stay light during normal memory use:
stdio MCP starts on demand and exits with the client
HTTP background mode is one local Node process plus SQLite/Orama state
LLM enrichment is optional; without API keys, Memorix falls back to local heuristic dedup/search
the heavier paths are build/test, Docker image builds, dashboard browsing, large imports, and optional LLM-backed formation
On this Windows development machine, the healthy HTTP control plane was observed at about 16 MB working set after several hours idle. Treat that as a local observation, not a cross-platform guarantee. See Performance and Resource Notes for knobs and trade-offs.
Programmatic SDK
Import Memorix directly into your own TypeScript/Node.js project — no MCP or CLI needed:
import { createMemoryClient } from 'memorix/sdk';
const client = await createMemoryClient({ projectRoot: '/path/to/repo' });
// Store a memory
await client.store({
entityName: 'auth-module',
type: 'decision',
title: 'Use JWT for API auth',
narrative: 'Chose JWT over session cookies for stateless API.',
});
// Search
const results = await client.search({ query: 'authentication' });
// Retrieve, resolve, count
const obs = await client.get(1);
const all = await client.getAll();
await client.resolve([1, 2]);
await client.close();
Three subpath exports:
Import
What you get
memorix/sdk
createMemoryClient, createMemorixServer, detectProject, all types
memorix/types
Type-only — interfaces, enums, constants
memorix
MCP stdio entry point (not for programmatic use)
How It Works
flowchart LR
subgraph ING["Ingress"]
A["Git Hooks<br/>commit + ingest"]
B["MCP Tools<br/>search, store, recall"]
C["CLI / TUI<br/>operator workflows"]
D["Dashboard<br/>read-mostly project view"]
end
subgraph RUN["Runtime"]
E["stdio MCP Server<br/>memorix serve"]
F["HTTP Control Plane<br/>background / serve-http"]
G["Project Binding<br/>git root + config"]
end
subgraph MEM["Memory"]
H["Observation<br/>facts, gotchas, fixes"]
I["Reasoning<br/>why, trade-offs, risks"]
J["Git Memory<br/>commit-derived ground truth"]
K["Session + Agent Team<br/>opt-in tasks, locks, handoffs"]
end
subgraph PROC["Processing"]
L["Formation<br/>quality shaping"]
M["Embedding + Index<br/>hybrid retrieval"]
N["Graph Linking<br/>entity relations"]
O["Dedup + Retention<br/>consolidate over time"]
end
subgraph USE["Consumption"]
P["Search / Timeline / Detail"]
Q["Dashboard / Agent Team View<br/>read-mostly state"]
R["Recall / Handoff / Resume"]
S["Skills / Sync / Orchestrate"]
end
A --> E
B --> E
C --> E
D --> F
E --> G
F --> G
G --> H
G --> I
G --> J
G --> K
H --> L
H --> M
I --> L
I --> N
J --> M
J --> N
K --> O
H --> P
I --> P
J --> P
K --> Q
H --> R
I --> R
J --> R
K --> S
Memorix is not a single linear pipeline. It accepts memory from multiple ingress surfaces, persists it across multiple substrates, runs several asynchronous quality/indexing branches, and exposes the results through retrieval, dashboard, and explicit Agent Team surfaces.
Memory Layers
Observation Memory: what changed, how something works, gotchas, problem-solution notes
Reasoning Memory: why a choice was made, alternatives, trade-offs, risks
Git Memory: immutable engineering facts derived from commits
Retrieval Model
Default search is project-scoped
scope="global" searches across projects
Global hits can be opened explicitly with project-aware refs
Source-aware retrieval boosts Git memories for “what changed” questions and reasoning memories for “why” questions
Version 1.0.10 tightens Memorix’s low-intrusion operator story: privacy-safe handoff diagnostics, clearer cross-agent memory boundaries, optional session semantics in generated rules, independent TUI agent LLM config, a better fresh-project cold-start path, safer update behavior, and a release-gate fix so the real serve-http smoke test no longer depends on port 19879 being free on the runner.
Privacy-Safe Handoff Receipt: memorix receipt --json and memorix doctor --receipt expose hashes/counts for project identity, writes, and optional probe results without leaking raw chat, memory text, queries, tool payloads, or local paths.
Lower-Intrusion Agent Guidance: Generated rules now treat memorix_session_start as optional and avoid repeating memorix_search in the same turn after a confirmed fresh-project cold start.
Separate TUI Agent LLM Config: agent / MEMORIX_AGENT_LLM_* lets TUI chat use a different provider/model from memory formation and rerank, while preserving fallback to llm.
Fresh-Project UX Fix: Empty project searches now explicitly say the tool call worked but the project has no stored Memorix memories yet, instead of looking like a generic retrieval failure.
Safer Update Checks: Auto-update now defaults to notify-only; background install is explicit opt-in via MEMORIX_AUTO_UPDATE=install.
Dashboard Config Consistency: Standalone dashboard status now loads project .env and project YAML before embedding/LLM status routes initialize, matching CLI and TUI behavior.
Development
git clone https://github.com/AVIDS2/memorix.git
cd memorix
npm install
npm run dev
npm test
npm run build
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)
评论