Files as Memory: How to Finally Cure AI Coding Agents of Context Amnesia

When AI Agents Hit the "Amnesia" Wall

Anyone who's used Claude Code, Cursor, or Codex CLI has probably run into the same frustrating scenario: you're halfway through a complex refactor when the context window fills up, or a single /clear command wipes everything out — all your planning, decisions, and progress, gone in an instant.

The context window is the maximum number of tokens a large language model can process in a single inference pass. Early models like GPT-3 had just 4K tokens, while the Claude 3 series has expanded to 200K tokens and GPT-4 Turbo supports 128K tokens. Despite this growth, the limitation remains a real bottleneck — not just because of the hard cap, but because as context grows longer, the model's "attention" becomes diluted and its ability to use earlier information drops significantly. This is what researchers call the "Lost in the Middle" problem: models process information in the middle of a long context least effectively.

For long-running agentic tasks, context loss is nearly fatal. A model's memory is inherently volatile — once a session is interrupted or the context is truncated, everything accumulated earlier simply vanishes. The GitHub project planning-with-files was built specifically for this pain point. With over 24,000 Stars and 61 new stars in a single day, the community's resonance with this problem speaks for itself.

The Core Idea: Write Your Plans to Disk

The project's philosophy can be summed up in one sentence: replace fragile context memory with file-based persistent planning.

The Manus-Style Persistence Strategy

planning-with-files describes itself as "Manus-style," mimicking the core approach of general-purpose agents like Manus — rather than cramming all state into the model's context, it saves planning, to-do lists, and execution progress as Markdown files on disk.

This mechanism delivers three immediate benefits:

Crash-proof: Whether the process crashes, the session ends, or the context is cleared, the planning files stay safely on disk, ready to be reloaded at any time.
Readable and auditable: Markdown is human-friendly plain text. Developers can open the files at any time to inspect the AI's reasoning, and even manually edit them to course-correct.
Cross-session continuity: When a new session starts, the Agent reloads the files and "remembers" where things left off — enabling true task handoff across sessions.

This design reflects an important paradigm in the AI Agent space: External Memory. Drawing from cognitive science research on human memory systems, AI Agent memory is typically divided into four types: working memory (current context), episodic memory (past interactions), semantic memory (knowledge base), and procedural memory (skills/tools). planning-with-files essentially takes a portion of working memory and persists it as episodic memory, using the file system to maintain information continuity across sessions. This mirrors classic cognitive architecture frameworks like ACT-R and SOAR, which similarly emphasize continuously writing working memory contents to long-term storage. Rather than fighting against the limits of the context window, the approach treats the file system as the Agent's "long-term memory," letting the context carry only the most immediately relevant information.

Three Key Capabilities

1. Deterministic Completion Gate

planning-with-files introduces a "deterministic completion gate" mechanism that targets another common AI Agent failure mode: claiming a task is done prematurely.

LLM hallucination doesn't only manifest as factual errors — it also appears as systematic bias in self-assessment of task completion. Research shows that models tend to consistently overestimate how complete a task is, a byproduct of RLHF (Reinforcement Learning from Human Feedback) training, where models are incentivized to give satisfying answers rather than accurate ones.

The mechanism works by requiring that every to-do item in the planning file be checked off before the task is considered done, forcing the Agent to go through each item before wrapping up. The determination is based entirely on file state — completely deterministic, with no reliance on the model's subjective self-assessment. In essence, it converts a "soft judgment" into a "hard constraint," making it far more reliable and eliminating the "strong start, weak finish" problem.

2. Multi-Agent Shared State

The project supports "multi-agent shared state on disk," enabling multiple Agents to collaborate through shared files on disk.

The core challenges in Multi-Agent Systems (MAS) are coordination and consistency. Traditional solutions include message queues (like Redis Pub/Sub), shared databases, or dedicated agent communication protocols (like FIPA-ACL). The "shared disk file" approach taken by planning-with-files essentially turns the file system into a simplified tuple space, similar to the classic Linda concurrency model — where processes coordinate by reading and writing to a shared space rather than communicating point-to-point. This design dramatically reduces coupling while naturally providing a "shared blackboard" that all Agents can read and write, making the collaboration process transparent and traceable.

3. Broad Compatibility via SKILL.md

Perhaps the most noteworthy aspect is its compatibility strategy. The project uses the SKILL.md standard to claim interoperability with 60+ agent tools, including:

Claude Code
Codex CLI
Cursor
Kiro
OpenCode

SKILL.md represents an emerging trend toward standardized capability description in the AI tooling ecosystem, similar to Anthropic's MCP (Model Context Protocol) and OpenAI's Assistants API tool definition format. SKILL.md uses a Markdown file to describe an agent tool's capability boundaries, invocation methods, and usage conventions. This "declarative capability description" approach shares the same design philosophy as Interface Definition Languages (IDL) and OpenAPI specifications in software engineering. By adhering to this standard, planning-with-files can integrate as a drop-in component into existing workflows without requiring custom adapters for each tool, dramatically lowering the barrier to adoption.

Why This Deserves Attention

It Addresses a Real Pain Point in Agent Engineering

24,000 Stars don't happen by accident. As more developers upgrade AI from "code completion" to "autonomous execution of complex tasks," task reliability and recoverability become core requirements. planning-with-files solves a genuine engineering problem with the most straightforward possible means — files. This kind of elegant simplicity tends to have the most staying power.

Simplicity Is Elegance

Compared to solutions that reach for vector databases or complex state machines, using Markdown files for persistence introduces almost zero additional dependencies — and anyone can understand and debug it. Low complexity translates directly to high robustness. The file system is highly reliable OS-level infrastructure, battle-tested through decades of operating systems engineering, and POSIX file semantics provide sufficiently strong atomicity guarantees for the vast majority of use cases.

Lessons for Agent Engineers

For developers currently building AI Agents, this project offers a reusable set of design patterns:

Don't put all your faith in the context window.
Externalize task planning, execution progress, and intermediate state to persistent storage.
Use deterministic checks rather than model self-assessment to determine task completion.
Embrace open standards (like SKILL.md) to improve interoperability across tools.

Conclusion

planning-with-files represents a pragmatic direction in AI Agent engineering: rather than trying to make models "remember everything," design a recovery system where it's okay if the Agent "forgets." When planning becomes reliable, readable, and recoverable files on disk, AI coding assistants finally have the foundation needed to handle long-running, complex tasks with confidence. For teams pursuing reliable automation, this may be precisely the step that moves AI Agents from "demo toy" to "production tool."