Memory types

Memory types

A memory has a type, and each type has its own writing tool with the same name. A pitfall is read back by the call that asks for pitfalls, not found by luck among everything else.

Which one to write

type	write it when…	tool
note	you established a fact or made a decision	note(title, content, …)
anti_pattern	something looked right and turned out to be a trap	anti_pattern(title, pattern, why_wrong, instead, …)
reasoning	an analysis settled a question and the why is worth keeping	reasoning(title, hypothesis, reasoning, result, revised_belief, next_time, …)
checkpoint	you are pausing and the next session needs your bearing	checkpoint(title, intent, established, pursuing, open_questions, …)
task	work will outlive this session	task(title, goal, items, …) — see Tasks
diagram	a routine is easier to follow as steps than as prose	diagram(title, nodes, edges, …) — see Diagrams

Note

One memory holds one fact. Retrieval ranks whole memories, so a body that answers four questions comes back for all four and is read for one. Write the second subject as its own memory and connect the two with link_memories().

What every memory carries

field	what it is
title	one line, at most 120 characters, naming the memory in the words someone would search for. It outweighs every other field in search.
domain	where it lives, as a path: acme/checkout/billing. See Domains.
also	other paths it belongs to, for subjects that cut across the tree
tags	synonyms and keywords the body does not use
confidence	unverified (default), confirmed or contradicted
review_after	optional: a date or span (90d) after which the claim needs a recheck
source_ref	optional: what to check it against — a file, a table, a URL
session	stamped automatically, so one conversation's memories group together

Typed bodies

checkpoint, anti_pattern and reasoning are written field by field and stored as one body with a label per field:

TEMPTATION: Retrying a failed charge with a fresh idempotency key.
WHY WRONG: Each key is a new request, so a retry after a timeout can charge twice.
INSTEAD: Derive the key from the order id and reuse it on every retry.

The dashboard shows those fields separately, and a body that does not read back into them is listed under Maintenance → Sections for a person to fix.

Example

note(
    title="Stripe sends charge.succeeded twice for one charge",
    domain="acme/checkout/billing",
    tags="idempotency, webhook, retry, duplicate delivery",
    content="A retry carries the same event id, so the handler has to key off "
            "the event id. Keying off the charge id books the order twice.",
)

A write returns the new uid. When something similar is already stored, it also returns similar with a line on what to do — update the old one, link the two, or keep both. It never blocks the write.

Changing a memory

to…	call
correct the content (the old version is kept)	edit_memory(uid, new_content=…)
add to it	edit_memory(uid, new_content=…, mode="append")
rename it or retag it	edit_memory(uid, title=…, tags=…)
say whether it still holds	set_confidence(uid, "confirmed" | "contradicted")
connect it to another	link_memories(from_uid, to_uid, "relates_to")
retire it (reversible)	forget(uid, reason, superseded_by)

handoff is a stored type with no writing tool: rows of it still count in must_read(), and task() is how work is passed to the next session.

---

See also: Tools for every parameter · Curation for confidence and review dates.