memorix

For Coding Agents

If you are using an AI coding agent to install or operate Memorix, have it read the Agent Operator Playbook first.

That playbook is the canonical AI-facing guide for:

• 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

Why Memorix

Most 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: multiple IDEs and agents can read the same local memory base instead of living in isolated silos.
• Memory Quality Pipeline: formation, compaction, retention, and source-aware retrieval work together instead of acting like isolated tools.

Memorix is built for one job: let multiple coding agents share the same durable project memory through MCP without giving up Git truth, reasoning history, or local control.

Supported Clients

Memorix currently ships first-class integrations for:

• Cursor
• Claude Code
• Codex
• Windsurf
• Gemini CLI
• GitHub Copilot
• Kiro
• OpenCode
• Antigravity
• Trae

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.

Quick Start

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:

• memorix serve if you just want Memorix available inside your IDE as fast as possible
• memorix background start if you want the dashboard and a shared HTTP control plane running in the background

Optional local UI:

memorix

Use bare memorix only when you want the interactive local workbench in a TTY. It is not the main setup path for most users.

Companion commands:

memorix background status
memorix background logs
memorix background stop

If you need the HTTP control plane in the foreground for debugging, manual supervision, or a custom port, use:

memorix serve-http --port 3211

If you are using the HTTP control plane across multiple workspaces or agents, make sure each session binds with memorix_session_start(projectRoot=...).

The deeper details around startup root selection, project binding, config precedence, and agent/operator workflows live in docs/SETUP.md and the Agent Operator Playbook.

Add Memorix to your MCP client:

Generic stdio MCP config

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

Generic HTTP MCP config

{
  "mcpServers": {
    "memorix": {
      "transport": "http",
      "url": "http://localhost:3211/mcp"
    }
  }
}

If you use the HTTP control plane across multiple workspaces or agents, the client or agent should also call memorix_session_start(projectRoot=ABSOLUTE_WORKSPACE_PATH) at the beginning of each project session.

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.

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

How It Works

flowchart LR
    subgraph Ingress["Ingress Surfaces"]
        A1["Git hooks / ingest"]
        A2["MCP tools"]
        A3["CLI / TUI"]
        A4["HTTP dashboard"]
    end

    subgraph Runtime["Memorix Runtime"]
        B1["stdio MCP server"]
        B2["HTTP control plane"]
        B3["project binding + config"]
    end

    subgraph Memory["Memory Substrates"]
        C1["Observation memory"]
        C2["Reasoning memory"]
        C3["Git memory"]
        C4["Session + team state"]
    end

    subgraph Processing["Async Processing"]
        D1["Formation pipeline"]
        D2["Embedding + indexing"]
        D3["Graph linking"]
        D4["Dedup + retention"]
    end

    subgraph Consumption["Consumption Surfaces"]
        E1["Search / detail / timeline"]
        E2["Dashboard / team views"]
        E3["Agent recall / handoff"]
    end

    A1 --> B1
    A2 --> B1
    A2 --> B2
    A3 --> B1
    A3 --> B2
    A4 --> B2

    B1 --> B3
    B2 --> B3

    B3 --> C1
    B3 --> C2
    B3 --> C3
    B3 --> C4

    C1 --> D1
    C1 --> D2
    C1 --> D3
    C1 --> D4
    C2 --> D1
    C2 --> D3
    C3 --> D2
    C4 --> D3

    D1 --> E1
    D2 --> E1
    D3 --> E2
    D4 --> E3
    C4 --> E3

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.

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

• Agent Operator Playbook
• AI Context Note
• 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 background start
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