> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory and rules

> Give agents your repository's facts and engineering standards, and understand what happens when a file is missing.

> [!NOTE]
>
> **Early Access.** Commands and behavior can change between releases.

Memory tells agents **what your project is**. Rules tell them **how to change it**. Architech's
agents load both for the repository they work in, alongside your
[project instructions](https://docs.mutagent.io/architech/features/project-context.md) in `AGENTS.md` or `CLAUDE.md`.

Start with [`/onboard`](https://docs.mutagent.io/architech/onboard). Review the drafts it proposes; existing files you wrote
are kept. You don't need to create empty files just to let an agent start work.

## What belongs where

| File | What to put in it |
| - | - |
| `.memory/repository-context.md` | The repository's purpose, stack, boundaries and important integration points. |
| `.memory/design-principles.md` | Product constraints and protected decisions agents must preserve. |
| `.engineeringrules/coding-rules.md` | Your code conventions, patterns to follow and patterns to avoid. |
| `.engineeringrules/testing-rules.md` | Your test commands, test locations, scope, worker limits and commit-hook checks. |
| `AGENTS.md` or `CLAUDE.md` | Project instructions loaded into the session's prompt, such as build commands and house rules. |

In a single repository, these paths are relative to its root. In a monorepo, keep repository-specific
facts and standards in the package or repository they govern. Shared files can live at the project
root; [context rules](https://docs.mutagent.io/architech/features/context-management.md) say when a child inherits them.

Agents refer to these files by shortcuts: `@rule:testing-rules` names
`.engineeringrules/testing-rules.md`, and `@memory:repo` names `.memory/repository-context.md`.
Names under `rules:` and `memory:` omit the shortcut prefix and `.md` suffix.

## When a file is missing

**Missing context proceeds with a warning.** Architech tries the configured context rules and
parent files, then works from the conventions beside the change if nothing supplies the file. The
agent records the decision and its source in `CONTEXT_MANIFEST`, and ends its report with a
**Recommended action**: add the file, inherit an appropriate one, or declare that it isn't needed.
It doesn't invent rules or create an exemption to clear the warning.

Only an explicit `required` declaration holds the code-writing step that needs the missing file.
Other independent work continues. **Reviews never block on a context gap**: the reviewer reports
it and still gives a verdict.

### The warning you see

For an undeclared repository named `web` with no testing rules in it or its parents, the resolver's
output includes these lines (excerpt):

```text theme={null}
WARNING: @rule:testing-rules - @rule:testing-rules is absent here and in every parent (expected .engineeringrules/testing-rules.md); proceed on the code beside the change (default). Proceed and record it in CONTEXT_MANIFEST.context_decisions.
  → testing-rules: missing here and in every parent for web → proceed; record in CONTEXT_MANIFEST
  CONTEXT-HINT/1 {"v":1,"shortcut":"@rule:testing-rules","repo":"web","decision":"proceed","source":"default","why":null,"approved":null,"action":"proceed-and-record"}
```

That missing file exits with code `0`, not a failure. The hint says **proceed and record**, not
"stop and ask for an exemption". In JSON output, `context_decision.recommended_action` names the
file to `create`, a `seed` if a file stood in, and a draft entry to `declare` in your context rules.
You decide which action fits your repository.

**1. Check the scope and spelling**

Make sure the agent is working in the right repository and the requested file name is correct.
If the resolver names another worktree that carries the file, rerun there rather than copying
its rules into the current checkout.

**2. Choose the lasting behavior**

Add genuine repository standards when they are useful. If the repository is generated, docs-only,
or intentionally follows another package, declare an exemption or inheritance instead.

**3. Review the decision**

Read the hint's repository, source and reason. A declared exemption is an `EXEMPT` decision,
not a warning; inherited files and unresolved gaps remain visible in the report.

> [card] [Context management](https://docs.mutagent.io/architech/features/context-management.md)
>
> Configure a generated SDK, require rules for a sensitive repository, or set a temporary exemption.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.