A new open-source tool called Persist OS tackles one of the most frustrating realities of AI-assisted development: these models write code fast but have no long-term memory. Created by developer Karthick Ramachandran and shared on Hacker News, Persist OS is a local-first CLI that converts your repository into durable engineering memory—capturing not just what changed, but why decisions were made.

The Context Window Problem

AI coding assistants like Claude Code, Cursor, and OpenAI's Codex excel at generating code quickly, but they operate in isolated conversation bubbles. They forget architectural choices, lose track of product requirements, and silently contradict earlier decisions when their context window gets too crowded. Ramachandran noticed this firsthand while vibe-coding MVPs for friends: AI tools accelerated development dramatically, but the resulting projects lacked traceable reasoning. Persist OS addresses this by embedding structured memory directly into the repository itself—product intent, architecture decision records (ADRs), module ownership boundaries, testing expectations, and security constraints all live as version-controlled files. When an AI agent needs to understand why something was built a certain way, it reads the repo's documentation rather than relying on fading chat history.

How It Works

The tool operates through simple commands: persist init scaffolds neutral repository memory with optional opinion packs for specific stacks like Laravel+React or Kotlin/Android. Developers capture decisions as they work using persist feature create, persist adr create, and persist module create. Architecture decision records get promoted from proposed to accepted status, and when a decision changes, persist adr supersede marks the old ADR as superseded while linking it to the new one. The critical differentiator is persist doctor—a deterministic validation command that returns exit codes. It checks for missing documentation, completion evidence (features marked complete without test results), memory drift where files cite ADRs that no longer exist, and staleness when source code changes but corresponding memory doesn't update. This isn't a vector embedding search or semantic retrieval system; it's plain-text reviewable files with explicit provenance.

Tool Integration

Persist OS integrates natively with major AI coding tools. For Claude Code, CLAUDE.md auto-imports AGENTS.md and a SessionStart hook injects live maps of accepted ADRs and modules each session. Cursor loads memory through an always-apply rule file at .cursor/rules/persist-memory.mdc. Codex discovers AGENTS.md automatically. The generated agent rules even embed CLI commands inline so the AI tool can run validation itself. The system generates pre-commit and pre-push hooks that invoke persist doctor, creating a regression gate before code leaves your machine—capturing commits made with --no-verify or before hooks were active. This transforms "is this work actually finished?" from a subjective judgment into an automated check with exit codes: zero means healthy, one means warnings only, two indicates errors.

Local-First Privacy

Persist OS makes explicit guarantees about privacy and simplicity—no network calls at runtime, no telemetry collection, no connections to MCP servers or AI APIs. It generates application code neither for production nor otherwise, installs nothing into your repository by default, and protects against path traversal and symlink attacks. The tool runs entirely on your machine using Node.js 20 or higher, published on npm with MIT licensing.

Key Takeaways

  • AI coding assistants excel at generation but suffer from context rot across sessions
  • Persist OS embeds structured decision memory directly into version-controlled repository files
  • Deterministic persist doctor validation provides exit codes for CI/CD integration
  • Local-first operation means no data leaves your machine—no network calls, no telemetry