From perpetuity
A note library that remembers how hard problems got solved, so the next session does not re-derive them. Recall runs when a non-trivial task starts: it reads a bounded index, then greps notes for the task tools, errors and domain terms. Capture writes one note when the task ends. Use when prior work would help: "have we solved this before", "what did we decide about X", "did we hit this error already", "remember how we fixed Y". It stays out of how code is written, so it never competes with code-writing skills for triggers.
How this skill is triggered — by the user, by Claude, or both
Slash command
/perpetuity:perpetuityThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A note library that gives you memory of how hard problems got solved, with zero
A note library that gives you memory of how hard problems got solved, with zero effort from the user. It is passive in one sense only: it acts automatically at the edges of a turn: recall when a task starts, capture when it ends. It has no daemon and no clock; it wakes only while you are already working.
Three behaviours: recall, capture, curate. Miss recall and the library is a diary nobody reads; miss capture and it stays empty; miss curate and it rots into near-duplicate sludge that poisons recall.
Global by default: ~/.claude/perpetuity/ with notes/ and INDEX.md inside.
Prefer a repo-local .perpetuity/ when the memory is clearly project-specific
and worth committing. Pick one per task; don't write the same note to both.
Deleting that directory and this skill folder fully uninstalls perpetuity.
The example note and index shipped in this skill folder are a seed, not the runtime store. On first capture, create the runtime directory if absent.
Skip for trivial or one-step tasks. Otherwise, before doing the work:
INDEX.md only. It is the bounded, always-loaded layer. Never load all
notes up front.notes/ for matching tags: and body terms.use_count by 1 and set last_used to
today. These counters drive decay; stale-but-useful notes shouldn't age out.confidence. Treat tentative as a lead, not gospel; if a note is
supersedes-pointed-at by a newer one, prefer the newer.If nothing matches, say so in one line and proceed cold. Absence of a note is a normal outcome, not a failure.
Capture writes or patches exactly one Markdown note. Patch an existing note when the lesson refines one (token-cheap); write a new note only for genuinely new ground.
Capture when one of these is true:
Skip these. Over-capture is the failure mode that turns the library to sludge:
When in doubt, do not capture. A smaller, trusted library beats a large one you stop reading.
One file per note under notes/, named by a kebab-case slug. Frontmatter is the
engine; the body follows the When / Procedure / Pitfalls / Verification shape.
Use this schema exactly (see notes/_example.md for a filled example):
---
name: <kebab-case-slug>
description: <one line: what it fixes and when to reach for it; drives recall>
tags: [<searchable>, <terms>]
created: <YYYY-MM-DD>
source_task: "<short phrase naming the task it came from>"
confidence: high # high | medium | tentative
state: active # active | stale | archived
use_count: 0
last_used: <YYYY-MM-DD>
supersedes: null # name of a note this replaces, if any
pinned: false
origin: agent-created # agent-created | hand-authored
---
Set origin: agent-created on every note you write. hand-authored is reserved
for notes the user wrote by hand, and curate must never touch those.
After writing or patching, add or update the note's line in INDEX.md (run
reindex.py if present, else edit the one line by hand to match the format in
INDEX.md). If INDEX.md has grown past its budget, don't widen the budget.
That's the signal for a curate pass.
/perpetuity-curateNever automatic in v0.1. Curate only when the user runs the command. It operates
solely inside the perpetuity directory and never on a note where
pinned: true or origin: hand-authored.
.archive/
snapshot before any mutation, so every pass is reversible.last_used: unused 30+
days → state: stale; unused 90+ days → move the file to .archive/ and set
state: archived. Ageing runs before any consolidation.supersedes at it (or fold and archive
the weaker). Consolidation is mandatory, not optional. It is what stops
near-duplicate sprawl..archive/. Nothing is ever
removed from disk.INDEX.md from the surviving notes' frontmatter and write a short
plain-language summary of what changed.INDEX.md is loaded by default; full notes load on match.Out of scope for v0.1, by design: Claude Code hooks, any daemon or cron behaviour, the HTML review dashboard, and a USER profile. Don't build them here.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub blakecyze/perpetuity --plugin perpetuity