Guides

Working with Memory

A Memory is something an NPC should still know in a Conversation that has not happened yet. Every one of them is listed, editable and deletable by the Player who owns it — that is the point, not a courtesy.

Where they live

Open an NPC and go to its Memory pane. It lists everything this NPC carries between Conversations, newest first, with when each was last used — used today, used 4 days ago, or never used.

A Memory shared across the Village carries a Village badge.

Write one yourself

Type it into the box at the top and press Remember.

Write each one so it makes sense on its own, months from now, with none of the Conversation around it. Up to 2000 characters.

The checkbox beside the button — Every NPC in the Village — sets the scope.

The two scopes

memory.scope is either npc or village, and it is the whole mechanism:

npc — this NPC knows it. The default.
village — every NPC in the Village knows it.

Use village for things that are true of you rather than of one NPC: how you like work handed back, what your projects are called, which of two conventions you follow. Use npc for everything else.

Listing one NPC's Memories always includes the Village-scoped ones, because those are genuinely in scope for it. A list that left them out would misrepresent what the NPC knows.

Let the NPC write its own

Grant the memory built-in on the NPC's Tools pane and it gets three Tools, each rendering in the transcript like any other Tool call:

Tool	What it does
`remember`	Saves something worth knowing later, at `npc` or `village` scope
`recall`	Looks for something it was told before
`forget`	Deletes a Memory that turned out to be wrong

Without that grant, the NPC writes nothing and reads nothing. The Memory pane still works; you are simply the only author.

How a Memory reaches a turn

Relevant Memories are supplied to the NPC before it answers, under a heading What you already know, rather than waiting for it to think of calling recall. An NPC that has to decide to look things up mostly will not, and the common case — "what did they tell me about this before" — is answerable from the question alone.

Retrieval works in two steps. A full-text search over the content narrows the field, then the survivors are ranked by similarity to the question and the best handful are supplied.

Two consequences follow, and both are worth knowing rather than discovering:

Ranking is semantic only when there is an embedding model: the one chosen in Settings → Memory embeddings, or OpenAI's when nothing is chosen and an OpenAI key is set. Without one, recall still works and ranks by keyword instead. Memory does not break; it gets blunter.
The lexical step comes first. A Memory worded completely differently from your question can be missed, because the first step never surfaces it to be ranked. MySQL's full-text defaults also apply, so very short words and common stop words are not indexed — a Memory whose only distinctive word is "AI" is not findable by that word.

The full reasoning, and the ceiling it accepts, is in ADR 0010.

Correct one

Press Edit, change the text, press Save. The edit takes effect immediately.

Editing clears the Memory's embedding rather than recomputing it, so an edited Memory is found by keyword until something re-embeds it. That keeps saving instant; it costs a little ranking quality in the meantime.

Delete one

The trash button forgets it. DELETE /api/memories/:memoryId removes the row, and a deleted Memory cannot influence any later turn — there is no second copy, no index that outlives it, nothing cached that keeps surfacing it.

A Memory you cannot inspect is a Memory you cannot trust, and a system that quietly accumulates beliefs about you is one you stop believing. That is why the whole set is enumerable and why deletion is real.

Doing this over the API

Everything the pane does is four routes:

The search parameter matches on content, and the listing returns at most 200 Memories, newest first.

Long Conversations

Memory is not what keeps one long Conversation coherent. History is windowed before it is sent to the Provider, and what falls off the front is condensed into a rolling summary that goes into the prompt in its place. A Conversation past the model's context window keeps working without you starting a new one.

Where to go next

Memory as a concept
Teaching a Skill, for procedure rather than fact
Granting Tools per NPC
Context Engineering: The Window Is a Budget, Not a Container — on the Codebrewerz blog, the reasoning behind recall and summaries.