/memory-consolidate

name: memory-consolidate
description: Consolidate brain memory and mine user sessions since the last consolidation checkpoint (sleep-cycle style). Use to reduce noisy prompt injection while preserving durable high-value memories.
kind: sop

Memory Consolidate

Overview

Run a "brain sleep cycle": 1. Consolidate existing memory (dedupe, decay, merge, vault relocation) 2. Mine **user** sessions since the last consolidation checkpoint 3. Persist a new checkpoint only after a successful run

Use the `brain` tool for brain changes and the `vault` tool for reference relocation. Never edit `brain.jsonl` directly.

---

Importance levels (retention)

Use these symbols while triaging entries:

• 🔴 **High importance** — durable, high-leverage, should remain in brain
• 🟡 **Medium importance** — useful but optional; review for merge/tightening
• 🟢 **Low importance** — stale/noisy/duplicative; prune or relocate

> For memory retention, **high importance means keep longer**, not delete.

---

Parameters

• **brain_path** (default: `~/.rho/brain/brain.jsonl`)
• **mine_sessions** (default: `true`)
• **since** (default: `last_consolidation`) — `last_consolidation | <ISO timestamp> | <duration>`
• **days_fallback** (default: `1`) — only used when no checkpoint exists
• **session_dir** (default: `~/.pi/agent/sessions/`)
• **max_new_entries** (default: `10`)
• **confidence_threshold** (default: `high`) — `high | medium`
• **checkpoint_key** (default: `memory_consolidate.last_consolidated_at`)

---

Steps

1) Inventory

List memory by type and count totals.

**You MUST report counts for:**

• learnings, preferences, behaviors, identity, user, context, tasks, reminders
• total active entries

2) Resolve mining window

Determine the lower bound timestamp: 1. If `since` is explicit timestamp/duration, use it. 2. If `since=last_consolidation`, read checkpoint from `checkpoint_key`. 3. If no checkpoint exists, use `days_fallback`.

**Constraints:**

• You MUST mine only sessions in the resolved window.
• You MUST include the resolved window in the final report.

3) Session mining (user messages only)

Extract durable learnings/preferences from user messages in matched sessions.

Confidence policy:

• **High**: explicit user statements/corrections/preferences → auto-add
• **Medium**: strong multi-session inference → add only if threshold is `medium`
• **Low**: ambiguous/one-off/hypothetical → skip

**Constraints:**

• You MUST NOT exceed `max_new_entries`.
• You MUST dedupe against existing memory before add.
• You MUST prefer high-confidence extractions first.
• You MUST include session id in `source` when available (`session:<id>`).

4) Decay stale learnings

Run `brain action=decay`.

**Constraints:**

• You MUST report decayed count.

5) Consolidate existing entries

Identify duplicates/superseded/stale entries and merge candidates.

Apply the importance lens:

• 🔴 Keep durable, high-value operational guidance
• 🟡 Merge or tighten wording
• 🟢 Remove if stale/noisy/redundant

**Apply the 30-day test to every entry:** "Would this change a decision I make 30 days from now?" If no, it's noise — remove it.

**Auto-remove categories (these should never have been stored):**

• Version numbers or update confirmations ("updated X to v1.2.3")
• Heartbeat or check-in status reports ("Heartbeat Feb 19: all clear")
• Benchmark scores or run results ("scored 42/89 = 47.2%")
• Bug sweep summaries without a generalizable root cause ("reviewed X, no bugs found")
• UI/feature implementation details ("button text changed to X", "layout uses 3 columns")
• Task completion status ("task X is complete", "run Y failed")
• Project-specific transient state that won't inform future decisions
• Duplicates — keep the best-worded version, remove the rest

**Constraints:**

• You MUST NOT remove preferences unless contradicted/superseded.
• You MUST NOT invent new facts while merging.
• When uncertain, keep.
• You SHOULD be aggressive about pruning — a smaller, high-signal brain is better than a large, noisy one.

6) Vault relocation for reference-heavy entries

"Reference-heavy" means useful knowledge that does **not** need to be injected every turn and can be searched ad hoc.

Typical candidates:

• long feature histories / changelog-style learnings
• architecture rationale requiring structure
• multi-step runbooks / deep troubleshooting notes
• linked research/reference material

**Constraints:**

• You MUST write vault notes before removing corresponding brain entries.
• Each note MUST include `## Connections` with `[[wikilinks]]`.
• Leave a short pointer memory when useful (e.g., "See [[note-slug]]").

7) Persist checkpoint (success only)

At end of successful consolidation, set/update checkpoint timestamp (`now`, UTC ISO-8601).

**Constraints:**

• You MUST update checkpoint only after successful completion.
• You MUST NOT advance checkpoint on partial/failed runs.

8) Report

You MUST report:

• counts before/after by type + total
• mining window and sessions analyzed
• added/skipped mined entries (with skip reasons)
• decayed, removed, merged, relocated counts
• vault notes created/updated (slugs)
• checkpoint old → new value
• up to 10 significant changes