Why memory works this way

Memory is where Jazz learns how you like things done. These are the design choices behind it and what each one gives you. For the mechanics, see Conversations, state, and memory.

Memory learns what you said, not what the agent concluded

Every save carries an exact quote from one of your messages, identified by an id the host assigned. Tool output, web pages, model summaries, and subagent prompts cannot establish a fact about you, and secrets and sensitive claims are refused.

This gives you three things. A web page cannot plant a standing instruction. An agent cannot talk itself into a preference. Every entry traces back to words you wrote, which jazz memory explain shows.

The cost is deliberate: Jazz does not infer your taste from how you behave. It learns what you tell it, including corrections such as “too formal”.

The agent proposes lessons; you decide

The one thing memory holds in the agent’s words is a lesson from its own mistake, such as “search for existing products before proposing to build one”. You should not have to say “remember” for the agent to learn from a mistake it just corrected, so it proposes the rule without being asked, during the conversation and in a background pass after the conversation ends.

A proposal is not a save. It waits until you accept it with a command you type, and no tool can accept one. That keeps the guarantee above: a web page can at most get a lesson proposed, and you read it before anything is saved.

The agent decides when to remember

You do not have to say “remember”. The agent saves a stated preference in the same turn, and a second pass before compaction catches durable facts it missed. See How the agent learns.

The agent is conservative on purpose. Each standing entry is injected into every future turn of every agent, so an uncertain fact is not saved. Keeping memory small is what keeps it trustworthy and cheap to carry.

A taste belongs to a context

How you write to a friend is not how you write to a colleague, and “run evals before merge” is not advice for your cooking assistant. Memory is partitioned into named scopes, which are topics — not ownership boundaries. Every agent reads and writes every scope, and any agent can create a scope when a conversation calls for one, so a lesson learned with one agent is available to all of them.

personal is the default scope. A preference like concise replies follows you across your terminal agent, your Telegram bot, and your CI reviewer because they all share it.
A project scope holds what applies only there.
Scopes are discovered from the memory directory, not configured per agent: what exists is what is visible to everyone, and jazz memory list shows the whole landscape.

Pay for context only where it applies

An entry under always/ shapes nearly every task, so it is injected on every turn. An entry under when/<topic>/ applies to a kind of task and is read when the agent looks it up. That split keeps the standing instructions short without losing the specific ones.

Memory is files you can read, edit, and delete

Entries are Markdown files under ~/.jazz/memory/. You can open them, change them, or delete them directly, or use jazz memory list, show, explain, and forget. explain shows an entry’s provenance and recent records of whether it was available to model requests. Those records show availability, not that the model used the entry well.

Forgetting sticks

Forgetting an entry also revokes the quoted source, so later compaction cannot save the same statement again. Memories created before source tracking may require you to review their original conversation history.

What memory is not for

Memory holds small facts and preferences, each one a thought you can audit. It is not for large working material, which belongs in the scratchpad, and it does not turn a procedure the agent worked out into a reusable skill. Skills are instructions you write or install.

Known limits today

An entry under when/ reaches the model when the agent looks it up. jazz memory recall reports how often a lookup happens before the first answer, per surface.
Only what you state, and lessons you accept, is learned. Jazz does not infer preferences from your edits or choices.
In-turn saving depends on the model following the save rule.

Conversations, state, and memory: the mechanics and commands
Agents: the rest of the agent configuration
Skills: reusable procedures