# Memory Organize

> Periodic maintenance of role memory: dedup, tidy, consolidate, and pending management.

- Skill: `dwsy/memory-organize` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dwsy/memory-organize`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dwsy/memory-organize/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Dwsy (https://skillmd.com/u/dwsy)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/dwsy/memory-organize

---


# Memory Organize

You are maintaining a role's persistent memory system. Keep it healthy, accurate, and useful.

## Memory Layers

```
consolidated.md  ← L2: deduplicated learnings + preferences (main)
pending.md       ← Pending: auto-extracted, awaiting verification
daily/*.md       ← L1: raw session logs
```

## Tools Available

| Tool | Purpose |
|------|---------|
| `role_exec({ op: "list" })` | List all memories, detect structural issues |
| `role_exec({ op: "consolidate" })` | Rule-based dedup: exact + Jaccard similarity. Safe, never deletes unique entries. |
| `role_exec({ op: "repair" })` | Fix markdown structure issues |
| `role_exec({ op: "llm_tidy" })` | LLM-guided: rewrites verbose, detects contradictions, suggests deletions |
| `role_search({ query: "..." })` | Search with auto-reinforce (≥0.5 → used+1) |
| `role_exec({ op: "reinforce", args: { content: "..." } })` | Increment `[Nx]` usage count |
| `role_exec({ op: "delete_learning", args: { content: "..." } })` | Remove stale entry |
| `role_exec({ op: "update_learning", args: { id/query, content } })` | Rewrite entry |
| `role_exec({ op: "role_info" })` | List role paths only; use memory ops for memory changes |

## Process

### Step 1: Assess

```
role_exec({ op: "list" })
```

Look for:
- **Parse issues** — structural problems
- **High [0x] count** — many unverified = noise
- **Long entries** — should be <120 chars

### Step 2: Repair (if needed)

```
role_exec({ op: "repair" })
```

Fixes: malformed headings, missing sections, stray lines. Safe, rule-based.

### Step 3: Consolidate (dedup)

```
role_exec({ op: "consolidate" })
```

**Rule-based, NOT LLM:**
- Exact text match → keep highest `[Nx]`
- Jaccard token similarity (config threshold) → merge, keep highest
- Rewrites the canonical section layout in `consolidated.md`
- Updates `# Last Consolidated` date

`consolidate` does **not** magically upgrade `[0x]` to Normal. Priority still depends on usage (`reinforce` / auto-reinforce during search).

### Step 4: LLM Tidy (deep cleanup)

```
role_exec({ op: "llm_tidy" })
```

LLM produces a plan:
- **Rewrite** verbose entries → concise
- **Detect contradictions** between entries
- **Suggest deletions** for stale entries
- **Add** new entries derived from synthesis

### Step 5: Pending Management

Check `memory/pending.md`:
Use the standard file-read tool on the injected role's `memory/pending.md` path only when pending details are needed.

- `[○]` pending → if relevant to current work, `search` to auto-promote (score ≥0.5)
- `[✓]` already promoted
- `[✗]` discarded (7-day auto-expiry)

Pending entries that survive 7+ days without use are auto-expired. Manual promotion via search.

### Step 6: Reinforce Active Memories

For insights used in this session:
```
role_exec({ op: "reinforce", args: { content: "<text>" } })
```

Moves memories toward High Priority `[3x]+`.

### Step 7: Remove Stale Entries

For provably outdated entries:
```
role_exec({ op: "delete_learning", args: { content: "<text>" } })
```

**Rules:**
- Only delete if provably wrong or no longer relevant
- Prefer `update_learning` over delete when in doubt
- Never delete preferences without user confirmation

## Maintenance Report

After organizing:

```
Memory Organize Report — <role>
- Before: X learnings, Y preferences
- After:  X' learnings, Y' preferences
- Repaired: yes/no
- Consolidate: removed N duplicates
- LLM tidy: rewrote N, deleted N, added N
- Pending: M promoted, K expired
```

## Maintenance Frequency

| Frequency | Actions |
|-----------|---------|
| Per session | auto-extract → pending (automatic) |
| On request | `consolidate` (safe dedup) |
| Weekly | `repair` + `consolidate` + reinforce |
| Monthly / heavy | `llm_tidy` + manual review + pending cleanup |

## Operation Rules

- **Be conservative**: When in doubt, leave entries alone. Better to under-clean than lose useful memories.
- **consolidate is safe**: only deduplicates, never deletes unique entries.
- **llm_tidy is destructive**: review the plan before applying.
- **Preserve user voice**: when updating preferences, keep original phrasing.
- **Never fabricate**: don't add entries just to make the count look better.