Task Cleanup

When you complete a task, the checkbox flips to - [x] and the task line stays in the markdown file. That’s good — it’s a record of what got done. But after a while, a working file (especially the Inbox) accumulates dozens of completed lines and starts feeling like an archive. Task cleanup removes completed lines after a retention window so your active files stay clean.

The cleanup is non-destructive in two important ways:

1. The Activity view still shows what got done, even after the line is removed from the file. Pensum keeps the completion record in its index for as long as you need.
2. The CLI / MCP / agent surfaces can still query completion history for the retention window of the index, even if the original task line is gone.

How retention works

Pensum runs cleanup automatically once every four hours while the plugin is active. It scans for completed tasks (- [x]) whose completion date is older than the applicable retention period, removes those lines, and rewrites the file.

The retention period is decided in a four-level hierarchy. The most specific rule wins:

1. Per-task #keep tag — task is never cleaned up
2. Per-note frontmatter (task_cleanup: N or task_cleanup: never)
3. Per-source defaults (Inbox / Project / Meeting / Daily note)
4. Global default (used when no source-specific default applies)

Settings reference

Under Settings → Pensum → Cleanup:

Setting	Default	What it controls
Default cleanup	7 days	Used when no per-source rule matches the task’s containing file
Inbox cleanup	3 days	Tasks in your configured inbox files
Project cleanup	7 days	Tasks in files with type: project in frontmatter
Meeting cleanup	Never	Tasks in files with type: meeting in frontmatter
Daily note cleanup	Never	Tasks in files inside the Daily Notes plugin’s folder

0 means “remove immediately on completion” (rare; useful for a noisy inbox if you’ve accepted that nothing in there is worth keeping). Never (or 0 interpreted as “skip” — the UI uses “Never”) leaves completed tasks in the file forever.

Why these defaults

Source	Default	Reasoning
Inbox	3 days	Inbox is a triage staging area; once you’ve decided what to do with a captured task and completed it, you rarely need to see it again three days later. Keeps the inbox light.
Project	7 days	Useful as recent context — “what did I finish on this project last week?” After a week, it’s history; check the Activity view instead.
Meeting	Never	Meeting notes are durable records. The action items from a meeting are part of the meeting’s record; deleting them later would change what the meeting “says.”
Daily note	Never	Same logic — a daily note is a journal entry. Removing completed tasks from past daily notes would rewrite your history.
Default	7 days	A reasonable middle ground for files that don’t fit any of the above (e.g. tasks in a research clipping or a meta-note)

You can change any of these. Reasonable variations:

• Inbox = 0 if you treat inbox as truly ephemeral and trust the Activity view as the record
• Project = 30 days if you like keeping a longer trail visible in the project file itself
• Meeting = 30 days if you want meeting notes to slim down after a month

Per-note override

A task_cleanup value in a file’s frontmatter overrides the per-source default for that file specifically:

---
type: project
task_cleanup: 30
---

Tasks in this project file will be retained for 30 days instead of the project default of 7.

Other values:

Value	Meaning
A number, e.g. 14	Keep for 14 days
never	Never clean up tasks in this file
0	Clean up on next sweep (essentially immediate)

Use task_cleanup: never for:

• A “recently completed” log file you want to keep forever
• A project file you want to preserve as a record after the project finishes
• An archived file you’ve moved out of active rotation

Per-task override (#keep)

The #keep tag on any individual task line prevents that task from ever being cleaned up, regardless of file or source defaults:

- [x] Shipped v1.0 #keep

Use #keep for milestone events you want preserved permanently — launch dates, major decisions, anything where the completed state of that specific task line is itself the artifact.

What “completed” means for cleanup

Cleanup only removes:

• Lines with - [x] status
• Whose completion date (✅ YYYY-MM-DD emoji) is older than the retention window

Lines without a completion date are never cleaned up (Pensum doesn’t infer when they were completed). If you mark a task done via Pensum (right-click → Complete, or Cmd+Shift+X, or the checkbox in any view), the completion date is added automatically. If you mark a task done by manually typing [x] without a completion date, it’s invisible to cleanup until you re-edit it.

This is deliberate — Pensum won’t delete data based on guesses about when something was completed.

What happens during cleanup

1. Pensum walks the index for tasks marked completed
2. For each, it computes the applicable retention window using the hierarchy above
3. If the completion date is older than the window, the task line is removed from the source file
4. The Activity view’s record of the task is preserved
5. Files modified during the sweep get rescanned to keep the index consistent

If something goes wrong (file is locked, sync conflict, etc.), the task stays in place and Pensum tries again on the next sweep. Cleanup is safe to interrupt at any time.

Triggering cleanup manually

Run Pensum: Rescan vault from the command palette — it triggers a full reconciliation that includes the cleanup pass.

There’s no “preview what would be cleaned up” command in v1.0. If you’re nervous, set Default cleanup and the per-source rules to Never first, then experiment with one file by setting task_cleanup: 7 in its frontmatter to see what happens.

Recovering cleaned-up tasks

If you cleaned up something you wish you hadn’t:

• From the Activity view — the completion record is still there; click through to the source file (if it’s a recurring task, the next occurrence will be in the file too)
• From git / sync history — if your vault is backed up via Obsidian Sync, git, iCloud, etc., the previous version of the file has the line

Pensum doesn’t keep a separate “trash” of cleaned-up tasks. The expectation is that the Activity record + your own vault backup are sufficient.

Cleanup and recurrence

When a recurring task is completed, two lines exist: the completed original and the new open occurrence. Cleanup operates on the completed original after its retention window. The new occurrence is open (not completed), so cleanup leaves it alone — it’ll either be completed later (and become eligible for cleanup itself) or stay open indefinitely.

Cleanup is off when

• The plugin is disabled
• You haven’t completed any tasks (nothing to clean)
• Every applicable rule resolves to never or 0 (you’ve turned cleanup off)