Skip to content

Latest commit

 

History

History
773 lines (561 loc) · 24.9 KB

SETUP.md

File metadata and controls

773 lines (561 loc) · 24.9 KB

Setup Guide

Memorix is a local-first shared memory layer for AI coding agents.

In the current release line, the normal path is:

npm install -g memorix
memorix init --global
memorix setup --agent <agent> --global

memorix setup installs the recommended Memorix integration for the target agent: plugin packages where supported, MCP config, usage guidance, hooks, and skills. With --global, it writes the user-level integrations the host supports. Run the same command inside a repo without --global only when you intentionally want repo-local guidance, rules, or hooks for that project.

Common runtime entry points:

Entry Use it for
memorix setup --agent <agent> --global one-command user-level agent integration; installs the stdio server with --mode lite so every tool taught in the generated guidance is actually reachable
memorix CLI commands direct workflows: setup, search/store, Git Memory, import/export, dashboard, diagnostics, orchestration, and automation
memorix serve stdio MCP server for IDEs and coding agents; defaults to a compact micro tool profile when launched manually
memorix background start long-lived HTTP MCP service plus dashboard
memorix serve-http --port 3211 foreground HTTP MCP for debugging or supervised launches
memorix / memcode bundled terminal agent that uses the same Memorix memory pool

Most users should start with memorix setup --agent <agent> --global. Use raw memorix serve only when you are wiring an MCP client manually. Use HTTP when you intentionally want one shared background process, browser dashboard, VPS Docker deployment, or multiple clients using the same MCP endpoint. Local development and verification run the Node service directly and do not require Docker. Use the CLI for manual operation and automation. Use memcode when you want the bundled terminal agent.

For agent-specific plugin, rules, hooks, and skills support, see INTEGRATIONS.md.


1. Requirements

  • Node.js >=22.18.0
  • npm
  • Git

Memorix project identity comes from Git. Open or initialize a real Git repository before expecting project-scoped memory to work:

git init

projectRoot and current working directory are detection anchors. The final project identity is derived from the real Git root and remote metadata. Memorix resolves an existing project directory to its real filesystem path before binding it, so equivalent macOS paths such as /var/... and /private/var/... do not create separate project or Claude local-MCP entries.


2. Install

npm install -g memorix

Initialize global defaults (optional):

memorix init --global

Install an agent integration:

memorix setup --agent claude --global
memorix setup --agent codex --global
memorix setup --agent copilot --global
memorix setup --agent cursor --global
memorix setup --agent pi --global
memorix setup --agent gemini-cli --global
memorix setup --agent opencode --global
memorix setup --agent windsurf --global
memorix setup --agent kiro --global
memorix setup --agent antigravity --global
memorix setup --agent trae --global
memorix setup --agent openclaw --global
memorix setup --agent hermes --global
memorix setup --agent codebuddy --global
memorix setup --agent omp --global
memorix setup --agent dsh --global

What this does:

  • Claude Code: installs a local marketplace plugin, attempts claude plugin install memorix@memorix-local, and writes CLAUDE.md guidance.
  • Codex: installs a user-level Personal marketplace plugin under ~/plugins/memorix, attempts codex plugin add memorix@personal, and keeps project-local .codex configuration untouched. The plugin owns its MCP server, skills, and optional hooks without changing your model, approval, or sandbox settings.
  • GitHub Copilot CLI: installs a local plugin package and attempts copilot plugin install <local-path>.
  • Cursor: writes Cursor MCP config, rules, skills, and hook guidance.
  • Pi: installs the user-level Memorix Pi package, attempts pi install <path> --approve, and writes native MCP config to ~/.pi/agent/mcp.json (Pi 1.0+). Project setup uses .pi/packages/memorix and .pi/mcp.json.
  • Gemini CLI: installs a local extension package under ~/.gemini/extensions/memorix with MCP, GEMINI.md, hooks, commands, and skills. Antigravity CLI has an official Gemini CLI migration path, but Memorix keeps Gemini CLI as its own active standalone target.
  • OpenCode: installs a local plugin file, OpenCode skill, MCP config, and AGENTS.md guidance.
  • Antigravity: installs a native plugin under ~/.gemini/config/plugins/memorix for global setup or .agents/plugins/memorix for workspace setup. The plugin bundles plugin.json, mcp_config.json, hooks.json, rules, and skills.
  • OpenClaw: installs ~/.openclaw/extensions/memorix as an OpenClaw-compatible bundle with bundled stdio MCP, skills, and an OpenClaw HOOK.md/handler.ts hook pack.
  • Hermes Agent: installs into Hermes home (%LOCALAPPDATA%\hermes on native Windows, ~/.hermes elsewhere, or HERMES_HOME), enables it in config.yaml, registers plugin hooks, a slash command, a CLI command, skills, and writes MCP config in mcp_servers.
  • Oh-my-Pi: installs an omp.extensions package, links it with omp plugin link <path> when available, and writes .omp/mcp.json or ~/.omp/agent/mcp.json for MCP.
  • DeepSeek Harness: writes a Memorix @deepseek-ai/dsh-mcp-client row into $DSH_HOME/cordis.patch.yml (default ~/.dsh/cordis.patch.yml), appends guidance to the harness AGENTS.md ($DSH_HOME/AGENTS.md, default ~/.dsh/AGENTS.md), and installs official skills under $DSH_HOME/skills (default ~/.dsh/skills). Tools appear as mcp__memorix__*; there is no hooks surface. Project-local setup (without --global) appends guidance to the project-root AGENTS.md and installs skills under .dsh/skills, while the MCP row still goes to the harness-level patch file.
  • Other supported agents: writes their MCP/rules/hooks files according to agent support.

Global setup writes user-level plugin, config, and hook files where the host supports them. Use the same command without --global only when you explicitly want repo-local guidance, rules, or hooks for the current project.

Memorix uses TOML as the user-facing configuration model:

  • ~/.memorix/config.toml for global defaults
  • <git-root>/memorix.toml for optional project overrides

Legacy memorix.yml, .env, and ~/.memorix/config.json are still read for compatibility, but new setup flows use TOML.

Useful checks:

memorix --version
memcode --version
memorix status
memorix config path
memorix doctor agents --agent <agent>

3. Choose Your Runtime

Option A: setup for existing agents

memorix setup --agent <agent> --global

Use this for Claude Code, Codex, Cursor, Windsurf, Copilot, Gemini CLI, OpenCode, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, DeepSeek Harness, or any supported agent. It is the default user-facing install path.

To see the current setup matrix:

memorix setup --list

If an agent does not naturally see or use Memorix after setup, inspect the integration layer:

memorix doctor agents --agent <agent>
memorix repair agents --agent <agent>

The doctor checks Memorix-owned MCP entries and guidance files for stale command paths, missing memorix MCP servers, missing Claude alwaysLoad, and outdated Memory Autopilot rules. For codex --scope global, MCP is owned by the user-level plugin rather than a direct config.toml entry. The doctor checks the plugin bundle, Personal marketplace entry, five declared lifecycle hooks, and the installed/enabled state reported by codex plugin list; it reports, but never auto-grants, any hook review Codex still requires.

After Codex setup, start a new thread so enabled plugins can load. If Codex asks to review plugin hooks, approve or decline them in /hooks; this is user-level plugin consent, not project trust. If doctor reports codex-plugin-disabled, open /plugins and turn Memorix on there; repair does not toggle a user-disabled plugin.

Option B: manual stdio MCP

memorix serve

Use this when your agent only needs a raw local stdio MCP process or you are debugging a manual config. The agent starts memorix serve and communicates with it over stdio.

A bare memorix serve defaults to --mode micro, which exposes 9 high-signal tools so agent context is not crowded by rarely used schemas. Use memorix serve --mode lite for the 21-tool solo memory surface, --mode team for the 29-tool coordination surface, or --mode full for all 48 advanced and MCP Memory compatibility tools.

memorix setup writes --mode lite into the installed MCP config: the generated guidance teaches the extended surface (sessions, timeline, reasoning, retention), so the installed server must actually expose it. Override with MEMORIX_MODE if you prefer a different profile.

Generic stdio MCP config:

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

Avoid npx in persistent MCP configs. Use the globally installed memorix binary so startup is predictable.

When an npm-based MCP client or registry tester must launch the package directly, use npx -y memorix serve. The explicit serve argument selects the stdio MCP server; a human running bare memorix in a terminal gets the bundled memcode agent instead.

Option C: memcode terminal agent

memorix
# or
memcode

Use this when you want a terminal coding agent with Memorix memory already wired in. memcode can read, edit, run commands, resume sessions, switch models, and search/store shared project memory. It uses the same project memory pool as MCP-connected agents.

Common commands:

memcode -p "summarize this repo"
memcode -c
memcode -r
memcode --model openai/gpt-4o

Inside the TUI:

/memory status
/memory search
/memory show
/memory hooks
/model switch
/resume
/tree
/config

See MEMCODE.md.

Option D: HTTP MCP + dashboard

memorix background start

This starts a local background service:

  • dashboard: http://localhost:3211
  • MCP endpoint: http://localhost:3211/mcp
  • health: http://localhost:3211/health

HTTP mode is for a shared process. It is useful when multiple clients should connect to one Memorix endpoint, when you want the browser dashboard, or when running Memorix through Docker on a VPS/hosted machine. It is not needed for the normal one-agent stdio MCP setup.

Companion commands:

memorix background status
memorix background logs
memorix background stop

Use foreground HTTP mode for debugging or custom launch supervision:

memorix serve-http --port 3211

memorix background start survives the terminal but not logout or reboot. For a supervised control plane that only execs memorix serve-http, use an OS unit. Keep the bind address loopback-only.

Linux systemd user unit (~/.config/systemd/user/memorix-http.service):

[Unit]
Description=Memorix HTTP MCP control plane
After=default.target

[Service]
Type=simple
ExecStart=/usr/bin/env memorix serve-http --host 127.0.0.1 --port 3211
Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin
Restart=on-failure
RestartSec=3

[Install]
WantedBy=default.target
systemctl --user daemon-reload
systemctl --user enable --now memorix-http.service

macOS LaunchAgent (~/Library/LaunchAgents/com.memorix.http.plist). Replace the memorix path with the output of which memorix:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.memorix.http</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/memorix</string>
    <string>serve-http</string>
    <string>--host</string>
    <string>127.0.0.1</string>
    <string>--port</string>
    <string>3211</string>
  </array>
  <key>KeepAlive</key>
  <true/>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.memorix.http.plist

Generic HTTP MCP config:

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

For multi-project HTTP usage, agents should call memorix_session_start(projectRoot=...) with the absolute workspace path when available. This prevents cross-project drift when the background service is shared.

HTTP sessions idle out after 12 hours by default. An expired session receives a fast 404 that tells the client to initialize again, rather than being treated as a project-binding failure. For clients that intentionally need a longer window:

$env:MEMORIX_SESSION_TIMEOUT_MS = "86400000"
memorix background restart

Set MEMORIX_SESSION_TIMEOUT_MS=0 only when the host has its own reliable session cleanup; otherwise keep a bounded idle window.

Option E: Docker HTTP service

docker compose up --build -d

Docker support is for serve-http, dashboard, and HTTP MCP. It is not a containerized version of stdio MCP.

See DOCKER.md.


4. Manual MCP Client Setup

Use this section when memorix setup --agent <agent> --global is not available for the target agent, or when you intentionally want to manage MCP configuration yourself.

Claude Code fallback

Recommended:

claude mcp add memorix -- memorix serve

Manual stdio shape:

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

Keep alwaysLoad: true for a manually managed Claude Code entry so its small Memorix tool set is available during print-mode startup. memorix doctor agents --agent claude reports a missing eager-load setting, and memorix repair agents --agent claude restores it without replacing unrelated MCP servers.

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 variants in Windsurf-like clients may use serverUrl:

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

Codex manual MCP compatibility

The user-level plugin is the default and should be the only Memorix route for Codex. Use this compatibility fallback only when the Codex plugin system is unavailable; do not add it alongside memorix@personal, because that creates duplicate MCP ownership.

Config file: ~/.codex/config.toml

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

HTTP:

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

For HTTP, pair the URL with agent instructions that call memorix_session_start(projectRoot=...) when the current workspace path is known.

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"]
    }
  }
}

Pi

Requires Pi 1.0+. Setup installs both the extension/skills package and a native MCP server entry:

memorix setup --agent pi --global

This merges mcpServers.memorix into ~/.pi/agent/mcp.json, preserving unrelated servers and settings. The default stdio entry runs memorix serve --mode lite. It also writes the user-level Memorix Pi package and registers it with:

pi install ~/.pi/agent/packages/memorix --approve

Check the loaded package resources with:

pi config --approve

You should see the Memorix extension and the shared official Memorix skills listed under the Pi package. Setup generates the same skills used by other supported agents; Pi does not maintain a separate skill set. Native MCP supplies the tools, and lifecycle capture comes from the extension.

For project-local setup, run memorix setup --agent pi from the project root. This writes .pi/mcp.json and installs .pi/packages/memorix with pi install <path> -l --approve. Pi must trust the project before it loads project-local MCP configuration.

For an explicitly shared HTTP control plane:

memorix setup --agent pi --global --mcp http
memorix background start

This writes mcpServers.memorix.url = "http://localhost:3211/mcp" instead of a stdio command. In HTTP mode, bind the active repository with memorix_session_start(projectRoot=...).

Use --mcp none to skip MCP configuration. Existing MCP configuration is left untouched.

After setup, run pi mcp list to check connections, then /reload in Pi (or restart it). Use /mcp to inspect servers in a session. Pi exposes MCP tools through codemode by default; tool discovery is not evidence that the server is missing. Extensions such as pi-mcp-adapter that replace Pi's built-in /mcp also replace native config loading; use Pi's built-in MCP support for this setup.

Gemini CLI, OpenCode, Antigravity, Trae, OpenClaw, Hermes Agent, Oh-my-Pi, and other MCP clients

If the client supports stdio MCP, use:

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

If it supports HTTP MCP, use http://localhost:3211/mcp.

OpenCode can also use a local Memorix plugin generated by setup:

memorix setup --agent opencode --global

This writes the OpenCode plugin, skills, MCP config, and AGENTS.md guidance in the selected scope. The generated plugin exports the legacy v1 hook function and a dual default object with the v1 server field plus the v2 id/setup contract, so OpenCode v1 and v2 can load the same file during the migration window. OpenCode 1.x events are received through its generic event hook.

Antigravity setup installs a native plugin at ~/.gemini/config/plugins/memorix for global setup or .agents/plugins/memorix for workspace setup. The plugin includes stdio MCP, official hooks, rules, and skills:

memorix setup --agent antigravity --global

OpenClaw setup installs a compatible bundle at ~/.openclaw/extensions/memorix, then best-effort runs openclaw plugins install <path> --force and openclaw hooks enable memorix. The bundle includes stdio MCP, skills, and an OpenClaw HOOK.md/handler.ts hook pack:

memorix setup --agent openclaw --global

Hermes Agent setup installs plugins/memorix under Hermes home (%LOCALAPPDATA%\hermes on native Windows, ~/.hermes elsewhere, or HERMES_HOME), enables it in config.yaml, registers hooks/commands/skills through the plugin, and writes mcp_servers.memorix:

memorix setup --agent hermes --global

Oh-my-Pi setup installs an omp.extensions package, best-effort runs omp plugin link <path>, and writes .omp/mcp.json for repo-local setup or ~/.omp/agent/mcp.json with --global:

memorix setup --agent omp --global

5. Configure Models And Memory

Minimal ~/.memorix/config.toml:

[agent]
provider = "openai"
model = "gpt-4o"
api_key = "..."

[memory.llm]
provider = "openai"
model = "gpt-4o-mini"
api_key = "..."

[embedding]
provider = "auto"

[memory]
inject = "minimal"
formation = "active"

What each lane does:

Lane Used by
[agent] model used by memcode while coding
[memory.llm] memory formation, summaries, deduplication, optional LLM rerank fallback
[rerank] optional HTTP rerank against a compatible /rerank API
[embedding] semantic/vector search
[memory] memory injection and formation behavior
[git] Git Memory hook and ingestion behavior
[server] server, dashboard, and port defaults

See CONFIGURATION.md for the full model and compatibility behavior.


6. Common Workflows

Terminal coding with memory

cd your-repo
memorix
/memory status

Store and search a memory from the CLI

memorix memory store --text "Auth tokens expire after 24h" --title "Auth token TTL" --entity auth --type decision
memorix memory search --query "auth token ttl"

Capture Git Memory

memorix git-hook --force
memorix ingest log --count 20

Move memory between machines

memorix transfer export --format json
memorix transfer import --data "<json export>"

This transfers stored memory artifacts, not private chat history from an IDE vendor.

Run orchestrated subagent work

memorix orchestrate coordinates task context, handoffs, advisory locks, verification, and review loops for subagent-style work. You don't need it for normal memory use.

memorix task list
memorix orchestrate --goal "Add user authentication"

Worktree behavior:

  • single-worker runs use the current checkout by default
  • multi-worker runs create task worktrees under .worktrees/
  • worktree creation failures stop the run instead of falling back to the shared checkout
  • dirty Git worktrees are rejected by default
  • successful task worktrees are merged back automatically unless --no-auto-merge is set

Useful safety flags:

memorix orchestrate --goal "Add auth" --isolated
memorix orchestrate --goal "Add auth" --no-worktree
memorix orchestrate --goal "Add auth" --allow-dirty
memorix orchestrate --goal "Add auth" --no-auto-merge

Use the team, task, message, handoff, and lock CLI commands when you need to inspect or operate that coordination state directly.


7. Troubleshooting

memorix opens memcode

That is expected in the current release line. Use memorix --help to see the full CLI and memorix serve for MCP.

No project memory appears

Check:

git status
memorix status
memorix receipt --json

Shared memory means stored memories are searchable by clients bound to the same Git project. It does not mean raw chat transcripts are mirrored.

Codex handshake timeout

Increase startup timeout:

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

Codex stale HTTP session after idle time

Set a longer timeout before starting the background service:

$env:MEMORIX_SESSION_TIMEOUT_MS = "86400000"
memorix background restart

Windsurf rejects MCP JSON on Windows

Ensure ~/.codeium/windsurf/mcp_config.json is valid UTF-8 JSON without BOM.

Project detection is wrong

  • open the real repository root in your IDE
  • avoid launching the agent from a system directory
  • set MEMORIX_PROJECT_ROOT only when the client cannot pass cwd reliably
  • run memorix status to inspect the active project identity

Git hook installed but commits are missing

Check:

memorix status
memorix ingest commit --force

The commit may have been filtered as noise. See GIT_MEMORY.md.


8. Uninstall

Preview:

memorix uninstall --dry-run

Stop background service and remove hooks:

memorix uninstall --background --hooks

Then remove the npm package:

npm uninstall -g memorix

Full local data purge:

memorix uninstall --dry-run --purge-data
memorix uninstall --yes --background --hooks --purge-data
npm uninstall -g memorix

--purge-data deletes local Memorix data under ~/.memorix, including memories, sessions, mini-skills, logs, and config. Use --dry-run first.

Memorix does not silently edit all MCP config files during uninstall. It reports remaining entries and shows where to remove them manually.

Common MCP config locations:

Agent Config file
Claude Code ~/.claude.json or .claude/settings.json
Cursor ~/.cursor/mcp.json or .cursor/mcp.json
Windsurf ~/.codeium/windsurf/mcp_config.json
Codex ~/.codex/config.toml
VS Code / Copilot .vscode/mcp.json
Kiro ~/.kiro/settings/mcp.json or .kiro/settings/mcp.json
Gemini CLI ~/.gemini/settings.json
Antigravity ~/.gemini/config/mcp_config.json, ~/.gemini/config/hooks.json, or plugin files under ~/.gemini/config/plugins/memorix
OpenClaw ~/.openclaw/openclaw.json
Hermes Agent %LOCALAPPDATA%\hermes\config.yaml on native Windows, ~/.hermes/config.yaml elsewhere, or HERMES_HOME\config.yaml
Oh-my-Pi .omp/mcp.json or ~/.omp/agent/mcp.json
Trae %APPDATA%/Trae/User/mcp.json on Windows
DeepSeek Harness $DSH_HOME/cordis.patch.yml (default ~/.dsh/cordis.patch.yml)
WorkBuddy ~/.workbuddy/mcp.json (user) or <project>/.workbuddy/mcp.json (project)

9. Related Docs