open-memory

One brain, every AI. An MCP server that gives any AI tool (Copilot, Claude, Codex, Cursor, ChatGPT) access to your personal knowledge base through a single open protocol.

Your memory lives as plain markdown files. QMD indexes and searches them (BM25 + vector embeddings). open-memory wraps it all in an MCP server that any client can connect to. No database. No SaaS. Files are the source of truth.

graph LR
    Copilot -->|MCP| OM[open-memory<br/>stdio or SSE]
    Claude_Code[Claude Code] -->|MCP| OM
    Cursor -->|MCP| OM
    Codex -->|MCP| OM
    ChatGPT -->|MCP| OM
    OM -->|QMD| FS[memory/*.md<br/>MEMORY.md<br/>notes/*.md]

    style OM fill:#2d333b,stroke:#539bf5,color:#adbac7
    style FS fill:#2d333b,stroke:#57ab5a,color:#adbac7

Transport: local (stdio) or remote (SSE over Tailscale/tunnel)

Why

Every AI tool has its own memory silo. Copilot doesn't know what you told Claude. Cursor doesn't remember what Codex learned. You re-explain context every time you switch tools.

open-memory fixes this: one directory of markdown files, one search index, one MCP server. Any tool that speaks MCP gets your full context.

Cost: $0. Self-hosted, no external services.

Quick Start

Prerequisites

• Node.js 20+
• QMD (the search/indexing engine)

Install QMD

# Using bun (fastest)
bun install -g qmd

# Or npm
npm install -g qmd

Set Up Your Memory

If you're starting fresh:

mkdir -p ~/memory/memory
echo "# My Knowledge Base" > ~/memory/MEMORY.md
echo "# $(date +%Y-%m-%d)" > ~/memory/memory/$(date +%Y-%m-%d).md

If you already use OpenClaw, your memory is at ~/.openclaw/ (MEMORY.md + memory/*.md). Point open-memory there.

Index Your Files with QMD

# Create a collection pointing to your memory directory
qmd collection add ~/memory --name my-memory --mask "**/*.md"

# Generate vector embeddings (needed for semantic search)
# Requires OPENAI_API_KEY or a local embedding model
qmd embed

QMD supports multiple embedding providers. See QMD docs for configuration.

Install & Run open-memory

# Clone
git clone https://github.com/DanWahlin/open-memory.git
cd open-memory

# Install & build
npm install
npm run build

# Configure (optional)
cp .env.example .env
# Edit .env to set QMD_BIN path, MEMORY_DIR, auth token, etc.

# Run (HTTP/SSE mode for remote clients)
npm start

# Or run in stdio mode (for local clients)
npm run start:stdio

Connecting AI Tools

GitHub Copilot CLI

The fastest way to connect. Run copilot in your terminal, then:

/mcp add

Fill in the interactive form:

Field	Value
Server Name	open-memory
Server Type	STDIO (press the corresponding number)
Command	node /path/to/open-memory/dist/stdio.js
Environment Variables	{"QMD_BIN": "/path/to/qmd", "MEMORY_DIR": "/path/to/your/memory"}
Tools	*

Press Ctrl+S to save. The server is available immediately, no restart needed.

You can also edit the config file directly at ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "open-memory": {
      "type": "local",
      "command": "node",
      "args": ["/path/to/open-memory/dist/stdio.js"],
      "env": {
        "QMD_BIN": "/path/to/qmd",
        "MEMORY_DIR": "/path/to/your/memory"
      },
      "tools": ["*"]
    }
  }
}

Manage your server with /mcp show, /mcp edit open-memory, or /mcp delete open-memory.

For remote access (SSE), use type "http" or "sse" with your server URL instead.

Claude Code

claude mcp add open-memory -- node /path/to/open-memory/dist/stdio.js

Or add to your MCP config:

{
  "mcpServers": {
    "open-memory": {
      "command": "node",
      "args": ["/path/to/open-memory/dist/stdio.js"],
      "env": {
        "QMD_BIN": "/path/to/qmd",
        "MEMORY_DIR": "/path/to/your/memory"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (Settings > MCP Servers):

{
  "mcpServers": {
    "open-memory": {
      "command": "node",
      "args": ["/path/to/open-memory/dist/stdio.js"],
      "env": {
        "QMD_BIN": "/path/to/qmd",
        "MEMORY_DIR": "/path/to/your/memory"
      }
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.open-memory]
command = 'node'
args = ['/path/to/open-memory/dist/stdio.js']

[mcp_servers.open-memory.env]
QMD_BIN = '/path/to/qmd'
MEMORY_DIR = '/path/to/your/memory'

VS Code (Copilot Chat)

Add to .vscode/mcp.json in your workspace (or ~/.vscode/mcp.json globally):

{
  "servers": {
    "open-memory": {
      "command": "node",
      "args": ["/path/to/open-memory/dist/stdio.js"],
      "env": {
        "QMD_BIN": "/path/to/qmd",
        "MEMORY_DIR": "/path/to/your/memory"
      }
    }
  }
}

Remote Access (SSE mode)

Run the HTTP server on a machine with your memory files:

OPEN_MEMORY_TOKEN=your-secret-token npm start

Connect from any MCP client that supports SSE or HTTP transport:

URL: http://<your-server>:3838/sse
Auth: Bearer your-secret-token

For GitHub Copilot CLI remote access, use /mcp add with type HTTP or SSE and paste the URL.

Over Tailscale, use your Tailscale IP. Over the internet, put it behind a reverse proxy with HTTPS.

Tools

open-memory exposes 7 MCP tools:

Tool	Description
search_memory	Semantic, keyword, or hybrid search across your knowledge base
read_memory	Read a specific memory file by path
write_memory	Append to today's daily note (or a specific file)
list_memories	List memory files in a directory
browse_recent	Preview recent daily notes
get_document	Get any indexed document by path or QMD docid
memory_status	Show index health, collections, and document counts

Configuration

All configuration via environment variables (or .env file):

Variable	Default	Description
QMD_BIN	qmd	Path to QMD binary
MEMORY_DIR	~/.openclaw	Root directory for memory files
DAILY_NOTES_DIR	memory	Subdirectory for daily notes (within MEMORY_DIR)
MAIN_MEMORY_FILE	MEMORY.md	Main memory file name
QMD_COLLECTION	(empty)	QMD collection to search (empty = all)
PORT	3838	HTTP server port (SSE mode)
OPEN_MEMORY_TOKEN	(empty)	Bearer token for auth (empty = no auth)

QMD Setup Guide

QMD is the search engine behind open-memory. It indexes markdown files and provides BM25 (keyword), vector (semantic), and hybrid search.

Collections

QMD organizes files into collections. Create one for your memory:

# Index a directory of markdown files
qmd collection add ~/my-notes --name notes --mask "**/*.md"

# List your collections
qmd collection list

# Re-index after adding files
qmd update

Embeddings

For semantic search, QMD needs vector embeddings:

# Set your API key (OpenAI, or compatible provider)
export OPENAI_API_KEY=sk-...

# Generate embeddings
qmd embed

# Check status
qmd status

Search Modes

# Keyword search (fast, exact matching)
qmd search "project decisions"

# Semantic search (finds conceptually related content)
qmd vsearch "what did we decide about the architecture"

# Hybrid (best quality, combines both + reranking via local LLM)
qmd query "why did we choose Postgres over MongoDB"

Architecture

graph TB
    Client[MCP Client<br/>Copilot · Claude · Cursor · Codex]
    Client -->|MCP Protocol<br/>stdio or SSE| Server

    subgraph Server[open-memory server]
        search_memory -->|vsearch / search / query| QMD
        read_memory --> FS_read[fs.readFileSync]
        write_memory --> FS_append[fs.appendFileSync]
        get_document -->|get| QMD
        list_memories --> FS_readdir[fs.readdirSync]
        browse_recent --> FS_readdir
        memory_status -->|status| QMD
    end

    Server --> FileSystem

    subgraph FileSystem[File System]
        MEMORY[MEMORY.md<br/>curated long-term knowledge]
        Daily[memory/YYYY-MM-DD.md<br/>daily notes]
        Other[*.md<br/>any indexed markdown]
    end

    style Client fill:#2d333b,stroke:#539bf5,color:#adbac7
    style Server fill:#1c2128,stroke:#539bf5,color:#adbac7
    style FileSystem fill:#1c2128,stroke:#57ab5a,color:#adbac7

Key design decisions:

• Files are the source of truth, not a database
• QMD handles all indexing and search (BM25 + vector)
• Zero external services required
• Two transport modes: stdio (local) and SSE (remote)
• Auth via bearer token for remote access

Docker

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY dist/ dist/
RUN npm install -g qmd
ENV QMD_BIN=qmd
EXPOSE 3838
CMD ["node", "dist/server.js"]

Mount your memory directory:

docker run -v ~/memory:/memory -e MEMORY_DIR=/memory -p 3838:3838 open-memory

License

MIT