Persist OS
Find a command⌘ KGitHub

Give your coding agent a memory that lasts.

Save the decisions behind your code. Persist keeps that context in your repository, so each session can pick up where the last one left off.

Read setup guide
npx persist-os@latest init
~/work/checkout-apilocal session
EXPLORERrepository
  • checkout-api
  • .persist/config.json
  • AGENTS.md
  • CLAUDE.md
  • docs/
  • 00-product/PRODUCT.md
  • 20-security/SECURITY_MODEL.md
  • 50-quality/QUALITY_GATES.md
  • 60-engineering/
  • adrs/

Plain files. Tracked in Git.

persist init 
Set up repository memory

Tools      Claude Code · Codex · Cursor
Memory     Six core documents + decisions
Test gate  Configure your test command

✓ Entry files, skills, hooks, and CI scaffolded
✓ Git hooks activated for this clone
Existing files and custom hook paths preserved.
Illustrative example. Commands do not execute.

A shared memory for
the tools you already use.

Claude Code
Codex
Cursor
AGENTS.mdPortable by design
01 / Memory that carries forward

Keep the reasoning
close to the code.

You’ve already worked through the tradeoffs.
Give the next session somewhere to find them.

Decisions with a history.

Record the alternatives and the reason you chose one. Accept it when the team agrees. If the decision changes, keep the trail.

Attach the files it governs so an agent sees the decision when working on them.

How decisions work
ADR-0004Proposed

Store money as integer cents

Context
Fractional values can drift during repeated calculations.
Decision
Use integer cents for amounts. Format decimals for display.
Governs
src/billing/**
Ready for human review. Not yet authoritative.
persist adr create "Store money as integer cents"

Interactive illustration of the decision lifecycle.

Chesterton fences02

A reason behind the code.

A “cleanup” can undo a hard-earned fix. Record the human-confirmed reason once, so future agents know what to preserve.

src/payments/split.ts18const ordered = stableSort(members);
19return distribute(total, ordered);
Reason missing

Why is the stable order necessary?

Doctor asks for a reason when changed source has none recorded.

Illustrative source and fence. Reasons come from people.

Context cards03

A starting point for each task.

Each area gets a short card: what it does, where to look, and which rules apply. Task lookup shows why a card matched.

docs/context/billing.mdMatch
Purpose
Calculate charges and settle invoices.
Matched
billing · rounding
Start with
src/billing/totals.ts
Keep in mind
ADR-0004: use integer cents.

Illustrative lookup. Try both tasks.

Deterministic keyword search with BM25 ranking. Claude Code and Codex use prompt hooks; other tools use a lookup skill.

02 / A home in your repository

Plain files.
A useful memory.

Start with six Markdown documents. Review them in pull requests, read them in your editor, and keep them when you switch tools.

Document your conventions so agents reuse what exists. Write down lessons so the next session doesn’t repeat the same mistake.

Explore the memory layout
Versioned with your code Configurable directory paths Yours to edit and review
your-repo / docsExplore the files
REPOSITORY MEMORY
＋ adrs/＋ context/
00-product/PRODUCT.md
#

What we’re building

A shared starting point for product decisions.

Purpose

What problem does this product solve?

Who it serves

Who uses it, and what do they need?

Boundaries

What have we deliberately left out?

Tracked in GitIllustrative prompts. Your team writes the answers.
03 / A check before the next commit

Memory needs maintenance.
Make it part of the work.

Write it down, use it, check it.
Keep what you learn for the next session.

01

Find the context

The task points to relevant files and decisions.

02

Make the change

The agent reviews its diff against governing ADRs.

03

Run the checks

Doctor at commit. Configured tests at push.

04

Keep the learning

Update the card, convention, or lesson you used.

Persist Doctor

Find the gaps
before you commit.

19 deterministic checks inspect memory and references, including ignored files, inactive hooks, and a 24 KB budget for always-loaded context.

Errors block the commit. Warnings are advisory. Agents handle the semantic review.

See all Doctor checks
19deterministic checks
with explicit outcomes
Try a repository stateIllustrative results
$ persist doctor
✓Required memory filesPASS
✓Context card pathsPASS
✓Decision referencesPASS
✓Completion evidencePASS
Exit 0

Evaluated checks pass.
The pre-commit check can continue.

Selected checks shown for clarity. Read the full check reference.

init activates hooks in the current Git clone, unless you opt out. Existing custom hook paths are respected. Configure a test command for the push gate; without one, it explicitly skips.

Hooks & CI
04 / Fits the way you work

Change tools.
Keep the context.

Your decisions stay in the repository. Persist gives each tool the entry files and skills it understands.

CLAUDE.mdImports the shared AGENTS.md
.claude/skills/Workflow guidance, loaded when needed
SessionStart + prompt hooksRepository map, then context for the task

Select a tool to see its setup.

01

Bring the repository you have.

adopt reads manifests and lockfiles, then proposes memory for human review. Your existing files are skipped by default.

02

Make room for bigger work.

Opt into feature plans and module memory when you need them. Scaffold ownership, tasks, and test plans without generating app code.

03

Give agents a repeatable workflow.

A catalog of 12 skills covers implementation, tests, decision review, security, conventions, and delivery. Module-memory guidance is conditional on module tracking.

04

Keep checks visible to the team.

A generated GitHub Actions workflow and Doctor JSON support CI. Refresh managed hooks with hooks sync, preserving docs, config, and user tool settings.

The repository stays yours.

Local CLI. No telemetry, AI API calls, account, or runtime network. Preview writes with --dry-run. Overwriting requires an explicit choice.

Open source, MIT
05 / Try the moving parts

A small command.
A useful next step.

Explore every command with a sample scenario.
These demos run only in this page.

You’re starting a repository and want future coding sessions to share the same instructions.

Illustrative example. No commands execute.
THE COMMAND
persist init
WHAT HAPPENS

Six core memory documents, agent entry files, workflow skills, hooks, and CI are scaffolded. Existing files are skipped by default.

ILLUSTRATIVE RESULT 
your-repo/
  AGENTS.md             shared rules
  docs/                 six core documents
  .persist/hooks/       commit and push checks
  .github/workflows/    CI checks
Full syntax and options
Browse all 16 command actions

persist init

Create repository memory and tool entry files. Interactive by default.

Use --dry-run to preview writes

persist adopt

Inspect an existing codebase and propose memory for review.

Manifests and lockfiles are the evidence

persist context <task>

Find area memory that matches a task.

--json · --limit

persist context add <name>

Scaffold a context card for an area of the code.

--purpose · --dry-run

persist fence add <path>

Record the human-confirmed reason code is shaped this way.

--why · --by · --adr

persist adr create <title>

Create a proposed architecture decision record.

Human review comes next

persist adr accept <name>

Accept a reviewed proposal as repository memory.

Accepted decisions guide later work

persist adr supersede <old> <new-title>

Record a replacement and preserve the previous decision.

The history stays linked

persist feature create <name>

Create a feature plan and tasks, with a test plan when configured.

Optional feature tracking

persist module create <name>

Scaffold module ownership, decisions, tasks, and test planning.

Optional module tracking

persist skill list

List the built-in workflow skill catalog.

Twelve catalog entries

persist skill create <name>

Generate a workflow skill for configured agent tools.

Claude and portable Agent Skills layouts

persist mcp add <server>

Scaffold proposed MCP context documentation offline.

No server connection

persist doctor

Check memory health, references, evidence, and drift.

--json · exits 0, 1, or 2

persist test-gate

Run the configured one-shot test command.

Explicitly skips when unconfigured

persist hooks sync

Refresh managed hooks from existing configuration.

--dry-run · preserves docs and config
A few practical details

Before you start.

More detail lives in the documentation.

Does this work with an existing repository?

Yes. Run persist adopt to inspect manifests and lockfiles and create an adoption report with proposed decisions. Review those proposals before accepting them. Existing files are skipped by default, and --dry-run previews writes.

Does Persist choose my architecture?

You choose the architecture, frameworks, and database. Persist records and distributes the decisions, then checks the memory and its references. People accept decisions; agents review their work against them.

Does my code leave my machine?

The CLI makes no runtime network calls and has no telemetry or AI API integration. The initial npm download needs network access. Your coding agent has its own data and privacy settings.

Do I need an account or subscription?

No. Persist OS is MIT-licensed open source software. It runs locally and stores memory as files in your repository. There is no Persist account or subscription.

How do the hooks work for a team?

init activates hooks in the current Git clone unless opted out, and respects an existing custom core.hooksPath. Each clone needs its own activation. Doctor runs before commits; the configured test command runs before pushes. Codex prompt hooks also require the tool’s trust review. See hook setup.

Can I use a different coding agent?

The shared AGENTS.md and Markdown memory are portable. Claude Code, Codex, and Cursor have generated entry files and tool-specific guidance. Other agents can read the same memory and use persist context "<task>" for lookup.

Start with one repository

Leave the next session
something to work with.

Set up the memory. Record a decision you’ve already made. Let the next agent pick up from there.

Follow the getting started guide
01

Run from your repository

npx persist-os@latest init
02

Record your first decision

npx persist-os adr create "Store money as integer cents"
03

Check your repository memory

npx persist-os doctor

Node.js 20+ · Or install globally: npm install -g persist-os

Find a command

Select a command to copy its example. Nothing runs in your repository.

Esc to close