Setup Guide

Memorix is an open-source cross-agent memory layer for coding agents via MCP, with tiered support for Cursor, Claude Code, Windsurf (★ core), GitHub Copilot, Kiro, Codex (◆ extended), and Gemini CLI, OpenCode, Antigravity, Trae (○ community).

Memorix has four common operator entry points:

memorix for the interactive local workbench in a TTY
memorix serve for the default stdio MCP path used by most IDE integrations
memorix background start for an optional long-lived HTTP control plane
memorix serve-http --port 3211 for foreground HTTP MCP, debugging, and manual supervision

The two server runtime modes are:

memorix serve for stdio MCP integrations
memorix background start or memorix serve-http --port 3211 for HTTP MCP, shared access, and a live dashboard endpoint

For most users, start with memorix or memorix serve. Move to HTTP only when you explicitly want one shared background control plane, multi-client MCP access, or a live dashboard endpoint.

Current Release Context

This guide targets the 1.0.8 working release line.

If you are setting up Memorix on a fresh machine or upgrading from an older install, the most visible operator-facing changes in 1.0.8 are:

provenance-aware memory fields and layered retrieval surfaces
stronger evidence semantics and citation-lite compact output
task-line scoping plus secret-safe storage/retrieval behavior
attribution auditing, retention explainability, and a cleaner remediation loop
OpenCode compaction using structured continuation context and post_compact
official Docker deployment for the HTTP control plane

Support Tiers

Tier	Clients	Meaning
★ Core	Claude Code, Cursor, Windsurf	Full hook integration + tested MCP + rules sync
◆ Extended	GitHub Copilot, Kiro, Codex	Hook integration with platform caveats
○ Community	Gemini CLI, OpenCode, Antigravity, Trae	Best-effort hooks, community-reported compatibility

Install ≠ runtime-ready. memorix hooks install succeeds when config files are written to disk; whether the agent actually loads and executes those hooks at runtime depends on the agent's own behavior. Core-tier agents are verified end-to-end; extended/community may have gaps.

1. Install and Initialize

Install Memorix globally:

npm install -g memorix

Initialize Memorix:

memorix init

The init wizard lets you choose between:

Global defaults for personal multi-project workflows
Project config for repo-specific overrides

Memorix then creates the two-file setup it is built around:

memorix.yml for behavior and project settings
.env for secrets only

See CONFIGURATION.md for the full model.

2. Choose a Runtime Mode

Option A: stdio MCP

memorix serve

Use this when your IDE launches Memorix as a local stdio MCP server. This is the default MCP path for most single-IDE setups.

Generic stdio MCP config:

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

Option B: HTTP MCP + Dashboard

memorix background start

This mode gives you:

HTTP MCP endpoint at http://localhost:3211/mcp
dashboard at http://localhost:3211
live dashboard with autonomous Agent Team state
a single long-lived Memorix process shared by multiple agents

Choose this mode when you intentionally want a shared control plane. It is not the default starting point for normal single-IDE memory use.

Companion commands:

memorix background status
memorix background logs
memorix background stop

Startup note:

serve-http seeds its default project root from --cwd -> MEMORIX_PROJECT_ROOT -> ~/.memorix/last-project-root -> process.cwd()
this helps the dashboard and control plane start in a sensible project even before any agent binds explicitly
in multi-session workflows, agents should still call memorix_session_start(projectRoot=...) to avoid cross-project drift
HTTP MCP sessions idle out after 30 minutes by default. For clients that do not transparently recover from stale HTTP session IDs, set MEMORIX_SESSION_TIMEOUT_MS before starting the control plane, for example MEMORIX_SESSION_TIMEOUT_MS=86400000 for 24 hours.

Use memorix serve-http --port 3211 when you want the same HTTP control plane in the foreground for debugging, manual supervision, or a custom port.

Important for multi-project usage:

In HTTP control-plane mode, agents should call memorix_session_start with projectRoot set to the absolute path of the current workspace or repo root when that path is available.
projectRoot is a detection anchor only; Git remains the source of truth for the final project identity.
If the client cannot provide a reliable workspace path, Memorix should fail closed rather than silently inventing an untracked/* project.

Recommended when:

you want to use the dashboard regularly
you want Team tools to work
you want multiple IDEs or agents to talk to one Memorix instance

Generic HTTP MCP config:

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

Some clients use a different key than transport. The per-client examples below show the exact shape where that differs.

Option C: Dockerized HTTP Control Plane

If you want Memorix as a long-lived containerized control plane:

docker compose up --build -d

This repo now ships:

an official Dockerfile
an example compose.yaml
a healthchecked HTTP deployment on port 3211

Docker mode is for:

memorix serve-http
dashboard access
HTTP MCP clients pointing at http://localhost:3211/mcp

It is not a containerized form of stdio MCP.

Important path truth:

project-scoped Git/config behavior only works when the container can see the repo path it is asked to bind
if you run Memorix in Docker on a different machine than your IDE, you must mount the relevant repos into the container or accept reduced project-scoped semantics

See DOCKER.md for the full deployment guide.

3. MCP Config by Client

If you want Memorix to generate IDE-specific dot files, install them explicitly:

memorix integrate --agent cursor
memorix integrate --agent windsurf
memorix integrate --agent opencode

This keeps the default experience MCP-first and zero-write until you opt into a specific IDE integration.

Claude Code

Recommended:

claude mcp add memorix -- memorix serve

Manual config example:

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

HTTP example:

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

If you use the HTTP control plane and your client supports workspace-aware prompts or rules, make sure it calls memorix_session_start with the current workspace absolute path as projectRoot.

Cursor

Project config: .cursor/mcp.json

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

Windsurf

Config file: ~/.codeium/windsurf/mcp_config.json

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

HTTP example:

{
  "mcpServers": {
    "memorix": {
      "serverUrl": "http://localhost:3211/mcp"
    }
  }
}

For Windsurf-like HTTP clients, pair the MCP URL with agent instructions that pass the current workspace absolute path as projectRoot when starting a Memorix session.

Codex

Config file: ~/.codex/config.toml

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

HTTP example:

[mcp_servers.memorix]
url = "http://localhost:3211/mcp"

For Codex-like HTTP clients, the transport URL alone is not enough for multi-project parallel work. The agent should also call memorix_session_start with the current workspace absolute path as projectRoot.

GitHub Copilot / VS Code

Project config: .vscode/mcp.json

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

Kiro

Project config: .kiro/settings/mcp.json

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

OpenCode

OpenCode integration is usually file-based and managed through Memorix hook installers or workspace sync. If you use stdio MCP directly, the same memorix serve command applies.

Gemini CLI and similar clients

If the client supports stdio MCP:

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

If it supports HTTP MCP, prefer:

http://localhost:3211/mcp

4. Dashboard

Recommended dashboard entry:

http://localhost:3211

This is the dashboard served by the HTTP control plane. In normal use, start it with memorix background start; use memorix serve-http when you want the same service in the foreground.

It includes:

Overview
Git Memory
Graph
Observations
Retention
Sessions
Team
Config
Identity Health

There is also a standalone memorix dashboard command. It is a local read-mostly dashboard that includes memory, sessions, and autonomous Agent Team state from SQLite. HTTP is optional and only needed for shared MCP access or a live control-plane endpoint.

5. Agent Team Features

Agent Team features are explicit autonomous-agent coordination surfaces. Use the CLI for the normal path:

memorix team status
memorix orchestrate --goal "..."

These features include:

agent registry
direct messages
file locks
task board

The standalone dashboard can show this state read-only. Start HTTP only when you also want a shared MCP control plane or a live dashboard endpoint.

6. Common Setup Flows

Minimal local setup

npm install -g memorix
memorix init
memorix serve

Recommended full setup

npm install -g memorix
memorix init
memorix git-hook --force
memorix background start

Then:

point your IDE MCP client to memorix serve or http://localhost:3211/mcp
open the dashboard at http://localhost:3211

7. Troubleshooting

Avoid `npx`

Do not launch Memorix with npx in normal MCP configs. It adds startup cost and can cause handshake timeouts.

Prefer:

memorix serve

Not:

npx memorix serve

Windsurf says the MCP config file has invalid JSON

On Windows, ~/.codeium/windsurf/mcp_config.json must be valid JSON encoded as UTF-8 without BOM. A BOM at the start of the file can make Windsurf reject otherwise valid JSON.

Codex handshake timeout

If Codex reports MCP startup timeouts, increase:

startup_timeout_sec = 30

or higher on slower Windows machines.

Codex stale HTTP session after idle time

If Codex is connected to http://localhost:3211/mcp and fails after a long idle period with a transport/body decoding error, the HTTP session may have expired server-side. Memorix defaults to a 30-minute HTTP session idle timeout. Increase it before starting the background control plane:

$env:MEMORIX_SESSION_TIMEOUT_MS = "86400000" # 24h
memorix background restart

This keeps the default safe for normal users while giving long-running Codex HTTP sessions a practical recovery knob.

Project detection is wrong

Memorix identifies projects from Git. If an IDE launches from a system directory or does not pass the workspace root correctly:

prefer opening the repository root in the IDE
if needed, set MEMORIX_PROJECT_ROOT
use memorix status to inspect the active project identity

Dashboard Agent Team page is empty

That usually means no autonomous agent workflow has created tasks, locks, messages, or explicit agent identities for this project yet.

Use:

memorix team status
memorix task list

To create autonomous work, use:

memorix orchestrate --goal "..."

If you specifically want shared HTTP MCP or a live dashboard endpoint, then start:

memorix background start

Git hook installed but commits are not appearing as memory

Check:

the repository has Git initialized
the hook file exists
the commit was not filtered as noise
the active project identity is correct

Use:

memorix status

and see GIT_MEMORY.md.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Setup Guide

Current Release Context

Support Tiers

1. Install and Initialize

2. Choose a Runtime Mode

Option A: stdio MCP

Option B: HTTP MCP + Dashboard

Option C: Dockerized HTTP Control Plane

3. MCP Config by Client

Claude Code

Cursor

Windsurf

Codex

GitHub Copilot / VS Code

Kiro

OpenCode

Gemini CLI and similar clients

4. Dashboard

5. Agent Team Features

6. Common Setup Flows

Minimal local setup

Recommended full setup

7. Troubleshooting

Avoid `npx`

Windsurf says the MCP config file has invalid JSON

Codex handshake timeout

Codex stale HTTP session after idle time

Project detection is wrong

Dashboard Agent Team page is empty

Git hook installed but commits are not appearing as memory

8. Related Docs

FilesExpand file tree

SETUP.md

Latest commit

History

SETUP.md

File metadata and controls

Setup Guide

Current Release Context

Support Tiers

1. Install and Initialize

2. Choose a Runtime Mode

Option A: stdio MCP

Option B: HTTP MCP + Dashboard

Option C: Dockerized HTTP Control Plane

3. MCP Config by Client

Claude Code

Cursor

Windsurf

Codex

GitHub Copilot / VS Code

Kiro

OpenCode

Gemini CLI and similar clients

4. Dashboard

5. Agent Team Features

6. Common Setup Flows

Minimal local setup

Recommended full setup

7. Troubleshooting

Avoid npx

Windsurf says the MCP config file has invalid JSON

Codex handshake timeout

Codex stale HTTP session after idle time

Project detection is wrong

Dashboard Agent Team page is empty

Git hook installed but commits are not appearing as memory

8. Related Docs

Avoid `npx`