Memory

A memory is a durable fact your team's instances should apply. Not a note you'll read later - something an instance recalls, mid-task, and acts on.

What belongs in memory

Good memories are the things you'd be annoyed to re-derive:

• Decisions and why you took them. "We use advisory locks rather than a queue for the migration, because X."
• Gotchas. "The gRPC client retries on UNAVAILABLE but not DEADLINE_EXCEEDED, so wrap long calls with an explicit deadline."
• Conventions. "Every table gets created_at/updated_at; we don't soft-delete."
• How-tos and runbooks that live nowhere else.
• References - who owns what, where a thing is.

What doesn't: transient state, anything secret, and anything already recorded in code or git history. A memory that duplicates the repo is one more thing to keep true.

Writing one

Say it, and let your instance store it:

"Remember that for the acme project: the client retries on UNAVAILABLE but not DEADLINE_EXCEEDED, so long calls need an explicit deadline or they hang. Type it as a gotcha."

Give it a title you'd search for - it's the handle, and re-using it is one way to update the memory later.

Project, type and tags

Three axes describe a memory, and they answer different questions. Keeping them separate is what stops your taxonomy collapsing into one undifferentiated pile of labels:

Shape, subject and scope. A memory can be a decision about oauth in kythene, and each part is worth filtering on separately.

The one that gets skipped is type, and the failure it causes is quiet: kind-words leak into tags instead. A workspace with tags literally named gotcha and decision has lost the distinction, because now "what kind of note is this" and "what is it about" share a namespace and neither filter means much. Set type unless the note genuinely fits no kind - not by default.

Also worth knowing:

• aliases - extra names a [[wikilink]] can use to reach this memory. Handy for imported notes whose old filename still gets linked. See Linking memory.
• private - keep it to yourself. It only ever tightens: a memory can also be made private automatically, and asking for "not private" never loosens that.

Keeping memory true

Memory that's wrong is worse than no memory at all, because an instance applies it with confidence and it reads exactly like a memory that's still true. Three mechanisms, by what actually happened to the fact:

• Supersede - the fact changed. Name the memory with supersedes, or write it again under the same title in the same project: a new version, history retained, approvals cleared.
• Deprecate - the fact stopped applying. Recall stops surfacing it, it stays retrievable for audit, and you can name the memory that replaced it.
• Forget - it should never have existed. The memory, its artifacts and their bytes, gone for good.

If a recalled memory contradicts the live system, correcting it is part of the task: verify against the real thing first, then supersede or deprecate. Instances are told this by the recall tool itself and by the workspace guide returned with every recall, so it holds for any MCP client, not only ones running the Claude skill.

Stale memory and supersession covers all of this properly - what each operation does to history and recall, how to read deprecated memory deliberately for audit, and where each one lives in the MCP API and the CLI.

Two scopes

• Your own, per project. In your workspace, scoped to the project you're working on. Private to you until you decide otherwise, and it follows you across every machine and every tool.
• The team's. Knowledge promoted into a team workspace, which every member's instance recalls - but only after an owner approves it. See Promoting memory to the team.

Promote sparingly. Team memory is the team's shared truth; per-project memory is the low-stakes scratch space where most of the volume should live.

Memory and privacy

Memories inherit the access rules of their project tag, so a memory in a private project is visible to that project's members and nobody else.

There's a subtler case Kythene handles for you. If an instance reads restricted content and then writes a memory summarising it, that summary inherits the restriction rather than quietly becoming a public paraphrase of private material. Where the sources can't be reconciled to a single project you belong to, the memory is kept private to you - it errs towards over-restricting. The reply tells the instance when a memory was scoped down, so it isn't a silent surprise.

This is on by default on the hosted service. Self-host operators enable it with memory_provenance - see Self-hosting.

From the CLI

printf '# Deploy gotcha\nMigration runs before the worker boots.\n' \
  | kythe remember - --project acme --title "Deploy gotcha" --type gotcha

kythe deprecate <memory-id> --replaced-by <new-memory-id>
kythe forget <memory-id>

remember takes a file path or - for stdin. Without a title it uses the first line of the body.