Memorix

Local-first memory platform for AI coding agents. Git truth, reasoning memory, and cross-agent recall in one MCP server.

Git Memory · Reasoning Memory · Cross-Agent Recall · Control Plane Dashboard

中文文档 · Quick Start · How It Works · Documentation · Setup Guide

Why Memorix

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

What makes Memorix different:

• Git Memory: turn git commit into searchable engineering memory with noise filtering and commit provenance.
• Reasoning Memory: store why a decision was made, not just what changed.
• Cross-Agent Local Recall: Cursor, Windsurf, Claude Code, Codex, Copilot, Kiro, OpenCode, Gemini CLI, and more can read the same local memory base.
• Memory Quality Pipeline: formation, compaction, retention, and source-aware retrieval work together instead of acting like isolated tools.

Quick Start

Install globally:

npm install -g memorix

Initialize project config:

memorix init

Memorix uses two files with two roles:

• memorix.yml for behavior and project settings
• .env for secrets such as API keys

Choose one runtime mode:

memorix serve

Use serve for normal stdio MCP integrations.

memorix serve-http --port 3211

Use serve-http when you want the HTTP transport, collaboration features, and the dashboard on the same port.

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. Git remains the source of truth for the final project identity; projectRoot is the detection anchor that keeps parallel sessions from drifting into the wrong project bucket.

Add Memorix to your MCP client:

{
  "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.

Core Workflows

1. Store and retrieve memory

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.

2. Capture Git truth automatically

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.

3. Run the control plane

memorix serve-http --port 3211

Then open:

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

This 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.

How It Works

graph TB
    A["git commit / agent tool call / manual store"] --> B["Memorix Runtime"]
    B --> C["Observation / Reasoning / Git Memory"]
    C --> D["Formation + Indexing + Graph + Retention"]
    D --> E["S