memory

Turn mined candidate turns into a small set of durable facts worth remembering.

Steps

1. Run the mine. sessions memory mine --repo <path> --json (omit --repo for the current repo; --all mines every repo in the index; add --since-last to mine only transcripts that changed since the previous mine, which is what the weekly summary uses). stdout is a JSON array of candidate records; progress goes to stderr. If the command is not found, say so and stop — do not substitute a search. If the array is empty, say there is nothing to triage and stop; never invent candidates.

2. Confirm fuzzy paraphrase pairs. sessions memory report --repo <path> --json (same scoping flags as the mine) returns a fuzzy array: freshly mined clusters that look like paraphrases of an APPROVED memory but scored below the binary's assert threshold. The binary deliberately does not make this judgment — you do. Present each pair (cluster.text ~ memory.text, with its similarity and session count) and ask confirm/deny, batched with the triage questions in step 7 rather than as a separate interrogation. If the array is empty, move on.

   • Confirm → sessions memory merge <memory-id> <cluster-id> — the approved memory is the canonical, the new phrasing folds into it. This is the same write-back as step 8's clustering merge: future mines recognize the phrasing as accounted for, and the pair stops appearing in the report. If merge exits non-zero on an unknown id, run sessions memory mine --repo <path> first and retry — report reads fresh evidence without persisting it, and merge only knows ids the store holds.
   • Deny → sessions memory snooze <cluster-id>. Reject would kill the fact itself, which is terminal and wrong when the fact is real; snooze is the suppression that persists the dismissal without a verdict. The report's pipeline drops suppressed clusters before classifying, so the denied pair goes quiet on later runs instead of being re-asked every triage. If snooze exits non-zero on an unknown id, run sessions memory mine --repo <path> first and retry, exactly as with merge. A denied pair resurfaces only the way any snooze does — a later merge folding in a new phrasing after the 30 days pass, which the current mine never produces, so in practice the denial holds until the clustering evidence changes.

3. Cluster paraphrases. Group candidates whose texts assert the same fact in different words — "use canary as the base branch" and "we branch off canary" are one memory in two phrasings. A cluster's distinctPhrasings is the number of distinct member texts. Keep the clearest phrasing as the cluster's text; the rest are evidence, not separate memory. Byte-identical repeats were already collapsed upstream, so every member you see is genuinely a different wording.

4. Read what is already binding. sessions memory documented --json lists every statement an agent working here is already told — the global CLAUDE.md, a repo CLAUDE.md or AGENTS.md, and Claude Code's own per-project memory store. Read it before the rubric, because it decides the rubric's first question.

   These are read, never written. This store complements those surfaces; it does not replace, edit, or override them.

   Other agents' stores are candidates, not gospel. If the user asks to pull in what another agent remembers — pi-hermes-memory's store, Claude's CLAUDE.md files — run sessions memory import --from pi-hermes (or claude, or all) FIRST, before mining: those facts land in the candidate batch you are about to triage, marked by their lack of session evidence. Triage them through the same rubric below; the review_agent_memories MCP tool previews what would import and flags entries that overlap memories already in the store (similarTo), and get_memory_sources inventories what stores exist. A pi-hermes fact scoped to a bare project name arrives unbound — bind it with --scope repo:. when you approve it, or reject it if the project is gone.