In a previous article we introduced MEM (Markdown Embedded Memory), the open source project that gives AI agents a persistent project memory, written in Markdown and kept inside the repository. The project has grown a lot since then, and version 1.2.2 is a good moment to take stock.
The core is still what it was: a specification, not software. It needs no runtime, SDK or dependencies, and it works with any agent that can read Markdown files and work on a repository, from Claude Code to OpenAI Codex, GitHub Copilot, Cursor and Windsurf. What changed is everything around the core: reserved commands for the most frequent operations, an extension catalogue you install from on demand, and five ready-to-use extensions, two of which tackle a very concrete problem: what a working session with an agent really costs.
What's new at a glance
From 1.0.4 to 1.2.2, MEM introduced:
- reserved commands,
MEM <COMMAND>, with six core commands available on every installation; - an extension catalogue (the manifest), with an explicit authorization model, version checks and an extension offer at first initialization;
- support for extensions that ship code, off by default and subject to a separate approval;
- five distributed extensions:
mem-commands,mem-toolbox,mem-workspace,mem-statsandmem-optimize; - new core rules on how to read the knowledge base, when to delegate to a subagent, where the agent's temporary files go and how commits are signed.
Reserved commands
The first visible change is a small command grammar. A line that starts with MEM, followed by an uppercase command, is an explicit instruction: the agent follows a documented procedure instead of inferring one from free text.
1 | MEM <COMMAND> [<SUBCOMMAND>] [target] |
When a command activates, the agent opens its reply with a line such as > MEM HELP: active, so a wrong activation is visible at once. A command quoted in a sentence, shown in a code block or written in lowercase does not activate.
There are six core commands, available without any extension:
MEM HELP: lists the available commands;MEM HELP <extension-id>explains one extension in full.MEM STATUS: MEM version,KB_ROOT, the configuration in effect, and the registered extensions with their installed and available versions.MEM INIT: initializes the knowledge base, including the extension offer.MEM UPDATE: updatesMEM.md, applies the upgrade steps and checks extension versions.MEM LINT: reviews the knowledge base, or one part of it.MEM FORCE: re-anchors the session, making the agent re-read the memory and the code and report which MEM files it read and which it changed.
Extensions add their own commands to the same namespace, and cannot override the core ones. You do not even need a command to learn what an extension does: type its name, alone or with a word asking for help (mem-optimize ?, explain mem-optimize), and the agent answers with its full help, changing nothing.
The extension catalogue
In the previous article, extensions were little more than an extensions/ area with an index. Today they are a complete mechanism. MEM publishes a catalogue, the manifest, which lists the available extensions, what each one provides and the exact list of files it is made of.
The key point is that the catalogue authorizes nothing. It is fetched over the network and its URL is configurable, so it cannot decide what runs in your repository. An extension is used only when its files are present under KB_ROOT/extensions/and it is registered as active in extensions/EXT.md: two files you review in a pull request like any other.
This gives two clearly distinct moments:
- installing an extension, or letting it write files, run commands or act outside the repository, requires your explicit approval, beforehand;
- using an extension already registered only requires disclosure: the agent names it on its acknowledgement line.
At first initialization, and after any update that brings a new extension, the agent asks a single multiple-choice question ("which extensions do you want to install?"), followed by one confirmation listing every file to be written and the URL it comes from. Extensions you do not choose are registered as declined and are not offered again.
Each extension has two layers: the base layer, distributed with MEM and replaced on every update, and the custom layer, under custom/, which belongs to the project and is never touched. Finally, every MEM.md update compares each installed extension's version with the catalogue's and reports the gap, without ever updating on its own.
Extensions that ship code
Almost everything MEM distributes is Markdown the agent reads. Some extensions, however, need a program: a hook that runs at the end of every agent turn cannot be a text instruction. These extensions declare executable content: yes and follow stricter rules:
- they are off by default: they are installed and run only with
extensions_allow_executable_content: true, and the agent never changes that setting on its own; - installing asks for an approval that names the executable files as code, and every update asks again;
- the code is copied into your repository, so each update arrives as a diff you can review in a pull request;
- it must not open console windows on your desktop, since hooks fire on every turn.
MEM does not pretend to sandbox this code: the safeguard is your approval and your ability to review it, not a promise.
The available extensions
mem-commands
mem-commands (1.0.0) adds three commands designed for day-to-day work with an agent. MEM REVIEW assesses a plan, a task or a troubleshooting note before it is implemented. MEM CHECK assumes some work was declared complete and verifies it against what actually exists: the diff, the source, the build and test results. MEM DEFINE lets you write commands of your own for the project. REVIEW and CHECK are read-only and produce a report with severity levels and a verdict.
mem-toolbox
mem-toolbox (1.0.3) answers two questions an agent would otherwise ask itself every session: which tool or library to use for a given task, and whether that tool is actually installed on this machine. Its catalogue covers media, documents and data (ImageMagick, ffmpeg, pandoc, typst, ReportLab, pandas, DuckDB and more), and the project can override it with entries of its own.
Tool availability, on the other hand, is a fact about one machine, so since 1.0.3 it lives in a single file per computer, ~/.mem/mem-toolbox/host.md, outside every repository and shared by all projects. The portable tools folder and the agent's Python or Node environment are asked once per computer, and a tool found while working on one project is known in all the others. The agent may install a package only into a dedicated environment, and only after an approval naming the package, version and registry.
mem-workspace
mem-workspace (1.0.0) is for those who want to keep the knowledge base in a private repository beside the public one, instead of inside it. The layout is simple: a workspace folder that is not a repository, holding the public repository, the private one with the knowledge base and, if needed, the wiki.
1 2 3 4 | <workspace root>/ public/ the product (public) private/ the knowledge base (private) wiki/ optional |
Privacy then comes from the remote, not from a .gitignore line, and the knowledge base finally gets history and backup. The extension teaches the agent which repository each file belongs to, and adds MEM WORKSPACE CHECK, which verifies that no private path or file has reached a public repository, history included.
mem-stats
mem-stats (0.1.1) measures what agent sessions really consume, using the logs clients already write on your machine: Claude Code transcripts and Codex rollouts. It records tokens per request, what fills the context (MEM included), where and why the prompt cache was rewritten, compactions and fresh starts, per project and for the whole machine.
An agent re-sends the whole conversation with every request, so a session costs mostly for what it carries: every page read, every tool result and every tool definition is paid again on each later request. mem-stats makes all this visible and answers questions like these with numbers: how much of my input is MEM? Which knowledge base pages weigh the most? Which tools am I paying for on every request without ever using them?
A wizard (MEM STATS SETUP) installs a hook that keeps the ledger current at the end of every turn at no token cost, and can import your whole history. The ledger is a local SQLite database that holds counts, never content: no prompts, no answers, no model calls, and nothing leaves the machine. Reports (MEM STATS REPORT) come as text or JSON, with the API-equivalent cost when a price card is available.
mem-optimize
mem-optimize (0.1.2) acts on what mem-stats measures, with one precise goal: keeping long sessions from wasting tokens. Its scope is the context lifecycle: when a session should end, how the work crosses into the next one, what happens after a long pause or a compaction. It does not filter or compress tool output, because in a long session the bill is driven by the context carried along, not by the latest output.
Its components, each of which can be enabled separately:
- Advisor: stays silent while the context is below the threshold (400k tokens by default); above it, the agent proposes a restart at the next natural breakpoint, and insists at 600k.
- Guided restart: only after you agree, the agent updates the resume point in the knowledge base and writes a short handoff note; after
/clear, or when you open a new conversation in the same project right away, the new session resumes from that note. - Long-pause stop: if you come back after the prompt cache has expired, on a context of at least 200k tokens, your first prompt is stopped once, because it would rewrite the whole context into the cache; the message is not lost and is carried into the new session.
- After a compaction: a short pointer asks the agent to re-read the knowledge base index and resume point.
- Unused tools: in Claude Code you can disable the tools you do not use, whose definitions would otherwise be re-sent with every request.
Finally, MEM OPTIMIZE PAGES lists the knowledge base pages that weigh most on your sessions, with a maintenance suggestion for each, and never edits them on its own. As with mem-stats, a wizard shows the complete plan and writes only after one confirmation.
mem-cleaner (in development)
The repository also contains mem-cleaner, designed for cleaning pipelines over files written by agents. It is still in development and not part of the catalogue.
Other core changes
Several changes concern the agent's behavior regardless of extensions:
- Economical reading: every page read stays in the conversation and is re-sent with every later request, so the agent reads knowledge base pages one at a time, only those it needs, with its own file-reading tool rather than through shell commands, and does not re-read a page it already has in context.
- Delegation: when it can delegate to a subagent, the agent hands off exploratory work with a lot of raw output and a value that lies in its conclusion (broad searches, reading many files, measurements).
- Temporary files: everything the agent produces for its own use goes in a single folder,
agent_tmp_dir, excluded from git before it is even created and cleaned up automatically after a number of days. - Commits as the user: the agent always commits and pushes with the user's configured git identity and, with
agent_credit: false(the default), adds no lines crediting the work to an agent or a model.
The new options appear in the MEM.config.md configuration block:
1 2 3 4 5 6 7 8 9 | agent_tmp_dir: ".tmp" agent_tmp_retention_days: 7 agent_credit: false extensions_enabled: true extensions_allow_external_side_effects: false extensions_allow_executable_content: false extensions_require_confirmation: true extensions_check_updates: true |
How to update
With mem_auto_update: true, the default, an existing knowledge base updates itself at the start of a session, applying the upgrade steps one version at a time. You can also ask for it explicitly with MEM UPDATE. Extensions are never updated or installed without your approval: the agent reports the available versions and offers the new extensions.
A new installation takes a single prompt:
1 2 3 | Download the latest MEM.md from https://raw.githubusercontent.com/Ryadel/MEM/main/src/MEM.md and save it to /MEM/MEM.md in this repository. Then read and apply /MEM/MEM.md as the persistent operational memory for this project. Initialize the MEM knowledge base if needed, then inspect the project before making claims about the implementation. |
During initialization the agent will offer you the extensions in the catalogue, and you choose which ones to install.
Conclusions
MEM 1.2.2 stays true to its original idea: a project memory in plain Markdown, visible, versioned and reviewable like the rest of the code. The new features add structure where it was needed: deterministic commands, an extension model that clearly separates what is offered from what is authorized and, with mem-stats and mem-optimize, the ability to see and reduce what working with an agent really costs.
The core still requires no runtime. Anything that needs one is an optional extension, and you decide whether to install it.
References
- MEM: Markdown Embedded Memory: official GitHub repository of the project.
- MEM Wiki: complete documentation of the core and of every extension.
- CHANGELOG: the detailed list of changes in every version.
- Extension catalogue: the manifest listing the distributed extensions and their files.
