# Context and memory

> What Matilda holds in a session, and what carries across them.

Source: https://maincode.com/docs/retention
Section: Matilda Code · Matilda documentation

---

## Two kinds of memory

Every session starts with a fresh context window. Anything Matilda knows at a
given moment is either **in context**, meaning this session, or in a **memory
file** it reads from your repo at startup. Nothing else persists.

**In context** — This session

The files, conversation, and command output the model is reasoning over
right now. Large, but finite. When it fills, older turns are summarised
rather than silently dropped.

**Memory files** — Across sessions

Plain-text `MATILDA.md` files that Matilda reads at the start of every
session. They live on your machine and in your repo, in your git history.

**Not kept** — After the call

Everything else. Your code is not uploaded as a corpus and not used for
training.

## Where memory files live

You can use any combination of these. Matilda loads all of them at startup.

| Field | Scope | Committed | Notes |
| - | - | - | - |
| `MATILDA.md` | Your whole team | Yes, project root | Shared conventions, build and test commands, architecture decisions. |
| `~/.matilda/MATILDA.md` | You, every project | No, your machine | Personal preferences that follow you between repositories. |
| `.matilda/MATILDA.local.md` | You, this project | No, gitignore it yourself | Project-specific but personal. Loads after the shared file, so it can override. |
| `AGENTS.md` | Your whole team | Yes, project root | Read automatically if your repo already has one for other tools. No need to duplicate. |

> **Caution** — `.matilda/` is not gitignored for you, and some projects deliberately commit
> `.matilda/settings.json`. If you use `MATILDA.local.md`, add it to your
> `.gitignore` yourself.

Run `/init` in a project without one and Matilda will draft a `MATILDA.md` for
you from what it finds in the repo.

## What belongs in a memory file

Things you would otherwise repeat every session:

- Build and test commands, `npm run test`, `make build`
- Conventions your team follows, "every new file needs JSDoc"
- Architectural decisions, "never call the database from a controller"
- Personal preferences, "always pnpm, never npm"

Leave out anything Matilda can work out by reading the code. These files work
best short and specific. The longer one gets, the less reliably it is followed.

## Managing context

**Add**

Pull directories into the workspace yourself instead of waiting for the agent
to find them.

```bash
matilda --add-dir ../shared-lib
```

Inside a session, reference a path with `@` to pull a specific file in.

**Inspect**

See what is loaded and roughly how much of the window it uses.

```
/context
```

**Compress**

Summarise the conversation so far and keep working with the room it frees.

```
/compress
```

**Clear**

Drop the working set and start fresh. Memory files are untouched, since they
are files rather than part of the session.

```
/clear
```

## What never leaves

- **Your source code** is read locally and sent per request only as needed. It
  is not retained after the response and not used for training.
- **Your memory files** live in your git history and on your machines, not
  ours.
- **Your credentials** sit in `~/.matilda/matilda-auth.json` with user-only
  file permissions.

> **Caution** — A project `MATILDA.md` is committed with your code and readable by everyone
> with repository access. Never ask Matilda to remember a secret there.