memsearch: a Markdown-backed memory layer for Claude Code, Codex and DSH
A persistent, unified memory layer for all your AI agents (e.g. Claude Code, Codex, DSH), backed by Markdown and Milvus.
At a glance
- What is it?
- memsearch stores agent conversation memory as plain .md files and indexes them in Milvus as a rebuildable shadow index. It is a good fit if you run more than one coding agent and want recall to survive a switch between them; it is the wrong tool if you want memory that outlives the host application's plugin system.
- Who is it for?
- Adopt memsearch if you already run two or more of the supported agents and want one searchable history instead of five isolated ones, and if you are comfortable with the memory directory living inside your repository. Skip it if you need a single agent's memory to work without the plugin system, or if you cannot run the ONNX embedding model locally, since the Codex install path explicitly asks for network access to fetch it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: each coding agent forgets on its own
A coding agent's context window ends when the session ends. Whatever you settled on in a conversation about a caching TTL, a migration order or a rejected library is gone the next time you start the tool, unless you wrote it down somewhere the agent reads. The usual workaround is a hand-maintained instructions file, but that is a static document. It records what you decided to write, not what you actually discussed.
memsearch targets that gap. The README describes it as cross-platform semantic memory for AI coding agents, with plugins for Claude Code, Codex, DeepSeek Harness, OpenClaw and OpenCode. The pitch that matters is the cross-platform part: a conversation held in one agent becomes searchable context in the others. If you use Claude Code for one repository and Codex for another, the memory store is shared rather than duplicated. The project also splits its audience explicitly, offering a zero-configuration plugin install for agent users and a CLI plus Python API for people building agents of their own. The second audience is the more interesting one, because it means the memory layer is usable without any of the five plugins.
Markdown as the source of truth, Milvus as a rebuildable index
The architectural decision that shapes everything else is where the data lives. Memories are ordinary .md files, and the README states that Markdown is the source of truth while Milvus is a shadow index, described as a derived, rebuildable cache. That ordering matters. If the vector store is lost or its schema changes between releases, the durable artefact is still a directory of text files you can read, diff and commit.
The retrieval path has three layers, which the README calls search, expand and transcript. Search hits the index; expand pulls surrounding context; transcript falls back to the original conversation record. Ranking combines dense vectors, BM25 sparse retrieval and RRF reranking, so exact token matches and semantic matches are both in play. Two mechanisms keep the index from drifting. SHA-256 content hashing skips unchanged content during indexing, and a file watcher re-indexes in real time when a memory file changes on disk. Because the files are the input, editing one by hand and saving it is a legitimate way to correct a memory, and the watcher will pick the edit up. That is a real advantage over systems where memory is only reachable through an API.
Installing it: three different entry points
The install path depends on which agent you use, and the three documented paths are not equivalent. For Claude Code, the README gives a plugin marketplace flow: /plugin marketplace add zilliztech/memsearch followed by /plugin install memsearch, then a restart to activate it. For Codex, installation is a clone plus a shell script: git clone --depth 1 https://github.com/zilliztech/memsearch.git, then bash memsearch/plugins/codex/scripts/install.sh. The README notes that codex --yolo is needed for ONNX model network access, which tells you the embedding model is downloaded on first use rather than vendored. For DeepSeek Harness, the install is uv tool install "memsearch[onnx]" followed by dsh plugin --profile web add @zilliz/memsearch-dsh, and then a restart of that profile or a new session.
Verification is the same across platforms. After a few conversations, ls .memsearch/memory/ should show daily .md files, and cat .memsearch/memory/$(date +%Y-%m-%d).md prints the current day's file. Recall is triggered either by an explicit command such as /memory-recall what did we discuss about Redis? or by asking naturally, since the README states the agent auto-invokes the skill when a question needs history. Codex and DSH use a registered memory-recall skill rather than a slash command. The ONNX extra in the DSH command and the network requirement in the Codex note are the two details to check against your environment before starting, because both imply the embedding model is fetched rather than bundled.
The procedural memory layer, and what it costs you
Beyond conversation capture, memsearch has a second and third kind of memory. The changelog describes skills distilled from repeated workflows: patterns you perform often get turned into reusable, installable agent skills and kept current in the background. Separately, optional background maintenance tasks keep durable PROJECT.md and USER.md notes up to date across sessions.
This is where the design becomes opinionated. Background processes that write to your memory store are convenient and also the hardest part to reason about, because the content of PROJECT.md and USER.md changes without a conversation triggering it. The README presents these as optional, which is the right framing. If you enable them, the sensible posture is to treat the generated files the way you would treat any machine-written commit: read the diff. Because the files are Markdown and the index is derived, an unwanted edit is recoverable, but only if you notice it. The skills layer raises a similar question in a different form. A distilled skill encodes a workflow the system inferred you repeat, and an inferred workflow can be subtly wrong in a way that is invisible until the agent applies it to the wrong repository.
Where memsearch is the wrong choice
The first limitation is structural. memsearch is delivered as plugins for specific agents plus a CLI and Python API. If your agent is not Claude Code, Codex, DSH, OpenClaw or OpenCode, you are on the Python API path and writing the capture and injection hooks yourself. The automatic capture that the README advertises for plugin users does not exist for you until you build it.
The second is the storage location. The default memory directory is .memsearch/memory/ inside the working tree, which is what makes the files version-controllable and also means they sit next to your source. Whether that directory is committed, ignored or kept out of the repository entirely is a decision the material does not settle, and it is a decision with consequences: conversation transcripts captured automatically can contain credentials, internal hostnames or customer data that you would not put in a repository. There is nothing in the supplied material describing redaction, scrubbing or a retention policy, so treat that as unverified rather than assuming it is handled.
The third is the dependency surface. Python 3.10 or later, an ONNX embedding model, and Milvus. The README describes Milvus as a rebuildable cache, which softens the operational weight, but you still need it running for search to work. For a single developer on a single agent, that is more infrastructure than a well-maintained instructions file, and the semantic recall it buys may not be worth the moving parts.
How it differs from a plain file-based memory skill
The closest alternative is the pattern memsearch itself cites as inspiration: a Markdown memory file that the agent reads at the start of a session, as used by OpenClaw. The difference is retrieval. A memory file is loaded whole, so its size is bounded by the context window and every session pays the cost of reading all of it, relevant or not. A larger file makes the agent slower and dilutes attention.
memsearch keeps the same file format but puts a hybrid index in front of it, so the agent retrieves a few matching passages instead of the entire history. That is a genuine improvement once the memory grows past the point where loading it wholesale is practical, and it is why the three-layer search, expand, transcript path exists. The trade-off is the index: a Milvus instance, an embedding model, a file watcher and a background maintenance loop, all of which can fail independently of the Markdown files. If your memory is small enough to read in full, the plain file approach is simpler and has fewer ways to break. The crossover point is roughly when you stop being able to read the whole memory directory in one sitting.
Licence, release cadence and what to check before adopting
memsearch is MIT licensed, which permits commercial and closed-source use and modification, with the usual requirement that the copyright notice and permission notice be preserved in copies. That is a permissive licence and the practical constraint is attribution, not usage. This is not legal advice; read the LICENSE file in the repository if the terms matter to your organisation.
On maintenance, the published releases run from v0.4.17 on 31 July 2026 through v0.4.18 on 19 August 2026 to v0.4.19 on 23 August 2026, with the last push to the repository dated 10 September 2026. That is a fast cadence on a pre-1.0 version number, which cuts both ways: fixes arrive quickly, and the memory format, the index schema or the plugin interfaces can change between minor releases. Because the Markdown files are the source of truth, a schema change should be recoverable by re-indexing from disk, which is the strongest argument for the shadow-index design. Verify that assumption in your own setup rather than taking it on faith: after upgrading, confirm that ls .memsearch/memory/ still lists your files and that a recall query returns a memory you know exists. If re-indexing from the Markdown directory does not restore search after an upgrade, the fallback the README promises is not actually there, and that is the first thing worth testing.
Editorial conclusion
Adopt memsearch if you already run two or more of the supported agents and want one searchable history instead of five isolated ones, and if you are comfortable with the memory directory living inside your repository. Skip it if you need a single agent's memory to work without the plugin system, or if you cannot run the ONNX embedding model locally, since the Codex install path explicitly asks for network access to fetch it. Before committing, run the plugin install for one platform only, confirm that .memsearch/memory/ fills with daily .md files after a few conversations, then inspect one of those files to see what the automatic capture actually writes before you let it accumulate.
Community notes