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.
Related MCP server: persistent-memory
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_memory and the note is stored.
Days later, in any connected tool, you ask: "How do payments work here?" The tool calls search_memory and gets the note back.
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.
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."
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 |
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.
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 |
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.
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
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The memory's numeric id, as shown after '#' in search_memory or memory_timeline results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds the blast radius (removes the memory for every connected tool), the irreversibility, the required user confirmation, and the response outcome (deleted vs not found). That is meaningful context an agent cannot infer from structured fields alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the action and consequences, then confirmation policy, then id provenance, then return value. No sentence is filler, though the id-source sentence overlaps the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive tool with no output schema, the description covers action, irreversibility, cross-tool impact, confirmation gate, input source, and return semantics. Nothing an agent needs in order to invoke it safely is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema's own id description already explains the numeric id and the '#' notation from search_memory/memory_timeline results, so the description's pointer to those sources largely duplicates it. Baseline 3 applies since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (permanently delete), resource (one memory), and selector (by its id), which cleanly separates it from siblings like save_memory and search_memory. The scope limitation to a single memory is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete trigger conditions (outdated, wrong, saved by mistake), an explicit confirmation requirement with its exception, and routes the agent to search_memory or memory_timeline to obtain the id. When-to-use, when-to-confirm, and where-to-get-input are all covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the shape of the result (per-project memory counts and creation timestamps), but says nothing about ordering, pagination, or behavior when no projects exist. With annotations doing the heavy lifting, this is an adequate but not rich disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with what is returned and followed by the routing guidance. Nothing is redundant — even "takes no arguments" is cheap and prevents a schema lookup.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A zero-param list tool with no output schema; the description compensates by naming the return fields (project name, memory count, creation date). Nothing else is needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so the baseline is 4; the description correctly confirms "Takes no arguments," consistent with the empty schema. There is no additional parameter nuance to convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List every project that has memories") and adds what the result carries (memory count, creation time). This clearly separates it from save_memory/search_memory/memory_timeline, which operate on memories rather than enumerating projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly frames the use case: discover the exact project name to pass to other tools, or see what the server knows. Alternatives are referenced generically ("the other tools") but there is no explicit statement of when not to use it — for a no-arg discovery tool that omission is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of memories, 1–200. Defaults to 50. | |
| since | No | Only include memories saved on or after this ISO 8601 date or timestamp, e.g. '2026-09-01'. Omit for all time. | |
| project | Yes | Project the memory belongs to. Use one stable name per codebase, such as the repository name (e.g. 'acme-shop'), so every tool and teammate files memories in the same place. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds valuable context by naming the exact return fields (date, saving tool, id, text), which matters since there is no output schema. It does not discuss pagination/ordering beyond the limit parameter or behavior on empty results, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: purpose and ordering first, routing guidance second, return shape third. No filler and no redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with 100% schema coverage and no output schema, the description supplies everything an agent needs: what it returns, how it orders, and when to prefer the sibling search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — all three parameters carry descriptions, including the 1–200 range, the default of 50, and the ISO 8601 example for 'since'. The description only restates the date filter at a high level, so the baseline 3 applies with the schema doing the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List a project's memories'), the ordering ('reverse chronological'), and the optional date filter. It explicitly distinguishes itself from search_memory by naming that sibling and the task it serves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use cases ('review what was recorded recently', 'overview of a project') and an explicit when-not with the alternative: 'rather than to answer a specific question (use search_memory for that)'. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional short labels for grouping and filtering, e.g. ['payments', 'decision']. | |
| content | Yes | The memory itself, as one self-contained sentence or short paragraph, e.g. 'Payments go through Stripe; orders are confirmed by the webhook, not the redirect.' | |
| project | Yes | Project the memory belongs to. Use one stable name per codebase, such as the repository name (e.g. 'acme-shop'), so every tool and teammate files memories in the same place. | |
| source_tool | No | Name of the AI tool saving the memory, e.g. 'cursor' or 'vscode'. Shown next to the memory in the web UI. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (not read-only, non-destructive, not idempotent, closed-world), so the description does not need to restate those. It adds useful behavior beyond annotations: memories are recallable across connected AI tools, and the call returns the new memory's id and timestamp. It omits any duplicate-detection or overwrite semantics despite idempotentHint=false, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence front-loads the core purpose, and the following sentences add usage, content style, and return value without padding. It is slightly redundant with the schema's content guidance, but no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with annotations present and no output schema, the description covers the essential behavior: persistent cross-tool storage, content expectations, and the returned id/timestamp. It could say more about duplicate writes or project scoping, but it is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already defines all four parameters, including the project naming convention and the content example. The description reinforces content quality ('one self-contained statement per memory, with enough context to make sense on its own') but largely repeats schema guidance rather than adding new parameter syntax or constraints, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Store a fact, decision, convention or piece of context about a project') and makes the purpose distinct from search/list/delete siblings. An agent can tell immediately that this is the write path for persistent project memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it: the user asks you to remember something, or you learn something durable that future sessions need, with concrete examples like architecture choices and deployment gotchas. It stops short of naming alternatives such as search_memory or delete_memory, so the routing guidance is clear but not fully comparative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results, 1–50. Defaults to 5. | |
| query | Yes | What you want to know, in plain words, e.g. 'how do we deploy?' | |
| project | Yes | Project the memory belongs to. Use one stable name per codebase, such as the repository name (e.g. 'acme-shop'), so every tool and teammate files memories in the same place. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered externally. The description adds genuinely useful behavior: result fields (id, match score, date, text), an empty-result message, and the fact that search is semantic or keyword-based depending on server configuration. That backend variability is a real operational caveat, but it stops short of explaining ranking quality or scoring semantics across the two modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, then usage trigger, then return behavior and search-mode caveat. Each sentence carries distinct information with no repetition. Slightly dense but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully compensates by enumerating returned fields and the empty-result case. Combined with annotations and full schema coverage, an agent has enough to call this correctly; only the behavioral difference between semantic and keyword modes is left unexplored.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented, giving a baseline of 3. The description reinforces that the query is a natural-language question and that results are ordered by match, but adds no syntax, limit behavior, or project-naming detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource with scope and ordering: 'Find the memories in a project that best match a natural-language question, best match first.' An agent immediately knows this is a relevance-ranked retrieval, not a listing. It does not name or contrast any sibling (save_memory, memory_timeline), so differentiation is inferential rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete triggers: before answering questions about conventions, decisions or setup, and before redoing work that may already be settled. No exclusions or named alternatives are offered, so an agent must infer that memory_timeline is the option for chronological browsing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0delete_memorylist_projectsmemory_timelinesave_memorysearch_memoryScored 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.
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.
Shared cross-LLM long-term memory over MCP: semantic recall, sessions, and media (pgvector).
Persistent memory, knowledge graph, task management and more for AI agents via MCP.