memorix

Using Memorix through Cursor, Windsurf, Claude Code, Codex, or another AI coding agent? Read the Agent Operator Playbook for the agent-facing install, MCP, hook, and troubleshooting rules.

What Is Memorix?

Memorix is a local-first memory control plane for coding agents.

It keeps project memory, reasoning context, Git-derived facts, and optional autonomous-agent state in one place so you can continue work across IDEs, sessions, terminals, and agent runs without losing project truth.

For most users, the default path is simple: use the local TUI/CLI or connect one IDE over stdio MCP. Treat HTTP as the shared-control-plane mode you opt into when you specifically want one long-lived background service, shared MCP access, or a live dashboard endpoint.

Why Memorix

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

Supported Clients

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.

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 above. Move to HTTP only when you intentionally want one shared background service, multi-client MCP access, or a live dashboard endpoint.

Common paths:

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.

TUI Workbench

Running memorix without arguments opens an interactive fullscreen terminal UI (requires a TTY). Use it for chat with project memory, search, quick memory capture, diagnostics, background service control, dashboard launch, and IDE setup. Press /help inside the TUI for the current command list.

Single-shot chat (no TUI): memorix ask "your question".

Operator CLI

Memorix exposes a CLI-first operator surface. Use it when you want to inspect or control the current project directly from a terminal. MCP remains the integration layer for IDEs and agents.

memorix session start --agent codex-main --agentType codex
memorix memory search --query "docker control plane"
memorix reasoning search --query "why sqlite"
memorix retention status
memorix team status
memorix task list
memorix audit project
memorix sync workspace --action scan

The CLI is intentionally task-shaped, not a 1:1 mirror of MCP tool names. Native capabilities are available through these namespaces: session, memory, reasoning, retention, formation, audit, transfer, skills, team, task, message, lock, handoff, poll, sync, ingest. MCP stays available for IDEs, agents, and optional graph-compatibility tools.

Docker

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:

Generic stdio MCP config

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

Generic HTTP MCP config

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

Common Workflows

The most common loop is deliberately small:

memorix memory store --text "Auth tokens expire after 24h" --title "Auth token TTL" --entity auth --type decision
memorix memory search --query "auth token ttl"
memorix session start --agent codex-main --agentType codex

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

HTTP MCP sessions idle out after 30 minutes by default. If your client does not automatically recover from stale HTTP session IDs, set a longer timeout before starting the control plane:

MEMORIX_SESSION_TIMEOUT_MS=86400000 memorix background start  # 24h

Agent Team is not the normal memory startup path and it is not a chat room between IDE windows. Join only when you need tasks, messages, locks, or a structured autonomous-agent workflow. For real multi-agent execution, prefer:

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

Resource Profile

Memorix is designed to stay light during normal memory use:

• stdio MCP starts on demand and exits with the client

• HTTP background mode is one local Node process plus SQLite/Orama state

• LLM enrichment is optional; without API keys, Memorix falls back to local heuristic dedup/search

• the heavier paths are build/test, Docker image builds, dashboard browsing, large imports, and optional LLM-backed formation

On this Windows development machine, the healthy HTTP control plane was observed at about 16 MB working set after several hours idle. Treat that as a local observation, not a cross-platform guarantee. See Performance and Resource Notes for knobs and trade-offs.

Programmatic SDK

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:

How It Works

flowchart LR
    subgraph ING["Ingress"]
        A["Git Hooks<br/>commit + ingest"]
        B["MCP Tools<br/>search, store, recall"]
        C["CLI / TUI<br/>operator workflows"]
        D["Dashboard<br/>read-mostly project view"]
    end

    subgraph RUN["Runtime"]
        E["stdio MCP Server<br/>memorix serve"]
        F["HTTP Control Plane<br/>background / serve-http"]
        G["Project Binding<br/>git root + config"]
    end

    subgraph MEM["Memory"]
        H["Observation<br/>facts, gotchas, fixes"]
        I["Reasoning<br/>why, trade-offs, risks"]
        J["Git Memory<br/>commit-derived ground truth"]
        K["Session + Agent Team<br/>opt-in tasks, locks, handoffs"]
    end

    subgraph PROC["Processing"]
        L["Formation<br/>quality shaping"]
        M["Embedding + Index<br/>hybrid retrieval"]
        N["Graph Linking<br/>entity relations"]
        O["Dedup + Retention<br/>consolidate over time"]
    end

    subgraph USE["Consumption"]
        P["Search / Timeline / Detail"]
        Q["Dashboard / Agent Team View<br/>read-mostly state"]
        R["Recall / Handoff / Resume"]
        S["Skills / Sync / Orchestrate"]
    end

    A --> E
    B --> E
    C --> E
    D --> F

    E --> G
    F --> G

    G --> H
    G --> I
    G --> J
    G --> K

    H --> L
    H --> M
    I --> L
    I --> N
    J --> M
    J --> N
    K --> O

    H --> P
    I --> P
    J --> P
    K --> Q
    H --> R
    I --> R
    J --> R
    K --> S

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 retrieval, dashboard, and explicit Agent Team 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

📖 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

What's New in 1.0.8

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

• CLI-First Product Surface: Every Memorix-native operator capability now has a task-oriented CLI route — session, memory, reasoning, retention, formation, audit, transfer, skills, team, task, message, lock, handoff, poll, sync, ingest. MCP remains the integration protocol and optional graph-compatibility layer.

• 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 runs plan, parallel execution, verification, fix, review, and merge loops across Claude, Codex, Gemini CLI, and 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.

• Opt-in Agent Team: task board, messages, file locks, handoff artifacts, and autonomous-agent heartbeat state. session_start is lightweight by default; team identity is opt-in via joinTeam or team_manage join.

• 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' to store, search, get, and resolve observations directly from your own code without MCP or CLI. Also exports createMemorixServer and detectProject.

• Test Suite Stabilization: E2e and live-LLM tests are excluded from the default suite, and load-sensitive tests are isolated so the default verification path stays deterministic.

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