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

open-memory

open-memory

Why

Quick Start

Prerequisites

Install QMD

Set Up Your Memory

Index Your Files with QMD

Install & Run open-memory

Connecting AI Tools

GitHub Copilot CLI

Claude Code

Cursor

Codex CLI

VS Code (Copilot Chat)

Remote Access (SSE mode)

Tools

Configuration

QMD Setup Guide

Collections

Embeddings

Search Modes

Architecture

Docker

License

Latest Blog Posts

MCP directory API