ReMe: Markdown Files as Agent Memory, With BM25 Search on Top

The Problem ReMe Picks: Agent Memory That Outlives the Context Window

Most agent runtimes forget. A conversation ends, the context window closes, and whatever the agent learned about a user's preferences, a codebase's conventions or a procedure that worked last week is gone. The usual fix is to stuff more history into the prompt, which does not scale, or to push everything into a vector store, which produces memory that no human can read or correct. ReMe takes a third position. The README describes it as a local-first, self-evolving personal knowledge base for AI agents, and the mechanism it chooses is the file system. Durable memory is Markdown with frontmatter and wikilinks. Indexes and generated metadata are treated as rebuildable. That single decision answers the question of who this is for: teams running assistants, coding agents or other runtimes that need shared, long-lived memory, and who want the durable artifact to be something a person can open in an editor. It is not aimed at someone who wants a drop-in embedding wrapper for a single chat loop. The scope is a workspace that several agents read and write over time.

Memory as File: Frontmatter, Wikilinks and a Rebuildable Index

The architecture follows from the storage choice. A memory node is a Markdown file with frontmatter carrying at least a name and a description, and a body that can reference other nodes with wikilinks. The README's own demo writes one such node at path=digest/wiki/quick-start-demo with a name, a description, and content that ends in a link to [[digest/wiki/memory-as-file.md]]. Retrieval then works on two axes. BM25 gives lexical matching over the text, and wikilink expansion pulls in the nodes connected to a match, so a query can reach a related passage without that passage containing the query terms. Optional embeddings add a semantic axis, but the README is explicit that they are disabled by default. That default matters more than it looks. It means a fresh install does not start an embedding model and does not require an embedding API key, so the first thing you can verify is pure lexical and graph retrieval. The claim in the README is that this returns line-level passages rather than loading the whole knowledge base into the agent context. I cannot confirm the recall quality of that combination from the material, and the README points to a separate memory search guide and a blog post for the benchmark discussion rather than stating a number inline.

Getting It Running: pip, .env and reme start

Installation assumes Python 3.11 or newer. The pip route is a single command: pip install "reme-ai[core]". The source route clones the repository, installs the Python package and the reme_studio directory in editable mode, then builds the Studio frontend with npm ci and npm run build:static, which the README says needs Node.js 22.13 or newer. Studio is the browser surface; if you only want the service and the CLI, the pip path is enough. Configuration is a .env file. LLM_API_KEY and LLM_BASE_URL are described as required for auto_memory, auto_resource, auto_dream and proactive refresh. EMBEDDING_API_KEY and EMBEDDING_BASE_URL are commented out by default and are only used after embedding components are explicitly enabled in the config. Starting the service is reme start, which binds 127.0.0.1:2333. Port conflicts are handled with an override argument rather than an edit: reme start service.port=8181, and the README also shows reme start workspace_dir=/tmp/reme-demo service.port=8181, which tells you workspace_dir is a first-class config key for relocating the memory root. Health and version checks are reme health_check and reme version, or over HTTP with a POST to /version carrying an empty JSON object. The demo sequence is reme write with path, name, description and content, then reme search query="agent memory markdown" limit=5, then reme read path=... .

Turning On Embeddings Is a Config Edit, Not a Flag

The README's note on semantic retrieval is the part most likely to trip people up. To enable embedding-based retrieval you uncomment components.as_embedding and components.embedding_store in reme/config/default.yaml, then change components.file_store.default.embedding_store from an empty string to default. That is three coordinated edits in a YAML file, and the failure mode is quiet: leave the file_store key empty and the embedding component is configured but never wired into the store that serves reads. There is no single switch. This is a reasonable design if you treat the config as the source of truth, and an annoying one if you expect an environment variable to do it. The upside is that the default path stays cheap. BM25, wikilink traversal, basic file operations and reading proactive topics all run without LLM credentials, per the README, so you can evaluate the retrieval model before you spend anything on a model provider. The downside is that the interesting self-evolving behaviour (auto_memory, auto_resource, auto_dream) is gated behind LLM_API_KEY, so the free tier and the full product are meaningfully different things.

Where ReMe Is the Wrong Tool

ReMe runs as a service. That is a real constraint, not a footnote. If your deployment model is a single Python process with no daemon, no port to bind and no .env to manage, then reme start on 127.0.0.1:2333 is friction you have chosen to accept. The same applies to multi-tenant SaaS: the README frames this as a personal knowledge base with a local workspace, and the demo paths (digest/wiki/...) are filesystem paths, so isolation between users becomes a workspace_dir problem you have to solve yourself. There is also a versioning cost. The README links back to 0.3.x, 0.2.x and a MemoryScope branch, and the release list shows several v0.4.1.x builds within days of each other in late August and early September 2026. Rapid patch releases on a young interface mean the CLI argument syntax and the config schema are the things most likely to move under you. Finally, the wikilink expansion is only as good as your link discipline. If agents write nodes without linking them, you are left with BM25 over a pile of files, and the graph half of the retrieval story contributes nothing.

How This Differs From a Vector-Database Memory Layer

The obvious alternative is the common pattern of embedding every message and storing the vectors in a database such as a vector index behind a retrieval API. The difference is not the embedding model, since ReMe supports embeddings too. It is what counts as the durable artifact. In the vector-first approach the vectors are the memory and the text is a payload you may or may not keep; deleting the index means deleting the memory. In ReMe the Markdown files are the memory and the index is explicitly described as rebuildable, which changes the operational story: you can move the workspace, diff it in git, or back it up with ordinary file tools, and a corrupted index is a re-index rather than data loss. The second difference is the retrieval unit. Vector search returns chunks ranked by similarity. ReMe combines BM25 with wikilink expansion, so a result can be justified by an explicit link an agent or a human wrote, not only by a distance in embedding space. That is a more auditable result, and a narrower one: it depends on links existing. If your data is a large corpus of unlinked documents, the graph expansion does less work and the comparison tilts back toward a pure vector store.

Licence, Maintenance and the Cost of Upgrading

ReMe is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant, with the usual requirements around preserving notices and stating changes. That is a permissive licence and it is a reason the file-based design is attractive: you can fork it, and because memory is stored as plain Markdown, leaving the project does not strand your data. I am not a lawyer and this is not legal advice; check the LICENSE file and your own obligations. The maintenance cost is the part the README does not quantify. What it does show is a project moving quickly: releases v0.4.1.9, v0.4.1.10 and v0.4.1.11 land within four days of each other, and the README carries an npm package, a Studio frontend, an HTTP surface, an MCP surface, a CLI and Python APIs. Every one of those is an interface that can change. The practical upgrade cost is therefore not the Python dependency, it is re-validating your config against reme/config/default.yaml and re-checking that your agent integrations still speak the current protocol. Pin a version, keep your workspace in version control, and treat the config file as something you re-read on each bump rather than something you set once.

Editorial conclusion

Adopt ReMe if your agents need memory that a human can open, diff and back up with normal file tools, and if you are willing to run a local service on 127.0.0.1:2333 and keep a .env with LLM_API_KEY for the auto_memory, auto_resource and auto_dream paths. Skip it if you want an in-process library with no daemon, or if your memory is already locked inside a vector database you cannot export. Before committing, run reme start, write one node, and confirm two things yourself: that the wikilink syntax in your content produces the retrieval you expect, and that the default config leaves embeddings off, so nothing calls an embedding endpoint until you edit reme/config/default.yaml.

Official sources

1. agentscope-ai/ReMe on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases