<p align="center">
  <img src="docs/icon.png" width="96" height="96" alt="OpenMemory icon">
</p>

<h1 align="center">OpenMemory</h1>

<p align="center">
  <strong>One shared memory for all your AI coding tools.</strong><br>
  Self-hosted, open source, works with any MCP client.
</p>

<p align="center">
  <a href="https://github.com/bkrdmrcioglu/openmemory-mcp/releases/latest"><img src="https://img.shields.io/github/v/release/bkrdmrcioglu/openmemory-mcp?color=5b4ff0" alt="Latest release"></a>
  <a href="https://github.com/bkrdmrcioglu/openmemory-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/bkrdmrcioglu/openmemory-mcp/ci.yml?branch=main&label=tests" alt="Tests"></a>
  <img src="https://img.shields.io/badge/MCP-server-7c3aed" alt="MCP server">
  <img src="https://img.shields.io/badge/self--hosted-Docker-0ea5e9" alt="Self-hosted with Docker">
  <a href="LICENSE"><img src="https://img.shields.io/github/license/bkrdmrcioglu/openmemory-mcp?color=64748b" alt="MIT license"></a>
</p>

<p align="center">
  <a href="#quick-start"><b>Quick start</b></a> ·
  <a href="#connect-your-ai-tool">Connect a tool</a> ·
  <a href="#how-it-works">How it works</a> ·
  <a href="#tools">Tools</a> ·
  <a href="#faq">FAQ</a>
</p>

<p align="center">
  <img src="docs/demo.gif" width="860" alt="Signing in to the OpenMemory web UI, browsing projects, searching memories by meaning and opening the Connect a tool dialog">
</p>

Every AI assistant forgets everything the moment you switch tools. Explain your project to one, open another, and you start from zero. OpenMemory is a small server you run yourself: your AI tools write what they learn into it and read it back later, whichever tool you are using.

- **Works with any MCP tool.** Cursor, VS Code, Windsurf and every other client that speaks the [Model Context Protocol](https://modelcontextprotocol.io) can save and recall memories.
- **Your data stays yours.** Everything lives in a Postgres database on your own machine or server.
- **Semantic search.** Ask in your own words and get the right note back.
- **Web UI included.** Browse, search, add and delete memories in the browser, in light or dark mode, on desktop or phone.
- **One command to run.** Docker Compose brings up the server and the database together.

## Screenshots

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/screenshot-dark.png">
  <img src="docs/screenshot.png" width="860" alt="The OpenMemory web UI: projects on the left, a project's memories grouped by date on the right">
</picture>

## How it works

```
 Cursor ─┐
 VS Code ┼──►  OpenMemory  ──►  Postgres + pgvector
 others ─┘    (your server)      (your data)
```

1. You tell your AI tool something worth keeping: *"Remember that payments go through Stripe."*
2. The tool calls OpenMemory's `save_memory` and the note is stored.
3. Days later, in any connected tool, you ask: *"How do payments work here?"* The tool calls `search_memory` and gets the note back.

## Quick start

You need [Docker](https://docs.docker.com/get-docker/). Then:

```bash
git clone https://github.com/bkrdmrcioglu/openmemory-mcp
cd openmemory-mcp
OPENMEMORY_TOKEN=pick-a-long-random-password docker compose up -d
```

That's it. Open **http://localhost:3333** and sign in with the token you picked.

> Generate a strong token with `openssl rand -hex 24`. Anyone with the token can read and write your memories.

## Connect your AI tool

In the web UI, click **Connect a tool** to get ready-to-paste config with your server's address filled in. Or copy it from here, replacing `YOUR_TOKEN`:

**Cursor:** Settings → MCP → *Add new MCP server* (edits `~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "openmemory": {
      "url": "http://localhost:3333/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

**VS Code:** create `.vscode/mcp.json` in your project

```json
{
  "servers": {
    "openmemory": {
      "type": "http",
      "url": "http://localhost:3333/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

**Any other MCP client:** endpoint `http://localhost:3333/mcp` (Streamable HTTP), header `Authorization: Bearer YOUR_TOKEN`.

<details>
<summary><b>Run it as a local stdio server instead</b></summary>

If you prefer your editor to start the server itself, build it once (`npm install && npm run build`) and point the client at it. It still needs a Postgres database with pgvector.

```json
{
  "mcpServers": {
    "openmemory": {
      "command": "node",
      "args": ["/path/to/openmemory-mcp/dist/index.js"],
      "env": { "DATABASE_URL": "postgres://openmemory:openmemory@localhost:5432/openmemory" }
    }
  }
}
```

</details>

Then just talk to your assistant:

- *"Remember that we deploy with Docker Compose on a single VPS."*
- *"What did we decide about the database?"*
- *"Show me everything we saved this week for this project."*

## Tools

| Tool | What it does |
|---|---|
| `save_memory` | Store a fact, decision or note for a project |
| `search_memory` | Find notes by meaning, not just exact words |
| `memory_timeline` | List a project's notes newest first, optionally since a date |
| `list_projects` | All projects with their note counts |
| `delete_memory` | Remove an outdated or wrong note |

## Running on a server

Run the same `docker compose up -d` on any VPS and put it behind your reverse proxy (Caddy, Nginx, Traefik, Coolify, …) with HTTPS. Point your tools at `https://your-domain/mcp`. One server can be shared by your whole team, so everyone's tools see the same project memory.

## Configuration

| Variable | Default | Description |
|---|---|---|
| `OPENMEMORY_TOKEN` | — | Access token for the API, MCP endpoint and web UI. Required in `http` mode |
| `OPENMEMORY_ALLOW_NO_AUTH` | `false` | Set to `true` to run `http` mode without a token (trusted networks only) |
| `OPENAI_API_KEY` | — | Optional. Enables high-quality semantic search (see below) |
| `DATABASE_URL` | set by compose | Postgres connection string (pgvector required) |
| `TRANSPORT` | `http` in compose | `http` for a network server, `stdio` for a local process |
| `PORT` | `3333` | HTTP port |

## FAQ

**Do I need an OpenAI (or any AI) API key?**
No. Without one, search matches on shared words, which is good enough to try it out. Add `OPENAI_API_KEY` and search understands meaning: *"backup"* finds a note about *"database snapshots"*. Your AI tools use their own accounts as usual; OpenMemory never calls a chat model.

**Where is my data?**
In the `openmemory_db` Docker volume on the machine running the server. Nothing is sent anywhere, except note text to the embedding API if you set `OPENAI_API_KEY`.

**Can I run it without Docker?**
Yes, with Node.js 20+ and Postgres with the [pgvector](https://github.com/pgvector/pgvector) extension:

```bash
npm install && npm run build
DATABASE_URL=postgres://user:pass@localhost:5432/openmemory TRANSPORT=http OPENMEMORY_TOKEN=... npm start
```

**Is it safe to expose to the internet?**
In `http` mode it refuses to start without a token, and the bundled compose file keeps the database private. Put it behind HTTPS. See [SECURITY.md](SECURITY.md).

## Roadmap

- Local embedding models (Ollama) for fully offline semantic search
- Automatic deduplication and summarisation of old memories
- Multiple tokens with per-project access
- Import and export

## Contributing

Bug reports, ideas and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) explains how to run it locally and run the tests, and [good first issues](https://github.com/bkrdmrcioglu/openmemory-mcp/labels/good%20first%20issue) are a nice place to start. Questions and ideas go to [Discussions](https://github.com/bkrdmrcioglu/openmemory-mcp/discussions).

## License

[MIT](LICENSE)