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["Search / Detail / Timeline / Dashboard / Team"]

Memory Layers

• 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

Retrieval Model

• 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

Documentation

Getting Started

• Setup Guide
• Configuration Guide

Product and Architecture

• Architecture
• Memory Formation Pipeline
• Design Decisions

Reference

• API Reference
• Git Memory Guide
• Modules

Development

• Development Guide
• Known Issues and Roadmap

AI-Facing Project Docs

• llms.txt
• llms-full.txt

Development

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 serve-http --port 3211
memorix git-hook --force

Acknowledgements

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

Star History

License

Apache 2.0