# Memory Defrag

Defragment a Basic Memory project: split bloated notes, consolidate scattered facts...

- Repository: https://github.com/basicmachines-co/basic-memory (4440 stars)
- Category: Writing
- License: AGPL-3.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add basicmachines-co/basic-memory --skill memory-defrag -g -a claude-code -y`
Codex: `npx skills add basicmachines-co/basic-memory --skill memory-defrag -g -a codex -y`
Cursor: `npx skills add basicmachines-co/basic-memory --skill memory-defrag -g -a cursor -y`
Gemini CLI: `npx skills add basicmachines-co/basic-memory --skill memory-defrag -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add basicmachines-co/basic-memory`

## Description

Defragment a Basic Memory project: split bloated notes, consolidate scattered facts, resolve contradictions, retire stale content. Plans first; deletes only when told. Run weekly or on demand.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Memory Defrag

Reorganize a project's notes so each topic has one clear, current home. Over
time notes grow past their topic, the same fact lands in several places, old
facts contradict new ones, and finished work lingers. Defrag fixes the content;
**memory-curate** handles links, relations, and tags.

## Project scope

If the project is unknown, discover it with `bm_project(command="list")`.
Pass a nonempty `project` on every note, folder, context and schema call, even
with one project or a qualified `memory://` URL. Use the chosen project's name,
`workspace/project`, or external ID; `<project>` below is a placeholder for it.
Recent activity also requires `project`. Search accepts `project` for one
project, `projects` for selected projects, or `all_projects=True` explicitly.
Discovery and bundled manuals need no project. Keep the same scope when following
returned paths, paginating, or recovering from a refusal.

## When to Run

- **Periodic**: weekly or every other week
- **On demand**: asked to clean up, reorganize, or defrag
- **Threshold**: a note grows past a few hundred lines, or several notes cover
  the same topic

## Process

### 1. Audit

Walk the whole project, not just recent changes. Stale content is usually in
notes nobody touched lately.

```python
# Every folder and note within depth 10. Page until has_more is false;
# descend into deeper folders separately if the project has them.
bm_find(path="/", depth=10, page_size=100, project="<project>")

# Recently busy notes, to look at first
bm_project(command="recent", since="30d", output_format="json", page_size=50, project="<project>")

# Notes on one topic, to spot overlap
bm_search(query="launch plan", project="<project>")

# Commitments due on or before today: finished work that lingers, or overdue items
bm_search(time_kind="due", valid_overlaps="(,2026-10-14]", project="<project>")
```

The rest: https://github.com/basicmachines-co/basic-memory/blob/HEAD/skills/memory-defrag/SKILL.md