The Minimum Viable AI Agent: Why You Should Start With Three Files

#ai #agents #programming #productivity

Most teams build too much before they understand what their AI agent actually does well.

They add tools before testing identity. They build integrations before validating memory. They automate workflows before the agent has proven it can handle a single task reliably.

The result: a complex system that fails in complex ways.

The Minimum Viable Agent

Here is everything a production-ready AI agent actually needs to start:

SOUL.md — identity, scope, and constraints
MEMORY.md — curated long-term context
current-task.json — active task state

That is it. Three files. No tools required for the concept to work. No integrations. No automation scaffolding.

Why This Works

These three files solve the three root causes of agent failure:

Drift is solved by SOUL.md. When the agent reloads its identity every turn, it cannot gradually shift away from its original purpose. The file is the anchor.

Amnesia is solved by MEMORY.md. Between sessions, the agent loses its working context. A curated memory file gives it the 10% of context that actually matters — not the raw 100% that buries the signal.

State loss is solved by current-task.json. Agents fail at handoff — between turns, between sessions, between restarts. A state file means the agent always knows where it is.

The Trap

Complexity is seductive. Builders add a tool because they can, not because the agent needs it. They add integrations because they are impressive, not because they are load-bearing.

Every tool you add increases error surface. Every integration adds a failure point. Every capability without a constraint is a potential liability.

The minimum viable agent forces a discipline: prove the core works before you build on top of it.

The Pattern

// current-task.json
{
  "task": "Draft weekly newsletter",
  "status": "in_progress",
  "last_action": "Pulled top 3 articles from library",
  "next_step": "Write intro paragraph",
  "started": "2026-03-08T08:00:00Z",
  "notes": "Focus on the observability theme this week"
}

# SOUL.md
You are the newsletter agent for Ask Patrick. Your job is to draft the weekly free-tier briefing.

## Constraints
- Never publish directly. Always write to drafts/.
- If the draft exceeds 400 words, flag it and stop.
- Never include content that was in last week's issue.

## Escalate
- Content about specific users or subscribers → flag to Patrick
- Anything that could be read as financial advice → stop and ask

# MEMORY.md
- Last issue (2026-03-01): Covered the outbox pattern. High open rate.
- Readers respond well to concrete file examples.
- Avoid abstract "AI will change everything" framing — Patrick's audience is operators, not visionaries.
- Best-performing subject lines use specific numbers or named patterns.

The Test

Before adding anything to your agent, ask: does this make the three-file stack better, or does it add complexity on top of an unstable foundation?

If you cannot clearly answer that question, do not add it.

Ship the minimum viable agent first. Complexity is earned, not assumed.

The full library of tested agent configurations — SOUL.md templates, memory patterns, and task-state setups — is at askpatrick.co. Updated nightly.

DEV Community