memorix

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.

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=...).

Deeper details on startup, project binding, config precedence, and agent workflows: docs/SETUP.md and the Agent Operator Playbook.

TUI Workbench

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.

Full Docker guide: docs/DOCKER.md

Add Memorix to your MCP client:

Generic stdio MCP config

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

Generic HTTP MCP config

{
  "mcpServers": {
    "memorix": {
      "transport": "http",
      "url": "http://localhost:3211/mcp"
    }
  }
}

The per-client examples below show the simplest stdio shape. If you prefer the shared HTTP control plane