openmemory-mcp
OpenMemory is a self-hosted MCP memory server for storing and recalling project context across AI tools.
Save durable project memories such as facts, decisions, conventions, deployment notes, and gotchas, with optional tags and source tool.
Search memories by natural-language query, returning best matches first; uses semantic search if configured, otherwise keyword search.
View a project’s memory timeline in reverse chronological order, optionally filtered by date.
List all projects with memory counts and creation dates to discover project names.
Permanently delete a memory by ID when it is outdated or wrong.
Use it from any MCP client, with a bundled web UI for browsing and managing memories.
Optional integration with OpenAI's embedding API to enable semantic search over stored memories, matching notes by meaning rather than only shared words.
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 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
Related MCP server: persistent-memory
How it works
Cursor ─┐
VS Code ┼──► OpenMemory ──► Postgres + pgvector
others ─┘ (your server) (your data)You tell your AI tool something worth keeping: "Remember that payments go through Stripe."
The tool calls OpenMemory's
save_memoryand the note is stored.Days later, in any connected tool, you ask: "How do payments work here?" The tool calls
search_memoryand gets the note back.
Quick start
You need Docker. Then:
git clone https://github.com/bkrdmrcioglu/openmemory-mcp
cd openmemory-mcp
OPENMEMORY_TOKEN=pick-a-long-random-password docker compose up -dThat'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)
{
"mcpServers": {
"openmemory": {
"url": "http://localhost:3333/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}VS Code: create .vscode/mcp.json in your project
{
"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.
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.
{
"mcpServers": {
"openmemory": {
"command": "node",
"args": ["/path/to/openmemory-mcp/dist/index.js"],
"env": { "DATABASE_URL": "postgres://openmemory:openmemory@localhost:5432/openmemory" }
}
}
}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 |
| Store a fact, decision or note for a project |
| Find notes by meaning, not just exact words |
| List a project's notes newest first, optionally since a date |
| All projects with their note counts |
| 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 |
| — | Access token for the API, MCP endpoint and web UI. Required in |
|
| Set to |
| — | Optional. Enables high-quality semantic search (see below) |
| set by compose | Postgres connection string (pgvector required) |
|
|
|
|
| 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 extension:
npm install && npm run build
DATABASE_URL=postgres://user:pass@localhost:5432/openmemory TRANSPORT=http OPENMEMORY_TOKEN=... npm startIs 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.
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 explains how to run it locally and run the tests, and good first issues are a nice place to start. Questions and ideas go to Discussions.
License
Available Tools
5 toolsdelete_memoryDelete memoryADestructiveIdempotent
Permanently delete one memory by its id, for example when it is outdated, wrong or saved by mistake. This cannot be undone and removes the memory for every connected tool, so confirm with the user first unless they asked for it explicitly. Get the id from search_memory or memory_timeline. Returns whether the memory was deleted or not found.
Inputs: id (required).
list_projectsList projectsARead-only
List every project that has memories, with how many each holds and when it was created. Use it to discover the exact project name to pass to the other tools, or to see what this memory server knows about. Takes no arguments.
Inputs: no named parameters.
memory_timelineList memories by dateARead-only
List a project's memories in reverse chronological order, optionally only those saved since a given date. Use it to review what was recorded recently or to get an overview of a project, rather than to answer a specific question (use search_memory for that). Returns each memory with its date, the tool that saved it, its id and its text.
Inputs: project (required), limit, since.
save_memorySave memoryA
Store a fact, decision, convention or piece of context about a project so it can be recalled later, from this or any other connected AI tool. Use it when the user asks you to remember something, or when you learn something durable that future sessions will need (architecture choices, how to deploy, gotchas, naming rules). Write one self-contained statement per memory, with enough context to make sense on its own. Returns the new memory's id and timestamp.
Inputs: content (required), project (required), tags, source_tool.
search_memorySearch memoriesARead-only
Find the memories in a project that best match a natural-language question, best match first. Use it before answering questions about the project's conventions, decisions or setup, and before redoing work that may have been settled already. Returns each match with its id, match score, date and text, or a message saying nothing was found. Search is semantic when the server has an embedding key configured, and keyword-based otherwise.
Inputs: query (required), project (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: save, search, chronological listing, project discovery, and deletion. The search_memory vs memory_timeline overlap is explicitly addressed in descriptions, guiding correct selection.
Four tools follow a consistent verb_noun pattern (save_memory, search_memory, list_projects, delete_memory), but memory_timeline breaks the convention with a noun-first name. This is a minor deviation that remains readable.
Five tools is well-scoped for a memory server, covering the core lifecycle without bloat. Each tool earns its place and there are no redundant operations.
The surface covers create, search, list, and delete, which handles most memory workflows. However, there is no update/edit operation and no direct get-by-id, so agents must work around via delete-and-recreate or search.
Maintenance
Related MCP Connectors
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Shared cross-LLM long-term memory over MCP: semantic recall, sessions, and media (pgvector).
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceSelf-hosted semantic memory for AI agents. Save worklogs, decisions, and notes via MCP, then recall them across sessions by meaning rather than keyword. Backed by Postgres + pgvector with local embeddings (multilingual-e5-base).1MIT
- AlicenseNot gradedqualityCmaintenanceA self-hostable MCP server that provides permanent memory for AI agents using Postgres + pgvector for semantic search and Markdown file sync.MIT
- FlicenseNot gradedqualityDmaintenanceA self-hosted AI memory service that shares durable project context between MCP-compatible clients such as Claude Code and Devin, via a REST API and a Streamable HTTP MCP server with tools to remember, recall, list, and forget memories.-
- FlicenseNot gradedqualityCmaintenanceSelf-hosted AI memory system for coding assistants, providing project-scoped memory storage and retrieval via MCP tools (add, search, list, delete) to recall prior learnings without re-running discovery.1-