# Memory (/agent/memory)

Memory is what the agent remembers about a project between sessions. Not the conversation - that's a
[session](/agent/sessions) - but the durable, non-obvious facts worth carrying forward.

Good memory entries look like:

- "The API client is generated; edit `openapi.yaml`, never `client.ts`."
- "We use `pnpm`, not `npm`. `npm install` breaks the lockfile."
- "Integration tests need `docker compose up -d` first."

## How it works [#how-it-works]

The agent writes memory itself when it learns something durable, and reads it back into the system
prompt on later runs. It's scoped per project, with a separate user scope for notes that apply
everywhere (see [Scopes](#scopes)).

Three tools drive it, and only the write prompts for approval:

| Tool | Approval |
| --- | --- |
| `memory_list` | No |
| `memory_read` | No |
| `memory_write` | Yes |

Because writes prompt, nothing enters memory without you seeing it.

## Where it lives [#where-it-lives]

As plain markdown files in your Jan home, outside the repository. You can read them, edit them, or
delete them. Nothing is hidden in an opaque store.

```
~/.jan/
|-- MEMORY.md                  # root index: user notes + one line per project with memory
|-- memory/<name>.md           # user-wide notes, every project
`-- projects/<slug>/
    |-- MEMORY.md              # index of this project's notes
    `-- memory/<name>.md       # this project's notes
```

Each `MEMORY.md` is generated: it is rebuilt on every `memory_write` and delete, so don't edit it by
hand - your changes would be overwritten. See [Project Config](/agent/project-config) for how
`<slug>` is chosen.

## Scopes [#scopes]

Memory names are scoped:

| Name | Refers to | Writable |
| --- | --- | --- |
| `name` | A note in this project | Yes |
| `user:name` | A user-wide note in `~/.jan/memory/`, for preferences that apply to every project | Yes |
| `project:<slug>` | Another project's `MEMORY.md` index | No |
| `project:<slug>/name` | One note from another project | No |

`memory_read` accepts all four. `memory_write` to another project is refused, so a session can only
change its own project's notes and your user notes.

The system prompt's **Available Memories** block lists this project's notes, your user notes, and
pointers to other projects that have memory, which the agent opens with `project:<slug>` only when
relevant. To keep other projects out of the prompt and refuse `project:` reads, set this in
`~/.jan/config.toml`:

```toml
memory_cross_project = false   # default: true
```

Retrieval is backed by the same store Jan Desktop uses for memory, so a fact learned in one is
available in the other.

<Callout type="info">
Memory is shared with [Jan Desktop's Cowork surface](/desktop/cowork), which ships in the
`nightly` channel only. Settings you change there apply to what the terminal agent recalls, and
vice versa.
</Callout>

## Keeping it useful [#keeping-it-useful]

Memory works when it's small and specific. A note that restates what any reader would see from the
README is noise; a note about the thing that surprised someone is worth keeping.

If the agent has stored something wrong, delete the file. There's no special command for it - they
are just files.

## Memory and AGENTS.md [#memory-and-agentsmd]

They overlap, and the distinction is who writes them:

| | Written by | Best for |
| --- | --- | --- |
| `AGENTS.md` | You | Rules you want followed every time |
| Memory | The agent | Facts it discovered and shouldn't have to rediscover |

If you find yourself correcting the same thing repeatedly, promote it into
[`AGENTS.md`](/agent/project-config#agentsmd) where it's guaranteed to be in the prompt.