---
doc:
  title: What the person said
guide:
  slug: memory
  brief: the words a person wants remembered
  description: >-
    store_memory_save and store_memory_recall: keeping what the person said
    about how they want things done, in their own words rather than your
    summary of them — what belongs in a memory, what context is for and what it is not,
    when to reach for each tool, how a recall is ranked, how a memory differs
    from the notes an app keeps, and where a document you wrote goes instead:
    project documents, written into the app's store as entities and found
    again with search.
---

# What the person said

A person says how they want things done once — "use grams, never cups" — and
then says it again next month, to a different agent, because the first
conversation ended. `store_memory_save` is where that sentence goes to stop
being said, and `store_memory_recall` is how it comes back.

The rule is one line long: **keep their words, not your summary of them.**

This page is those two tools: what belongs in a memory, what does not, how they
are ranked, and how they differ from an app's `NOTES.md`.

The map is at <https://yaks.app/docs.md>.

## The shape

Two things go in, and only two:

    store_memory_save {
      said: 'use grams, never cups',
      context: 'setting up the recipe app',
      about: 'recipes'
    }

`said` is the person's sentence, exactly as they said it. `context` is the one
line somebody needs in order to read that sentence later — what was being talked
about when they said it. `about` names an app, by slug, where the words were
about one; leave it out where they were about everything.

That is all a memory needs, and there is no field for what you concluded from
what they said.

## Why verbatim

An agent that summarises what somebody told it can only ever remove information.
Everything the summary keeps was already in the sentence; anything it drops is
gone, and no agent afterwards can get it back — including you next week. Six
months of that and the person's own words have been through a dozen rewrites and
mean something else.

So save the sentence:

    said: 'i want it to feel soft and friendly, not technical'

and not what you took from it:

    said: 'user prefers approachable UI copy'      ← no

The second one reads like a decision somebody made. Nobody made it. It is your
paraphrase carrying the person's authority, and the next agent cannot tell the
difference.

## What context is for, and what it is not

Context is a handle, not a record. It names what was being worked on, not what
was concluded:

    said: 'never on a Sunday'
    context: 'about the app mailing the volunteer list'      ← yes

    said: 'never on a Sunday'
    context: 'The user asked that outbound mail be suppressed on
      weekends, which we implemented by checking the day in worker.js
      before calling deliver, see the sendable() helper…'       ← no

Two lines is the ceiling, and a save with more is clamped to the first two. If
the words stand on their own, leave it out.

## Reaching for it

Save the moment they state a preference, a standard, a taste, a way of working,
or something they never want done again. The tell is that they are talking about
_how_ rather than _what_: "always show me the link", "keep the pages plain",
"don't ask me before you deploy", "put the newest at the top".

Recall before you build or change anything, and whenever a choice is one they
might already have made:

    store_memory_recall { said: 'how the pages should look' }

Say what you are about to decide, in a few words. It answers the memories
nearest that in meaning, closest first, whether or not they share a word with
it, so "how the pages should look" finds "keep it soft, not technical". A memory
saved a moment ago is ranked once its vector is made, a few seconds later. With
no `said` at all you get the newest.

Each one comes back whole: the sentence and its context. Never a snippet — half
of what somebody said is worse than none of it.

## They come back with `about`

The newest few come back with `about`, under a heading of their own, beside the
notes of every app you can reach — so one call at the top of a conversation is
usually the whole of it. `store_memory_recall` is for the rest, and for the
moment a particular question comes up.

They belong to the space, not to an app. Everyone in the space reads them and
everyone who may write there can save one, so a thing said to one agent about
one app is known to every agent working anywhere in that space.

## Against a NOTES.md

`about` returns both, and they hold different things:

- **`NOTES.md`** is the rules for one app, written by an agent, in whatever
  words make them followable — "every ingredient's amount is repeated in the
  step that uses it". It lives beside that app's `index.html`. See
  <https://yaks.app/docs/notes.md>.
- **A memory** is what the person said, in their words, across the whole space —
  "use grams, never cups".

When they state a rule for one app, both are right: keep their sentence with
`store_memory_save`, and write the rule the app is to be built by into its
`NOTES.md`.

## Project documents

A memory is the person's sentence. A `NOTES.md` is how one app is kept, in their
terms, in four kilobytes. Neither is the place for a document you wrote — how
the game's combat resolves, the shape a page expects its rows in, why the
schedule is generated a month ahead, the overview somebody asked you to write
down. That is not a sentence to preserve and it is not house rules.

Write it where the app's own knowledge already lives: as an entity in the app's
store, which is what `doc` is for.

    graph_apply({ app: 'idler-rpg', entities: [{
      entity: { eid: '$d' },
      alias: { name: 'combat' },
      note: {},
      doc: {
        title: 'Combat',
        body: '# Combat\n\nA tick is ten seconds...' } }] })

`doc.title` and `doc.body` are both searched, so the document is findable the
moment it is written — by anyone, in any conversation, including you next week:

    search({ text: 'a swing resolves' })
    graph_query({ app: 'idler-rpg', query: '.note&?doc' })
    graph_show({ ids: ['combat'] })

Give `search` the words that are in the document, not the question you want
answered: it matches the text as a phrase, ranked. A trailing `*` prefix-matches
the last word.

Two small things make that work, and both are ordinary:

- **A component of its own.** `note: {}` — declared in the app's `vocab.json`
  with no properties at all — is what separates your documents from the app's
  own data, which has `doc` on it too. Then `.note` is the whole reading list.
- **A name.** `alias: {name: 'combat'}` makes the write idempotent: writing
  "combat" again patches the document that already holds that name instead of
  leaving two, and a name can be used wherever an eid can, so `graph_show` reads
  it back without a lookup.

They are rows in the app's store like any other, so they travel with the app, a
member reads them, and whatever they held an hour ago can be put back for thirty
days.

What they must not be is a memory. `store_memory_save` is for the person's words
and nothing else, and a document of yours saved there is your prose carrying
their authority — handed to the next agent as something they said. When they ask
for an overview to be kept, both halves are right: keep their sentence with
`store_memory_save`, and write the document into the store.