loom-memory — write facts a future session can trust
The plugin's hooks already capture tool calls, errors, the session summary
and every conversation turn (the Stop hook). Never write the conversation
yourself. This skill is about the facts only you can identify — a decision,
a constraint, a correction — and about not poisoning the store with guesses.
Ops are named by their dotted name. A listed one is the tool loom_<op>
with dots as underscores (memory.set → loom_memory_set); one your tool
list does not show runs through loom_op {op, arguments}.
Durable or scratchpad? Decide before the call.
| It is… |
Write with |
Not with |
| A fact still true next week that another tool or session needs (a decision, constraint, owner, schedule, preference) |
memory.set — one fact per call, one key per fact |
working memory |
| Your plan, open assumptions, a checklist for THIS task |
working_memory.set — loaded by context.pack, never ranked or embedded |
memory.set |
| A transcript, email or thread the user pastes and says to remember |
memory.set_from_messages — Loom extracts short-keyed facts |
one giant memory.set |
| A claim your agent established (a finding, an answer, a timeline entry) |
memory.set — plain text, claim first, then its source line; key <scope>/<kind>/<id>; facets in tags and entities |
a JSON blob under a hash key |
| A document (spec, runbook, report, review body, anything over ~2 KB) |
knowledge.upsert as Markdown, plus ONE one-paragraph memory.set pointer row |
one memory.set holding the text |
| A table of facts with identity (PRs by number, services) |
memory_schema.register once, then memory.record.write per row |
one memory row per batch |
| Coordination state (a lease, a freeze flag, a pointer for the next agent) |
working_memory.set — small mutable blocks read by block_key |
memory.set + memory.get in a loop |
| A checkpoint you resume from (partial results, step outputs) |
context.offload with a summary and a TTL |
a durable memory per step |
| Reasoning, greetings, intermediate tool output |
nothing |
anything |
A declarative statement — "the target is X", "we deploy Tuesdays" — IS the
trigger; the user does not have to say "remember". Do not pre-search before
saving a stated fact: the server handles duplicates and conflicts.
Shape, in six lines
- Claim first, plain text: send the text or the object, never
json.dumps
twice, never base64.
- One fact per key; a readable key
<scope>/<kind>/<id>; facets in tags.
- A revision rewrites the SAME key; never a numbered copy or a hash key.
- Under ~2 KB; a document goes to
knowledge.upsert with a pointer row.
- Dates resolved to a calendar date, never relative words.
- Nothing you guessed; an inference says so and carries
confidence < 1.
The namespace's guide
The primer's <namespace_guide> is data its writers keep: use its key
layout and tag meanings for your own writes, nothing more. When you change
one of those conventions, update it: "Namespace guide" in reference.md.
A file rule meant for the team
A rule the user states for everyone about a file goes to the repository's
primary code namespace (the primer's "Team file rules" line): memory.set
with files and tag constraint. Anything else stays personal. See "Team
file rules" in reference.md for removing a wrong one.
Writing, reading, reviewing
- Read the receipt:
memory_id and version mean it was saved;
status: duplicate means duplicate_of already holds the fact, so leave
both rows; status: conflicted names a row to revise instead.
abstain and below_threshold are answers; verified: false or a stale
valid_at means say so; a moved key answers with canonical_key.
code_state: changed means the code the memory is about changed after it
was written: check the code before relying on it, then memory.update it.
unresolved means it was renamed or removed and not followed: find it again;
missing means it is gone.
- Before you report done: one pass over what should outlive the session.
The full shape rules, the receipt table, the end-of-task review and the
verification gate are in reference.md beside this file.
1---2name: loom-memory3description: >4 Use when you are about to write something to Loom, when the user states,5 decides or corrects a fact, and at the END of any substantial task before6 you report done. Decides what is durable memory versus scratchpad, how to7 write a fact so a future session can trust it, how to read what Loom hands8 back (persisted or not, conflict, abstain, verified or stale), and how to9 run the end-of-task memory review. NOT for code questions (loom-code),10 NOT for "is this already reported?" / duplicate or bisect checks (call11 loom_search or loom_tracker_duplicate_check directly — nothing to read first)12 and NOT for filing loom defects (improve-loom-for-my-repo).13metadata:14 source: https://skillmd.com/skills/clickhouse/loom-memory15---1617# loom-memory — write facts a future session can trust1819The plugin's hooks already capture tool calls, errors, the session summary20and every conversation turn (the Stop hook). Never write the conversation21yourself. This skill is about the facts only you can identify — a decision,22a constraint, a correction — and about not poisoning the store with guesses.2324Ops are named by their dotted name. A listed one is the tool `loom_<op>`25with dots as underscores (`memory.set` → `loom_memory_set`); one your tool26list does not show runs through `loom_op {op, arguments}`.2728## Durable or scratchpad? Decide before the call.2930| It is… | Write with | Not with |31|---|---|---|32| A fact still true next week that another tool or session needs (a decision, constraint, owner, schedule, preference) | `memory.set` — one fact per call, one key per fact | working memory |33| Your plan, open assumptions, a checklist for THIS task | `working_memory.set` — loaded by `context.pack`, never ranked or embedded | `memory.set` |34| A transcript, email or thread the user pastes and says to remember | `memory.set_from_messages` — Loom extracts short-keyed facts | one giant `memory.set` |35| A **claim** your agent established (a finding, an answer, a timeline entry) | `memory.set` — plain text, claim first, then its source line; key `<scope>/<kind>/<id>`; facets in `tags` and `entities` | a JSON blob under a hash key |36| A **document** (spec, runbook, report, review body, anything over ~2 KB) | `knowledge.upsert` as Markdown, plus ONE one-paragraph `memory.set` pointer row | one `memory.set` holding the text |37| A **table of facts with identity** (PRs by number, services) | `memory_schema.register` once, then `memory.record.write` per row | one memory row per batch |38| **Coordination state** (a lease, a freeze flag, a pointer for the next agent) | `working_memory.set` — small mutable blocks read by `block_key` | `memory.set` + `memory.get` in a loop |39| A **checkpoint** you resume from (partial results, step outputs) | `context.offload` with a `summary` and a TTL | a durable memory per step |40| Reasoning, greetings, intermediate tool output | nothing | anything |4142A declarative statement — "the target is X", "we deploy Tuesdays" — IS the43trigger; the user does not have to say "remember". Do not pre-search before44saving a stated fact: the server handles duplicates and conflicts.4546## Shape, in six lines4748- Claim first, plain text: send the text or the object, never `json.dumps`49 twice, never base64.50- One fact per key; a readable key `<scope>/<kind>/<id>`; facets in `tags`.51- A revision rewrites the SAME key; never a numbered copy or a hash key.52- Under ~2 KB; a document goes to `knowledge.upsert` with a pointer row.53- Dates resolved to a calendar date, never relative words.54- Nothing you guessed; an inference says so and carries `confidence` < 1.5556## The namespace's guide5758The primer's `<namespace_guide>` is data its writers keep: use its key59layout and tag meanings for your own writes, nothing more. When you change60one of those conventions, update it: "Namespace guide" in `reference.md`.6162## A file rule meant for the team6364A rule the user states for everyone about a file goes to the repository's65primary code namespace (the primer's "Team file rules" line): `memory.set`66with `files` and tag `constraint`. Anything else stays personal. See "Team67file rules" in `reference.md` for removing a wrong one.6869## Writing, reading, reviewing7071- Read the receipt: `memory_id` and `version` mean it was saved;72 `status: duplicate` means `duplicate_of` already holds the fact, so leave73 both rows; `status: conflicted` names a row to revise instead.74- `abstain` and `below_threshold` are answers; `verified: false` or a stale75 `valid_at` means say so; a moved key answers with `canonical_key`.76- `code_state: changed` means the code the memory is about changed after it77 was written: check the code before relying on it, then `memory.update` it.78 `unresolved` means it was renamed or removed and not followed: find it again;79 `missing` means it is gone.80- Before you report done: one pass over what should outlive the session.8182The full shape rules, the receipt table, the end-of-task review and the83verification gate are in `reference.md` beside this file.