Memorix MCP Server

Memorix

Local-first shared memory layer for AI coding agents.
One project memory system for Claude Code, Codex, Cursor, Windsurf, Copilot, Gemini CLI, OpenCode, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, and any MCP-capable agent.

Shared Project Memory | MCP | Git Memory | Reasoning Memory | Plugins | Orchestration

Chinese | Install | Agents | Quick Start | Memory Model | memcode | Docs

---

Memorix gives the AI coding agents you already use a shared, searchable project memory that survives new chats, IDE switches, terminal sessions, and handoffs. The memory lives under the Git project, not inside one chat window or one tool.

Use Claude Code today, Codex tomorrow, and Cursor in the afternoon. The agent can change; the project memory stays the same.

Use Memorix when you keep re-explaining the same project to a new agent session: the last session already figured something out, another IDE cannot see it, or a design decision is buried in a chat you cannot find anymore.

Problem	What Memorix adds
The next session forgets what the last session learned	Project-scoped memory, session summaries, timelines, and detail retrieval
Different agents know different things	One local memory pool available through MCP, hooks, CLI, SDK, and the bundled terminal agent
Git records what changed, but agents cannot recall it well	Git Memory turns commits into searchable engineering facts
Architecture decisions disappear into old chats	Reasoning Memory stores why choices were made, with alternatives and trade-offs
Static rule files drift	Gotchas, fixes, and project skills evolve from real work
Parallel agent work gets messy	memorix orchestrate coordinates task context, handoffs, locks, verification, and review loops

Memorix is local-first. SQLite is the canonical store, Orama handles search, and LLM-backed formation/embedding is optional. Without model keys, Memorix still works with local full-text retrieval.

Memorix connects through the interfaces each agent already supports: plugin packages, MCP, project rules, hooks, skills, or the bundled terminal agent. memorix setup chooses the right setup for each agent and keeps stdio MCP as the default transport.

Claude Code official plugin + MCP + hooks + skills	Codex CLI official plugin + MCP + AGENTS.md	GitHub Copilot CLI plugin + MCP + hooks + skills	Cursor MCP + rules + skills	Windsurf MCP + rules + hooks	Gemini CLI extension + MCP + hooks + skills
OpenCode local plugin + MCP + skills + AGENTS.md	pi coding agent package + extension + skill	Kiro MCP + steering + hooks	Antigravity plugin + MCP + hooks + skills	Trae MCP + project rules	memcode bundled terminal agent
OpenClaw bundle + MCP + hooks + skills	Hermes Agent plugin + MCP + hooks + skills	Oh-my-Pi package + MCP + hooks + skills	Any MCP Client stdio or HTTP MCP

_{Works with agents that speak MCP, expose hooks/rules, or support plugin/package entries. One local-first memory layer shared across all of them.}

Integration surfaces:

Surface	What it does	Memorix entry
Setup command	Installs the recommended one-time user-level Memorix integration	memorix setup --agent <agent> --global
MCP	Gives an agent Memorix tools for search, detail retrieval, storage, reasoning, and coordination	bundled in setup packages or memorix serve
Usage guidance	Teaches an agent when and how to use Memorix without forcing memory lookup on every prompt	bundled or generated by memorix setup
Hooks	Optional auto-capture of prompts, tool events, file edits, and session lifecycle events where the agent exposes hooks	bundled or generated by memorix setup
Plugin or bundle package	Installs plugin, compatible-bundle, or package files where the agent supports them	Claude Code, Codex, GitHub Copilot CLI, Antigravity, OpenClaw, Hermes Agent, Oh-my-Pi, Pi
Extension	Installs extension files where the agent supports them	Gemini CLI
Local plugin	Installs local plugin files where the agent loads them directly	OpenCode
MCP/rules config	Writes MCP, rules, steering, guidance, or hook config for IDEs and agents that expose those surfaces	Cursor, Windsurf, Kiro, Trae
Skills	Turns durable project knowledge into reusable task guidance	memorix skills and memorix_promote
memcode	Opens the bundled terminal agent that already uses Memorix memory	memorix or memcode

See Integration Surfaces for the current support matrix and what each generated file means.

Use the same setup command without --global only when you intentionally want repo-local guidance, rules, or hooks in the current Git project.

CLI, MCP, and HTTP are different entry points:

• memorix CLI is the direct command surface for setup, memory search/store, Git Memory, import/export, dashboard, orchestration, diagnostics, and automation.
• memorix serve is the stdio MCP bridge used by IDEs and coding agents.
• memorix background start / memorix serve-http run the HTTP service for a shared endpoint, dashboard, Docker, or multiple clients.

Requirements:

• Node.js >=22.19.0
• Git, because project identity is derived from the real Git root

Install and initialize:

npm install -g memorix
memorix init --global                   # optional defaults
memorix setup --agent claude --global   # or codex, copilot, cursor, pi, gemini-cli, opencode,
                                       # windsurf, kiro, antigravity, trae, openclaw, hermes, omp

memorix init is optional. It creates or updates TOML configuration:

• ~/.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.

If you want repo-local guidance or hooks for a specific repository, run the same setup command from inside that repo without --global.

Connect an existing agent

Use the setup command first. The global form is the normal one-time install:

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 omp --global

What it installs depends on the target agent, but the goal is the same: make Memorix available wherever you open that agent without asking you to wire every repo by hand.

• Claude Code: installs the Memorix plugin package, adds CLAUDE.md guidance, and enables hook capture when you do not pass --noHooks.
• Codex: installs the Memorix plugin package, adds AGENTS.md guidance, and enables hook capture when you do not pass --noHooks.
• GitHub Copilot CLI: installs the Copilot plugin package and official Memorix skills.
• Pi: installs the user-level Pi package and official skills.
• Cursor: writes Cursor MCP/rules/config entries in the chosen scope.
• Gemini CLI: installs the extension package, GEMINI.md context, hooks, and skills. Antigravity CLI has an official Gemini CLI migration path, but Gemini CLI remains an active standalone target.
• OpenCode: installs the local plugin file, opencode.json, skills, and AGENTS.md guidance.
• Windsurf, Kiro, Trae: write the MCP/rules/hooks files the target supports.
• Antigravity: installs the official plugin package with plugin.json, mcp_config.json, hooks.json, rules, and skills under ~/.gemini/config/plugins/memorix or .agents/plugins/memorix.
• OpenClaw: installs an OpenClaw-compatible bundle with .mcp.json, official 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 the plugin in config.yaml, registers plugin hooks, slash/CLI commands, skills, and writes MCP config.
• Oh-my-Pi: installs an omp.extensions package with extension hook events, a memorix command, official skills, and writes MCP config.

Need a quieter install? Add --noHooks for targets where setup can control hook capture separately from the host's official package entry.

If you intentionally want repo-local guidance or hooks, run the same command inside that repository without --global.

If your agent only needs a manual MCP entry, use stdio:

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

HTTP is not required for normal setup. Use it only when you intentionally want a shared background service, dashboard, Docker, or multiple clients using the same endpoint:

memorix background start

Then point the client at:

http://localhost:3211/mcp

In HTTP mode, agents should bind the active repo explicitly with memorix_session_start(projectRoot=...) when the client can provide the workspace path. Git remains the final source of truth for project identity.

Uninstall

Preview what will be removed:

memorix uninstall --dry-run

Stop the background service and remove hooks:

memorix uninstall --background --hooks

Full cleanup:

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

memorix uninstall reports MCP config entries for manual cleanup instead of silently editing every MCP file it finds.

Work from the CLI

memorix memory search --query "release blocker"
memorix reasoning search --query "why sqlite"
memorix git-hook --force
memorix ingest log --count 20
memorix dashboard

Use the bundled terminal agent

memorix
# or
memcode

This opens memcode, a terminal coding agent that uses the same Memorix project memory as your MCP-connected agents.

Layer	Stores	Best for
Observation Memory	facts, gotchas, fixes, implementation notes	"How does this work?"
Reasoning Memory	rationale, alternatives, constraints, risks	"Why did we choose this?"
Git Memory	commit-derived engineering facts	"What changed and where?"

Search is project-scoped by default. scope="global" searches across projects. The search boosts Git Memory for "what changed" questions and reasoning records for "why" questions.

You want	Run
Install an agent integration package	memorix setup --agent <agent> --global
Manually expose stdio MCP	memorix serve
Run shared HTTP MCP plus dashboard	memorix background start
Debug HTTP MCP in the foreground	memorix serve-http --port 3211
Inspect or manage memory directly	memorix memory, memorix reasoning, memorix session, memorix ingest
Use the bundled terminal agent	memorix or memcode
Run orchestrated subagent work	memorix orchestrate --goal "..."

memorix orchestrate uses the current checkout for single-worker runs. When running multiple workers, it creates task worktrees under .worktrees/ and merges successful task branches back. Use --isolated to force worktree isolation for one worker, --no-worktree to disable it, --allow-dirty to run with uncommitted changes, and --no-auto-merge to preserve task worktrees for manual review.

memcode is the terminal coding agent bundled with Memorix. It can read, edit, run commands, resume sessions, switch models, and use /memory commands — all backed by the same project memory as your MCP-connected agents.

Use it when you want a terminal agent with memory already wired in.

one Git project -> one shared Memorix memory pool

See docs/MEMCODE.md for the memcode-specific guide.

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"

Use [memory.llm] and [embedding] for Memorix memory quality and retrieval. Use [agent] for the model memcode talks to while coding. Keep credentials in global config or environment variables, and do not commit secrets.

For OpenRouter embeddings, use provider = "api", base_url = "https://openrouter.ai/api/v1", and model = "qwen/qwen3-embedding-8b". Memorix accepts OPENROUTER_API_KEY for that embedding endpoint; MEMORIX_EMBEDDING_API_KEY remains the explicit override.

Docker is for the HTTP service, not stdio MCP:

docker compose up --build -d

Then open:

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

The container must be able to access the repository path passed as projectRoot for project-scoped Git and config behavior.

Use Memorix directly from TypeScript:

import { createMemoryClient } from 'memorix/sdk';

const client = await createMemoryClient({ projectRoot: '/path/to/repo' });

await client.store({
  entityName: 'auth-module',
  type: 'decision',
  title: 'Use JWT for API auth',
  narrative: 'Chose JWT because the API is stateless and used by multiple clients.',
});

const results = await client.search({ query: 'auth decision' });
await client.close();

Start here	Use when
Docs Map	You want the shortest route to the right guide
Setup Guide	Installing, using memorix setup, choosing stdio vs HTTP
Integration Surfaces	Plugin packages, MCP, project rules, hooks, and skills support
Configuration	TOML config, model lanes, compatibility files
API Reference	MCP tools and CLI commands
Git Memory	Commit ingestion and searchable engineering truth
Docker	Containerized HTTP service
memcode	Using the bundled terminal agent
Agent Playbook	AI-facing execution guide for install, binding, hooks, and troubleshooting
Development	Contributing, testing, release checks
Changelog	What changed in each release

LLM-friendly summaries: llms.txt and llms-full.txt.

git clone https://github.com/AVIDS2/memorix.git
cd memorix
npm install
npm run lint
npm test
npm run build

Memorix draws from the MCP ecosystem and prior memory projects such as mcp-memory-service, MemCP, claude-mem, and Mem0. memcode is based on the Pi coding-agent codebase and adapts its terminal-agent model for the Memorix ecosystem.

Apache 2.0