llms-full.txt

# Memorix - Full Documentation for AI Systems

> Open-source cross-agent memory layer for coding agents via MCP

## Overview

Memorix is an open-source MCP server written in TypeScript that provides persistent, project-aware memory for coding agents. It is designed for coding workflows, not generic chat memory, and works across Cursor, Claude Code, Codex, Windsurf, Gemini CLI, GitHub Copilot, Kiro, OpenCode, Antigravity, and Trae through MCP.

If you are an AI coding agent helping a user install or operate Memorix, read [docs/AGENT_OPERATOR_PLAYBOOK.md](https://github.com/AVIDS2/memorix/blob/main/docs/AGENT_OPERATOR_PLAYBOOK.md) before taking action. It is the canonical operator guide for runtime mode selection, Git/project binding, integrations, hooks, and troubleshooting.

Memorix solves four recurring problems in AI-assisted development:

1. **Session amnesia** - the next chat forgets what the previous one learned
2. **IDE isolation** - memory created in one coding IDE is invisible to another
3. **Engineering truth loss** - commits record what changed, but not in a form agents can easily recall
4. **Config and workflow fragmentation** - MCP config, agent rules, and IDE integrations drift apart over time

## Product Model

Memorix is best understood as four layers:

1. **Runtime layer**
   - MCP server over stdio or HTTP
   - Project detection
   - Config loading and project switching

2. **Memory core**
   - Observations
   - Sessions
   - Search index
   - Retention
   - Export/import
   - Knowledge graph relations

3. **Quality layer**
   - Formation pipeline
   - Source-aware retrieval
   - Compaction
   - Optional LLM quality improvements
   - Optional local vector search

4. **Platform layer**
   - Git Memory
   - Hooks and auto-capture
   - Rules sync
   - Workspace sync
   - Team collaboration
   - Dashboard

## Memory Layers

### 1. Observation Memory

Observation memory stores reusable project knowledge such as:

- architecture decisions
- gotchas
- bug fixes
- implementation notes
- discoveries
- trade-offs
- what changed

Examples:

- `decision` - chose queue-based ingestion over direct writes
- `problem-solution` - fixed dashboard width jump by stabilizing scrollbar gutter
- `gotcha` - npm publish fails from Windows device-style cwd paths
- `what-changed` - reworked project detection to use git identity consistently

### 2. Reasoning Memory

Reasoning memory stores the **why** behind decisions:

- alternatives considered
- rationale
- constraints
- expected outcomes
- risks

This is the layer that helps future agents understand why a system was designed a certain way instead of only seeing the final code change.

### 3. Git Memory

Git Memory turns commits into structured memory with provenance:

- `source='git'`
- commit hash
- files changed
- inferred type
- entity extraction
- noise filtering

Memorix can:

- install a `post-commit` hook
- ingest a single commit
- ingest a commit range or recent history
- skip low-value commit noise
- preserve release and milestone commits

This is one of Memorix's main differentiators for coding agents.

## Retrieval Model

Memorix retrieval is intentionally layered:

- **Search** - compact project-scoped or global retrieval
- **Timeline** - chronological context around an event
- **Detail** - full observation detail
- **Dashboard** - visual and operational view

Important retrieval behavior:

- default search is **current-project scoped**
- `scope="global"` searches across projects
- global results can be opened explicitly with project-aware refs
- source-aware retrieval boosts:
  - Git memory for "what changed" style queries
  - reasoning/decision memory for "why" style queries
  - both for debugging/problem-solving style queries

## Configuration Model

Memorix now uses a simple outward-facing model:

- `memorix.yml` for behavior and project settings
- `.env` for secrets

Internally it still supports layered config and compatibility fallbacks, but the intended user-facing mental model is:

- **behavior in YAML**
- **secrets in `.env`**

This is more structured than flat env-only config and is intended to keep the system explainable.

## Runtime Modes

### Stdio MCP

```bash
memorix serve
```

Use this for normal MCP clients that expect stdio transport.

This is the best fit for quick, single-project usage where the client already launches Memorix from the correct workspace root.

Generic stdio MCP config:

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

### HTTP MCP + Dashboard

```bash
memorix background start
```

Use this when you want:

- HTTP MCP transport
- collaboration tools
- the dashboard on the same port
- a long-lived control plane that keeps running in the background

Use `memorix serve-http --port 3211` when you want the same HTTP control plane in the foreground for debugging, manual supervision, or a custom port.

Important:

- 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.
- `projectRoot` is a detection anchor only; Git remains the source of truth for the final project identity.
- If the client cannot supply a reliable workspace path, HTTP mode should fail closed instead of silently inventing an `untracked/*` project.

Typical endpoints:

- MCP endpoint: `http://localhost:3211/mcp`
- Dashboard: `http://localhost:3211`

Generic HTTP MCP config:

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

## Supported Environments

Memorix is designed for multi-agent and multi-IDE coding workflows. It supports integrations and workflows around:

- Cursor
- Windsurf
- Claude Code
- Codex
- Copilot / VS Code MCP setups
- Kiro
- Antigravity
- OpenCode
- Trae
- Gemini CLI

The exact integration surface differs by IDE, but the shared memory model remains the same.

## Key Capabilities

### Persistent Cross-Session Memory

Agents can search prior work at session start and continue from real project context instead of asking the user to re-explain.

### Cross-Agent Recall

Different coding agents can read from the same local memory base, making handoff and tool switching much smoother.

### Git-Memory Pipeline

Memorix can capture engineering truth from Git and make it searchable as memory instead of raw commit text.

### Reasoning Preservation

Memorix can store design rationale and trade-offs directly, which is critical for avoiding contradictory future suggestions.

### Dashboard / Control Plane

The dashboard exposes:

- memory source distribution
- Git Memory views
- config provenance
- project identity health
- retention and session summaries
- graph visualization

### Team Collaboration

When running with HTTP transport, Memorix also supports:

- agent registry
- advisory file locks
- task board
- agent-to-agent messages

## Tool Surface

Memorix exposes MCP tools across several groups:

### Core Memory

- `memorix_store`
- `memorix_search`
- `memorix_detail`
- `memorix_timeline`
- `memorix_resolve`
- `memorix_retention`
- `memorix_transfer`

### Session and Reasoning

- `memorix_session_start`
- `memorix_session_end`
- `memorix_session_context`
- `memorix_store_reasoning`
- `memorix_search_reasoning`

### Quality and Maintenance

- `memorix_consolidate`
- `memorix_deduplicate`
- `memorix_formation_metrics`
- `memorix_promote`
- `memorix_skills`

### Platform and Integrations

- `memorix_rules_sync`
- `memorix_workspace_sync`
- `memorix_dashboard`

### Team Tools

- `team_manage`
- `team_file_lock`
- `team_task`
- `team_message`

The exact set may evolve, so AI systems should not hard-code stale tool counts.

## Optional Enhancements

### LLM Quality Mode

If configured with an API key, Memorix can use LLMs for:

- narrative compression
- semantic deduplication
- higher-quality ranking and enrichment

### Local Vector Search

Memorix works out of the box with BM25/full-text search. It can also use optional local vector providers for better semantic retrieval without requiring cloud embeddings.

## Recommended AI Usage Pattern

At session start:

1. load session context with `memorix_session_start`
2. in HTTP control-plane mode, pass `projectRoot` = the absolute current workspace or repo-root path when available
3. if session start cannot resolve the project, retry with the correct path before using project-scoped tools
4. search relevant recent memory
5. fetch detail only when needed

During work:

1. store meaningful decisions, fixes, gotchas, and milestones
2. resolve memories when tasks are completed
3. prefer reasoning-rich summaries over raw logs

At session end:

1. store a concise session summary
2. include what changed, why, current state, and next steps

## When Memorix Is Strongest

Memorix is strongest when the task is:

- codebase-specific
- project-memory heavy
- multi-session
- multi-agent
- Git-aware
- explanation-sensitive

It is especially strong for:

- "what changed recently?"
- "why did we choose this?"
- "what broke here before?"
- "which commit relates to this behavior?"
- "what should the next agent know before continuing?"

## Core Links

- GitHub: https://github.com/AVIDS2/memorix
- npm: https://www.npmjs.com/package/memorix
- README: https://github.com/AVIDS2/memorix/blob/main/README.md
- Setup Guide: https://github.com/AVIDS2/memorix/blob/main/docs/SETUP.md
- Configuration Guide: https://github.com/AVIDS2/memorix/blob/main/docs/CONFIGURATION.md
- Git Memory Guide: https://github.com/AVIDS2/memorix/blob/main/docs/GIT_MEMORY.md
- Architecture: https://github.com/AVIDS2/memorix/blob/main/docs/ARCHITECTURE.md
- API Reference: https://github.com/AVIDS2/memorix/blob/main/docs/API_REFERENCE.md
- Changelog: https://github.com/AVIDS2/memorix/blob/main/CHANGELOG.md