OthmanAdi/planning-with-files

Persistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.

What it solves

AI coding agents often suffer from "volatile memory," where their task plans and progress are lost when the context window is reset (e.g., via /clear), during compaction, or after a crash. This leads to goal drift, repeated mistakes, and the need for the user to manually restate goals.

How it works

Instead of keeping a to-do list in the volatile context window, this project implements a "filesystem as memory" approach. It maintains three persistent Markdown files on disk:

  • task_plan.md: Tracks phases, checkboxes, and the current resume point.
  • findings.md: Stores research notes and decisions.
  • progress.md: Logs session activity and test results.

Lifecycle hooks (such as UserPromptSubmit or SessionStart) automatically re-inject the relevant plan context from these files back into the agent's window at the start of each turn, ensuring the plan survives context loss and remains in the model's attention window.

Who it’s for

Developers using AI coding agents (such as Claude Code, Cursor, GitHub Copilot, or Hermes Agent) for long-running, complex tasks that require persistence across sessions or context resets.

Highlights

  • Persistence: Plans survive /clear commands, crashes, and context compaction.
  • Agent Agnostic: Compatible with 60+ agents via the Agent Skills standard and native plugins for several major tools.
  • Goal Stability: Prevents goal drift by re-injecting the plan head every turn.
  • Integrity Checks: Uses SHA-256 attestation to detect if the plan has been silently tampered with.
  • Completion Gating: Can prevent an agent from declaring a task "done" until all phases in the disk-based plan are marked complete.

Related

  • Project
    kleosr/cursorkleosr

    A persistent memory system for Cursor AI agents that uses always-on rules and Markdown files to track project state and goals across sessions.

  • Project
    mindmuxai/brain.md

    A persistent, file-based memory layer for coding agents that stores project decisions and constraints as plain Markdown in the repository.

  • Project
    akitaonrails/ai-memory

    ai‑memory is a Rust‑based server that records every observation a coding‑assistant makes (prompts, tool calls, session boundaries) as plain markdown files in a git‑backed wiki. The server can be run locally, in Docker/Podman, or on a homelab box and is designed to be shared across many agents (Claude Code, Codex, Cursor, Gemini CLI, etc.), machines and team members. Hooks posted by agents are consolidated into readable wiki pages at session end; the next session receives a concise handoff so it can continue exactly where the previous one stopped. Storage is human‑readable markdown plus a SQLite index (FTS5, entity and optional vector search). By default it needs no LLM or embedding keys; optional Anthropic/OpenAI integrations add LLM‑generated summaries and semantic search. Multi‑user authentication, audit logs and per‑person attribution are built in. Install via Arch AUR, Docker wrapper, or native binary, start the server, register a client and its hooks, and the system works transparently.

  • Project
    JamesShi96/project-butler

    A persistent memory system for AI coding assistants that uses a structured Markdown-based memory stack to maintain project context, rules, and progress across sessions.

  • Project
    jsmastery-pro/skills

    A set of modular AI agent skills that implement a professional engineering workflow, moving project state from chat sessions into repository files for persistence and team collaboration.