AgentsVille

Concepts

Memory

A Memory is something an NPC should still know in a Conversation that has not happened yet.

Conversations end. Memory is what survives them: a preference you stated once, a decision you made in March, the fact that your staging database is called something unhelpful. Without it, a Player who explains a process on Monday explains it again on Tuesday, to the same NPC.

Two scopes

NPC. Only that NPC knows it. Most Memories are this.

Village. Every NPC you own can recall it. Use this for what everybody should know — how your team names things, who the customer is, which repository is the real one.

An NPC's recall always covers its own Memories plus the Village's, because that is genuinely what it knows. A Village-scoped Memory written by one NPC is recalled by another.

Written by the NPC, or by you

An NPC with the memory capability granted has three Tools:

  • remember — save a fact, at NPC or Village scope.
  • recall — look something specific up.
  • forget — delete a Memory that has turned out to be wrong.

Each call renders in the transcript, so you can see the moment an NPC decided something was worth keeping.

You can also write, edit and delete Memories yourself, from the NPC's Memory page. Neither route is the "real" one.

Supplied, not fetched

Before an NPC answers, AgentsVille finds the Memories that bear on what you just asked and puts them into the prompt under a heading of their own. The NPC does not have to think to call recall — an NPC that has to decide to remember mostly will not, and "what did they tell me about this before" is answerable from the question alone.

recall exists for the cases where the NPC needs something more specific than what it was handed.

Always yours to read and delete

Every Memory is listed, searchable, editable and deletable by the Player who owns it. Deleting one stops it influencing any later turn.

This is not a convenience feature. A store you cannot enumerate is a store you cannot trust, and a system that quietly accumulates beliefs about you is one you stop believing. It is also why AgentsVille has no opaque index behind the Memory list — what you see there is what the NPC gets.

How recall actually works

AgentsVille runs on MySQL 8.4, which has no vector type. Rather than adding a second datastore to back up and keep consistent, Memory uses what MySQL does have:

  1. A full-text search over Memory content narrows hundreds of rows to tens.
  2. Those survivors are scored by similarity against your question.
  3. The best handful go into the prompt.

If a question matches nothing lexically, recall falls back to your most recent Memories rather than returning nothing. See ADR 0010.

Two consequences worth knowing:

  • Recall is lexical before it is semantic. A Memory worded completely differently from your question can be missed, because step 1 never surfaced it for step 2. Wording a Memory the way you would ask about it helps.
  • MySQL's full-text rules apply. Words shorter than three characters and common stop words are not indexed, so a Memory that is only "AI" is not findable by that word.

Semantic ranking is optional

The similarity step needs an embedding model: the one the Operator picks in Settings → Memory embeddings — a local model works — or OpenAI's when nothing is picked and an OpenAI key is set. A Village with neither still remembers and still recalls — it ranks by keyword instead. Nothing fails, and nothing is lost.

Memory is not the Conversation window

Long Conversations are kept coherent separately, by trimming what is sent each turn and keeping a rolling summary. Memory is the thing that crosses Conversations. See Conversation, Message and Part.

Next

Further reading