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> --globalmemorix 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.
- 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 initprojectRoot 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.
npm install -g memorixInitialize global defaults (optional):
memorix init --globalInstall 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 --globalWhat this does:
- Claude Code: installs a local marketplace plugin, attempts
claude plugin install memorix@memorix-local, and writesCLAUDE.mdguidance. - Codex: installs a user-level Personal marketplace plugin under
~/plugins/memorix, attemptscodex plugin add memorix@personal, and keeps project-local.codexconfiguration 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/memorixand.pi/mcp.json. - Gemini CLI: installs a local extension package under
~/.gemini/extensions/memorixwith 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.mdguidance. - Antigravity: installs a native plugin under
~/.gemini/config/plugins/memorixfor global setup or.agents/plugins/memorixfor workspace setup. The plugin bundlesplugin.json,mcp_config.json,hooks.json, rules, and skills. - OpenClaw: installs
~/.openclaw/extensions/memorixas an OpenClaw-compatible bundle with bundled stdio MCP, skills, and an OpenClawHOOK.md/handler.tshook pack. - Hermes Agent: installs into Hermes home (
%LOCALAPPDATA%\hermeson native Windows,~/.hermeselsewhere, orHERMES_HOME), enables it inconfig.yaml, registers plugin hooks, a slash command, a CLI command, skills, and writes MCP config inmcp_servers. - Oh-my-Pi: installs an
omp.extensionspackage, links it withomp plugin link <path>when available, and writes.omp/mcp.jsonor~/.omp/agent/mcp.jsonfor MCP. - DeepSeek Harness: writes a Memorix
@deepseek-ai/dsh-mcp-clientrow into$DSH_HOME/cordis.patch.yml(default~/.dsh/cordis.patch.yml), appends guidance to the harnessAGENTS.md($DSH_HOME/AGENTS.md, default~/.dsh/AGENTS.md), and installs official skills under$DSH_HOME/skills(default~/.dsh/skills). Tools appear asmcp__memorix__*; there is no hooks surface. Project-local setup (without--global) appends guidance to the project-rootAGENTS.mdand 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.tomlfor global defaults<git-root>/memorix.tomlfor 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>memorix setup --agent <agent> --globalUse 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 --listIf 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.
memorix serveUse 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.
memorix
# or
memcodeUse 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-4oInside the TUI:
/memory status
/memory search
/memory show
/memory hooks
/model switch
/resume
/tree
/config
See MEMCODE.md.
memorix background startThis 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 stopUse foreground HTTP mode for debugging or custom launch supervision:
memorix serve-http --port 3211memorix 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.targetsystemctl --user daemon-reload
systemctl --user enable --now memorix-http.servicemacOS 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.plistGeneric 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 restartSet MEMORIX_SESSION_TIMEOUT_MS=0 only when the host has its own reliable
session cleanup; otherwise keep a bounded idle window.
docker compose up --build -dDocker support is for serve-http, dashboard, and HTTP MCP. It is not a containerized version of stdio MCP.
See DOCKER.md.
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.
Recommended:
claude mcp add memorix -- memorix serveManual 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.
Project config: .cursor/mcp.json
{
"mcpServers": {
"memorix": {
"command": "memorix",
"args": ["serve"]
}
}
}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"
}
}
}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 = 30HTTP:
[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.
Project config: .vscode/mcp.json
{
"servers": {
"memorix": {
"command": "memorix",
"args": ["serve"]
}
}
}Project config: .kiro/settings/mcp.json
{
"mcpServers": {
"memorix": {
"command": "memorix",
"args": ["serve"]
}
}
}Requires Pi 1.0+. Setup installs both the extension/skills package and a native MCP server entry:
memorix setup --agent pi --globalThis 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 --approveCheck the loaded package resources with:
pi config --approveYou 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 startThis 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.
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 --globalThis 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 --globalOpenClaw 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 --globalHermes 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 --globalOh-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 --globalMinimal ~/.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.
cd your-repo
memorix
/memory statusmemorix memory store --text "Auth tokens expire after 24h" --title "Auth token TTL" --entity auth --type decision
memorix memory search --query "auth token ttl"memorix git-hook --force
memorix ingest log --count 20memorix transfer export --format json
memorix transfer import --data "<json export>"This transfers stored memory artifacts, not private chat history from an IDE vendor.
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-mergeis 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-mergeUse the team, task, message, handoff, and lock CLI commands when you need to inspect or operate that coordination state directly.
That is expected in the current release line. Use memorix --help to see the full CLI and memorix serve for MCP.
Check:
git status
memorix status
memorix receipt --jsonShared memory means stored memories are searchable by clients bound to the same Git project. It does not mean raw chat transcripts are mirrored.
Increase startup timeout:
[mcp_servers.memorix]
command = "memorix"
args = ["serve"]
startup_timeout_sec = 30Set a longer timeout before starting the background service:
$env:MEMORIX_SESSION_TIMEOUT_MS = "86400000"
memorix background restartEnsure ~/.codeium/windsurf/mcp_config.json is valid UTF-8 JSON without BOM.
- open the real repository root in your IDE
- avoid launching the agent from a system directory
- set
MEMORIX_PROJECT_ROOTonly when the client cannot pass cwd reliably - run
memorix statusto inspect the active project identity
Check:
memorix status
memorix ingest commit --forceThe commit may have been filtered as noise. See GIT_MEMORY.md.
Preview:
memorix uninstall --dry-runStop background service and remove hooks:
memorix uninstall --background --hooksThen remove the npm package:
npm uninstall -g memorixFull 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) |