Memory
Memory is what the agent remembers about a project between sessions. Not the conversation - that's a session - but the durable, non-obvious facts worth carrying forward.
Good memory entries look like:
- "The API client is generated; edit
openapi.yaml, neverclient.ts." - "We use
pnpm, notnpm.npm installbreaks the lockfile." - "Integration tests need
docker compose up -dfirst."
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).
Three dedicated workspace tools drive it. None prompts for approval, even with --safe:
| Tool | Approval |
|---|---|
memory_list | No |
memory_read | No |
memory_write | No |
The agent can save notes without asking first. Explicit tool denies still apply; see Tools & permissions.
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 notesEach 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 for how
<slug> is chosen.
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:
memory_cross_project = false # default: trueJan Desktop uses a separate permanent store at <data-folder>/agent-workspace. Its memory is
not automatically shared with the terminal agent's user and project stores.
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
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 where it's guaranteed to be in the prompt.