MEM: Persistent Operating Memory for AI Agents Empower AI-assisted projects with a readable, indexed and persistent operating memory layer that helps preserve context, document work and support long-running technical workflows

AI agents are becoming increasingly useful in software projects, but they still have a very practical weakness: they lose operational context 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 that problem with a deliberately transparent approach: a readable, indexed and persistent operating memory for AI agents, stored as Markdown and maintained as part of the project itself.

The project is available on GitHub at github.com/Ryadel/MEM. At its core there 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.

Furthermore, MEM also introduces two important concepts: support for a remote MEM source, and an extension model for task-specific operational behavior. These additions make the project more interesting because they move it beyond local documentation and toward a reusable operating layer for agentic workflows.

What MEM is

MEM is a Markdown-based project memory system for AI agents. It gives an 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 inspect.

MEM uses plain Markdown files for that 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 the optional MEM.config.md, then uses the configured knowledge base root as the persistent technical memory for the project.

This gives the agent an operating context before it starts editing code, answering project questions, or writing documentation. More importantly, it gives the project a place where useful knowledge can accumulate without being trapped inside one conversation.

Compatibility

MEM does not require a specific runtime, dedicated SDK or proprietary integration: it is compatible with any AI coding assistant or LLM agent that can read Markdown files, inspect a repository and update project files.

This means it can be used with tools such as Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Visual Studio Code with AI extensions, Visual Studio with chat extensions or coding assistants, as well as any custom agent based on models such as GPT, Claude, Gemini, Llama or similar.

The only practical requirement is that the tool can access the MEM.md file and treat it as the project’s persistent operating context. From that point on, MEM remains vendor-independent: the agent reads the instructions, consults the knowledge base, updates logs and documentation, and keeps the context aligned with the repository according to the rules defined by the project.

How to use

Installing and using MEM is incredibly simple: you can choose between automatic (LLM-driven) or manual (user-driven) install.

Automatic install

The fastest way is to give your AI coding assistant or LLM agent the URL of the latest MEM.md file and ask it to install MEM in your project.

A typical prompt can be:

The agent should create the target folder if it does not exist, save the file locally, then use it as the bootstrap memory for the project.

Manual install

If you prefer to control the installation flow, perform the following steps:

• Get the latest version of the MEM.md file from the MEM GitHub repository.
• Place it under a suitable root-level folder of your project, such as MEM.
• Open your favourite AI coding assistant or LLM agent.
• Ask the agent to read and apply the MEM.md file before doing any non-trivial work on the project.
• Let the agent initialize or update the project knowledge base as work progresses.

A typical first prompt can be:

From that point 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 makes an important distinction: the source code remains the implementation source of truth, while the (MEM-powered) Knowledge Base is the explanation layer.

This separation of concerns is one of the MEM's most important distinctive features: a project "memory" can become dangerous if it starts replacing inspection of the real implementation. MEM avoids that by requiring the agent to inspect the actual source code before making implementation claims. Documentation can explain how the project works, why decisions were made, and which conventions apply, but it must not drift away from the codebase. The memory helps the agent work faster and with better continuity, but it does not excuse shallow assumptions. If behavior is inferred from code, MEM expects source references: if something is uncertain, the uncertainty should be marked explicitly.

A structured MEM-KB

A default MEM-KB (shortcut for MEM Knowledge Base) has a compact structure:

The structure is quite straightforward: MEM.index.md is the navigation entry point; MEM.project.md describes the project identity, domain, stack, and constraints; architecture/ explains how the system currently works; docs/ stores broader technical or functional documentation.

Other folders cover the knowledge that tends to disappear between sessions: logs/ records activity, tasks/ tracks work items, troubleshooting/ preserves diagnosed errors and tested fixes, decisions/ stores ADRs, while conventions/ captures project-specific rules.

The goal is not to create a large documentation framework. MEM prefers small, accurate updates over long speculative pages. A useful memory grows incrementally: one troubleshooting note after a real diagnosis, one ADR after a meaningful decision, one daily log after meaningful work.

Persistent Activity Logs

One of the most useful features of MEM is the daily log. Files such as logs/YYYY-MM-DD.md record factual information about the work performed during a session: what changed, which files were touched, which problems were found, what remains 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 full transcript.

A good log entry can be brief and still valuable. For example, it can record that token validation was refactored, that a specific controller and configuration file were modified, 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 resume work without reconstructing everything from memory.

Remote MEM source

By default, MEM is loaded from the local MEM.md. However, MEM.config.md can now define a remote source by setting mem_source: "remote" and providing a mem_remote_url. In that configuration, the local MEM.md becomes a bootstrap loader: the agent must fetch the remote MEM document and use it as the active operating context.

This opens 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 still keeps its own knowledge base. A consultant or maintainer can reuse a consistent MEM setup across client projects without copying the full operating contract manually.

MEM also defines failure policies for remote loading:

• stop: stop the work and report that the remote MEM could not be loaded.
• fallback_local: continue with the local MEM.md and report the fallback.
• fallback_cache: continue with the cached remote file, if available; otherwise, stop.

Remote MEM support changes the scale of the project. A local Markdown memory is useful for one repository, but a remote bootstrap model is useful for a group of projects that need shared operating rules.

This matters in real technical environments. Teams often want consistent behavior across repositories: how agents should document work, when ADRs are required, how troubleshooting notes should be written, how secrets must be handled, and which external actions require confirmation. Without a shared source, these rules are copied, forked and slowly forgotten.

Remote MEM gives those rules a single place to live, while preserving local project context inside each repository. The local knowledge base can still describe the actual code, architecture, tasks and logs. The remote document can define the common operating contract.

MEM also makes the precedence rules clear: remote content cannot override explicit user instructions or higher-priority system and developer instructions. It also must not contain secrets. That limitation is essential if remote memory is used across multiple projects or teams.

Operational Extensions

Another major feature of MEM is the extensions/ area. MEM defines Operational Extensions as optional modules for task-specific behavior. They can contain routines, checklists, commands, API calls, notification flows, or other actions that do not belong in the general project knowledge base.

The extension entry point is extensions/EXT.md, which acts as the active extension index. Each real extension lives in its own folder and exposes its main instructions at extensions/<extension-id>/index.md. A template file, extensions/EXT.index.template.md, defines how new extension indexes should be structured.

This is a useful separation. General project memory should remain stable and broadly applicable. Extensions can be narrower: release routines, deployment checklists, incident handling, content publishing flows, ticket synchronization, QA procedures, or integration-specific workflows.

An agent reads Operational Extensions only when they are relevant: when the user explicitly asks for extension behavior, when the task clearly matches an active extension or when a KB page points to one. That avoids loading unnecessary operational instructions during unrelated work.

Side effects and safety

MEM treats external side effects with care. An extension may define actions such as HTTP requests, notifications, deploys, 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 failure and avoid aggressive retries unless the user asks. These constraints make the extension model more credible because they anticipate the risks of operational automation instead of treating them as an afterthought.

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:

The precedence model remains explicit. The user’s instruction for the current task has the highest priority, followed by MEM.config.md, then the defaults in MEM.md, then auto-detected values from reliable project files.

This hierarchy keeps MEM flexible without making it unpredictable. A repository can define its defaults, a remote MEM can provide a shared operating layer, and the user can still override the behavior for the current task when necessary.

Practical use cases

MEM is a strong fit for 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 context loss has a real cost.

The remote source feature makes it more suitable for organizations that maintain multiple repositories. The extension model makes it more useful for projects that have repeatable operational routines. Together, they move MEM from a local documentation convention to a practical agent memory framework.

The format remains intentionally simple: Markdown can be reviewed in pull requests, searched with standard tools, and edited by humans without a dedicated platform. That transparency is one of MEM’s strengths: the memory is not hidden inside a proprietary agent system, and it can evolve with the project.

Known limitations

MEM does not replace tests, code review, or human judgment. It gives AI agents a better working context, but the quality of that context depends on the quality of the updates. If the agent writes vague notes, fails to inspect source files, or leaves obsolete claims in place, the memory will become unreliable.

The specification addresses this risk with source references, uncertainty markers, and knowledge base linting. MEM asks agents to review the KB periodically for stale claims, contradictions, orphan pages, unresolved drafts, and documentation that no longer matches the code. That is not glamorous work, but it is exactly what keeps a project memory usable over time.

Conclusions

MEM started from a simple need: give AI agents persistent project memory that humans can read and maintain. With remote MEM support and Operational Extensions, it becomes a more complete operating layer for agent-assisted technical work.

The project is still grounded in plain Markdown, which is the right choice for this kind of tool. It keeps the memory visible, versionable and easy to correct. The newer features add scale and extensibility without hiding the mechanism behind an opaque platform.

For teams already experimenting with AI agents in development workflows, MEM is worth watching because it addresses one of the less glamorous but most important problems in agentic work: preserving the context that makes future work better.

References

• MEM: Markdown Embedded Memory: official GitHub repository for the MEM project.
• Markdown Guide: practical reference for Markdown syntax and formatting.
• Architecture Decision Records: overview and resources about ADRs and lightweight decision documentation.
• GitHub Docs: About READMEs: useful background on repository-level documentation practices.

Print Friendly & PDF Download