2026-06-23 19:48 UTCIn-site rewrite5 min readUpdated: 2026-06-23 20:08 UTC

Show HN: Persist OS – Durable decisions for AI code

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 and validates it with a deterministic doctor, with no network or telemetry.

SourceHacker News AIAuthor: karthickrmchn

Notifications You must be signed in to change notification settings

Fork 0

Star 1

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

80 Commits

.agents/skills

.claude/skills

.github

.pagecast

.persist

docs

examples

scripts

site

src

tests

.gitignore

.prettierignore

.prettierrc.json

AGENTS.md

CLAUDE.md

CONTRIBUTING.md

LICENSE

PHILOSOPHY.md

README.md

SECURITY.md

eslint.config.js

llms.txt

package.json

pnpm-lock.yaml

tsconfig.json

tsup.config.ts

vitest.config.ts

Repository files navigation

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 (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

Command Purpose

persist init Create neutral repository memory (and a pre-commit hook).

persist init --preset Add an opinion pack: rich guidance and proposed ADRs.

persist init --ai-tools Generate files only for the AI tools you use (claude, codex, cursor, generic).

persist adopt Inspect an existing repo and propose reviewable memory.

persist preset list List built-in presets.

persist feature create Scaffold feature memory (PRD, acceptance, tests, review).

persist adr create Create a proposed architecture decision record.

persist adr accept Promote a proposed ADR to accepted source-of-truth.

persist adr supersede Record a changed decision: mark the old ADR superseded by a new accepted ADR.

persist module create Scaffold module memory (ownership, boundaries, tests).

persist skill create Generate a portable AI agent skill (Claude + Agent Skills).

persist skill list List the built-in agent skill catalog.

persist mcp add Generate offline, proposed memory for an MCP server.

persist doctor Validate memory health, evidence, and drift.

persist guard --source Fail when staged source changed without tests (add to your gates to enforce).

What Doctor Checks

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

Category Detects Severity

Structure Missing config, required docs, or feature / module / ADR sections error

Completion evidence A feature marked complete with review pending or no test / result evidence error

ADR quality An accepted ADR with no meaningful consequences error / warn

Security A security-sensitive feature with no documented security impact error / warn

Drift Memory that references a missing, or not-yet-accepted, ADR error / warn

Superseded Memory still citing a decision that has been superseded by a newer ADR warning

Staleness Memory citing src/ code that changed long after the memory did (git-based; off-git skips) warning

Context budget The always-loaded agent files (CLAUDE.md + AGENTS.md + Cursor rule) grown past a budget warning

Content A feature PRD, module, or (once work exists) the threat / security model left as a stub warning

Conventions The canonical-vocabulary doc left as a stub once the repository has real work warning

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.

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).

Preset Stack Proposes (always as proposed ADRs)

laravel-react Laravel + React Laravel, Inertia + React, Eloquent, Sanctum, Form Requests + Policies, queues, Pest

laravel-vue Laravel + Vue Laravel, Inertia + Vue, Eloquent, Sanctum, Form Requests + Policies, queues, Pest

laravel-api Laravel (API) Laravel, versioned REST + API Resources, Eloquent, Sanctum, queues, Pest

kotlin-android Kotlin / Android Compose, Coroutines + Flow, Hilt, Room, MVVM

python-fastapi Python / FastAPI FastAPI, PostgreSQL + SQLAlchemy, Pydantic, pytest, Redis

ios-swift iOS / Swift SwiftUI, async/await + Observation, SwiftData, MVVM

nextjs Next.js / TS App Router, typed data layer, Tailwind, Vitest + Playwright

flutter Flutter Platform and state-management guidance

generic none Architecture-neutral memory

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:

Tool How memory loads

Claude Code CLAUDE.md (auto) imports AGENTS.md; a SessionStart hook injects a live map of accepted ADRs and modules every session.

Cursor .cursor/rules/persist-memory.mdc is an always-apply rule that loads the memory rules into every request.

Codex AGENTS.md is auto-discovered and loaded.

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:

Accepted ADRs and repository decisions 6. Module docs
Architecture docs 7. Feature plans
Engineering standards 8. Task files
Current PRD and accepted changes 9. External context
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.

[truncated for AI cost control]