See it in 40 seconds
Create memory, accept a decision, capture an MCP tool's context, and let the gate flag what's still missing.
Git tracks what changed. persist tracks why.
A local-first CLI that writes the decisions, constraints, and standards behind your code into plain files that live next to it — and validates that memory with a deterministic persist doctor. Architecture-neutral. No network, no telemetry, no AI API calls.
No install needed — run any command with npx persist-os <command>, or npm i -g persist-os.
AI gets software to a working shape fast — but most of the why ends up in a chat window that resets every session. When a teammate, a real engineering team, or a fresh agent takes over, they inherit the code without the context. Persist OS keeps that reasoning in the repository, where it survives every session and gets reviewed in pull requests.
Decisions, ownership, and constraints are committed to the repo — not trapped in a context window.
persist doctor is deterministic and returns an exit code, so "is this actually done and consistent?" becomes a check you can run.
Presets, adopt, and MCP capture produce proposed memory. A human accepts it with persist adr accept — nothing becomes truth silently.
Create memory, accept a decision, capture an MCP tool's context, and let the gate flag what's still missing.
You capture intent and decisions; Persist writes durable memory that humans review and agents re-read; the doctor validates it for a hook or CI gate.
Each command guides you — it names the file it created, where it lives, and what to do next.
| Command | What it does |
|---|---|
| persist init | Create neutral repository memory, plus agent skills, pre-commit and pre-push hooks, a CI workflow, a Claude SessionStart hook, and a Cursor rule. Surfaces the detected stack (proposed). |
| persist init --preset <id> | Add an opinion pack: rich guidance and proposed ADRs for a real stack. |
| persist init --ai-tools <list> | Generate files only for the AI tools you use: claude, codex, cursor, generic. |
| persist adopt | Inspect an existing repo (read-only) and propose reviewable memory, with the source each signal was inferred from. |
| persist preset list | List the built-in opinion packs. |
| persist feature create <name> | Scaffold feature memory: PRD, acceptance, tests, review, completion report. |
| persist adr create <title> | Create a proposed architecture decision record. |
| persist adr accept <name> | Promote a proposed ADR to accepted source-of-truth. |
| persist adr supersede <old> <new> | Record a changed decision: mark the old ADR superseded by a new accepted ADR. |
| persist module create <name> | Scaffold module memory: ownership, boundaries, tests, decisions. |
| persist skill create <name> | Generate a portable AI agent skill for Claude Code and the Agent Skills format. |
| persist skill list | List the built-in agent skill catalog. |
| persist mcp add <server> | Generate offline, proposed memory for an MCP server (e.g. Figma) and a capture skill. |
| persist doctor | Validate memory health, completion evidence, drift, and unfilled security docs. Exit codes 0 / 1 / 2. |
| persist guard --source <dirs> | Fail when staged source changed without tests — add it to your gates to enforce it. |
Presets propose vetted, stack-specific decisions — always as proposed ADRs you accept or reject. The schema makes a silent acceptance impossible.
| Preset | Stack | Proposes |
|---|---|---|
| laravel-react | Laravel + React | Inertia + React, Eloquent, Sanctum, Form Requests + Policies, queues, Pest |
| laravel-vue | Laravel + Vue | Inertia + Vue, Eloquent, Sanctum, Form Requests + Policies, queues, Pest |
| laravel-api | Laravel (API) | Versioned REST + API Resources, Eloquent, Sanctum, queues, Pest |
| nextjs | Next.js / TS | App Router, typed data layer, Tailwind, Vitest + Playwright |
| python-fastapi | Python / FastAPI | FastAPI, PostgreSQL + SQLAlchemy, Pydantic, pytest, Redis |
| kotlin-android | Kotlin / Android | Compose, Coroutines + Flow, Hilt, Room, MVVM |
| ios-swift | iOS / Swift | SwiftUI, async/await + Observation, SwiftData, MVVM |
| flutter | Flutter | Platform and state-management guidance |
| generic | none | Architecture-neutral memory |
Writing memory only helps if the agent reads it, so persist init wires each tool with its own native mechanism.
CLAUDE.md auto-loads and imports AGENTS.md; a SessionStart hook injects a live map of accepted ADRs and modules every session.
.cursor/rules/persist-memory.mdc is an always-apply rule that loads the memory rules into every request.
AGENTS.md is auto-discovered — the portable floor that carries the same rules everywhere.
A memory layer and a quality gate have to be trustworthy. So Persist OS never calls a model to judge your work — it checks structure and evidence with reproducible rules. Same input, same answer, every time. The thinking stays with you and your agent; the proof-of-work stays with the gate.