Daniel's been elbow-deep in agentic coding workflows and he's hit a question that's been nagging at me too. He's looking at two competing patterns for giving an agent persistent memory of a project, and both are still very much alive. The lightweight approach is markdown files in the repo — a memory store, context notes, spec folders, a CLAUDE.md file, skills that tell the agent to write things down as it works. Version-controlled, human-readable, diffable. The other side is a proper vector memory layer — Pinecone, Supermemory, something connected over MCP with namespaces per project, semantic recall instead of grepping files. And he's asking why we're still seeing both approaches in earnest for what looks like the same job. What is each one actually good at that the other genuinely can't do? Where does a hybrid stop being clever and start being two sources of truth that disagree? And which one would you bet on for a solo developer with a few dozen active repositories?
The question that's hiding inside all of this is what "memory" even means for a coding agent, and I think that's where most of the confusion lives. Because we're using one word for at least three different things.
Go on.
There's project structure memory — where things live, what the directory conventions are, which linter config applies to which subdirectory. There's decision memory — why we chose Redis over Postgres for the session store, why that endpoint is rate-limited to fifty requests. And then there's pattern memory — the developer always structures error handling this way, always names test files with underscores, always wants async over sync unless there's a reason. Those three things have almost nothing in common except that an agent needs to know them.
And the markdown file pattern is natively good at the first two and terrible at the third.
A CLAUDE.md or a memory bank file sitting in the repo root is essentially a structured document the agent reads at the start of a session. It tells the agent where things are and what rules to follow. The agent can also write back to it — append a decision log, update a context summary. And because it's markdown in version control, you get diffs for free, you get blame for free, you can read it yourself when the agent does something baffling and you want to know what it was told.
And the vector database is the other way round. Terrible at the first two, natively good at the third.
Right. A vector store doesn't give you a crisp answer to "where do tests live" because that's not a semantic question — it's a lookup. But it does give you "the last six times the developer rejected a synchronous approach, here's what they said and here's what they chose instead," retrieved by similarity to the current context. That's pattern memory, and a markdown file can't do it at all unless the agent already knows exactly which section to grep for.
So the real answer to Daniel's first question — why both are still standing — is that they solve different problems and calling both of them memory is a category error.
It's a category error that the whole industry is making, by the way. Every framework out there — mem0, Letta, Zep, LangMem — they all talk about agent memory as one thing, and then you look at what they actually store and it's a mix of structured facts, unstructured reflections, and raw conversation logs. They're all solving different parts of the problem and slapping the same label on it.
Let's get concrete. Walk me through what the markdown pattern actually looks like in practice for a real project.
So the pattern that's emerged — and it's mostly community-driven, not something any one company shipped — is you scaffold a project with a memory directory. Inside it you've got something like a project-context file, a decisions log, maybe a specs folder with one file per feature. You've got a CLAUDE.md or an AGENTS.md at the root that acts as the entry point. And you give the agent skills — essentially prompt fragments — that tell it to read those files at session start and write back to them when it learns something new.
And the writing-back part is where it gets interesting, because the agent has to decide what's worth saving.
That's the hard problem. The agent has to recognize that something it just did or learned is durable — that it applies beyond this session. And it has to summarize it well enough that a future instance of itself, starting cold, can pick it up and use it. Most implementations I've seen use a pretty simple heuristic: if the agent makes a decision that contradicts a previous assumption, or if it discovers a constraint that isn't documented anywhere, it writes a note.
And that works until it doesn't.
It works until the notes accumulate and nobody's curating them. After about three weeks of active development, you've got forty markdown files and the agent is reading all of them at the start of every session. Context window gets eaten, the agent starts missing things in the middle, and you've recreated the problem you were trying to solve.
So the markdown pattern has a shelf-life problem.
It has a compression problem. The files are human-readable but they're not agent-optimized. An agent doesn't need to read the full decision log from three months ago — it needs the three relevant entries. But markdown files don't do retrieval, they do loading. You load the file or you don't.
Which is exactly where the vector approach shines. Semantic retrieval means the agent only pulls what's relevant to the current task.
And it pulls it fast, and it pulls it across project boundaries if you've set up namespaces right. That's the thing Daniel's getting at with the hybrid — the vector store can hold things that aren't specific to one repo. If the agent learns that Daniel always wants error handling in a particular pattern, that's not a project fact, that's a Daniel fact. It belongs in a namespace that spans repositories.
But now we've got two stores and the agent has to know which one to query for what.
And it won't. That's where the hybrid stops being clever and starts being two sources of truth. The agent doesn't have a reliable internal model of what lives where. It might write a decision to the markdown file and a related pattern observation to the vector store, and three sessions later it queries the wrong one or queries both and gets conflicting information because one was updated and the other wasn't.
The sync problem.
The sync problem is the whole game. Once you have two stores, you need a reconciliation mechanism, and now you're not building an agent memory system, you're building a distributed database with eventual consistency and conflict resolution. And the agent is the transaction coordinator, which is insane.
So the hybrid is appealing on paper and a nightmare in practice.
Unless you're very disciplined about what goes where. And discipline is not something I'd bet on for a solo developer with a few dozen repos who's just trying to get things done.
Let's talk about the MCP angle, because that's the other piece Daniel mentioned. Connecting a vector store over the Model Context Protocol.
MCP changes the calculus a bit because it means the vector store isn't embedded in the agent's runtime — it's a service the agent calls, same way it calls a terminal or a browser. That means you can swap backends without changing the agent's logic. Pinecone today, Supermemory tomorrow, whatever. And Supermemory in particular is interesting because it's built specifically for this use case — it's not a general-purpose vector database, it's a memory layer for AI agents with MCP as the transport.
What does Supermemory actually do that Pinecone doesn't?
It handles the ingestion and organization. With raw Pinecone you're managing embeddings, chunking strategies, metadata filters, all of that yourself. Supermemory abstracts that away — you give it content and it figures out how to store and retrieve it. It's closer to what Daniel's describing as a proper memory layer. But it's still a separate system from the repo.
And separate systems drift.
Separate systems drift, and separate systems need separate maintenance, and separate systems fail in ways that are hard to debug because the agent's behavior suddenly changes and you don't know whether the problem is in the prompt, the markdown files, or the vector store.
So let's get to the betting question. Solo developer, few dozen active repos. Which way would you go?
I'd go markdown-first with a very specific constraint that I think most people miss.
Which is?
Don't let the agent read everything. The naive pattern is "load all memory files at session start," and that's the thing that breaks at scale. What you want instead is a two-tier system within the markdown approach. You've got an index file — call it MEMORY.md or whatever — that lists what's available and summarizes each file in one line. The agent reads that first, then decides which files to actually load based on the task.
So you're building a manual retrieval layer inside the file system.
It's grepping with extra steps, but the extra steps are the agent making a relevance judgment, which it's actually pretty good at if you give it good summaries. And the summaries stay fresh because the agent updates them when it updates the underlying files.
And this avoids the context window problem because the agent isn't loading forty files, it's loading the index and then maybe three files.
Right. And it avoids the sync problem because there's only one store. The index is just another markdown file. It can't disagree with the files it indexes because it's generated from them.
What do you lose by not having the vector store?
You lose cross-project pattern recognition. If the agent learns something about how Daniel works in project A, it won't automatically apply that in project B unless Daniel manually copies the insight over or the agent happens to have both repos checked out and makes the connection, which is unlikely.
That feels like the real loss. The vector store's killer feature isn't semantic search within a project — it's semantic search across projects.
It is. And for a solo developer, that's actually huge. Daniel's not just building one thing — he's got dozens of repos, and the way he works is probably pretty consistent across them. A vector store with a Daniel namespace could accumulate pattern knowledge that makes every new project start faster.
But you just said you'd bet on markdown.
I would, because the cross-project benefit is real but the maintenance cost of the vector store is also real, and for a solo developer the math doesn't work out. You're trading a genuine but occasional win against a constant background tax of keeping two systems coherent.
There's a third option that Daniel didn't mention and I think it's worth bringing up.
What's that?
Embed the markdown files and use them as the vector store's source of truth. Instead of the agent writing to two places, it writes to markdown files only, and you've got a background process — could be a GitHub Action, could be a cron job, could be an MCP tool the agent calls explicitly — that re-indexes the markdown files into a vector database on a schedule.
So the markdown is the write path and the vector store is a read-only cache.
The agent never writes to the vector store directly. It writes markdown, commits it, and the vector store is rebuilt from the markdown. One source of truth, two access patterns.
That's clever. The agent gets semantic retrieval but it never has to decide where to store things. And if the vector store gets corrupted or goes out of sync, you just rebuild it.
And you get the cross-project benefit because the indexing process can pull from multiple repos. Daniel's pattern knowledge lives in the markdown files across all his projects, and the vector store makes it queryable.
The downside is latency. If the agent writes a crucial insight and needs it in the next session, but the re-index hasn't run yet, it's not available.
That's what the markdown files are for. The agent always reads the local markdown first. The vector store is for discovery — finding things the agent didn't know to look for.
So it's not two sources of truth, it's one source of truth with a search index on top. That's just how databases work.
It's just how databases work, and we've somehow forgotten that because we're all excited about vectors.
I want to push on something, though. The whole conversation assumes the agent is making good decisions about what to write down. And in my experience, that's the part that actually fails, regardless of storage backend.
The agent writes down the wrong things.
Or writes down things that are true in the moment but stop being true two refactors later. Or writes down things that are too vague to be useful. "The project uses modern patterns" — thanks, that's nothing. Or it writes down things that are too specific. "The user model has a field called last_login_ip" — great, and next week that field gets renamed and now the memory is actively harmful.
Stale memory is worse than no memory.
Much worse. No memory means the agent asks a question or makes a wrong assumption and you correct it. Stale memory means the agent acts confidently on wrong information and you might not catch it until something breaks.
So the real skill isn't storage, it's forgetting.
Intelligent forgetting is the hard problem in agent memory. Not just expiring old entries — the agent has to recognize when something it wrote down is no longer true. And that's a reasoning problem, not a storage problem. The markdown file and the vector store are both equally bad at it.
Unless the markdown files are version-controlled and you can see what changed.
That's actually a point for the markdown approach that I don't think gets enough attention. When the agent writes to a markdown file and commits it, you get a diff. You can see exactly what it added, what it removed, what it changed. If it wrote something wrong, you can catch it in code review. With a vector store, the agent is upserting embeddings and you have no idea what changed unless you build an audit layer on top.
Observability.
Observability and trust. If I can't see what the agent remembers, I can't trust what it does. And for a solo developer who's shipping real code, trust matters more than retrieval quality.
So we've got markdown winning on trust and simplicity, vector winning on cross-project discovery, and the hybrid winning on nothing because it introduces a sync problem that cancels out the benefits.
I think that's right. And I think the trend Daniel's observing — toward markdown, lightweight files, Obsidian-style graphs — is a reaction to exactly that. People tried the fancy vector stuff, discovered it was brittle and opaque, and retreated to something they could read and version and understand.
But serious people keep reaching for Pinecone because they've got problems that markdown can't solve. If you're building an agent that needs to recall patterns across thousands of interactions with hundreds of users, a markdown file is a joke. You need semantic search.
Right. The serious people aren't wrong, they're just solving a different problem. The confusion comes from the fact that both camps call what they're doing "agent memory."
Let's give Daniel a concrete recommendation. Solo developer, few dozen repos. What does he actually do on Monday morning?
Monday morning, he sets up a memory directory in his most active repo with three files: a project overview, a decisions log, and a patterns file. He writes a CLAUDE.md that tells the agent to read the overview and decisions log at session start, and to consult the patterns file when it's unsure about conventions. He adds a skill that tells the agent to append to the decisions log when it makes a non-obvious choice, and to update the patterns file when it notices a recurring convention.
And he does not install Pinecone.
Not on Monday. On Monday he ships code. After a month, if he's finding that the agent keeps rediscovering the same patterns across repos, he sets up that background indexing process — markdown as source of truth, vector store as read cache. But he doesn't let the agent write to the vector store directly.
And if he's already got a vector store set up and it's working?
Then he keeps it. The advice isn't "vector stores are bad." It's "don't introduce a second write path unless you've got a problem that requires it." Most solo developers don't.
I want to come back to something you said earlier about the agent making bad decisions about what to write down. Is there a way to make that better without building a whole reasoning system?
The simplest thing that actually works is to make the agent write down the question it was trying to answer, not just the answer. Instead of "the rate limit is fifty requests per minute," it writes "we set the rate limit to fifty requests per minute because the upstream API throttles at sixty and we wanted headroom." The context around the decision is what makes it durable — when the upstream API changes its limits, the agent can read that and understand why the number was chosen and whether it still applies.
So you're encoding the reasoning, not just the conclusion.
And that's something markdown is good at. It's a narrative format. A vector embedding of "fifty requests per minute" loses all of that context. A markdown file preserves it.
Which is another argument for markdown as the write path even if you've got a vector store for retrieval. You want the reasoning somewhere, and the vector embedding strips it.
The embedding captures semantic similarity, not causal reasoning. It'll tell you that two decisions are related, but it won't tell you why, and it won't tell you whether the relationship still holds.
Daniel also mentioned Obsidian-style graphs, and I think that's worth pulling on for a second. What's the graph actually giving you?
The graph is a visualization of links between notes. In an agent memory context, it's showing you which memories reference each other. The idea is that you can see clusters forming — these five decisions are all about authentication, these three patterns are all about error handling — and that helps you curate.
But the agent isn't looking at the graph.
Not yet. There's some experimental work on agents that navigate a knowledge graph rather than a flat list of files, but it's early. For now the graph is for the human. It's a curation tool.
So it's memory for the developer, not memory for the agent.
Which is useful in a different way. If you've got forty markdown files and you want to know which ones are stale, the graph can show you which ones haven't been linked to or updated in months. It's garbage collection for project knowledge.
I'm now imagining a future where the agent maintains a knowledge graph and uses it to decide what to forget. That's the thing you said was the hard problem.
That is the hard problem, and I don't think anyone has solved it well. The closest I've seen is agents that timestamp their memories and apply a decay function — older memories get lower retrieval scores unless they've been recently reinforced. But that's a heuristic, not understanding.
It's the memory equivalent of "if I haven't used this variable in six months, maybe I don't need it."
And we all know how that refactor goes.
I've deleted variables I was still using. I've deleted variables I was still using and then blamed the compiler.
The compiler is very patient with you.
The compiler and I have an understanding. It doesn't judge my life choices and I don't read its error messages carefully.
That explains a lot about your code.
We're off topic.
We are. Let me pull us back to Daniel's actual question, because I think we've answered the "what is each good at" part but we haven't fully addressed the "where does the hybrid break" part.
You said the hybrid breaks when the agent has to decide where to store things.
Right, but let me make that more specific. The break isn't just that the agent makes wrong decisions — it's that the decision itself is a cognitive load on the agent. Every time it learns something, it has to classify the thing it learned, pick a storage backend, format the content appropriately for that backend, and then remember which backend it used so it can query the right one later. That's a lot of steps for something that should be automatic.
Each step is a chance to fail.
Each step is a chance to fail, and the failures compound. If it classifies something as project-specific when it's actually cross-project, it goes to the wrong store and never gets retrieved in the context where it's needed. If it formats something for markdown but stores it in the vector database, the retrieval quality degrades because the chunking wasn't designed for that format.
The hybrid doesn't just add complexity, it adds failure modes that don't exist in either pure approach.
A pure markdown approach has failure pattern — stale files, context window bloat, poor cross-project retrieval. A pure vector approach has failure pattern — opaque updates, embedding drift, difficulty reasoning about what was stored. But the hybrid has all of those plus the classification and sync failures, and the classification failures are the ones that are hardest to debug because they're silent. The agent just doesn't find the thing it needs, and you don't know why.
Which brings us back to your recommendation. Start simple, add complexity only when the simple thing demonstrably fails.
When you do add complexity, add it in a way that doesn't create a new write path. The background indexing approach Corn described — markdown as source of truth, vector store as read cache — that's complexity that adds capability without adding failure pattern.
Because if the vector store breaks, you rebuild it. If the agent writes something wrong to the markdown, you see it in the diff. There's no scenario where the two stores disagree and you can't tell which one is right.
The markdown is always right by definition. That's the design principle. One canonical store, and everything else is derived from it.
Hilbert: I kept a project journal for about eight years.
A project journal?
Hilbert: Spiral-bound notebooks. One per project. Date at the top of each entry, what I did, why I did it, what I learned. When I finished a project, the notebook went on a shelf. I had maybe forty of them by the end.
That's essentially the markdown pattern, just analog.
Hilbert: It worked until I needed to find something across projects. Then I was pulling notebooks off the shelf, flipping through pages, trying to remember which project I was working on when I solved that particular problem. The index was in my head, and my head is not a reliable index.
Did you ever build a cross-notebook index?
Hilbert: I started one. Got about three notebooks in and realized I was spending more time on the index than on the work. That's when I stopped.
That's the vector store argument in a nutshell. The markdown works perfectly until you need cross-project retrieval, and then you need an index, and building the index by hand is a job in itself.
Hilbert: The thing I learned, though — and this is what I wanted to say — is that the cross-project retrieval wasn't actually as important as I thought it would be. Most of the time, when I needed something, it was from the current project or the most recent one. The shelf of old notebooks was a comfort more than a tool.
You're saying the cross-project benefit is real but overestimated.
Hilbert: I'm saying I kept forty notebooks and opened maybe six of them more than once. The value was in the writing, not the retrieving. Writing things down forced me to be clear about what I'd done and why. The retrieval was a bonus that almost never happened.
That's a point I hadn't considered. The act of writing the memory might be more valuable than the act of retrieving it.
Because writing forces the agent — or the developer — to crystallize what they learned.
That crystallization is what makes future sessions better, even if the specific memory is never retrieved. The agent that wrote down "we use async because the database driver is non-blocking" is an agent that understood the project well enough to explain it. That understanding carries forward even if the file is never read again.
Hilbert: I've still got the notebooks. They're in a box.
Of course they are.
We should probably land this. Daniel asked three things: what each approach is actually good at, where the hybrid breaks, and which one to bet on. I think we've got clear answers on all three.
Markdown is good at trust, observability, and narrative reasoning. Vector stores are good at cross-project semantic retrieval and pattern recognition at scale. The hybrid breaks when the agent has to classify and route memories, because classification is a hard problem and failures are silent.
For a solo developer with a few dozen repos, start with markdown, add a read-only vector index later if cross-project retrieval becomes a real bottleneck, and never let the agent write to two places.
One source of truth, one write path, and a deep suspicion of anything that calls itself memory but can't show you a diff.
Thanks to Hilbert Flumingtop for producing, and for the notebook revelation.
This has been My Weird Prompts. You can find every episode at my weird prompts dot com, or email the show at show at my weird prompts dot com.
We'll be back soon.
