open-memex

# open-memex

> Persistent memory for your AI coding agents — on your machine, in plain Markdown, shared by every tool you code with.

[![npm version](https://img.shields.io/npm/v/open-memex.svg)](https://www.npmjs.com/package/open-memex)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
[![open-memex MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/stoneskin/open-memex/badges/score.svg)](https://glama.ai/mcp/servers/stoneskin/open-memex)

[中文文档](./README.zh-CN.md)

Every AI coding session starts from zero: you re-explain the project, the agent
rediscovers the same gotchas, and yesterday's decisions vanish when the chat
ends. open-memex gives your agents a memory that survives the session. Say
"remember: we deploy on Fridays" once, and next week Copilot, Cursor, opencode,
or Claude Code already knows — because they all read and write the same local
memory on your machine.

- **Free and open source** (Apache-2.0). No account, no cloud, no telemetry —
  everything lives on your machine, in files you can open and edit.
- **Local-first**: memories are plain Markdown files (the source of truth) with
  a rebuildable SQLite keyword index. Nothing leaves your machine unless you
  explicitly share it.
- **One memory, every agent**: wire up several editors with one command; they
  share the same memory instead of keeping separate silos.

![Terminal demo: two memories saved on Monday, recalled by search in a fresh session on Friday](./docs/assets/open-memex-demo.svg)

New here? This README takes you from install to a working memory in about a
minute. The [concept guide](./docs/CONCEPTS.md) explains the mental model in
depth once you're up and running.

## Contents

- [Quick start](#quick-start)
- [Core concepts](#core-concepts)
- [Which editors, which features](#which-editors-which-features)
- [Installation](#installation)
- [Setting up your editor](#setting-up-your-editor)
- [What `init` changes on your machine](#what-init-changes-on-your-machine)
- [Capture: how memories get saved](#capture-how-memories-get-saved)
- [Tools the agent gets](#tools-the-agent-gets)
- [Memory types](#memory-types)
- [Team workflow: sharing memories through Git](#team-workflow-sharing-memories-through-git)
- [Retrieval: how memories come back](#retrieval-how-memories-come-back)
- [Security & data](#security--data)
- [Limitations](#limitations)
- [Upgrading](#upgrading)
- [Storage layout](#storage-layout)
- [Config](#config)
- [CLI reference](#cli-reference)
- [MCP server](#mcp-server)
- [Scopes, in detail](#scopes-in-detail)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)
- [Project status](#project-status)

## Quick start

You need **Node.js ≥ 22.14** (check with `node -v`). Then:

```sh
npm install -g open-memex
open-memex init
```

`init` detects the editors you have installed (VS Code, Cursor, opencode, and
Visual Studio when your project has a solution file) and connects each one to
open-memex. Restart your editor afterwards.

**See it work** (30 seconds):

```sh
open-memex add "This project deploys on Fridays"
```

Now open a new chat in your editor and ask your agent: *"When does this project
deploy?"* It already knows — no re-explaining. That round trip, capture once and
recall forever, is the whole product. Everything below is detail.

Optional but recommended — check everything is wired up:

```sh
open-memex doctor
```

## Core concepts

Three ideas explain almost everything open-memex does.

![open-memex architecture: your editors share one local memory — Markdown files as the source of truth, an SQLite FTS5 index for search, personal scope that never leaves the machine, and project scope shared through git PRs](docs/assets/open-memex-architecture-en.png)

**1. Two scopes: `project` and `personal`.**
Every memory belongs to one of two places:

- **project** — knowledge about one codebase (decisions, constraints, lessons).
  Scoped to the current repo automatically; you never set this up by hand.
- **personal** — knowledge about *you* (preferences, habits) that applies in
  every project. It lives only on this machine and can never be shared into a
  repo.

Facts about you ("I prefer concise diffs") go to `personal`; everything else
defaults to the current project.

**2. Capture → recall.**
Memories are saved as small Markdown files, one fact each. On the first turn of
every new session, open-memex hands your agent the most relevant ones
automatically, so it starts the session already knowing them. The agent can also
search the full memory on demand. You never have to "load" anything yourself.

**3. Your files, your rules.**
The Markdown files are the source of truth — open them, edit them, delete them,
grep them. The SQLite index next to them is just a search accelerator and
rebuilds from the files at any time (`open-memex reindex`). Team sharing, when
you want it, goes through the same review flow as code: nothing is shared
automatically (see [Team workflow](#team-workflow-sharing-memories-through-git)).

## Which editors, which features

open-memex talks to editors two ways: a native **opencode plugin**, and a
standard **MCP server** that any MCP-capable editor can use. (MCP — Model
Context Protocol — is the open standard editors use to give agents extra tools;
open-memex appears in your editor as a set of `memory_*` tools.) What you get
depends on which path an editor uses:

| Editor | Setup | Tools | Session-start recall | Keyword auto-capture |
|---|---|---|---|---|
| opencode (native plugin, recommended) | `open-memex init --client opencode --global` | 5 core tools | Built in — first turn of every session | Yes — `remember …`, `记住…` |
| VS Code (Copilot) | `open-memex init --client vscode` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
| Cursor | `open-memex init --client cursor` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
| Claude Code | `claude mcp add open-memex -- open-memex mcp` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
| Visual Studio 2022 17.14+ / 2026 | `open-memex init --client visualstudio` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
| Codex and other MCP clients | `open-memex mcp --print-config` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |

\* MCP has no hard session-start hook, so open-memex sends the agent guidance in
the MCP handshake (including how many drafts are waiting) and `init` writes the
fuller version into the editor's instruction files. In practice agents follow
it; the opencode plugin is the only path with true built-in first-turn
injection. The [Tools](#tools-the-agent-gets) section lists the 5 core tools
and the 6 extra workflow tools, so the "5 vs 11" split is explicit.

All editors on the same machine read and write the **same** memory — a
constraint captured in VS Code is respected in opencode; a lesson learned in
Cursor shows up in Claude Code. (Different machines do not sync automatically;
see the [FAQ](#faq).)

`init` also installs an **Agent Skill** (a short instruction file that teaches
skill-aware agents to use the CLI) for VS Code and Cursor, and for opencode in
per-project MCP mode. With the opencode native plugin wired, no skill is
installed there — the plugin already provides the memory tools, and a second
instruction set only made agents chatty.

## How it compares

| | open-memex | Instruction files (`CLAUDE.md`, `AGENTS.md`, …) | Cloud memory services | Chat history |
|---|---|---|---|---|
| Where it lives | Your machine + your repos | In the repo | Vendor servers | Gone when the chat ends |
| Who maintains it | Captured as you work; you review | You write and update by hand | The service | — |
| Works across AI tools | Yes — any MCP client (same machine) | One file per tool convention | Per-integration | No |
| Review before sharing | Yes — outbox + pull request | Yes — it's just files | Varies | No |
| Human-readable | Plain Markdown files | Yes | Dashboard / API | No |

Instruction files are great for a handful of standing rules — keep using them
(open-memex can even draft one from your memories; see `distill-agents` below).
open-memex covers the growing pile of decisions, lessons, and preferences that
no one remembers to write down.

## Installation

### Requirements

- **Node.js ≥ 22.14** (`open-memex doctor` verifies this for you). The floor is
  the SQLite driver's: `better-sqlite3` 13 is built against Node-API 10, which
  Node gained in 22.14.0 — older Node segfaults on the first database open.

### Install the CLI

```sh
npm install -g open-memex
```

That's the stable release. Installing the package may print a reminder to run
`open-memex init` — the editor wiring is a separate step (see
[Setting up your editor](#setting-up-your-editor)), so don't worry if you
don't see the reminder; just run `init` next.

Two alternatives:

- **No install — run via npx:** `npx -y open-memex <command>` runs any command
  without installing (e.g. `npx -y open-memex init --client vscode`). Slower to
  start, nothing to uninstall.
- **Alpha builds** (newest features, rougher edges, for testers):
  `npm install -g open-memex@alpha`. Check what's published with
  `npm view open-memex version` (stable) and `npm view open-memex@alpha version`
  (alpha).

If `open-memex` isn't found after installing, your PATH needs attention — see
[Troubleshooting](#troubleshooting).

### From source (for contributors)

```sh
git clone -b main https://github.com/stoneskin/open-memex.git
cd open-memex
npm install
node --experimental-strip-types src/cli.ts <command>
```

## Setting up your editor

Run `init` from your **project root** (the top folder of the repo you're working
in) so the project scope resolves to that repo:

```sh
open-memex init --yes
# …or without installing the package first:
npx -y open-memex init --yes
```

`--yes` accepts the recommended defaults for everything `init` asks