MAG — Persistent memory for your AI tools

One memory store. Works across every tool on your machine.

MAG stores the context your AI tools lose when you close the session. It runs as a local binary, single SQLite file, no external services required. API embedding models are optional. Every tool that supports MCP reads from the same memory: Cursor, Claude Code, Windsurf, Cline, Claude Desktop. The retrieval pipeline is hybrid FTS5 + ONNX embeddings + graph traversal, built in Rust, benchmarked at 91.1% word-overlap on LoCoMo. AutoMem's published score is 90.5%.

Why MAG

• One binary, one file. No Python runtime, no external service required. All data stays local by default.
• Hybrid retrieval. FTS5, ONNX embeddings, graph traversal, and multi-phase advanced search in a single pipeline.
• Works across tools. Cursor, Claude Code, Windsurf, Cline, Claude Desktop — same memory, same file.
• Agent-oriented. Checkpoints, reminders, lessons, profile state, lifecycle tools, and MCP integration.
• Portable. Additive migrations, JSON export/import, no standing service dependency.

Compared With AutoMem / OpenMemory MCP

MAG and AutoMem solve the same class of problem: durable memory for local agents. The differences are in the operating model.

On the shared LoCoMo benchmark (word-overlap scoring), MAG scores 91.1% vs AutoMem's published 90.5%. See Benchmarks below.

Install

Shell (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/George-RD/mag/main/install.sh | sh

Homebrew

brew install George-RD/mag/mag

npm

npm install -g mag-memory

pip

pip install mag-memory

Cargo

cargo install mag-memory

From source

git clone https://github.com/George-RD/mag.git
cd mag
cargo build --release
# Binary: ./target/release/mag

GitHub Releases

Download prebuilt binaries for macOS (x64, ARM), Linux (x64, ARM), and Windows (x64) from Releases.

Configure Your MCP Client

MAG runs as an MCP server. Add it to your client's config to start using it.

Claude Desktop / Cursor / Windsurf

Add to your MCP config file:

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

If mag is not on your PATH, use the full path:

{
  "mcpServers": {
    "mag": {
      "command": "/Users/you/.mag/bin/mag",
      "args": ["serve"]
    }
  }
}

Claude Code

claude mcp add mag -- mag serve

npx (no install)

Use MAG without installing anything:

{
  "mcpServers": {
    "mag": {
      "command": "npx",
      "args": ["-y", "mag-memory", "serve"]
    }
  }
}

CLI

mag ingest "The retry logic should use exponential backoff with jitter"
mag search "retry logic"
mag semantic-search "how should retries work?"
mag advanced-search "deployment rollback process"
mag recent --limit 5
mag --help

Models download automatically on first use. Data is stored in ~/.mag/. Run mag paths to see active locations.

Benchmarks

Current benchmark snapshots were captured on 2026-03-19 at commit 26e51cf3 on macOS aarch64. Word-overlap is the primary LoCoMo metric (comparable to AutoMem's published 90.5%).

LoCoMo (word-overlap scoring, 2 samples, bge-small-en-v1.5)

788 memories, 304 questions across 2 samples. Avg query: 34 ms, avg embed: 7.5 ms, seed time: 9.7 s.

Embedding Model Comparison (LoCoMo word-overlap, 2 samples)

ONNX models use int8 quantization unless marked ¹ (no pre-built int8 available); the voyage-4-nano 1024-dim row uses mixed int8/fp32 quantization (int8 and fp32 runs averaged). API models are unquantized. Temporal Reasoning is 91.5% for every model and excluded. Scores across models within ~1 pp are within benchmark variance (304 questions, ~1.5% SE).

¹ FP32 (no pre-built int8 ONNX available).

bge-small-en-v1.5 is the default (Apache 2.0, Xenova int8). It uses 32 MB on disk and 180 MB peak RSS — a 35% reduction vs the previous FP32 default (277 MB) with identical quality. MiniLM-L6 int8 is the lightest option at 22 MB / 95 MB RSS with equivalent quality. bge-base int8 is the best local ONNX model at +0.7 pp for only 1.4× the latency. Switching embedding models requires re-embedding stored data — see issue #89. Multi-hop is stuck at 73–77% across all models — architectural issue tracked in issue #84.

Other Benchmarks (earlier snapshot, 2026-03-12)

Full methodology, commands, and result tables are in docs/benchmarks.md. Historical runs are tracked in docs/benchmark_log.csv.

Benchmark Safety

Benchmark runs do not touch the normal MAG production database. The official LongMemEval harness uses a fresh in-memory SQLite database per question, and the LoCoMo harness uses a fresh in-memory SQLite database per sample. The main persistent side effect is dataset/model caching under the active MAG root.

Compatibility

Windows support is untested. If you verify MAG on a tool or platform not listed here, open an issue to update the matrix.

Guarantee

MAG has no servers to shut down. Your memories live in a single SQLite file. Open it with any SQLite browser. Export everything with one command. The binary keeps working whether we maintain this project or not. MIT licensed, no tiers.

By default, the binary reads and writes a local SQLite file. API embedding models (optional) send query text to external services. See SECURITY.md for the full data flow audit.

Retrieval Model

MAG currently supports:

• text search over FTS5
• semantic search over ONNX embeddings
• similar-memory lookup from a stored memory ID
• graph traversal and version-chain lookup
• advanced retrieval that fuses vector and lexical candidates

The advanced path combines vector similarity and FTS hits with reciprocal-rank fusion, then refines ranking with event type, time decay, word overlap, importance, priority, and feedback signals. Queries are classified by intent (Keyword / Factual / Conceptual / General) to weight retrieval modes appropriately. Entity extraction runs at ingest time for auto-tagging and graph-edge creation.

Architecture

mag
├── src/
│   ├── main.rs
│   ├── cli.rs
│   ├── mcp_server.rs
│   ├── app_paths.rs
│   ├── benchmarking.rs
│   └── memory_core/
│       └── storage/sqlite/
│           └── entities.rs
├── benches/
│   ├── longmemeval/
│   ├── locomo/
│   ├── onnx_profile.rs
│   └── scale_bench.rs
└── tests/

Development

Local Quality Gate

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features

Benchmark Commands

The recommended way to run the standard LoCoMo benchmark:

./scripts/bench.sh

For individual benchmarks or the omega-memory comparison, clone omega-memory locally first. The comparison script accepts either --omega-repo or the OMEGA_REPO environment variable.

cargo run --release --bin fetch_benchmark_data -- --dataset all
cargo run --release --bin longmemeval_bench -- --json
cargo run --release --bin longmemeval_bench -- --official --questions 10 --json
cargo run --release --bin locomo_bench -- --json
cargo run --release --bin scale_bench -- --max-scale 10000 --search-queries 50
OMEGA_REPO=/path/to/omega-memory uv run --project "$OMEGA_REPO" python benches/python_comparison.py

License

MIT