AI agents are becoming increasingly useful in software projects, but they still have a very concrete weakness: they lose operational context far too easily. A session can produce good code, useful analysis, a troubleshooting path or an architectural decision; then most of that value disappears, unless someone turns it into durable project documentation.
MEM, short for Markdown Embedded Memory, is a project designed to solve this problem with a deliberately transparent approach: a readable, indexed and persistent operational memory for AI agents, stored in Markdown and maintained as an integral part of the project.
The project is available on GitHub at github.com/Ryadel/MEM. At its core is a bootstrap file, MEM.md, which tells the agent how to load the project memory, how to interpret the knowledge base, when to update it, how to preserve activity logs and how to handle project-specific rules.
MEM also introduces two important concepts: support for a remote MEM source and an extension model for specific operational behaviors. These additions make the project more interesting, because they take it beyond local documentation and bring it closer to a true reusable operational layer for agentic workflows.
What MEM is
MEM is a Markdown-based project memory system for AI agents. It gives the agent a stable context layer that can be read, reviewed, versioned and updated over time.
The idea is simple: a project should not depend on chat history to remember how it works. Architecture notes, conventions, decisions, troubleshooting entries, task status and daily activity should live in a structured knowledge base that both humans and agents can consult.
MEM uses plain Markdown files for this purpose. The main file, MEM.md, acts as the agent's bootstrap memory. When an agent starts meaningful work, it reads that file first, then loads MEM.config.md if present, and then uses the configured knowledge base root as the project's persistent technical memory.
This way the agent has operational context before it starts changing code, answering questions about the project or writing documentation. Even more importantly, the project gets a place where useful knowledge can accumulate instead of staying trapped inside a single conversation.
Compatibility
MEM is compatible with any AI coding assistant or LLM agent that can read Markdown files and work on a repository. It can be used with Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Visual Studio Code with AI extensions, Visual Studio with chat or coding assistant extensions, and with custom agents based on GPT, Claude, Gemini, Llama or equivalent models.
It requires no SDK, runtime or proprietary integration: just make the MEM.md file available and ask the agent to read it and apply it as the project's persistent operational memory.
How to use it
Installing and using MEM is extremely simple: you can choose between an automatic installation, driven by the LLM, or a manual one, handled by the user.
Automatic installation
The quickest way is to give your AI coding assistant or LLM agent the URL of the latest version of the MEM.md file and ask it to install MEM in your project.
A typical prompt might be:
1 2 3 | Download the latest version of the MEM.md file 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. |
The agent should create the destination folder if it does not exist, save the file locally and then use it as the project's bootstrap memory.
Manual installation
If you prefer to control the installation flow directly, follow these steps:
- Download the latest version of the
MEM.mdfile from the MEM GitHub repository. - Place it in a suitable top-level folder inside your project, for example
MEM. - Open your favorite AI coding assistant or LLM agent.
- Ask the agent to read and apply the
MEM.mdfile before doing any non-trivial work on the project. - Let the agent initialize or update the project knowledge base as the work progresses.
A typical first prompt might be:
1 2 | 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. |
From then on, the agent can use MEM as the project's persistent context layer: it can read existing documentation, update daily logs, record decisions, preserve troubleshooting notes and keep the knowledge base aligned with the actual source code.
Source of Truth
MEM introduces an important distinction: the source code remains the source of truth for the implementation, while the MEM-powered Knowledge Base is the explanatory layer.
This separation is one of MEM's most significant distinguishing features: a project "memory" can become dangerous if it starts replacing inspection of the actual implementation. MEM avoids this risk by requiring the agent to inspect the actual source code before making claims about the implementation. Documentation can explain how the project works, why certain decisions were made and which conventions apply, but it must not drift away from the codebase. Memory helps the agent work faster and with greater continuity, but it does not justify shallow assumptions. If a behavior is inferred from the code, MEM requires source references; if something is uncertain, the uncertainty must be stated explicitly.
A structured MEM-KB
A default MEM-KB (short for MEM Knowledge Base) has a compact structure:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | KB_ROOT/ MEM.md MEM.config.md MEM.remote-cache.md MEM.index.md MEM.project.md architecture/ docs/ conventions/ decisions/ logs/ drafts/ tasks/ troubleshooting/ references/ glossary/ changelog/ archive/ index.md extensions/ EXT.md EXT.index.template.md <extension-id>/ index.md |
The structure is fairly straightforward: MEM.index.md is the entry point for navigation; MEM.project.md describes the project's identity, domain, stack and constraints; architecture/ explains how the system currently works; docs/ holds broader technical or functional documentation.
The other folders cover the knowledge that tends to get lost between sessions: logs/ records activity, tasks/ tracks work items, troubleshooting/ keeps diagnosed errors and verified solutions, decisions/ holds ADRs, while conventions/ collects project-specific rules.
The goal is not to build a large documentation framework. MEM prefers small, accurate updates over long, speculative pages. Useful memory grows incrementally: a troubleshooting note after a real diagnosis, an ADR after a significant decision, a daily log after a relevant work session.
Persistent Activity Logs
One of MEM's most useful features is the daily log. Files such as logs/YYYY-MM-DD.md record factual information about the work done during a session: what changed, which files were touched, which problems were found, what is still pending and which notes may help future sessions.
This is especially useful with AI agents, because conversations contain too much noise. They include attempts, corrections, temporary assumptions and side paths that are not useful as permanent documentation. A MEM log should preserve the outcome, not the whole transcript.
A good log entry can be short and still valuable. For example, it can record that token validation was refactored, that a specific controller and a configuration file were changed, that integration tests are still missing and that a related troubleshooting note was added. That is enough for a future agent, or a human maintainer, to pick up the work without rebuilding everything from memory.
Remote MEM source
By default, MEM is loaded from the local MEM.md file. However, MEM.config.md can now define a remote source by setting mem_source: "remote" and providing a mem_remote_url. In this configuration, the local MEM.md file becomes a bootstrap loader: the agent must fetch the remote MEM document and use it as the active operational context.
This opens up several practical scenarios. A team can keep a shared MEM policy in a central location and let multiple repositories load it. An organization can maintain common rules for documentation quality, security boundaries, agent behavior and operational discipline, while each project keeps its own knowledge base. A consultant or maintainer can reuse a consistent MEM configuration across multiple client projects without manually copying the whole operational contract.
MEM also defines failure policies for remote loading:
stop: stops the work and reports that the remote MEM cannot be loaded.fallback_local: continues with the localMEM.mdand reports the fallback.fallback_cache: continues with the cached remote file, if available; otherwise it stops.
Remote MEM support changes the scale of the project. A local Markdown memory is useful for a single repository, but a remote bootstrap model is useful for a group of projects that need to share operational rules.
In real technical contexts this makes a difference. Teams often want consistent behavior across repositories: how agents should document their work, when ADRs are needed, how to write troubleshooting notes, how to handle secrets and which external actions require confirmation. Without a shared source, these rules get copied, forked and slowly forgotten.
Remote MEM gives these rules a single place to live, while preserving the local project context inside each repository. The local knowledge base can keep describing actual code, architecture, tasks and logs. The remote document can define the common operational contract.
MEM also clarifies the precedence rules: remote content cannot override explicit user instructions or higher-priority system and developer instructions. In addition, it must not contain secrets. This boundary is essential if the remote memory is used across multiple projects or teams.
Operational Extensions
Another important MEM feature is the extensions/ area. MEM defines Operational Extensions as optional modules for task-specific behaviors. They can contain routines, checklists, commands, API calls, notification flows or other actions that do not belong in the project's general knowledge base.
The entry point for extensions is extensions/EXT.md, which acts as the active extensions index. Each actual extension lives in its own folder and exposes its main instructions in extensions/<extension-id>/index.md. The template file extensions/EXT.index.template.md defines how new extension indexes should be structured.
It is a useful separation. The general project memory should stay stable and broadly applicable. Extensions can be more targeted: release routines, deployment checklists, incident handling, content publishing flows, ticket synchronization, QA procedures or workflows specific to a given integration.
An agent reads Operational Extensions only when they are relevant: when the user explicitly asks for an extension's behavior, when the task clearly matches an active extension, or when a KB page points to one of them. This avoids loading unnecessary operational instructions during unrelated work.
Side effects and security
MEM treats external side effects carefully. An extension can define actions such as HTTP requests, notifications, deployments, ticket creation or writes to external systems. These actions can change state outside the local repository, so the specification requires explicit user confirmation, unless allow_extension_external_side_effects: true is set in MEM.config.md.
This is the right default. A memory system for agents should make work more repeatable, but it should not silently turn documentation into automation with external impact. The updated defaults also include require_confirmation_for_extension_side_effects: true, reinforcing the same principle.
Extensions are also forbidden from sending secrets, tokens, passwords, real environment variable values, raw logs or unnecessary personal data. If an extension action fails, the agent should report the error and avoid aggressive retries, unless the user explicitly asks for them. These constraints make the extension model more credible, because they anticipate the risks of operational automation instead of treating them as a secondary detail.
Configuration file
MEM.config.md is where project-specific behavior is defined. The updated defaults include both the remote source settings and the extension settings:
1 2 3 4 5 6 7 8 9 | mem_source: "local" mem_remote_url: null mem_remote_cache: false mem_remote_cache_path: "MEM.remote-cache.md" mem_remote_fail_policy: "stop" enable_operational_extensions: true allow_extension_external_side_effects: false require_confirmation_for_extension_side_effects: true |
The precedence model remains explicit. The user's instruction for the current task has the highest priority, followed by MEM.config.md, then by the defaults in MEM.md, and finally by values automatically detected from reliable project files.
This hierarchy keeps MEM flexible without making it unpredictable. A repository can define its own defaults, a remote MEM can provide a shared operational layer, and the user can still override the behavior for the current task when needed.
Practical use cases
MEM is particularly well suited to long-running software projects, especially when AI agents are involved in coding, refactoring, troubleshooting or documentation. It also works well for infrastructure repositories, internal tools, security projects, technical writing pipelines and any project where losing context has a real cost.
The remote source feature makes it better suited to organizations that maintain multiple repositories. The extension model makes it more useful for projects with repeatable operational routines. Together, these two features move MEM from a local documentation convention to a practical memory framework for agents.
The format stays deliberately simple: Markdown can be reviewed in pull requests, searched with standard tools and edited by humans without a dedicated platform. This transparency is one of MEM's strengths: the memory is not hidden inside a proprietary agentic system and can evolve together with the project.
Known limitations
MEM does not replace tests, code review or human judgment. It gives AI agents better working context, but the quality of that context depends on the quality of the updates. If the agent writes vague notes, does not inspect the source files or leaves outdated claims lying around, the memory will become unreliable.
