mikeyobrien/memory-consolidate

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