Persist OS

Durable, AI-ready engineering memory for your repository — and a deterministic doctor that
proves it stays healthy.

Persist OS is a local-first CLI that turns a repository into the source of truth for why it is
built the way it is. It creates structured, reviewable memory — product intent, architecture
decisions, module ownership, testing and security expectations, AI agent rules — and then
validates that memory with persist doctor. Architecture-neutral. No network, no telemetry, no
code generation.

Website · Install · Quickstart ·
Commands · What Doctor Checks · Presets ·
Why I built this · Contributing

AI can write code fast, but its context is temporary — it forgets decisions, compacts conversations,
and drifts from earlier intent. Git records what changed. Persist OS records why, in a form
humans and agents can re-read and validate before and after work.

What are we building?   Why did we decide this?
What must not drift?    What evidence proves this work is complete?

When these questions live in the repository instead of a chat window, the repository can answer
them.

Not a vector memory engine. Tools like supermemory or mem0 retrieve information with
embeddings; Persist OS writes the decisions themselves — reviewable files, not vectors — and
checks they stay consistent. They're complementary, not competitors. →
Why I built this

Why Persist OS

• Memory that outlives the conversation. Decisions, constraints, and ownership are committed to
  the repo, not trapped in an agent's context window.
• A gate, not just docs. persist doctor is deterministic and returns an exit code, so "is this
  work actually finished and consistent?" becomes a check you can run in a hook or CI.
• Decisions change safely. When a decision changes, persist adr supersede records it (the old
  ADR is marked superseded, the new one links back) and Doctor flags any memory still citing the old
  one — so the trail stays auditable instead of silently contradicted. The generated agent rules
  even carry the CLI commands inline, so your AI tool uses them itself.
• Fights context rot. Doctor warns when the always-loaded memory bloats into a wall of text, or
  when it still points at src/ code that changed long after the memory did — so memory stays a
  lean, current map, not a stale dump.
• Reuse over reinvent. Generated CONVENTIONS.md (your canonical, reusable vocabulary) and
  LESSONS.md (durable pitfalls) load into every agent session, and the agent is told to keep them
  current itself — so it reuses your components and patterns instead of reinventing them, and stops
  repeating mistakes you already solved. It works even on vibe-coded projects, because the agent
  maintains the memory, not you.
• Architecture-neutral by design. Persist OS records and protects your decisions. It never
  silently picks a framework, database, or pattern for you.
• Local-first and private. No network calls, no telemetry, no AI API calls, no remote templates.
  It runs entirely on your machine.
• Safe by default. Non-destructive writes, path-traversal and symlink protection, and a refusal
  to overwrite an existing installation without explicit intent.

Install

Run it without installing — the quickest way to try it:

npx persist-os@latest init

Every command works the same way: npx persist-os <command> (e.g. npx persist-os doctor).

Or install the CLI globally:

npm install -g persist-os
persist --help

(Requires Node.js >= 20. Published at
npmjs.com/package/persist-os.)

Quickstart

# 1. Create repository memory (architecture-neutral, or pick an opinion pack)
persist init
persist init --preset kotlin-android   # optional, proposes stack decisions

# 2. Capture intent and decisions as you work
persist feature create checkout
persist adr create payment-provider
persist adr accept payment-provider    # promote a proposal to accepted memory

# 3. Bring an MCP server's context into durable memory (offline)
persist mcp add figma

# 4. Validate the memory is healthy and complete
persist doctor

Every command guides you — it names the file it created, where it is, and what to do next.

Generate files only for the AI tools you use: persist init --ai-tools claude,cursor (default: all
of claude, codex, cursor; AGENTS.md is always written).

persist init also generates tracked pre-commit and pre-push hooks in .persist/hooks/ that
run persist doctor plus any gates you configure. The pre-push hook is the final regression gate
before code leaves your machine (it catches commits made with --no-verify or before the hook was
active). Enable them once per clone — Persist OS proposes the command but never runs it for you:

git config core.hooksPath .persist/hooks

Commands

What Doctor Checks

persist doctor is the part that makes Persist OS more than a template. Every check is
deterministic, local, and read-only.

Exit codes:  0 = healthy   1 = warnings only   2 = errors

Because it returns an exit code, Doctor drops straight into the completion loop:

pnpm test:run && pnpm typecheck && persist doctor

Use it locally via the generated pre-commit hook, or add persist doctor as a step in CI. Add
--json (persist doctor --json) for a stable, machine-readable report — handy for CI artifacts,
hooks, and agent handoffs.

Presets

Presets are opinion packs. They ship proposed guidance and proposed ADRs for a stack's real
decision forks — and they can never silently accept a choice for you (the schema enforces Proposed
status on every preset decision).

Adding a preset is a small contribution — see CONTRIBUTING.md.

How It Works

How agents load the memory

Writing memory only helps if the agent reads it, so persist init wires each tool with its own
native mechanism:

The portable guarantee across every tool is AGENTS.md plus the generated Agent Skills
(.agents/skills/). The dynamic per-session ADR/module map is a Claude Code bonus; the Cursor rule
and AGENTS.md carry the same rules everywhere else.

AGENTS.md leads with a short, imperative Rules block (read memory first, reuse the
conventions, record lessons, don't contradict accepted ADRs, run persist doctor before "done") —
and instructs the agent to keep CONVENTIONS.md and LESSONS.md current itself, so that memory
stays useful without anyone hand-writing it. The human just reviews the agent's edits in the pull
request.

Repository Memory

Persist OS creates a memory structure under docs/ and .persist/config.json, with an explicit
source-of-truth order:

1. Accepted ADRs and repository decisions     6. Module docs
2. Architecture docs                          7. Feature plans
3. Engineering standards                      8. Task files
4. Current PRD and accepted changes           9. External context
5. Security and testing docs                 10. Chat history

If external context or chat history conflicts with repository memory, repository memory wins.

Local-First Guarantees

Persist OS does not:

• make network calls at runtime;
• collect telemetry;
• connect to MCP servers or call AI APIs;
• generate production application code;
• install dependencies into your repository;
• overwrite existing files by default.

Examples

Committed sample outputs show the exact memory each preset generates:

examples/generated-generic/         examples/generated-kotlin-android/
examples/generated-nextjs/          examples/generated-python-fastapi/
examples/generated-ios-swift/       examples/generated-flutter/
examples/generated-laravel-react/   examples/generated-laravel-vue/
examples/generated-laravel-api/

Development

pnpm install
pnpm lint
pnpm format:check
pnpm test:run
pnpm typecheck
pnpm build
pnpm pack:check

Run the gates above and persist doctor before claiming work is complete. See
CONTRIBUTING.md for the full workflow and how to add a preset, and
SECURITY.md for the security model.

Acknowledgments

The landing page is deployed with
Pagecast — thank you.

License

MIT — see LICENSE.