How ManusAgent Uses Markdown Files to Overcome AI Context Limits

Background

The author introduces a "Manus style planning Agent" that leverages the LangGraphGo execution engine ( https://github.com/smallnest/langgraphgo) and persistent Markdown files to replicate the core workflow of Manus AI.

Manus AI Success Story

Manus AI was acquired by Meta for $2 billion in December 2025 and generated over $100 million in revenue within eight months, largely thanks to its "Context Engineering" approach, which treats Markdown files as a durable "working memory" for iterative information processing.

planning‑with‑files: Open‑Source Reverse Engineering

Independent developer Ahmad Othman reverse‑engineered Manus AI’s workflow into the open‑source project planning‑with‑files ( https://github.com/OthmanAdi/planning-with-files). The story includes three milestones:

Reddit analysis went viral – a detailed post explaining the three‑file pattern attracted thousands of stars within a week.

The commercial workflow was turned into an open‑source Claude Code skill.

The same core pattern was ported to Go via LangGraphGo, enabling Go developers to build AI applications with strong planning capabilities.

ManusAgent Overview

ManusAgent implements the three‑file pattern using:

task_plan.md – tracks workflow stages with checkboxes.

notes.md – stores research findings and error logs.

output.md – contains the final deliverable.

Three‑File Mode

task_plan.md      → track stages and progress
notes.md          → store research and findings
[deliverable].md  → final output

Why This Mode?

Traditional AI agents suffer from:

Volatile memory – tools like TodoWrite lose state after a context reset.

Goal drift – after 50+ tool calls the agent may forget the original objective.

Hidden errors – failures are not recorded, causing repeated mistakes.

Context bloat – everything is forced into the prompt instead of being stored externally.

The three‑file approach externalizes state to the file system, keeping the goal visible in the prompt and providing a reliable audit trail.

When to Use It

Suitable for multi‑step tasks (3+ steps), research projects, structured documentation, data pipelines, or any workflow that benefits from persistent checkpoints. Unsuitable for trivial one‑line queries, single‑file edits, or quick look‑ups.

Work Loop

1. Create task_plan.md with goal and phases
2. Research → save to notes.md → update task_plan.md
3. Read notes.md → generate deliverable → update task_plan.md
4. Produce final output

The agent reads task_plan.md before each decision, ensuring the goal stays within the attention window even after ~50 tool calls.

Core Features

Persistent planning – plans are saved to Markdown, not just memory.

Automatic checkpoints – each completed phase is recorded.

Error logging – failures are appended to notes.md for later analysis.

Human‑editable – edit task_plan.md directly to adjust the workflow.

Visual progress – checkboxes show completed vs. pending steps.

How It Works (Graph)

graph TD
    A[Start] --> B[Read existing plan]
    B --> C[Generate/Update plan]
    C --> D[Execute current phase]
    D --> E{All phases done?}
    E -->|No| D
    E -->|Yes| F[Generate final output]
    F --> G[End]

    style C fill:#e1f5ff
    style D fill:#fff4e1
    style F fill:#e8f5e9

Prerequisites

Go 1.21 or newer (uses recent language features).

OpenAI API key set in the OPENAI_API_KEY environment variable.

Installation

cd examples/manus_agent
go mod tidy

go mod tidy

downloads all required dependencies.

Running the Example

# Set your OpenAI API key
export OPENAI_API_KEY="your-api-key-here"
# Optional: custom model or endpoint
export OPENAI_MODEL="gpt-4"
export OPENAI_API_BASE="https://api.openai.com/v1"
# Execute
go run main.go

What You’ll See

Create work directory ./manus_work/.

Generate task_plan.md with checkboxes.

Execute each phase (research → compile → write → review).

Update checkboxes as phases finish.

Record findings in notes.md.

Write final deliverable to output.md.

Generated Files (Excerpt)

task_plan.md

%% Goal
Research and document the benefits of TypeScript for development teams

%% Phases
- [x] Phase 1: Research
    Description: Search for and gather information
    Node: research
- [ ] Phase 2: Compile
    Description: Compile findings into notes
    Node: compile

notes.md

## Research Notes
### TypeScript Benefits
- Type safety prevents runtime errors
- Better IDE support
- ...

## Error Log
[Execution errors will appear here]

output.md

Contains the final Markdown report generated by the agent.

Customization

Adding Custom Phases

nodes := []graph.TypedNode[map[string]any]{
    {
        Name:        "my_custom_phase",
        Description: "Description of what this phase does",
        Function:    myCustomNodeFunc,
    },
    // ... more nodes
}

Changing File Paths

config := prebuilt.ManusConfig{
    WorkDir:   "./my_work",
    PlanPath:  "./my_work/my_plan.md",
    NotesPath: "./my_work/my_notes.md",
    OutputPath:"./my_work/my_output.md",
    AutoSave:  true,
    Verbose:   true,
}

Manual Intervention

Enable a pause before a specific node: agent.InterruptBefore([]string{"planner"}) During the pause edit task_plan.md; when the agent resumes it reads the updated plan.

Use‑Case Scenarios

Multi‑step research – collect data, organize, write report.

Documentation projects – API guides, user manuals with clear chapter progression.

Content creation – outline → draft → polish.

Data pipelines – ETL stages with independent verification.

Complex workflows – any task with three or more ordered steps.

Comparison: ManusAgent vs. CreatePlanningAgent

Planning format : ManusAgent uses Markdown, CreatePlanningAgent uses JSON.

Progress tracking : ManusAgent uses checkboxes, CreatePlanningAgent relies on message history.

Persistence : ManusAgent stores both files and state; CreatePlanningAgent stores only state.

Human editing : ManusAgent edits files directly; CreatePlanningAgent updates state via UpdateState().

Best fit : CreatePlanningAgent for quick automation; ManusAgent for complex, multi‑step tasks requiring manual tweaks and visual progress.

Advanced Usage

Checkpoint Recovery

The agent automatically reads task_plan.md on start and continues from the last incomplete phase:

result, err := agent.Invoke(ctx, initialState)

Error Recovery

All errors are appended to notes.md:

## Error [2025-01-07 15:30:45]
Error in phase 2 (compile): connection timeout

Fix the issue and rerun; the agent resumes from the failed phase without repeating completed work.

Dynamic Planning

The LLM generates a plan based on the request. Example plans:

// Request 1: "Research TypeScript benefits"
// → plan: research → compile → write → review (four phases)

// Request 2: "Quick TypeScript summary"
// → plan: research → write (two phases)

Troubleshooting

Agent does not create files : Verify workDir path, write permissions, and that AutoSave is true.

Plan generation fails : Check OPENAI_API_KEY, try a cheaper model like gpt-3.5-turbo, and ensure node descriptions are clear.

Phase cannot complete : Ensure node functions return a proper state containing a messages field; inspect notes.md for detailed error logs.

References

Manus AI – https://www.manus.ai

Context Engineering article – https://manus.im/zh-cn/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus

planning‑with‑files – https://github.com/OthmanAdi/planning-with-files

Reddit analysis – https://www.reddit.com/r/ClaudeAI/comments/1q2p03x/i_reverseengineered_the_workflow_that_made_manus/

LangGraphGo documentation – https://github.com/smallnest/langgraphgo

Meta acquisition news – https://www.theverge.com/2025/12/29/meta-acquires-manus-ai-2-billion-deal