Matilda
Contact
Guides

Context and memory.

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

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.

This session
In context

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.

Across sessions
Memory files

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.

After the call
Not kept

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.

Fieldtypedescription
MATILDA.md
~/.matilda/MATILDA.md
.matilda/MATILDA.local.md
AGENTS.md
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

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

Shell
matilda --add-dir ../shared-lib

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

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.