# Agent memory

What an agent works out about your repo settles into memory that outlasts the run. The next run starts where the last one stopped, not from zero.

Every run teaches the agent something: the build command that actually works, the test that needs a database, the folder nobody should touch. Kestrel keeps those facts per repo and hands the useful ones to the next run.

![Notes from a run start as short-term memory. The ones that hold up across runs settle into long-term memory, and the next run reads them first.](/illos/agent-memory.svg)

## How it fills

Agents save facts with the `remember` tool as they work. A fact is kept for the run first. If later runs find it true again, it moves to long-term memory; if a run proves it wrong, it is dropped.

## Read it

```bash Terminal
kestrel memory list --repo acme/web-app

build      npm run build:ci needs NODE_OPTIONS=--max-old-space-size=4096
tests      checkout.test.ts needs the payments mock on port 4010
avoid      Don't edit src/generated, it is rebuilt from schema.graphql
style      Use the Money type for prices, never number
```

## Edit it

Memory is yours. Add what you know, and remove what is out of date.

```ts TypeScript
await kestrel.memory.add("acme/web-app", { topic: "tests", text: "Run tests with --runInBand in CI" });
await kestrel.memory.forget("acme/web-app", { topic: "build" });
```

```python Python
kestrel.memory.add("acme/web-app", topic="tests", text="Run tests with --runInBand in CI")
kestrel.memory.forget("acme/web-app", topic="build")
```

> [!NOTE]
> On Team, memory is shared by everyone in the workspace. A fact one person's run learns helps every run after it.