Open-source cross-agent memory layer for coding agents.
Tiered MCP support across Cursor, Claude Code, Codex, Windsurf, Gemini CLI, GitHub Copilot, Kiro, OpenCode, Antigravity, and Trae.

Three-Layer Memory | Team Collaboration | Workspace Sync | Multi-Agent Orchestration | Dashboard

Chinese | Quick Start | Docker | Supported Clients | Core Workflows | Documentation | Setup Guide

If you are an AI coding agent and your user asked you to install, configure, or troubleshoot Memorix — read the Agent Operator Playbook first. It is the canonical guide written for you, covering:

• installation and runtime-mode selection
• Git/project binding rules
• stdio vs HTTP control-plane setup
• per-agent integration and hooks
• generated dot-directory behavior
• troubleshooting and safe operating rules

The only cross-agent memory layer that preserves Git truth, reasoning context, and local control — across 10 IDEs and agents.

Most coding agents remember only the current thread. Memorix gives them a shared, persistent memory layer across IDEs, sessions, and projects.

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.

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:

Most users should choose one of the first two options above.

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.

Memorix now exposes an operator-oriented CLI surface for the most common human workflows. Use it when you want to inspect or control the current project directly from a terminal without going through MCP tool calls.

memorix session start --agent codex-main --agentType codex
memorix memory search --query "docker control plane"
memorix team status
memorix task list
memorix message inbox --agentId <agent-id>
memorix lock status --file src/cli/index.ts
memorix poll --agentId <agent-id>

The CLI is intentionally human-shaped, not a 1:1 mirror of MCP tool names. MCP remains the full agent/tool API; the CLI groups the main operator actions into readable namespaces:

• memorix session ...
• memorix memory ...
• memorix team ...
• memorix task ...
• memorix message ...
• memorix lock ...
• memorix handoff ...
• memorix poll

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:

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

{
  "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, keep the generic HTTP block above and use the client-specific variants in docs/SETUP.md.

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

claude mcp add memorix -- memorix serve

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

For the full IDE matrix, Windows notes, and troubleshooting, see docs/SETUP.md.

Use MCP tools such as:

• memorix_store
• memorix_search
• memorix_detail
• memorix_timeline
• memorix_resolve

This covers decisions, gotchas, problem-solution notes, and session handoff context.

Install the post-commit hook:

memorix git-hook --force

Or ingest manually:

memorix ingest commit
memorix ingest log --count 20

Git memories are stored with source='git', commit hashes, changed files, and noise filtering.

memorix background start

Then open:

• MCP HTTP endpoint: http://localhost:3211/mcp
• Dashboard: http://localhost:3211

Companion commands:

memorix background status
memorix background logs
memorix background stop

Use background start as the default long-lived HTTP mode. If you need to keep the control plane in the foreground for debugging or manual supervision, use:

memorix serve-http --port 3211

This HTTP mode gives you collaboration tools, project identity diagnostics, config provenance, Git Memory views, and the dashboard in one place.

When multiple HTTP sessions are open at once, each session should bind itself with memorix_session_start(projectRoot=...) before using project-scoped memory tools.

Requires the HTTP control plane (background start or serve-http).

# Register an agent
memorix team join --name cursor-frontend --agent-type cursor

# Create and claim tasks
memorix task create --description "Fix auth redirect loop"
memorix task claim --task-id <id> --agent-id <agent-id>

# Send messages between agents
memorix message send --from <agent-id> --to <agent-id> --type info --content "Auth module is done"

MCP tools: team_manage, team_task, team_message, team_file_lock, memorix_poll.

Run a structured coordination loop across multiple agents:

memorix orchestrate --goal "Add user authentication" --agents claude-code,cursor,codex

The loop: plan → parallel execution → verify gates → fix loops → review → merge. Supports capability routing, worktree isolation, agent fallback, and cost tracking.

Migrate MCP configs, rules, workflows, and skills from one agent to another:

# Scan what's installed across all agents
memorix sync scan

# Preview migration to a new agent
memorix sync migrate --target cursor

# Apply (writes configs with backup/rollback)
memorix sync apply --target cursor

MCP tools: memorix_workspace_sync, memorix_rules_sync.

Auto-generate SKILL.md files from your project's memory patterns, or promote important observations to permanent mini-skills:

# List discovered skills
memorix skills list

# Generate skills from memory
memorix skills generate --target cursor

MCP tools: memorix_skills, memorix_promote.

Import Memorix directly into your own TypeScript/Node.js project — no MCP or CLI needed:

import { createMemoryClient } from 'memorix/sdk';

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

// Store a memory
await client.store({
  entityName: 'auth-module',
  type: 'decision',
  title: 'Use JWT for API auth',
  narrative: 'Chose JWT over session cookies for stateless API.',
});

// Search
const results = await client.search({ query: 'authentication' });

// Retrieve, resolve, count
const obs = await client.get(1);
const all = await client.getAll();
await client.resolve([1, 2]);

await client.close();

Three subpath exports:

Memorix is not a single linear pipeline. It accepts memory from multiple ingress surfaces, persists it across multiple substrates, runs several asynchronous quality/indexing branches, and exposes the results through different retrieval and collaboration surfaces.

• Observation Memory: what changed, how something works, gotchas, problem-solution notes
• Reasoning Memory: why a choice was made, alternatives, trade-offs, risks
• Git Memory: immutable engineering facts derived from commits

• Default search is project-scoped
• scope="global" searches across projects
• Global hits can be opened explicitly with project-aware refs
• Source-aware retrieval boosts Git memories for "what changed" questions and reasoning memories for "why" questions

📖 Docs Map — fastest route to the right document.

Additional deep references:

• Memory Formation Pipeline
• Design Decisions
• Modules
• Known Issues and Roadmap
• AI Context Note
• llms.txt
• llms-full.txt

Version 1.0.8 builds on the 1.0.7 coordination/storage/team baseline with an operator CLI, official Docker path, dashboard refinements, and broad hooks fixes.

• Operator CLI: Human-oriented namespaces (memorix session, memory, team, task, message, lock, handoff, poll) so the most common project ops no longer require MCP tool calls.
• Docker Deployment: Official Dockerfile, compose.yaml, healthcheck, --host binding, and DOCKER.md for running the HTTP control plane in a container.
• Multi-Agent Orchestrator: memorix orchestrate — plan → parallel execution → verify gates → fix loops → review → merge. Claude, Codex, Gemini CLI, OpenCode with capability routing, worktree isolation, and agent fallback.
• SQLite Canonical Store: Observations, mini-skills, sessions, and archives in SQLite. Shared DB handle, freshness-safe retrieval, dead JsonBackend removed.
• Team Identity: Agent registration, heartbeat, task board, handoff artifacts, stale detection. session_start auto-registers agents with default role mapping.
• Dashboard Semantic Layering: Team page filter tabs (Active/Recent/Historical), de-emphasized historical agents, project switcher grouped by real/temporary/placeholder, identity page cleanup.
• Hooks Fixes: OpenCode event-name key mapping + Bun.spawn → spawnSync; Copilot pwsh fallback + global-hooks guard; hook handler diagnostic logging.
• Programmatic SDK: import { createMemoryClient } from 'memorix/sdk' — store, search, get, resolve observations directly from your own code without MCP or CLI. Also exports createMemorixServer and detectProject.
• Test Suite Stabilization: E2e and live-LLM tests excluded from default suite; deterministic merge-conflict test. 147 files, 2002 tests, 0 skipped, 0 failed.

git clone https://github.com/AVIDS2/memorix.git
cd memorix
npm install

npm run dev
npm test
npm run build

Key local commands:

memorix status
memorix dashboard
memorix background start
memorix serve-http --port 3211
memorix git-hook --force

Memorix builds on ideas from mcp-memory-service, MemCP, claude-mem, Mem0, and the broader MCP ecosystem.

Apache 2.0