Memory and chat history are different things

This is the key idea, without which Mem0's code looks close to magic. By default the library does not put every message into the database verbatim - it receives messages and extracts compact facts from them.

That is exactly why memory is normally far more compact than a full transcript: the model receives not every old message in sequence, but a small number of facts related to the current question.

Technically this unfolds in two phases, and Mem0 appears in your application in precisely two places. Calling add() starts the write phase: the library looks for related existing context, extracts facts from the new messages, drops exact duplicates, creates embeddings, and stores the result together with identifiers and metadata. Calling search() runs the read phase: the query is turned into a searchable representation, Mem0 ranks candidates, applies filters and returns the best memories. What happens next is up to your code - how many results to put into the prompt and how to word the system instruction.

One caveat will save you time if you compare notes with articles online. In April 2026 the project changed its extraction and retrieval scheme, so many older examples describe the previous architecture. Three things changed. Automatic extraction became ADD-only: it adds new facts and no longer tries to update or delete old ones in the same model pass - if a user reports a new fact, it may sit alongside the previous one, while explicit correction and deletion are performed by your application. Retrieval became multi-signal: it combines semantic similarity, BM25 keyword matching and entity matching, so it looks at more than closeness of meaning. And entity linking appeared: named entities are extracted from memory - people, organisations, places, objects, events and a few more types, eleven accepted in all - and a match on them lifts a record in the results. Dates, numbers and monetary amounts are discarded deliberately. An important caveat: entities and BM25 only reorder, they do not widen the pool - the candidates still come from semantic search. Full Graph Memory in the current architecture remains a Mem0 Platform feature rather than a separate OSS module.

The same migration brings a detail that trips up older code: in the current Python OSS, user_id for search() and get_all() is passed inside filters. A call like search("...", user_id="alice") belongs to the former API.

What memory is assembled from

Mem0 is easier to think of not as a single database but as a small pipeline whose main components can be swapped independently in the open-source version. That is the main reason people pick OSS in the first place.

In the default Python configuration the documentation lists the OpenAI gpt-5-mini model, text-embedding-3-small embeddings, a local Qdrant in /tmp/qdrant, and SQLite history at ~/.mem0/history.db. Keep that list in mind: it explains why the very first run needs a key for model access.

Installation and the first stored fact

The minimal Python install looks like this:

If you stay on the default configuration, you need an OpenAI key:

The key is required not because the library is paid, but because Mem0 does not "understand" the conversation by itself: a model is used to extract facts, and an embedding model to represent text as vectors. In the open-source version both components are replaceable, including with local ones through Ollama - we will come back to that near the end.

For extended hybrid search the README separately suggests NLP dependencies:

Now the interesting part - the first write. Note that we pass not a prepared fact but ordinary dialogue messages:

Memory() creates a memory engine with default components, add() analyses the messages and picks out what is worth keeping, and user_id="alex" ties the memory to a specific person - which is critical as soon as you have more than one user. The database ends up with something compact such as "The user's name is Alex" and "Alex likes basketball and video games", rather than a mandatory copy of the whole conversation.

Retrieval and the working loop

You can pull a fact out in the same human language it was said in:

What happens here is fundamentally different from an ordinary database. We are not asking it to find the string "basketball" - we ask a question, and Mem0 looks for memories whose meaning relates to the query and returns the best candidates. The top_k=3 parameter means "return no more than three suitable memories"; it is not a magic correct number, you tune it for your product against answer quality, latency and context size. If you are migrating from an older version, note that in the current OSS the default top_k is 20 and the default threshold is 0.1, so the number of results may change unexpectedly.

But memory does not answer the user. Its results have to be handed to the model, and the full loop looks like this:

The order here matters more than the syntax. First we read memory - before going to the model we look for facts that might help with the current question. Then we turn the results into plain text, because the model has no idea what a Mem0 object is; it needs textual context. The model answers, treating those memories as additional information rather than built-in magic. And only after the answer do we hand the fresh pair of messages back to memory, so new long-term facts can be extracted from it.

The result is a loop: find the past, answer with the past in mind, store the new. That loop is what turns an ordinary stateless model call into an application that gradually accumulates context.

Whose memory is this

As soon as you have more than one user, the main risk of any memory system surfaces: put everyone's memories into a shared pile and search without limits, and one day you will hand one person's data to another. That is why memory is partitioned by scope.

In practice it looks like this:

After that you can search strictly within the right user's memory and the right category, instead of hoping that a similarity search will not accidentally pick up somebody else's fact.

Memory has to be more than additive

A real product must let you correct and delete knowledge: people change addresses, abandon old preferences, or simply ask you to delete their data.

Since the move to the ADD-only algorithm this has become especially important. Automatic extraction only adds facts, so if your application needs to reliably replace a specific old piece of knowledge, do it with an explicit update() or delete() rather than hoping the new fact will push the old one out by itself.

Sometimes interpretation is not wanted at all - the text must be stored verbatim. There is a separate flag for that:

This mode is useful for already prepared facts, machine events and texts where any rewording is undesirable. But if you are passing an ordinary long dialogue, automatic extraction usually yields cleaner memory that is easier to search.

On the other side of the loop - on reads - you also have control. Semantic similarity should not be the only way to pick memory: sometimes you know for certain that the search must cover only work notes, or only one user.

Filters cut off obviously unsuitable records first, and the reranker, if configured, changes the order of the found candidates in a second pass. That can improve precision, but it adds latency - and cost, with an external provider.

A configuration you can take to production

The Memory() constructor is fine for a first run, but in production it is better to decide explicitly where your data lives and which models process it.

Four things change compared with the defaults. Qdrant is spelled out, so you control the server address and the collection name instead of an implicit local store. The extraction model is configured separately, so the provider and parameters can be changed. The embedder is independent of the LLM - these are different jobs, and different models may do them. And the reranker stays optional: add it after you have measured the quality of basic retrieval, not simply because it exists. Worth remembering separately is the documentation's advice to keep the extraction model's temperature at or below 0.2 - memory comes out more stable that way.

The same thing in Node.js

The concept does not change with the language; the syntax and naming conventions do: Python uses snake_case, TypeScript uses camelCase. The one subtlety that is easy to trip over: in Node the open-source version must be imported from mem0ai/oss.

When memory is needed by several services, not one function

If several applications talk to memory, it is more convenient to run a separate REST service - the repository ships a Docker stack with an API and a dashboard for exactly that. The quick path from the README:

Or a plain container start:

According to the current documentation the reference setup uses port 8888 for the API and 3000 for the dashboard, and the server itself includes authentication, per-user API keys and a request audit log. Here also hides a rake that costs dearly: the AUTH_DISABLED=true variable is intended for local development only. Memory often contains user data, so an open endpoint without authentication on a public server turns into a direct leak.

A separate question is whether everything can be closed inside your own infrastructure. It can: the open-source version lets you replace the external model and embedder with local ones, for example through Ollama, and keep the vector store on your own machine - then the backend sends no memory to the cloud, facts are extracted locally, embeddings are built locally, and Qdrant or pgvector holds the vectors on your side.

But "self-hosted Mem0" and "everything local" are not the same thing, and it is easy to fool yourself here. If you run the library yourself but use OpenAI for extraction and embeddings, that data still goes to an external model provider. To make sure nothing leaves your infrastructure, you have to localise both the models and the storage.

The command line and agent sign-up

The project has an official CLI, and it installs one of two ways - through npm or through pip, both giving the same mem0 binary with identical behaviour. One thing about it needs stating up front: the CLI works against the managed platform's API, not the open-source memory engine we have been going through above.

The most curious part of it is the agent sign-up path. A key is minted with no email, no dashboard and no one-time codes, and the whole route fits into four commands:

The command set covers the usual memory lifecycle: setup, add, search, list, read by identifier, update, delete, bulk import from JSON, work with entities and inspection of background events such as bulk deletions. There is also mem0 status for checking the connection and the current project.

But something else is more interesting - a mode built for something other than a human. The global --agent flag (aliased as --json) turns any command into a structured response of the same shape: status, command name, duration, scope, count, and data trimmed to the fields an agent actually needs. Spinners, colours and banners are suppressed entirely, and errors go to the same output stream as JSON too, with a non-zero exit code.

The second command returns the whole command tree as JSON - so an agent can discover for itself what is available rather than relying on a description baked into a prompt. This is a rare case of a tool designed on the assumption that a program will be calling it, not a person at a keyboard.

OSS or Platform, and what it costs

One detail from the README is worth keeping in mind when comparing numbers: the published benchmark results for the managed platform use proprietary optimisations that are not in the open-source SDK. Those numbers cannot be transferred one to one to your local installation.

There are three honest caveats about money and data. Open source does not mean everything is free: the library itself is open, but models, embeddings, the reranker and infrastructure can cost money, and the default configuration calls external OpenAI models - so paid calls appear. Next, extracted memory is more sensitive than an ordinary log: it deliberately concentrates important facts about a person, so treat it as personal data - separate users, control access, provide deletion, keep secrets out of logs, think about retention. And finally, self-hosted does not guarantee zero external traffic: check the whole chain - the extraction model, embeddings, the reranker and the database itself - because a single cloud component is enough for part of your data to leave.

When Mem0 is needed, and when it is redundant

A good scenario for a separate memory layer is a personal assistant that has to remember preferences for months; a support bot that needs the context of past tickets; an agent working on a project across several sessions; an application with personal recommendations; and finally several agents that need a managed shared layer of long-term context.

Conversely, Mem0 will be redundant in a one-off chat of a few messages; in an ordinary CRUD system where the data is already structured and a SQL query retrieves it; in a task that needs verbatim archiving of a conversation rather than fact extraction; in simple RAG over static documentation, if personal and evolving memory is not needed.

It is also useful here to separate two things people often conflate. RAG answers the question "which external knowledge relates to this query?", while a memory layer answers "what does this agent already know about the user, past actions and previous sessions?". Both systems live side by side in one product quite happily.

Six mistakes on first acquaintance

Serving all memory to all users. If memory is personal, restrict retrieval by at least the correct user_id.

Treating add() as an ordinary INSERT. With inference enabled it is a pipeline involving a model, and the result may be more compact and more formal than the original text.

Mixing OSS and Platform documentation. The products share the general idea, but their capabilities and classes differ: Memory belongs to the open-source version, MemoryClient to Mem0 Platform.

Taking old API examples. After the 2026 migration some parameters and defaults changed - most noticeably in search(), get_all(), entity filters, top_k, threshold and extraction behaviour.

Assuming more memory is automatically better. The goal of retrieval is not to return as much text as possible, but to give enough useful context without drowning the model in irrelevant memories.

Not planning for deletion. Any long-lived user memory needs a clear lifecycle: how to update a fact, how to delete one record, how to delete a person's memory entirely, and what to do with temporary data.

Reduced to a single formula it comes out like this: the point of Mem0 is not to stuff the whole past chat into a database, but to turn past interactions into manageable facts and return to the model only the small slice of the past that helps answer right now.

Sources

This article was checked against the Mem0 repository and official documentation on 9 August 2026. Supplemented on 14 August 2026: defaults and signatures re-verified against a fresh clone, the account of entity-aware retrieval refined, the filter key in the TypeScript example corrected, and a section on the command line added. The project moves quickly, so before carrying code into a new project it is worth re-checking the migration guide and the quickstart for your installed version.

• GitHub: mem0ai/mem0
• The mem0 command line
• Agent sign-up
• How Mem0 Works
• Memory Types
• Add Memory
• Search Memory
• Open Source Python Quickstart
• Open Source Node.js Quickstart
• Configure the OSS Stack
• Self-Hosted Setup
• OSS v2 - v3 migration
• Platform vs Open Source