persistent-markdown-working-memory-system
Implements a three-file markdown-based external memory system (task_plan.md, findings.md, progress.md) that persists across AI agent context window resets and session boundaries. The system treats the filesystem as non-volatile disk storage analogous to RAM, automatically serializing agent state, decisions, and discoveries to markdown files that survive /clear commands and context loss. Each file serves a distinct purpose: task_plan.md tracks phases and decisions, findings.md captures research and technical decisions, progress.md logs session history and test results.
Unique: Uses filesystem-as-disk pattern inspired by Manus AI ($2B Meta acquisition) to solve context window volatility by treating three markdown files as persistent external working memory that survives agent session resets, context clears, and token limit exhaustion — a fundamental architectural shift from stateless to stateful agent design.
vs alternatives: Unlike vector databases or RAG systems that require external infrastructure, this approach uses plain markdown files as the persistence layer, making it zero-dependency, fully auditable, and git-compatible while solving the core problem of volatile AI context that traditional memory systems don't address.
three-file-schema-based-state-tracking
Enforces a structured markdown schema across three files with specific sections and update frequencies: task_plan.md tracks phases, decisions, and error logs (updated after phase completion); findings.md captures research discoveries and technical decisions (updated every 2 view/browser operations); progress.md logs session history and test results (updated throughout session). Each file has a defined structure with headers, status indicators, and timestamp tracking, creating a queryable state representation that agents can read before deciding on next actions.
Unique: Defines a three-file markdown schema with specific update frequencies and section structures (task_plan.md phases, findings.md discoveries, progress.md logs) that creates a queryable state representation agents can read before deciding, rather than relying on implicit context or unstructured notes.
vs alternatives: More structured than free-form notes but simpler than database schemas, making it human-readable, git-diffable, and agent-queryable without requiring external infrastructure or complex parsing logic.
phase-based-task-decomposition-and-tracking
Decomposes complex tasks into explicit phases tracked in task_plan.md with status indicators (not-started, in-progress, complete, blocked). Each phase has a clear objective, success criteria, and dependencies on prior phases. The system uses phase boundaries to scope context windows, create git checkpoints, and trigger state updates. Agents read the current phase from task_plan.md before deciding on actions, ensuring work stays focused on the current phase rather than drifting across multiple objectives. Phase completion triggers automatic updates to task_plan.md and can trigger git commits, creating explicit checkpoints in the project history.
Unique: Treats phase-based decomposition as a first-class pattern with explicit status tracking in task_plan.md, using phase boundaries to scope context windows, create git checkpoints, and trigger state updates — making task structure explicit and queryable rather than implicit in agent context.
vs alternatives: Unlike implicit task decomposition in agent prompts which is lost on context reset, this approach makes phases explicit in markdown files with status tracking, enabling agents to understand task structure and current progress even after session interruptions or context resets.
findings-discovery-and-technical-decision-logging
Maintains findings.md as a searchable reference of research discoveries, technical decisions, and their rationale. Agents update findings.md after every 2 view/browser operations or significant discoveries, recording: what was discovered, why it matters, what decision was made, and what alternatives were considered. This creates a queryable knowledge base that agents can reference before making similar decisions, avoiding redundant research and enabling consistent decision-making across sessions. Findings are organized by topic or decision category, making them searchable without requiring full file reads. The pattern enables agents to build institutional knowledge that persists across sessions and can be shared with other agents.
Unique: Treats findings.md as a queryable knowledge base of discoveries and decisions that agents can reference before making similar choices, enabling consistent decision-making and avoiding redundant research across sessions — making institutional knowledge explicit and persistent.
vs alternatives: Unlike context-based knowledge which is lost on context reset, findings.md provides persistent, searchable reference of discoveries and decisions that agents can query without re-running research, enabling knowledge accumulation and sharing across sessions and agents.
progress-logging-and-session-history-tracking
Maintains progress.md as a session log that records all actions taken, test results, and session history throughout the agent's work. Entries are timestamped and include: what action was taken, what the result was, what was learned, and what comes next. Progress.md grows throughout the session and serves as a detailed audit trail of everything the agent did. Unlike task_plan.md (which tracks phases) and findings.md (which tracks discoveries), progress.md tracks the moment-by-moment execution history. This enables agents to review what was attempted in prior sessions, understand why certain approaches were taken, and avoid repeating failed attempts.
Unique: Maintains progress.md as a detailed, timestamped execution log that records every action, result, and learning throughout the session, creating a complete audit trail that enables agents to understand prior session context and avoid repeating failed attempts — treating execution history as a first-class artifact.
vs alternatives: Unlike generic logs which are often discarded or archived, progress.md is a persistent, queryable record that agents can reference to understand prior session context and execution history, enabling learning from past attempts and detailed debugging of agent behavior.
read-before-decide-workflow-pattern
Implements a critical workflow pattern where agents must read the three markdown files (task_plan.md, findings.md, progress.md) before making decisions or taking actions. This pattern breaks the stateless agent loop by forcing agents to check current state, previous decisions, and error history before proceeding. The pattern is enforced through hook system automation and critical rules that prevent agents from acting without first consulting the persistent state files, creating a synchronous decision-making loop tied to filesystem state.
Unique: Enforces a synchronous read-before-decide loop where agents must consult persistent markdown state files before taking actions, breaking the stateless agent pattern by making every decision dependent on querying the filesystem state rather than relying on volatile context window memory.
vs alternatives: Unlike prompt-based context injection which loses state on context reset, this pattern makes state queries mandatory and persistent, ensuring agents always have access to the latest findings and decisions regardless of context window size or session boundaries.
session-recovery-and-context-restoration
Enables agents to recover from context window resets, /clear commands, or session interruptions by reading the three markdown files to reconstruct the prior session state. When a session resumes, the agent reads task_plan.md to identify the last completed phase, findings.md to understand prior discoveries and decisions, and progress.md to review session history and test results. This restoration process reconstructs the agent's understanding of project state without re-running prior work, allowing seamless continuation from the last known checkpoint.
Unique: Treats markdown files as persistent checkpoints that survive context window resets, enabling agents to reconstruct full project state from disk without re-running prior work — a fundamental shift from stateless to stateful agent design that makes context window exhaustion recoverable rather than fatal.
vs alternatives: Unlike traditional RAG or vector database recovery which requires external infrastructure and loses fine-grained decision context, this approach uses plain markdown files as checkpoints, making recovery deterministic, auditable, and git-compatible while preserving full decision history.
git-checkpoint-workflow-integration
Integrates git commits as explicit checkpoints in the agent workflow, allowing agents to create git snapshots after completing phases or achieving milestones. The workflow uses git commits to mark stable states in the three markdown files and project code, enabling rollback to prior states if errors are discovered. Agents can reference git commit hashes in task_plan.md and progress.md, creating a version-controlled audit trail of state changes. This pattern combines filesystem persistence with git's version control, providing both recovery and history tracking.
Unique: Combines filesystem-based markdown persistence with git version control, using git commits as explicit checkpoints that mark stable states in both code and agent state files, enabling rollback and audit trails that neither filesystem persistence nor git alone provides.
vs alternatives: Stronger than markdown-only persistence because git provides immutable history and rollback capability; stronger than git-only because markdown files provide human-readable state snapshots that survive git operations and enable agent state recovery without code changes.
+5 more capabilities