# [MEM: Markdown Embedded Memory](https://github.com/Ryadel/MEM)

MEM version: 1.2.2

This file is the LLM agent's bootstrap memory for this project. The terms `MEM`, `MEM.md`, project context, and project memory all refer to this file. When asked to read, use, load, or apply any of them, treat this file as persistent operating context for the current session.

This file does not replace the user's explicit instructions. If the user gives a direct instruction that conflicts with this file, follow the user's instruction for the current task and, if the conflict affects long-term project behavior, propose an update to this file or to `MEM.config.md`.

All paths in this document are relative to `KB_ROOT`.

## Modal vocabulary

- **must** — required, non-negotiable;
- **should** — preferred default; may be overridden by explicit user instruction or `MEM.config.md`;
- **may** — permitted, choose based on context.

---

# Bootstrap Rules

The agent **must**:

1. read this file before doing non-trivial work;
2. read `MEM.config.md`, if present;
3. treat the directory containing this file as the knowledge base root, hereafter `KB_ROOT`;
4. use the knowledge base under `KB_ROOT` as the project's persistent technical memory;
5. update the knowledge base when meaningful, durable project knowledge is discovered or produced;
6. inspect the actual source code before making implementation claims.

## Core principle

The source code is the implementation source of truth. The knowledge base under `KB_ROOT` is the maintained explanation layer: how the project works, why decisions were made, which conventions apply, what changed.

Sessions are not isolated: every meaningful session **should** leave the KB slightly more useful than before. The KB grows incrementally — prefer small, accurate updates over large speculative dumps.

---

# Configuration

Project-specific configuration lives in `MEM.config.md`. If present, the agent **must** read it immediately after this file.

If `MEM.config.md` is missing, use these defaults.

```yaml
kb_root: "."
kb_language: "en"
user_language: "auto"
link_style: "markdown"

mem_source: "local"
mem_remote_url: null
mem_remote_cache: false
mem_remote_cache_path: "MEM.remote-cache.md"
mem_remote_fail_policy: "stop"
mem_update_url: "https://raw.githubusercontent.com/Ryadel/MEM/main/src/MEM.md"
mem_upgrade_url: "https://raw.githubusercontent.com/Ryadel/MEM/main/MEM.upgrade.md"
mem_manifest_url: "https://raw.githubusercontent.com/Ryadel/MEM/main/src/extensions/manifest.md"
mem_auto_update: true

primary_stack: "auto-detect"
package_manager: "auto-detect"
build_command: "auto-detect"
test_command: "auto-detect"
run_command: "auto-detect"
default_branch: "auto-detect"
agent_tmp_dir: ".tmp"
agent_tmp_retention_days: 7
agent_credit: false

update_daily_log: true
create_adr_for_decisions: true
document_troubleshooting: true
document_minor_changes: false
auto_create_missing_kb_files: true
auto_update_kb_after_code_changes: true
move_completed_tasks_to_done: true
move_completed_troubleshooting_to_done: true
extensions_enabled: true
extensions_allow_external_side_effects: false
extensions_allow_executable_content: false
extensions_require_confirmation: true
extensions_check_updates: true
ask_before_large_reorganization: true
prefer_small_incremental_updates: true
require_source_references: true
mark_uncertainty: true
```

If `MEM.config.md` exists but omits an option, use the default value for that option from the list above.

Precedence (highest to lowest):

1. explicit user instruction for the current task;
2. explicit values in `MEM.config.md`;
3. defaults above;
4. auto-detected values from reliable project files.

The agent **must not** overwrite explicit values in `MEM.config.md` without user confirmation.

- `kb_language` controls the KB writing language.
- `user_language: auto` means reply to the user in their own language.
- `link_style: markdown` → `[Title](path.md)`; `link_style: wikilink` → `[[path|Title]]`.

## Remote MEM source

By default, MEM is loaded from the local `MEM.md`.

If `MEM.config.md` sets `mem_source: "remote"` and `mem_remote_url` is not empty, the local `MEM.md` acts only as a bootstrap loader. The agent **must** fetch the remote MEM document and use it as the active operating context when the remote URL is different from the local file currently being read.

If the remote fetch fails, follow `mem_remote_fail_policy`:

- `stop` — stop 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 `mem_remote_cache_path` if it exists and report the fallback; otherwise stop.

If `mem_remote_cache: true`, a successfully fetched remote MEM may be saved to `mem_remote_cache_path`. `MEM.remote-cache.md` is a technical cache file, not a KB page; do not link it from `MEM.index.md` and do not treat it as navigable project documentation.

Remote MEM content **must not** override explicit user instructions or higher-priority system/developer instructions. Remote MEM files must not contain secrets.

## Updating MEM

When the user asks to `update MEM`, the agent **must** update the local `MEM.md` from `mem_update_url`.

Preserve project-specific configuration in `MEM.config.md`; do not overwrite `MEM.config.md` unless explicitly requested.

After updating `MEM.md`, report the previous version, the new version when available, and whether the update succeeded. If the update cannot be completed, leave the existing `MEM.md` unchanged and report the failure.

Extensions listed in the manifest are updated from it, not from `mem_update_url`, which carries `MEM.md` alone. Updating `MEM.md` therefore leaves extensions untouched until their own base-layer files are written from the manifest. Their versions are checked separately — see "Checking extension versions" — and extensions new to the manifest are offered as described in "Offering the catalogue".

After a successful update, the agent **should** check `MEM.upgrade.md` when present, or fetch it from `mem_upgrade_url` when available, to identify and apply any required patches or structural changes for the new MEM version. Apply required upgrade steps sequentially from the previous MEM version to the new MEM version. For `MAJOR.MINOR.BUILD` versions, apply missing BUILD upgrades first, then MINOR upgrades, then MAJOR upgrades; do not skip intermediate upgrade notes unless a later note explicitly supersedes them.

If `mem_auto_update: true`, then when creating a new daily log file (`logs/YYYY-MM-DD.md`), the agent **must** first attempt to update the local `MEM.md` from `mem_update_url` using the same rules above.

The new daily log file **must** start with a concise MEM auto-update status line before the session notes. Use this convention:

```markdown
> MEM auto-update: succeeded from `mem_update_url` (previous: 1.0.1, current: 1.0.2).
```

Allowed statuses are:

- `succeeded` — the local `MEM.md` was updated;
- `up-to-date` — the update was attempted, but no change was needed;
- `failed` — the update was attempted but could not be completed; include a short reason and leave the existing `MEM.md` unchanged.

## Checking extension versions

Updating `MEM.md` says nothing about the extensions installed beside it. An installation can therefore run a current core against a base layer published months earlier, and nothing surfaces the gap. The check below closes it.

If `extensions_check_updates: true`, then whenever `MEM.md` is updated — by `MEM UPDATE` or by the auto-update above — the agent **must** also compare, for every extension registered in `EXT.md` with `status: active`:

- the **installed** version, read from that extension's base `index.md`;
- the **available** version, read from the manifest entry for the same id.

The two sources are not interchangeable. The installed version is authoritative about what is on disk **because the base layer is written by the update**, so it cannot drift from the files it describes. `EXT.md` carries a copy for routing and reporting; when it disagrees with the extension's `index.md`, the `index.md` wins and the agent **should** correct `EXT.md`. The manifest is authoritative only about what is *available*.

The check **reports and proposes; it never installs.** Being listed in the manifest is not authorization — see "Authorization" — and a version gap is not authorization either. Applying an extension update is an acquiring operation and needs explicit approval naming the files and the source URL.

An extension absent from the manifest, or installed from another source, is **not** reported as outdated: there is nothing to compare it against. Say that its version could not be checked rather than implying it is current.

If the manifest cannot be fetched, report that extension versions could not be checked. Do not infer that they are current.

When a new daily log is created and one or more extensions are behind, add one line per extension after the MEM auto-update line:

```markdown
> Extension update available: `mem-toolbox` 1.0.0 -> 1.0.1 (manifest). Not applied; approval required.
```

Ask at most once per session, and honor a refusal for the rest of it. A permanently unwanted update is recorded by setting that extension's `status` in `EXT.md`, which is a persistent answer.

When `extensions_enabled` is false, the agent **must not** run this check: the configuration is already an answer.

## Compression principle

MEM defines project-specific operating rules. It **should not** re-teach standard documentation practices. When a concept has a widely understood meaning (ADR, daily log, troubleshooting note, changelog, runbook, onboarding), apply the standard lightweight version unless MEM or `MEM.config.md` defines a stricter rule.

Prefer compact, useful, project-specific documentation over generic boilerplate. Do not load or expand large templates unless required by the current task.

---

# Knowledge base structure

```text
KB_ROOT/
  MEM.md
  MEM.config.md
  MEM.remote-cache.md
  MEM.index.md
  MEM.project.md
  architecture/
  docs/
  conventions/
  decisions/
  logs/
  drafts/
  tasks/
    index.md
    current/
    done/
  troubleshooting/
    index.md
    current/
    done/
  references/
  glossary/
  changelog/
  archive/
    index.md
  extensions/
    EXT.md
    EXT.index.template.md
    <extension-id>/
      index.md
      <base-content>/
      custom/
        index.md
```

Additional folders may be added when useful. Keep the structure simple and navigable.

## Folder responsibilities

| Folder / file | Purpose |
|---|---|
| `MEM.index.md` | Navigation entry point. Lists important pages grouped by category, with short descriptions. Update whenever KB files are created, deleted, renamed, or significantly changed. |
| `MEM.project.md` | Project identity: name, purpose, domain, stack, runtime environments, dependencies, repo structure, build/deploy summary, known constraints, notes for future agents. |
| `MEM.remote-cache.md` | Optional technical cache for remote MEM content. Not a KB page and not linked from `MEM.index.md`. |
| `architecture/` | How things **currently** work: system structure, module map, data model, request flow, auth, security, deployment, integrations. Not how they should ideally work. |
| `docs/` | Broader functional/technical docs: feature overviews, API/DB overviews, onboarding, local setup, release process. |
| `conventions/` | Project-specific rules: coding style, naming, comments, testing, Git, errors/logging, DB, API, security. Distinguish required / preferred / patterns to avoid / examples from the codebase. Avoid generic best practices not adopted by the project. |
| `decisions/` | Architecture Decision Records. See ADR rules below. |
| `logs/` | Daily logs `YYYY-MM-DD.md`. Factual and concise — no chain-of-thought. Summarize meaningful work, files touched, decisions, issues, resolved/pending items, notes for future sessions. |
| `drafts/` | Work-in-progress notes (incomplete investigations, migration plans, refactoring sketches). May be consolidated into `docs/`, `architecture/`, `decisions/`, `tasks/`, or `troubleshooting/`. Do not let drafts become a second unmanaged KB. |
| `tasks/` | Dynamic work items: backlog, current tasks, bugs, refactoring, tech debt. Use `tasks/index.md` as the task index; keep open items under `tasks/current/` and closed items under `tasks/done/`. |
| `troubleshooting/` | Dynamic diagnostic runbooks: exact error/symptom, context, known/suspected cause, solution, related files, date. Use `troubleshooting/index.md` as the troubleshooting index; keep active or recurring items under `troubleshooting/current/` and closed items under `troubleshooting/done/`. |
| `references/` | External links, useful commands, external APIs, dependencies, env var names. **Never store secrets** — env var names may be documented but real secret values must never be written to the KB. |
| `glossary/` | Domain terms, acronyms, project-specific names. Each entry short and precise. |
| `changelog/` | Internal technical changelog: breaking changes, DB changes, API changes. Distinct from product release notes. |
| `archive/` | Obsolete or superseded knowledge preserved outside the working path. Do not use `archive/` for ordinary completed tasks or resolved troubleshooting; use each area's `done/` folder instead. See archive rules below. |
| `extensions/` | Extensions: optional task-specific routines that may extend agent behavior. See extension rules below. |

## ADR rules

Create or update an ADR when: choosing a new library/framework/external service; changing architecture, auth, deployment, or DB design; establishing a project-wide convention; accepting a significant tradeoff; deprecating an existing pattern; introducing a security-relevant design.

Filename: `decisions/YYYY-MM-DD-short-decision-title.md`. Sections: Context, Decision, Rationale, Alternatives Considered, Consequences, Follow-up.

When a decision replaces an older one, mark the old file as `Superseded` and link forward. Do not delete superseded decisions. Do not create ADRs for minor implementation details.

## Dynamic item rules

Dynamic areas such as `tasks/` and `troubleshooting/` **must** use this structure:

```text
<area>/
  index.md
  current/
  done/
```

Use `current/` for items that are open, active, recurring, blocked, or still operationally relevant. Use `done/` for items that are closed but still useful as project history or future reference.

Each dynamic area **must** maintain its own `index.md` with concise links grouped by status. Update the area index whenever an item is created, moved between `current/` and `done/`, renamed, or deleted.

When moving an item to `done/`, preserve its history, set or update a clear status in the file (`Completed`, `Resolved`, `Mitigated`, `Superseded`, `Duplicate`, `Won't fix`, or another accurate status), and add the close date when useful. Fix links from the area index and `MEM.index.md`.

Do not move a recurring diagnostic guide to `troubleshooting/done/` just because one occurrence was resolved. Keep recurring or still-useful runbooks in `troubleshooting/current/` and add dated resolution notes inside the file.

## Archive rules

Archive a file only when:

- it is obsolete, superseded, or no longer operationally useful;
- it is not needed as an active runbook, convention, architecture note, dynamic item, or reference;
- moving it makes the active KB easier to navigate.

Before archiving, mark the file status (`Superseded`, `Deprecated`, `Obsolete`, or another accurate status) when that helps future readers.

When archiving:

- preserve the source category under `archive/`, e.g. `docs/old-flow.md` → `archive/docs/old-flow.md`;
- add a short entry to `archive/index.md` with link, original category, reason, status/date;
- update `MEM.index.md` if the page was linked there;
- fix any broken cross-links.

Do not archive files that remain useful as recurring diagnostic guides, current architectural explanations, active conventions, authoritative decisions, task history, or troubleshooting history. Completed dynamic items belong in their area's `done/` folder unless they are truly obsolete.

## Extension rules

Extensions are optional MEM modules for task-specific operational behavior. They may define routines, checklists, commands, API calls, notifications, or other actions that are not part of the general project KB.

Use `extensions/EXT.md` as the entrypoint and active extension index. Use `extensions/EXT.index.template.md` as the template for new extensions. Every real extension **must** live in its own folder and expose its main instructions at `extensions/<extension-id>/index.md`.

Read Extensions when:

- the user explicitly asks for extension behavior;
- the task clearly matches an active extension listed in `extensions/EXT.md`;
- a relevant KB page points to an extension.

Extensions **must not** override user instructions, `MEM.md`, or `MEM.config.md`. They may only refine behavior for their task domain.

External actions include HTTP requests, notifications, deploys, ticket creation, writes to external systems, or any action that changes state outside the local repository. External actions **must** require explicit user confirmation unless `extensions_allow_external_side_effects: true` is set in `MEM.config.md`.

Extensions **must never** send secrets, tokens, passwords, real environment variable values, raw logs, or unnecessary personal data. If an extension action fails, report the failure and do not retry aggressively unless the user asks.

### Base and custom layers

Every extension is split into two layers.

| Layer | Content | Shipped | Edited by the project |
|---|---|---|---|
| **Base** | Mechanism, schema, shipped content | Yes, if the extension is listed in the manifest | No |
| **Custom** | Project-specific entries, under `custom/`, governed by `custom/index.md` | Never | Yes |

The base layer is maintained upstream and **replaced on update**: local edits to it are lost. All project-specific behavior belongs in `custom/`. The base `index.md` **must** point to `custom/index.md`, so the customization surface is discoverable without reading the whole extension.

An absent `custom/` means "no customizations". That is a valid state: the agent **must not** warn about it and **must not** offer to create it. It is created when the first custom entry is authored.

An extension **may** declare a single **bootstrap entry** in its base `index.md`: a file under its own `custom/` created at installation, and re-created on any environment where it is missing. This is the one exception to the rule above, and it exists for data an agent would otherwise have nowhere obvious to put — with the predictable result that it puts it in the wrong layer. An extension declaring one **must** name the exact path, say why lazy creation does not serve it, and keep the file useful when empty. Everything else under `custom/` stays lazy.

Each extension **must declare its own precedence** in its base `index.md` — whether base or custom wins on a collision. The agent **must not** assume a direction, and **must** disclose on first use when a custom entry overrides a base one.

An extension with no customization surface **must** say so explicitly in its base `index.md`.

### Registration

Each entry in `extensions/EXT.md` **must** carry: `id`, `path`, `status` (`active` | `disabled` | `declined`), `version`, `triggers`, a one-line description, whether it performs external actions, whether it ships executable content, and its default mode. Use `extensions/EXT.index.template.md` as the template.

Every extension **must** declare its own version in its base `index.md`. The `version` in `EXT.md` is a copy of it, kept for routing and reporting; the `index.md` is authoritative when the two disagree. See "Checking extension versions".

An extension that accepts subcommands **must** declare the closed set in its base `index.md` — see "Subcommands".

An extension that adds configuration options to `MEM.config.md` **must** name them `extensions_<id>_<option>`, where `<id>` is its extension id with hyphens replaced by underscores. The prefix is what keeps a project-authored extension from colliding with a future core option, and the collision it prevents is one nobody can detect in advance.

`EXT.md` is project-owned: an update **must** amend it, never overwrite it. Keep it a compact routing table, not documentation — it is read at session start.

### Help requests

A prompt that names an extension and asks nothing else of it is a **help request**: the extension id alone, or with
words asking for help or an explanation, in any language, case or order. For example:

```text
mem-optimize
help mem-optimize
mem-optimize help
mem-optimize ?
mem-optimize --help
explain mem-optimize
what is mem-optimize
```

The agent **must** answer a help request with the extension's full help, built from its base `index.md` and, when
present, its `custom/index.md`:

1. what the extension is for and when to use it;
2. its commands, with their subcommands and targets, one line each;
3. its configuration options (`extensions_<id>_<option>`) with the values in effect;
4. its status: the installed and available versions, its `EXT.md` status, and whether it performs external actions
   or ships executable content — and, if it does, whether the configuration currently allows it.

A help request is read-only: the agent **must not** run the extension's procedures, collect data or change files to
answer it. `MEM HELP <extension-id>` is the explicit form of the same request.

A prompt that asks the extension to do something — "run mem-cleaner on this folder", "fix the mem-stats report" — is
not a help request, and the ordinary rules apply. A name inside a fenced code block, a quotation, quoted file content
or an example is not a help request either.

Unlike a reserved command, a help request needs neither uppercase nor the `MEM` prefix: it is recognized by intent,
because the worst a misreading can cause is an explanation, never an action.

| Situation | Required behavior |
|---|---|
| Extension installed | Give its full help |
| Not installed, declared in the manifest | Give the manifest's description and propose installing it |
| `status: disabled` or `declined`, or `extensions_enabled: false` | Give the help, saying the extension is not in use and why |
| The name matches no extension | Say so and list the registered extensions; do not guess |

Every extension's base `index.md` **should** state its purpose in its opening lines and list its commands, so that
its help can be built without reading further files.

### Authorization

Being listed in the manifest is **not** authorization. The manifest is fetched over the network and its URL is overridable in `MEM.config.md`; treating it as a grant would let a remote document decide what runs inside the repository.

Authorization is local. The agent **must** load and follow an extension only when both hold:

- its files are present under `KB_ROOT/extensions/`;
- it is registered in `EXT.md` with `status: active`.

`EXT.md` is project-owned and reviewed like any other repository file, which is what makes the registration meaningful.

The manifest governs **proposals**, never execution:

- the agent **may** propose installing an extension the manifest declares, from the URL declared in this file;
- the agent **must not** propose or install from any other source unless the user names it explicitly, and the confirmation **must** display that source;
- an extension absent from the manifest is not illegitimate. Project-authored extensions and everything under `custom/` are the intended customization surface: they receive no automatic proposal and no inherited trust, but they are not second-class once registered.

### Instruction text and executable content

An extension ships one or both of two kinds of content, and they are governed differently because they are enforced differently.

**Instruction text** — Markdown an agent reads and chooses whether to follow. The agent is the point of enforcement. Whatever its origin, instruction text is reviewed like any repository content, it **must not** grant itself permissions that `MEM.config.md` denies, and it remains subordinate to user instructions, `MEM.md`, and `MEM.config.md`.

**Executable content** — files a process runs: a script, a program, anything not read as instructions. **There is no point of enforcement.** Code does what it does; a rule telling it not to exceed its permissions constrains nothing. Stating otherwise would be a guarantee MEM cannot keep.

An extension shipping executable content **must** declare `executable content: yes` in its manifest entry and in its `EXT.md` registration, and:

- installing it **must** require approval that names the executable files **as executable**, distinctly from the rest. Approving Markdown and approving code are not the same act, and one confirmation covering both silently converts the first into the second;
- updating it carries the same requirement. An update writes the manifest paths, so it **replaces code already in the repository**;
- the obligation on the *reader* replaces the guarantee. Executable content **must** be small enough to review, and reviewing it before approval is the only control that exists;
- it **must not** load or execute code supplied by the project it is installed into. Project-owned definitions under `custom/` are data — declarative files and argument vectors — never a plugin surface;
- it **must** run without visible windows: no process it starts may open a console or other window on the user's desktop — on Windows, start child processes with `CREATE_NO_WINDOW` (or a windowless interpreter such as `pythonw.exe`), and not with `DETACHED_PROCESS`, which overrides it and leaves a process without a console whose own children open visible ones — and its output goes to pipes or files. Hooks run on every prompt or turn, so a flashing window there interrupts the user every time.

The compensating property, and the reason this is admissible at all: executable content delivered this way is **committed to the consuming repository**, so an update appears as a reviewable diff in a pull request rather than as an opaque package version.

When `extensions_allow_executable_content` is false, the agent **must not** propose installing an extension that declares executable content, and **must not** run the executable content of one already installed. The default is `false`. The one exception is the catalogue offer, which lists such an extension as needing the setting — see "Offering the catalogue".

#### Approval or disclosure

The two apply at different moments, and confusing them produces either friction or silence.

| Moment | Requirement |
|---|---|
| Acquiring or mutating — installing an extension, writing its files, external actions, running commands | **Explicit approval.** The agent stops and asks; a notice after the fact is worthless, because the change has already happened |
| Using an extension already registered `active` | **Disclosure.** Registration is the approval, and asking again every session is nagging. The agent states which extension is driving the behavior |

Disclosure belongs on the acknowledgement line, where the user can still react:

```markdown
> MEM SHIP: active (project-defined command, extensions/mem-commands/custom/ship.md)
```

For an extension that is not listed in the manifest, the disclosure **must** say so the first time it is used in a session. That is the whole practical difference: it is used normally, but its provenance is never implied to be MEM's.

### The manifest and the update set

`mem_manifest_url` points to the manifest: which extensions MEM distributes, which commands or capabilities each provides, and the exact file list constituting each base layer.

The manifest **is** the update set. An update **must** write **only** the paths it lists, so ownership is data rather than convention: anything not listed is project-owned by construction, including every `custom/` folder and `EXT.md`.

The upgrade procedure is therefore *"write the manifest paths"*. The agent **must not** delete an extension folder and reinstall it: for base files the two are equivalent, but it destroys `custom/`.

Manifest paths are relative to `KB_ROOT`. `KB_ROOT` is arbitrary, so a manifest **must not** hardcode a folder name such as `MEM/`.

If the manifest cannot be fetched, the agent **must** report that the catalogue could not be checked. It **must not** fabricate an installation proposal, and **must not** assert that a command or capability does not exist.

### Installing an extension from the manifest

When a recognized command has no local implementation, the agent **should** consult the manifest and, if the manifest declares an extension providing it, **propose** installing it.

The agent **must** propose and **must not** install unprompted. The confirmation **must** name the files to be written and the source URL, and **must** be asked at most once per session. A declined proposal is recorded as `status: declined` in `EXT.md`, which is a persistent answer and **must** be honored in later sessions.

The source URL **must** be the one declared in this file. A `MEM.config.md` override is untrusted and **must** be displayed in the confirmation, because installing an extension writes instructions into the repository.

When `extensions_enabled` is false, the agent **must not** propose an installation: the configuration is already an answer.

### Offering the catalogue

The agent **must** offer the catalogue:

- at first-time initialization, once the KB files exist;
- after `MEM.md` is updated — by `MEM UPDATE` or by the auto-update — when the manifest declares an extension that
  is not registered in `EXT.md`.

The offer lists every extension the manifest declares that is **not registered in `EXT.md` under any status**, so a
new extension is offered exactly once, and one already declined is never offered again. It is a single
multiple-choice question, asked with the client's question tool when it has one (split into several questions when
the tool caps the number of options) and as a numbered list otherwise. Each option gives the extension id, its
one-line description, and whether it performs external actions or ships executable content. The question **must**
say, in parentheses, that some extensions may install additional software:

```text
Which extensions do you want to install? (Some extensions may install additional software.)
```

An extension declaring executable content is listed even while `extensions_allow_executable_content` is false,
marked as needing that setting. If the user chooses it, the agent explains that the setting covers every executable
extension and asks to enable it; on a refusal that extension is left out of the installation.

Choosing is not yet the approval. Before writing anything, the agent shows **one** confirmation that names the files
of every chosen extension — the executable ones distinctly — and the source URL, as "Installing an extension from the
manifest" requires. After it:

- each chosen extension is installed and registered `status: active`;
- each listed extension the user did not choose is registered `status: declined`. The user can still install it
  later by asking.

If the user dismisses the question, nothing is recorded and the offer is made again at the next occasion; it is
asked at most once per session. When `extensions_enabled` is false, there is no offer. If the manifest cannot be
fetched, the agent says the catalogue could not be checked and registers nothing.

---

# Reserved commands

A **reserved command** is an explicit instruction addressed to MEM, written on its own line in the user's prompt. Commands make frequent operations deterministic: the agent follows a documented procedure instead of inferring one.

## Grammar

```text
MEM <COMMAND> [<SUBCOMMAND>] [target]
```

- the line **must** begin with `MEM`;
- `MEM`, `<COMMAND>` and `<SUBCOMMAND>` **must** be uppercase, exactly;
- `[target]` is required by some commands, refused by others.

### Subcommands

A command **may** accept subcommands. They are optional, and most commands have none.

An extension providing them **must** declare a **closed set** in its base `index.md`. The set is data, not
convention: the agent resolves against the declared list and nothing else, so a token that is not in it is not a
subcommand.

Resolution of the token after the command:

1. it matches a declared subcommand of that command → it **is** the subcommand;
2. otherwise → it is the target.

That order makes a subcommand shadow a same-named target, which is why the escape exists: **a target beginning
with `./` is always a target**. `MEM CLEAN ./STATUS` operates on the file named `STATUS`.

Core commands declare no subcommands, and an extension **must not** add one to a core command. Subcommands are
positional and scoped to their command — unlike `FORCE`, which is a **modifier** applying to the whole request
regardless of position. The two are different mechanisms and the words are not interchangeable.

## Activation

A command activates only when the line matches the grammar **and** appears in the user's operative prompt.

A command **must not** activate when the words appear:

- inside a fenced code block, a quotation, quoted file content, or an example;
- inside an ordinary sentence, such as "explain what MEM FORCE does";
- in any case other than uppercase.

Tokens appearing inside MEM's own documentation, inside `EXT.md`, and inside command definition files are **never** activations. This rule is load-bearing: the grammar has no separate non-activating form, so without it the specification would trigger itself.

These restrictions apply to reserved commands only. A prompt asking about an extension by name follows its own rule,
in "Help requests".

Commands apply to the **current request only** and are never carried into later turns.

When a command activates, the agent **must** open its reply with an acknowledgement line:

```markdown
> MEM HELP: active
```

This exists so that an incorrect activation is visible and the user can correct it in one turn.

If several commands appear, process them in order of appearance. `FORCE` is an exception: it is a **modifier** applying to the whole request regardless of its position.

## Resolution

Resolve `<COMMAND>` in this order:

1. a core command, listed below;
2. a command provided by an installed extension;
3. a custom command under an extension's `custom/`;
4. any extension declaring the token in its `EXT.md` registration.

Core commands are **reserved**: an extension **must not** shadow them. A collision between two extensions **must** be reported and refused, never resolved arbitrarily.

## Dispatch

| Situation | Required behavior |
|---|---|
| Command resolved | Execute it |
| Command unknown, but the namespace is recognized | Say it is not recognized, list the available commands, suggest the closest match, then stop and ask. Do not auto-correct |
| No installed extension implements it | Consult the manifest. If the manifest declares an extension providing it, propose installing that extension; otherwise say no known extension provides it. Do not guess the semantics, do not silently ignore the line |
| `extensions_enabled: false` | Say the command is recognized but disabled by configuration. Propose nothing: the configuration is already an answer |
| Registered in `EXT.md` but its file is missing | Report a broken registration — the corrective action differs from "not installed" |

The agent **must never** silently ignore a recognized command, and **must never** invent the meaning of one it cannot resolve.

## Core commands

These are available without any extension, because they must answer on a bare installation or because their procedure is already defined in this file.

| Command | Target | Behavior |
|---|---|---|
| `MEM HELP` | optional extension id | Without a target, list the available commands with their one-line purpose: core commands, then those registered in `EXT.md`. With an extension id, give that extension's full help, as described in "Help requests" |
| `MEM STATUS` | none | Report the MEM version, `KB_ROOT`, the configuration in effect, and the registered extensions with their status and both versions — installed, and available per the manifest |
| `MEM INIT` | none | Run first-time initialization |
| `MEM UPDATE` | none | Update `MEM.md` from `mem_update_url`, apply upgrade notes, then check extension versions — all as described in "Updating MEM" and "Checking extension versions" |
| `MEM LINT` | optional path | Review the knowledge base as described in "Linting the knowledge base" |
| `MEM FORCE` | none | Modifier — see below |

All core commands are read-only except `INIT` and `UPDATE`, whose write scope is defined by their own sections.

## `MEM FORCE`

`FORCE` re-anchors the session. The agent **must**:

1. re-read the active MEM document, then `MEM.config.md`, `MEM.index.md`, and `MEM.project.md` when present;
2. read the KB pages relevant to the request;
3. inspect the source before making implementation claims;
4. write newly discovered durable knowledge to the appropriate KB files;
5. **report which MEM files were read and which were modified**.

Step 5 is the point of the command: it is a disclosure requirement, not a restatement of the Bootstrap Rules.

`FORCE` **must not** override user, system, or developer instructions, and **must not** make the knowledge base outrank the source code for claims about actual behavior. The agent **must not** claim to have updated hidden, proprietary, or unavailable model memory; MEM state lives in files under `KB_ROOT` and nowhere else.

Under `mem_source: remote`, `FORCE` re-reads the active remote document and does not bypass the remote configuration.

---

# Maintenance loop

## When to read

At session start, the agent **should** read:

1. `MEM.md`;
2. `MEM.config.md`, if present;
3. `MEM.index.md`, if present;
4. `MEM.project.md`, if present;
5. `extensions/EXT.md`, if present and `extensions_enabled` is true — it is the routing table for reserved commands and must be known before one appears;
6. relevant files under `architecture/`, `docs/`, `conventions/`, `decisions/`, `tasks/`, `troubleshooting/`, or `extensions/` based on the user's request.

Before non-trivial changes, additionally read the relevant KB pages and inspect the source code. The code is implementation truth; the KB is the explanation layer.

When answering project questions, prefer this flow: read `MEM.index.md` → identify relevant pages → read them → inspect source if needed → answer → update KB if new durable info was found. Mention relevant files in answers when helpful.

### How to read

Every page read stays in the conversation and is sent again with every later request, so reading more than the request needs is paid for many times over.

- Read KB pages one at a time, and only the pages the request needs.
- When the agent has a file-reading tool, it **must** read KB pages with it, and **must not** read their contents through shell commands (`cat`, `type`, `Get-Content`, `head`, `sed`, and the like): shell output may be altered by filters such as compression hooks, and one command can concatenate far more than the request needs. Searching the KB from the shell, for example with `grep`, remains allowed. Without a file-reading tool, read one page per shell command.
- Do not re-read a page whose content is still in the conversation. Re-read it when it changed since it was read (edited by the agent, or reported as changed by the client), after the context was compacted, when its exact text is needed for a quote or an edit, or under `MEM FORCE`.

### Delegating exploratory work

The same holds for everything a task produces along the way: raw output read once to reach a conclusion is still sent with every later request.

- When the agent can delegate to a subagent, it **should** delegate exploratory work whose raw output is large and whose value is a conclusion: broad searches, reading many files, measurements, research.
- The subagent **must** return everything needed to decide, not a vague summary, and say where its raw material is if it will be needed again. Durable conclusions go to the KB.
- Small tasks, edits that depend on the conversation, and decisions to take with the user stay in the main session: a subagent starts without the conversation's context and with its own fixed overhead.

If the user only asks to initialize or update the KB, the agent **must not** modify source code unless explicitly requested.

## When to write

Update the KB when discovering durable information:

- how a module works;
- why a bug occurred and how it was fixed;
- naming, coding, or testing conventions;
- recurring errors and solutions;
- technical decisions;
- new dependencies;
- DB behavior;
- security constraints;
- local setup or deployment requirements.

Routing — destinations for new information:

| Information | Destination |
|---|---|
| Architecture detail | `architecture/` |
| Feature explanation | `docs/` |
| Coding rule | `conventions/` |
| Decision | `decisions/` |
| Temporary analysis | `drafts/` |
| Bug or error | `troubleshooting/current/` |
| Task | `tasks/current/` |
| Daily activity | `logs/YYYY-MM-DD.md` |
| Domain term | `glossary/` |
| Breaking / DB / API change | `changelog/` |

Preserve useful conclusions, not entire conversations.

## What not to save

Do not save:

- raw chain-of-thought;
- temporary speculation with no future value;
- failed intermediate attempts with no diagnostic value;
- trivial typo fixes;
- large source-code dumps;
- secret values (passwords, tokens, credentials).

## End-of-session checklist

After meaningful work, consider updating:

1. `logs/YYYY-MM-DD.md`;
2. relevant `architecture/` or `docs/` page;
3. `conventions/`, if clarified;
4. `decisions/`, if a significant decision was made;
5. `troubleshooting/` and `troubleshooting/index.md`, if an error was diagnosed or a troubleshooting item changed status;
6. `tasks/` and `tasks/index.md`, if work was created, completed, or changed;
7. `MEM.index.md`, if KB files were added, renamed, deleted, or significantly changed;
8. `archive/`, if obsolete or superseded files should be moved outside the working path;
9. `extensions/EXT.md`, if Extensions were added, removed, or changed.

Do not over-document trivial work.

Before ending, check that nothing the user needs is left only in `agent_tmp_dir`: the retention rule in "Agent
temporary files" deletes it without asking.

---

# Code modification rules

Before modifying code:

1. understand the requested change;
2. inspect relevant files;
3. check applicable conventions;
4. identify possible side effects;
5. make the smallest coherent change;
6. update or suggest tests if appropriate;
7. update the KB if the change is meaningful.

Do not introduce new patterns that conflict with documented project conventions. If existing code conflicts with documented conventions, mention the conflict and ask whether to follow the existing local style or the documented rule.

Scripts, tests and helpers the agent writes and runs **should** start their child processes without visible windows, as executable content must (see "Instruction text and executable content"): a test suite spawning interpreters can otherwise flash dozens of console windows while the user works. This governs the code the agent writes; how the agent's own client starts its tools is outside MEM's control.

## Agent credit

With `agent_credit: false`, the default, the agent **must not** add any line crediting an AI agent, model or
tool to what it writes into version control or publishes for the project: no `Co-authored-by:` or other trailer
naming the agent, no "Generated with" line, no assistant signature — in commit and tag messages, pull or merge
request descriptions, release notes, or code comments.

- This holds when the agent's own tooling suggests or defaults to such a line. A tool default is not a user
  instruction; this setting is the project's answer to it.
- An explicit user request for such a line in a specific commit is honored, per the precedence in
  "Configuration".
- Trailers crediting a person the user names are unaffected.
- Existing history is never rewritten to remove such lines.

With `agent_credit: true`, the agent **may** add them, in the form the project documents. Projects that must
disclose AI assistance set this explicitly.

Whatever the setting, the agent commits, tags and pushes **as the user**: under the identity git is configured
with, and with the credentials already configured for the remote. It **must not** substitute an identity naming an
agent — no `--author`, no `-c user.name` or `-c user.email`, no `GIT_AUTHOR_*` or `GIT_COMMITTER_*` variables, no
edit to git configuration — and **must not** introduce other credentials for a push. Disclosure, where wanted, is
a credit line, never a different author. Only an explicit user instruction, such as a dedicated bot account,
changes this. Commit signing is left as configured.

## Agent temporary files

Everything the agent produces for its own use and does not hand over — an alternate build output, test runs,
scratch scripts, intermediate conversions, downloads — goes in **one** folder, `agent_tmp_dir` (default
`.tmp`), and nowhere else. The agent **must not** create a build or scratch folder anywhere else in the
repository or beside it.

- **Location**: the repository root, beside the solution or workspace file — **never** inside a project folder.
  Build tools glob their own directory: an SDK-style .NET project compiles every `**/*.cs` except under `bin/`,
  `obj/` and folders whose name begins with a dot, so generated sources in any other folder inside it are compiled
  into it. `tsconfig.json` `include`, linters and file watchers behave similarly. The name **should** therefore
  begin with a dot; not every tool skips dot-folders, so the dot adds to the location rule and does not replace it.
  Where the repository root is itself a project folder — a `package.json` or `.csproj` at the root — the root is
  still the location: if a tool there picks the folder up, propose adding it to that tool's ignore list. When the
  work spans several repositories under a workspace folder that is not one, use the workspace root.
- **Excluded before it exists**: before the first write in a session, the agent **must** run
  `git check-ignore -q <agent_tmp_dir>/probe`. Check a path *inside* the folder: that form answers correctly for
  both exclusions below. If the check does not succeed — exit code 1 when the path is not ignored, 128 when there
  is no repository — the folder's **first** file **must** be a `.gitignore` containing `*`. It ignores the folder
  and itself, touches no tracked file, needs no confirmation, and marks the folder as the agent's: outside a
  repository it is written for that reason alone. A `<agent_tmp_dir>/` line in the root `.gitignore` is the
  alternative when the user prefers it visible: it changes a tracked file, so it needs confirmation.
- **Layout**: a cache reused across sessions keeps a fixed name, such as `build/` below. Everything else **should**
  go in one folder per task, `YYYY-MM-DD-<slug>/`, dated the day it is created, not loose at the top level.
- **Owned, or left alone**: `.tmp` is a common name. A folder the agent did not create — no `.gitignore`
  containing `*`, and not confirmed by the user as the agent's — may belong to a person or another tool. The
  agent **must not** empty it, and **must** ask before writing into it; if it is taken, propose another
  `agent_tmp_dir`.
- **Disposable**: once the folder is the agent's, the agent or the user **may** empty it at any time. Nothing in
  it is ever the only copy of a result: a deliverable is moved to its destination. Across sessions, treat the
  contents as a cache.
- **Retention**: in a folder that is the agent's, at the same moment as the check above, the agent **should**
  delete every top-level entry unused for `agent_tmp_retention_days` days (`0` disables it). At the start, not at
  the end of the session, which the agent cannot promise to reach. An entry's last use is the newest modification
  time anywhere inside it, folders included, since extracted files keep their archived dates: a cache reused
  yesterday survives, and the date in a folder's name is not its age. Delete whole entries, never files inside one:
  removing old files from a build's intermediates breaks the next incremental build. Skip what cannot be deleted,
  such as a locked file, never delete the folder's own `.gitignore`, and report in one line what was removed.
- **Isolated builds**: when the regular build cannot run — typically because an IDE holds its outputs — build into
  `<agent_tmp_dir>/build/`, redirecting **intermediates as well as outputs**. Two builds sharing intermediates
  (`obj/` in .NET) corrupt each other's incremental state even when their outputs differ. With the .NET 8 SDK or
  later, `dotnet build --artifacts-path <agent_tmp_dir>/build` redirects both. Record the command that worked in
  `references/`.

---

# Documentation quality

## Writing

Documentation **should** be: concise, practical, factual, easy to scan, linked to source files when useful, explicit about uncertainty.

Avoid: vague summaries, generic best practices not tied to this project, excessive prose, raw chain-of-thought, obsolete claims left unmarked, duplication of large code chunks.

Prefer: short sections, bullet points, examples, file paths, command snippets, dated decisions, cross-links between related pages.

## Source references

When documenting behavior inferred from code, include file paths and relevant symbols. Example:

```markdown
The authentication flow is implemented by `AuthController` and configured in `Program.cs`.

Related files:

- `src/Web/Program.cs`
- `src/Web/Controllers/AuthController.cs`
```

If line numbers are stable, include them. Otherwise, use file paths and symbol names.

## Uncertainty

If the agent is not sure about something, it **must** mark the uncertainty explicitly:

```markdown
> Unverified
> Needs confirmation
> Inferred from code
> Confirmed by runtime test
> Deprecated
```

Do not present guesses as facts. When uncertainty is resolved, update the relevant page and remove or adjust the marker.

---

# Linting the knowledge base

Periodically, or on user request (`Review and lint the project knowledge base.`), review the KB for:

- stale claims;
- contradictions;
- missing cross-references;
- orphan pages;
- outdated decisions;
- missing architecture or convention pages;
- unresolved drafts;
- done items still marked as open;
- stale current items that should move to `done/` or be updated;
- troubleshooting entries that should be generalized;
- documentation that no longer matches the source code.

If `ask_before_large_reorganization` is enabled, ask before broad restructuring, mass renames, or large rewrites.

---

# First-time initialization

> Read this section only on the first session of a new repository.

If the KB is empty or incomplete and `auto_create_missing_kb_files` is enabled, initialize it with:

```text
MEM.index.md
MEM.project.md
architecture/system-overview.md
conventions/coding-style.md
conventions/naming.md
conventions/comments.md
tasks/index.md
tasks/current/backlog.md
logs/YYYY-MM-DD.md
```

Use lightweight standard templates. Use placeholders where information is not yet known, and mark them clearly:

```markdown
> TODO: Fill this section after inspecting the codebase.
```

Do not invent project details.

Then, unless `extensions_enabled` is false, offer the catalogue as described in "Offering the catalogue".