Memory skills for AI agents.
Resume anywhere. Any task, any session, any model, from a checkout.
A record is what a senior engineer leaves behind: what was decided, what was ruled out, what comes next. perdure has AI agents write it as they work, keeps it in git beside the code, and checks it like code, so a checkout is the full context for the next session, the next agent, or you in three weeks.
How it works. A plugin for Claude Code and Codex, a skill pack for Cursor
and 70+ other agents. Install it, add its instructions to your CLAUDE.md or
the project's AGENTS.md (/perdure:install writes them for you in Claude
Code), and the agent keeps one markdown record per multi-step task in your
repository as it works; a Python script checks the record when the task closes
and generates a one-page handoff. No service, no account, nothing to keep
running.
The check is a linter for records: a closed record carries its review or a written reason for skipping one, a claim that nothing was committed is checked against git, and the report states what it covered.
Quick install, Claude Code (Codex and other agents: Quick start below):
claude plugin marketplace add arbelh/perdure
claude plugin install perdure@perdureThen, in a Claude Code session, /perdure:install installs the recommended
setup on enter. From then on the record opens itself.
A real record, from the repository perdure was built in, trimmed:
---
workflow: dev-changelog-and-plain-tags
status: completed
started: 2026-09-15T15:08:55-07:00
updated: 2026-09-15T15:09:28-07:00
---
# Goal
Keep the full changelog in the dev tree at CHANGELOG.md (never exported); public
tags are plain vX.Y.Z
# Decisions
- Dev tree: `CHANGELOG.md` at root, full internal history, never exported.
Public: no changelog file; GitHub Releases with notes from …
- Tags: plain `vX.Y.Z` in the public repository.
# Next step
Done. Future releases: add the internal entry to CHANGELOG.md, write
maintainer/RELEASE-NOTES-<version>.md, tag …
# Review
Review: skipped — file move and pointer updates pinned by the gate; no
reviewer dispatched. START WORK REVIEW CLOSE RESUME
┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
│ one record│─▶│ what was │─▶│independent│─▶│lint · gate│─ ─ ─ ─ ─ ▶│ checkout. │
│per unit of│ │ decided, │ │ verdict, │ │ HANDOFF │new session│ any model.│
│ work │ │ set aside │ │ appended │ │ on verdict│ new agent │ continues.│
└───────────┘ └───────────┘ └───────────┘ └───────────┘ └───────────┘
start verdict close continue
The session ends. The context compacts, or a different model picks up the task. The plan is gone, the paths you ruled out are back on the table, and the agent is about to try the one you rejected last week.
perdure makes the checkout the memory. Install once, add its instructions, and the model opens a record when a task begins, writes it as it works, and closes it through the check, which needs a verdict or a recorded skip. Nothing else changes in how you work.
If you know decision records, you know half of perdure. The other half is the same idea applied to the whole task, written by the agent and checked by a script.
It works beside any skill pack: they make the agent build well, perdure makes it remember. In daily use on the author's production repositories since March 2026.
- Nothing to re-explain. The next session, or the next model, reads the record and continues.
- Decisions on the record. Every choice, and every path set aside, written down where the code lives.
- A check that shows its work. It tells you which records still hold, and names what it did not check.
- No service, no account. Plain markdown files in your repository, and nothing else to keep running.
Claude Code
claude plugin marketplace add arbelh/perdure
claude plugin install perdure@perdureThen, in a Claude Code session:
/perdure:install
The plugin install adds the /perdure:* commands and two hooks: the lint runs
on its own when a record closes, and sessions can be archived before /compact.
/perdure:install is what makes it automatic. It writes the records directive
into ~/.claude/CLAUDE.md, so the model opens a record when a task begins and
closes it when the work is done, without being asked; enter installs the
recommended setup, "adjust" walks the options. Skip it and you drive with
/perdure:start.
/perdure:health checks the setup. /perdure:uninstall removes the directive,
the AGENTS.md marker block and the preferences file; claude plugin uninstall perdure@perdure removes the plugin.
Later, claude plugin marketplace update perdure then
claude plugin update perdure@perdure moves you to the newest release.
Any agent, one command (Codex, Cursor, Copilot, Windsurf and 70+ more)
The open skills CLI installs perdure's fourteen skills into the agent of your choice:
npx skills add arbelh/perdure # all fourteen skills
npx skills add arbelh/perdure --list # browse first
npx skills add arbelh/perdure --skill continue # just the one you needNothing else to clone. Every skill that runs a check carries
scripts/with it: Python 3, no dependencies. Droptemplates/AGENTS.mdinto your project and any model follows the convention.
Codex CLI, native plugin
codex plugin marketplace add arbelh/perdure
codex plugin add perdure@perdureCodex CLI 0.122 or later. The same fourteen skills; Codex keeps the whole
checkout in its plugin cache, so the checks are in its scripts/ directory.
No agent: CI, or by hand
git clone https://github.com/arbelh/perdure ~/perdure
cd your-project
python3 ~/perdure/scripts/rot-lint.py --strict . # exits 1 on a contradiction
python3 ~/perdure/scripts/handoff.py . --check # exits 1 when the page is stale| What you're doing | Command | Key principle |
|---|---|---|
| Pick up where you left off | /perdure:continue |
Any session. Any model. |
| See where things stand | /perdure:handoff |
Orientation in one page |
| Start a task | /perdure:start |
One record per task |
| Get an independent review | /perdure:verdict |
A second pair of eyes, on the record |
| Close it out | /perdure:close |
Closes on a verdict |
| Record a decision | /perdure:decide |
Outlives the task |
| List your tasks | /perdure:list |
Everything open, at a glance |
Any other agent: the same skills by name — continue, handoff,
start, verdict, close, decide.
The commands above are the daily path. Every skill is a plain SKILL.md any
agent can read, with its scripts beside it.
| Skill | What it does | Use when |
|---|---|---|
| start | Opens one record for the task, with the sections the convention names | You begin a task that will outlast one session |
| continue | Resumes from the record, in any session, with any model | A new session opens, or a different model picks the task up |
| close | Lints, checks the verdict, sets the status, writes the HANDOFF page | The work is done and reviewed |
| list | Every record and its status, at a glance | Before you start anything, to see what is open |
| Skill | What it does | Use when |
|---|---|---|
| verdict | An independent review, appended to the record; closing requires one | Before you call a task done |
| decide | A decision record that outlives the task, alternatives included | A choice will outlive the task: architecture, data, cost, security |
| decisions | The decisions in force, superseded, or rejected | Before you change something an earlier decision covers |
| Skill | What it does | Use when |
|---|---|---|
| handoff | The one-page orientation, generated from the records; --check confirms it is current |
Handing the project to someone else, or to yourself next month |
| archive | A session transcript as portable markdown, local by default | A session worth keeping as text, before compaction or at day's end |
| Skill | What it does | Use when |
|---|---|---|
| raw | An index of the sessions that ran: the denominator for coverage | Measuring how much of the work left a trail |
| coverage | How many sessions left a record, and how strong each link is | Asking which sessions never left a record |
| Skill | What it does | Use when |
|---|---|---|
| install | Adds the records directive to your Claude Code CLAUDE.md; optional | Once, after installing the plugin in Claude Code |
| health | Checks the setup and the installed version | Something seems off, or after an update |
| uninstall | Reverses install, nothing else | You want the directive and preferences gone |
It runs at every close: the close skill runs it in every tool, and in Claude Code a hook runs it on its own. Nothing is counted as passed that was never looked at.
Every record follows one anatomy:
┌────────────────────────────────────────────────────────────────┐
│ perdure/workflows/2026-09-15-greet-fn.md │
│ │
│ ┌─ Frontmatter ────────────────────────────────────────────┐ │
│ │ workflow: greet-fn │ │
│ │ status: in-progress | parked | completed | abandoned │ │
│ │ started: 2026-09-15T09:12:00Z │ │
│ │ updated: 2026-09-15T10:40:00Z │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ # Goal → one to three sentences │
│ # Plan → checkboxes │
│ # Findings → what exploration and work returned │
│ # Decisions → choices made; lasting ones become ADRs │
│ # Files modified → as edits land │
│ # Open questions → what is unresolved │
│ # Next step → always current: the resume point │
│ # Review → the verdict block; the gate reads it │
│ # Outcome → filled at close │
└────────────────────────────────────────────────────────────────┘
Key design choices:
- One file per task. Records shard per task, so parallel work never fights over a shared index.
- Status is a vocabulary. Four words the checks can read. Anything else trips the close gate.
- The gate checks the record, not the reviewer. Any independent verdict in the schema satisfies it: another plugin's agent, a generic subagent, a person.
- Derived pages are generated, never edited. The HANDOFF page is rebuilt from the records; a hand edit earns a warning and a regeneration.
- Checks report their coverage. Every run ends with which checks ran on which records, and why the rest did not.
Three layers, each worth a different degree of trust:
| Layer | What it holds | Who produces it |
|---|---|---|
| Asserted | the records: what was decided, set aside, still open | whoever did the work |
| Observed | an index of the sessions that ran | the raw skill, from Claude Code's session files |
| Derived and checked | the HANDOFF page, the lint, coverage | scripts, from the two layers above |
The checked layer only ever reports what it read, and says so. The full account is in docs/THREE-LAYERS.md.
| session resume (per tool) | a notes file | perdure | |
|---|---|---|---|
| lives in your repository, versioned with the code | — | ✓ | ✓ |
| readable by any tool, any model | — | ✓ | ✓ |
| checked for contradictions | — | — | ✓ |
| reports what it did not check | — | — | ✓ |
| a review verdict before a task closes | — | — | ✓ |
| Piece | What it is |
|---|---|
| The convention | docs/RECORDS-CONVENTION.md: one record per task under perdure/, decision records, a review-verdict schema. Plain markdown; any agent can follow it. |
| The lint | scripts/rot-lint.py: five deterministic checks and a coverage table for every run. The skills run it at every close; --strict for CI. |
| The close gate | a hook that lints a record as it closes and keeps the HANDOFF page current. |
| The review gate | /perdure:verdict appends an independent verdict; closing requires one. |
| The HANDOFF page | perdure/HANDOFF.md, built from the records: what is in force, what is open, each claim with its source. Created at the first close, kept current by the close gate; /perdure:handoff --check confirms it. |
| Coverage | /perdure:raw indexes the sessions that ran; /perdure:coverage shows how many produced a record. |
| Archives | /perdure:archive exports transcripts to markdown under perdure/archives/, local by default. |
| Decisions | /perdure:decide, /perdure:decisions. |
Project structure
.claude-plugin/ plugin.json · marketplace.json — Claude Code
.codex-plugin/ plugin.json — Codex CLI
.agents/plugins/ marketplace.json — Codex CLI
skills/ the fourteen skills — what any agent reads
scripts/ rot-lint · handoff · close-workflow · new-workflow · coverage · raw-index · export-session
hooks/ close gate · pre-compact archive
docs/ RECORDS-CONVENTION.md · THREE-LAYERS.md
templates/ AGENTS.md — the instructions your project receives
Every release passes a deterministic eval gate and isolated end-to-end dry runs against the exported checkout, then ships through a whitelist export. The published tree is the plugin, exactly as installed.
A companion plugin, perdure-team (five specialist agents), will be published at a later time.
Small changes that keep the plugin small land fastest. CONTRIBUTING.md says what to check before a pull request and what shape a skill, a script, or a tool adapter takes.
 |
Arbel Hakopian · @arbelh |
MIT. Use it in your projects, teams, and tools.