How the Agent Works

MEM.md is mostly about the knowledge base, but it also sets rules for how the agent behaves while it works: what it reads and when, how it keeps its context small, where it puts throwaway files, how it commits, and what it never does without asking. This page explains those rules and the reasons behind them.

Each session starts from the knowledge base

At the start of a session the agent reads, in order: MEM.md, MEM.config.md, MEM.index.md, MEM.project.md, and extensions/EXT.md when extensions are enabled. It then reads only the pages relevant to the request. Before a non-trivial change it reads the related pages and inspects the code: the code is the truth about what the system does, the knowledge base explains it.

To answer a question about the project, the usual path is index, relevant pages, source if needed, answer, then a knowledge base update if something durable came out of it.

Reading economically

Everything an agent reads stays in the conversation and is sent again with every later request. A page read once at the start of a long session may be paid for a hundred times. MEM therefore asks the agent to:

• read knowledge base pages one at a time, and only the ones the request needs;
• use its own file-reading tool, not shell commands such as cat, type or Get-Content. Shell output can be altered by filters, such as output-compression hooks, and one command can concatenate far more than needed. Searching with grep and similar tools is fine;
• not re-read a page that is still in the conversation, unless the page changed, the conversation was compacted, its exact text is needed for a quote or an edit, or you asked for MEM FORCE.

Delegating exploratory work

The same arithmetic applies to everything the agent reads along the way. When a client supports subagents, the agent should hand them work whose raw output is large but whose value is a conclusion: broad searches, reading many files, measurements, research. The subagent returns what is needed to decide, plus where its raw material is. The main session keeps the conclusions, not the bulk, and durable conclusions go to the knowledge base.

Small tasks, edits that depend on the conversation, and decisions to take with you stay in the main session: a subagent starts without the conversation's context and carries its own fixed overhead.

The mem-stats extension measures how much of each request these rules save, and mem-optimize acts on the rest of a session's lifecycle.

Temporary files go in one place

Agents produce throwaway files: a second build because the IDE has the first one locked, test runs, a script to try something, a converted document. Left alone they scatter them, and the clutter gets committed or, worse, compiled into a project.

MEM gives them one folder, .tmp/ at the repository root (rename it with agent_tmp_dir):

• Never inside a project folder, because build tools pick up everything in their own directory. The leading dot helps too, since the .NET SDK skips dot-folders, so keep it if you rename the folder.
• Excluded from git before it exists. If git does not already ignore it, the folder's first file is its own .gitignore containing *, which touches none of your files. A line in your root .gitignore is used instead only if you confirm it.
• Never adopted by mistake. A .tmp folder the agent did not create is never emptied, and the agent asks before writing into it.
• Tidy inside. A reused cache keeps a fixed name such as build/; everything else goes in one folder per task, named with its date and a short description, for example 2026-10-09-pdf-to-md/.
• Self-cleaning. At the start of each session the agent deletes every entry nobody has used for 7 days (agent_tmp_retention_days, 0 turns it off). Age counts from the last use, so a build reused daily is never deleted, and entries are removed whole so an incremental build is never left half-deleted. This is safe because nothing in the folder is ever the only copy of a result: the agent checks that before ending a session.
• Isolated builds done right. When it builds beside a locked build, the agent redirects intermediates as well as outputs; two builds sharing obj/ corrupt each other. On .NET 8 and later, dotnet build --artifacts-path .tmp/build does both.

Commits are yours, and unsigned by the agent

• The agent commits and pushes as you: with the name, email and credentials git is already configured with. It never sets a different author, never overrides user.name or user.email, never brings its own token. Only an explicit instruction, such as using a dedicated bot account, changes that.
• With agent_credit: false (the default) nothing the agent writes into version control or publishes for the project carries a line crediting an AI agent, model or tool: no Co-authored-by: trailer, no "Generated with" line, no signature, even when the agent's own tooling adds one by default. Organisations that must disclose AI assistance set agent_credit: true and document the form they want. An explicit request for a specific commit wins either way, and trailers for people you name are untouched.
• Existing history is never rewritten to remove such lines.
• The agent does not commit or push unless you ask.

Changing code

Before modifying code the agent understands the request, inspects the relevant files, checks your conventions, considers side effects, makes the smallest coherent change, and updates or proposes tests where they make sense. It does not introduce patterns that conflict with your documented conventions. When existing code and a documented convention disagree, it points out the conflict and asks which one to follow.

If you only ask it to initialize or update the knowledge base, it does not touch source code.

No windows popping up

Scripts and tests the agent writes and runs should start their child processes without visible windows. A test suite that spawns interpreters can otherwise flash dozens of console windows while you work. For code shipped by extensions this is mandatory; see Extensions.

Asking before acting outside the repository

Actions that change something outside the local repository need your explicit confirmation: HTTP requests, notifications, deploys, ticket creation, writes to external systems. Only extensions_allow_external_side_effects: true in MEM.config.md waives that, and some extensions ask regardless. Nothing the agent sends out may contain secrets, tokens, real environment variable values, raw logs or unnecessary personal data.

What the agent never claims

MEM state lives in files under KB_ROOT and nowhere else. The agent must not claim to have "remembered" something in hidden model memory, and must not present a guess as a fact: unverified statements are marked as such (see Knowledge Base).