Claude Code (MCP)

claude mcp add mem-zero --transport http \
  "http://your-host:8765/mcp/your-project-slug/http/your-user-id" \
  -s local

CLI

pip install mem-zero
mem-zero-cli --url http://your-host:8765 --api-key your-key projects

The CLI provides direct terminal access to all memory operations:

# List projects
mem-zero-cli projects

# Add a memory
mem-zero-cli add my-project "Chose PostgreSQL over Redis for session storage"

# Pipe text from stdin
echo "User prefers dark mode" | mem-zero-cli add my-project -

# Search
mem-zero-cli search my-project "database decision"

# List memories
mem-zero-cli list my-project

# Export/import for backup and migration
mem-zero-cli export my-project -o backup.json
mem-zero-cli import backup.json --project new-project

# Health check
mem-zero-cli health

# Diagnostics
mem-zero-cli stats
mem-zero-cli stats --project my-project

All commands support --json for machine-readable output. Run mem-zero-cli --help for full usage.

REST API (any tool)

Anything that can make HTTP requests can use mem-zero directly:

# Store a memory
curl -X POST http://your-host:8765/api/v1/projects/my-project/memories \
  -H "Content-Type: application/json" \
  -d '{"text": "Switched from Redis to PostgreSQL for session storage because we need ACID transactions"}'

# Search memories
curl -X POST http://your-host:8765/api/v1/projects/my-project/search \
  -H "Content-Type: application/json" \
  -d '{"query": "database decision", "top_k": 5}'

The project slug must start with a letter or number, followed by lowercase alphanumeric characters, hyphens, or underscores (1-63 chars). Each unique slug creates an isolated collection.

mem-zero exposes a standard streamable-HTTP MCP endpoint with Bearer auth, so any MCP-capable agent connects without server-side changes. Everything below points at the same URL:

http://your-host:8765/mcp/your-project-slug/http/your-user-id

Export your key first so it stays out of the config files:

export MEM_ZERO_API_KEY="your-key"

OpenAI Codex CLI

~/.codex/config.toml (or .codex/config.toml for a single repo). A url key implies streamable HTTP — there is no transport field to set:

[mcp_servers.mem-zero]
url = "http://your-host:8765/mcp/your-project-slug/http/your-user-id"
bearer_token_env_var = "MEM_ZERO_API_KEY"

GitHub Copilot (VS Code, Visual Studio, JetBrains, Xcode)

.vscode/mcp.json — prompts once for the key, then stores it:

{
  "inputs": [
    { "type": "promptString", "id": "mem-zero-key", "description": "mem-zero API key", "password": true }
  ],
  "servers": {
    "mem-zero": {
      "type": "http",
      "url": "http://your-host:8765/mcp/your-project-slug/http/your-user-id",
      "headers": { "Authorization": "Bearer ${input:mem-zero-key}" }
    }
  }
}

opencode

opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mem-zero": {
      "type": "remote",
      "url": "http://your-host:8765/mcp/your-project-slug/http/your-user-id",
      "enabled": true,
      "headers": { "Authorization": "Bearer {env:MEM_ZERO_API_KEY}" }
    }
  }
}

Goose

~/.config/goose/config.yaml — headers support ${VAR} substitution:

extensions:
  mem-zero:
    enabled: true
    type: streamable_http
    name: mem-zero
    uri: http://your-host:8765/mcp/your-project-slug/http/your-user-id
    headers:
      Authorization: "Bearer ${MEM_ZERO_API_KEY}"
    timeout: 300

OpenClaude

Not to be confused with opencode above — OpenClaude is a Claude Code-compatible CLI that runs against any provider, including a local Ollama. Its config is Claude Code's, so --scope project writes the same .mcp.json:

openclaude mcp add --transport http mem-zero \
  "http://your-host:8765/mcp/your-project-slug/http/your-user-id" \
  --header "Authorization: Bearer ${MEM_ZERO_API_KEY}" \
  --scope project

This pairs well with mem-zero if you want the whole stack local: OpenClaude driving an Ollama model, with mem-zero's Ollama backend doing extraction and embeddings.

Qwen Code

settings.json — note it uses httpUrl (not url) for streamable HTTP:

{
  "mcpServers": {
    "mem-zero": {
      "httpUrl": "http://your-host:8765/mcp/your-project-slug/http/your-user-id",
      "headers": { "Authorization": "Bearer ${MEM_ZERO_API_KEY}" },
      "timeout": 300000
    }
  }
}

Grok Build (xAI)

grok mcp add --transport http mem-zero \
  "http://your-host:8765/mcp/your-project-slug/http/your-user-id" \
  --header "Authorization: Bearer ${MEM_ZERO_API_KEY}"

Or in ~/.grok/config.toml:

[mcp_servers.mem-zero]
transport = "http"
url = "http://your-host:8765/mcp/your-project-slug/http/your-user-id"
headers = { "Authorization" = "Bearer ${MEM_ZERO_API_KEY}" }

Editors with their own MCP support

Cursor, Windsurf, Cline, Zed, and JetBrains Junie each have an MCP settings panel — add the same URL and Authorization: Bearer header. This is also how you use mem-zero alongside a non-Anthropic model such as grok-code-fast-1: the editor handles MCP, the model just sees the tools.

Agents without MCP support (Aider, for example) can still use the REST API or the mem-zero-cli shown above.

## Project memory (mem-zero)

This project has a persistent memory server available over MCP.

**Search first.** At the start of every session, search memory for prior context
on whatever you're about to work on. Do this before reading code — it will tell
you about decisions and dead ends the code doesn't explain.

**Store at checkpoints**, not continuously: after completing a feature, fixing a
bug, or making a decision worth remembering.

Store:
- Decisions and the reasoning behind them, especially when alternatives were
  rejected ("chose X over Y because Z")
- Non-obvious workarounds and gotchas — things that would surprise a future reader
- Dead ends from debugging, so the next session doesn't repeat the investigation
- Conventions and preferences that aren't written down anywhere else

Do NOT store:
- Anything `git log`, `grep`, or the code itself already answers — function
  signatures, file structure, what a method does
- Per-file change lists, version bumps, or test results
- Fragments that can't stand alone ("Root cause", "Solution")

**Quality bar:** each memory is one complete, self-contained sentence that a
future session can understand with no other context. Name systems and tools
explicitly rather than saying "this" or "it". One memory per decision, not one
per file touched.

`delete_memories` and `delete_all_memories` are destructive — always ask before
calling them.

mem-zero supports three LLM backends for fact extraction and deduplication.

Auto-detection: If LLM_BACKEND is not set, the backend is chosen automatically:

• OPENAI_API_KEY present → openai
• OLLAMA_BASE_URL present → ollama
• Neither → bundled

Using with Ollama (recommended)

Ollama gives the best results. The bundled 3B model works for basic use, but a 7B+ model on GPU produces significantly better fact extraction. If you have a dedicated GPU, qwen2.5:14b is the sweet spot for quality vs. resource usage.

docker run -d \
  --name mem-zero \
  -p 8765:8765 \
  -v mem-zero-data:/mem-zero/storage \
  -e OLLAMA_BASE_URL=http://your-ollama-host:11434 \
  -e LLM_MODEL=qwen2.5:14b \
  ghcr.io/sworcery/mem-zero:latest

Fallback: When using Ollama, if the server is unreachable, requests automatically fall back to the bundled 3B model. The fallback is lazy — it only loads into memory on the first failure. Extraction quality is reduced but the service stays available.

Using the bundled backend

The bundled backend runs a quantized Qwen2.5-3B model on CPU with no external dependencies. It handles embeddings well and provides basic fact extraction. For better extraction quality, use Ollama or an OpenAI-compatible API.

Using with OpenAI-compatible APIs (beta)

docker run -d \
  --name mem-zero \
  -p 8765:8765 \
  -v mem-zero-data:/mem-zero/storage \
  -e OPENAI_API_KEY=sk-... \
  ghcr.io/sworcery/mem-zero:latest

Works with any OpenAI-compatible API (OpenAI, Groq, Together, etc.) by setting OPENAI_BASE_URL. This backend has not been extensively tested — if you encounter issues, please report them.

A management UI is served at the root URL (http://your-host:8765/). From the dashboard you can:

• Monitor system health, uptime, and live performance charts
• Browse all projects and their memory counts
• View, search, and delete memories per project
• Consolidate similar memory fragments
• Delete entire projects
• Add new memories manually

Enable DIAGNOSTICS_ENABLED=true to see performance metrics, accuracy stats, score distributions, and error tracking on the home page.

Optionally protect it with basic auth via DASHBOARD_USER and DASHBOARD_PASS.

If API_KEY is set but no dashboard credentials are, the dashboard prompts once for the API key when it first gets a 401 and keeps it in sessionStorage for that browser tab. It is never written to localStorage, the URL, or the page source.

Set API_KEY to protect all API and MCP endpoints. When set, requests must include the key as a Bearer token:

curl -H "Authorization: Bearer your-api-key" \
  http://your-host:8765/api/v1/projects

For MCP clients, add the header to your client config. In Claude Code's .mcp.json:

{
  "mem-zero": {
    "type": "http",
    "url": "http://your-host:8765/mcp/my-project/http/my-user",
    "headers": {
      "Authorization": "Bearer your-api-key"
    }
  }
}

A query parameter (?api_key=your-key) is also accepted for clients that can't set headers.

If API_KEY is not set, all endpoints are open — suitable for trusted networks.

The dashboard has its own basic auth (DASHBOARD_USER/DASHBOARD_PASS) since browsers need a login prompt rather than Bearer tokens.

If you set dashboard credentials without an API_KEY, those same Basic-auth credentials now also protect /api, /mcp, and /debug. Previously they were left open behind a password-protected dashboard. With both set, the dashboard accepts either: a logged-in browser session or a Bearer token.

Back up project memories to a JSON file, or migrate between servers:

# Export via CLI
mem-zero-cli export my-project -o backup.json

# Import to same or different server
mem-zero-cli import backup.json
mem-zero-cli import backup.json --project different-project

# Export via REST
curl http://your-host:8765/api/v1/projects/my-project/memories?limit=1000 > backup.json

The export format includes project metadata, timestamps, and all memory content. Importing re-processes text through the LLM pipeline (extraction and dedup), so imported memories are properly deduplicated against existing content.

mem-zero supplements conversations — it's not a transcript. Store things a future session would need that aren't obvious from reading the code or git history.

Search first. At the start of every conversation, search mem-zero for prior context. A well-maintained memory store means you never start from scratch.

Store decisions, not play-by-play. "Chose PostgreSQL over Redis because we need ACID transactions" is useful. "Updated line 42 in server.py" is not — that's what git log is for.

Store dead ends. If you spend 30 minutes debugging something that turned out to be a red herring, store that. It prevents future sessions from going down the same path.

Quality over quantity. Each memory should be a complete, self-contained statement. One memory per logical change or decision — not one per file touched. Fragments like "Root cause" or "Solution" without context are useless noise.

Let the code speak. Don't store function signatures, file structure, what a method does, or test results. The codebase is the authoritative source for those. Store the why, not the what.

For Claude Code, add instructions to your CLAUDE.md telling the assistant to use mem-zero proactively. Without explicit instructions, most assistants won't store memories on their own.

GET    /health                                  — health check
GET    /api/v1/projects                         — list all projects
GET    /api/v1/projects/{slug}/memories          — list memories (?limit=&offset=; X-Next-Offset header carries the cursor for the next page)
POST   /api/v1/projects/{slug}/memories          — add memory {"text": "..."}
POST   /api/v1/projects/{slug}/search            — search {"query": "...", "top_k": 10}
DELETE /api/v1/projects/{slug}/memories/{id}      — delete one
DELETE /api/v1/projects/{slug}/memories           — delete all memories
DELETE /api/v1/projects/{slug}                    — delete entire project
POST   /api/v1/projects/{slug}/reembed            — regenerate embeddings for all memories
POST   /api/v1/projects/{slug}/cleanup            — fix garbled text and split multi-fact entries
POST   /api/v1/projects/{slug}/consolidate        — merge similar fragments into clean summaries
GET    /api/v1/diagnostics                        — performance and accuracy metrics
GET    /api/v1/projects/{slug}/diagnostics        — per-project metrics
POST   /api/v1/diagnostics/reset                  — clear collected metrics
POST   /api/v1/diagnostics/export                 — full metrics snapshot as JSON
GET    /debug/config                              — active backend/config summary (never the API key)

The diagnostics endpoints and /debug/config return 404 unless DIAGNOSTICS_ENABLED=true.

All settings are via environment variables.

General

Upgrading and want the per-backend default? mem-zero persists your env vars to .env.saved on the storage volume so Unraid template edits can't silently blank them. That means an old explicit EMBEDDER_DIMENSIONS=768 is restored even after you clear the field. To go back to the default, also delete /mem-zero/storage/.env.saved (it is regenerated on next start).

Bundled backend

Ollama backend

OpenAI backend

Qdrant

The container bundles everything into a single image using s6-overlay for process supervision:

• Qdrant — embedded vector database, data persisted to /mem-zero/storage
• FastAPI — HTTP server handling MCP transport, REST API, and static dashboard
• Qwen2.5-3B — bundled LLM for fact extraction and dedup (CPU-only, ~1.8 GB RAM)
• fastembed — bundled embedding model (nomic-embed-text, ~270 MB)

External LLMs (Ollama, OpenAI) are supported as alternatives. When using Ollama, the bundled model serves as an automatic fallback if Ollama is unreachable.

Project isolation is enforced at the Qdrant collection level. Each project slug maps to {prefix}_{slug}, and all queries are scoped to a single collection.

Permissions

The Qdrant and mem-zero processes run as an unprivileged account (uid 99 / gid 100 by default — the Unraid convention), not root. On the first start after upgrading, the container chowns /mem-zero/storage to that id once (a sentinel file skips the walk on later boots; it can take a while on large volumes). Override with PUID / PGID, or set PUID=0 to run as root like older releases. Ports below 1024 can no longer be bound.