---
name: memory-management
description: Best practices for MEMORY.md hub, memory/shards, and long-term knowledge retention
version: 1.1.0
---

# Memory Management

Guidelines for keeping long-term memory useful and within size limits:

## Layout

- **Sharded (default for new workspaces):** `MEMORY.md` is a short **hub** (TOC + guidance). Bulk entries go to `memory/shards/<topic>.md` (default `general`). Marker: `memory/shards/.mugi_memory_layout`.
- **Monolith (legacy):** everything in root `MEMORY.md` until you run **`migrate_memory_to_shards`**.
- Use **`append_to_memory`** with optional **`shard`** (aliases `topic`, `category`) for topic files.

## When to update memory

- User shares a **preference** (communication style, tool choices, project conventions)
- A **fact** is established that will be referenced again (API keys location, server addresses, project structure)
- A **pattern** emerges from repeated interactions (user always wants tests, prefers concise answers)

## When NOT to update memory

- Transient information (today's weather, one-off calculations)
- Information already in memory (check first with `search_memory`)
- Raw conversation content (summaries handle this)

## Structure

- Use clear section headers; dated blocks per workspace conventions
- One fact per bullet point — atomic, self-contained
- Include dates for time-sensitive facts ("as of 2026-03")
- Prefix corrections with context: "Previously X, now Y because Z"

## Maintenance

- When memory approaches the soft cap, archive low-value entries rather than deleting
- Merge duplicate entries during maintenance passes
- Remove entries the user has explicitly contradicted
- Consolidation merges optionally go to `memory/shards/consolidation.md` when sharded (hub stays small)
