Every guide to giving an AI agent memory starts the same way. Pick an embedding model, stand up a vector database, chunk your data, tune your retrieval. I assumed I would do exactly that. Then, before I wrote a single line of it, I looked hard at the problem I was actually trying to solve, and I could not find the part that needed any of it.
This is the reasoning that led me to build a memory API for agents with no vector database, no embeddings, and no model in the loop. I am also going to tell you exactly when that decision is wrong, because it often is, and you should know which side of the line you are on before you copy anyone's architecture, including mine.
Here is what agents actually kept failing at. Not "find me something similar in meaning to this." They failed at "remember the specific thing I was told last session."
Take a coding agent, the case most people reading this have felt. The agent that helped you on Monday has no idea on Tuesday that you already decided to use Postgres, that the deploy step runs through a specific script, that the client's name is spelled a particular way. Every session starts from zero. You re-explain the same context every morning.
That is not a search problem. There is nothing fuzzy about it. You know the exact thing you want back and you know what to call it. It is a key, a value, and the ability to read it later, unchanged.
Vector search answers a different question: "what are the things most similar in meaning to this query." That is a genuinely hard and genuinely useful capability. It is also not what "remember that we chose Postgres for this project" needs. That needs store under a name, get it back by that name, later, reliably.
Once I separated them, the whole design fell out.
There is semantic memory: retrieval over a large body of text where you do not know the exact item you want, only roughly what it is about. "What did the design doc say about rate limits?" You want the relevant passage even if you cannot name it. This is what embeddings and vector databases are for, and they are very good at it.
Then there is named memory: facts and state you can point at. "The user prefers metric units." "This project deploys on Fridays." "The last invoice number was 1043." You are not searching by meaning. You stored something specific and you want it back by name.
A lot of what people call "agent memory" is the second kind wearing the first kind's clothes. The reflex is to reach for semantic search because that is what the tutorials show, when the actual need is a reliable place to put named facts and read them back.
This is the important part, and it is the reason I can write the rest of this honestly.
If your problem is retrieval over an unstructured corpus, you want embeddings. If an agent needs to answer questions about a hundred documents it has never been told how to index, if recall has to be fuzzy, if "find me the relevant thing" is the whole job, then a vector database is the correct tool and a key-value store is the wrong one. Do not let a simplicity pitch talk you out of the right architecture. If that is your shape, close this tab and go set up your embeddings. You will be happier. The mistake is not using vector search. The mistake is defaulting to it for a problem that was never semantic to begin with.
Deciding my problem was named memory, not semantic memory, took an entire category of machinery off the table. No embedding step on every write. No index to tune. No re-embedding when you change models. No debugging why a retrieval that should have been obvious ranked third. No second piece of infrastructure to run and pay for.
What is left is boring in the best way. You name a key, you store a value, you read it back exactly as you left it. It has a TTL if you want facts to expire on their own. You can list what an agent knows and do a literal text search over it. That is close to the entire surface area.
And there is a point about trust hiding in that simplicity. This is memory. It is the thing your agent believes about the world. I would rather that be a store I can inspect completely and reason about with certainty than a similarity ranking I have to interrogate. For this specific job, the boring inspectable version is not a compromise. It is a feature.
The honest objection at this point is: fine, if it is just keys and values, why not a table in the Postgres I already run? For a single agent, you should. That is not a business, that is a CREATE TABLE
.
It changes the moment you have more than one agent that need to read each other's writes. A planner hands off to an executor. A research agent leaves findings for a writer agent. Now you are not storing memory, you are sharing state across processes, and you are suddenly building the boring hard parts yourself: namespacing so agents do not clobber each other, scoping so the right agents see the right memory, a permission model, key management. That is the part worth not writing again. Shared memory across agents, handed to you, is the actual reason to reach for a service here rather than a column in a table you already have.
Durability and TTLs are commodity. Shared state with the access model already solved is not.
It does not do semantic search, and it will not pretend to. It does not read your documents and decide what matters. You direct what gets remembered. If you want meaning-based retrieval over a corpus, this is the wrong layer and I will tell you so.
The one thing I know it is missing, and I only know because someone pushed me on it publicly, is a lifecycle state on memories: a way to mark a fact as retired rather than deleted, with a link to what replaced it, so an agent can tell which memories are still load-bearing and which are just history. That is a temporal problem, not a semantic one, which is exactly why it belongs in a store like this without dragging in embeddings. It is the next real thing I am building.
If your agent memory need is genuinely semantic, use a vector database. If it is named facts and shared state, you may have been reaching for far more machinery than the problem asked for. That was the whole realization, and I built the tool I wished I had found instead of the one every tutorial pointed me at. I would rather be told where this reasoning breaks than agreed with, so if you see the hole, say so.