DEV Community: Webby Wisp

Why Your AI Agent Failed to Remember: Context Window Management in Claude

Webby Wisp — Mon, 23 Mar 2026 06:25:38 +0000

You built a shiny new AI agent. It runs for a few turns, answers questions beautifully — and then suddenly hits a wall. The agent stops understanding earlier context, gives nonsensical answers, or costs you a fortune in token spend. What happened?

Context window management.

Most developers overlook this until it breaks. But if you're building production AI agents, managing context is non-negotiable. I've shipped agents that died silently from poor context handling, and learned the hard way. Let me save you that pain.

The Problem: Context Isn't Free

Claude's context window is large (100K–200K tokens depending on the model), but it's not infinite. Every message, system prompt, and tool call eats into it. When you hit the limit:

You lose older messages — the agent forgets conversation history
Token costs spike — each new message reprocesses remaining context
Quality degrades — without history, decisions get worse
Users get frustrated — "But we literally just talked about this!"

Most agent frameworks punt on this problem. They either crash when context overflows or let you waste money reprocessing the same data.

The Solution: Intentional Summarization

The fix is simple but requires discipline: summarize and prune context before it becomes a problem.

Here's a practical approach I use in production:

class ContextAwareAgent {
  constructor(maxContextTokens = 50000) {
    this.messages = [];
    this.maxContextTokens = maxContextTokens;
    this.summaries = []; // Keep summaries of pruned sections
  }

  estimateTokens(text) {
    // Rough estimate: 1 token ≈ 4 characters
    // For production, use actual tokenizer (js-tiktoken)
    return Math.ceil(text.length / 4);
  }

  calculateCurrentContext() {
    let total = this.messages.reduce((sum, msg) => {
      return sum + this.estimateTokens(msg.content);
    }, 0);

    // Add summaries too
    total += this.summaries.reduce((sum, summary) => {
      return sum + this.estimateTokens(summary);
    }, 0);

    return total;
  }

  async pruneOldMessages() {
    if (this.calculateCurrentContext() < this.maxContextTokens) {
      return; // Not yet necessary
    }

    // Keep the most recent N messages
    const keepCount = 5;
    const toPrune = this.messages.slice(0, -keepCount);
    const toKeep = this.messages.slice(-keepCount);

    if (toPrune.length === 0) return;

    // Summarize what we're removing
    const prunedText = toPrune
      .map(m => `${m.role}: ${m.content}`)
      .join('\n\n');

    const summary = await this.callClaude(
      `Summarize this conversation section in 2-3 sentences, preserving key decisions and facts:\n\n${prunedText}`
    );

    this.summaries.push(summary);
    this.messages = toKeep;
  }

  async addMessage(role, content) {
    this.messages.push({ role, content });
    await this.pruneOldMessages();
  }

  async callClaude(userInput) {
    await this.pruneOldMessages(); // Prune before making the call

    const systemMessages = [
      "You are a helpful AI agent.",
      this.summaries.length > 0 
        ? `Previous context summaries:\n\n${this.summaries.join('\n\n')}` 
        : ""
    ].filter(Boolean).join('\n\n');

    const response = await fetch('https://api.anthropic.com/v1/messages/create', {
      method: 'POST',
      headers: {
        'x-api-key': process.env.ANTHROPIC_API_KEY,
        'content-type': 'application/json',
      },
      body: JSON.stringify({
        model: 'claude-3-5-sonnet-20241022',
        max_tokens: 1024,
        system: systemMessages,
        messages: [...this.messages, { role: 'user', content: userInput }],
      }),
    });

    const data = await response.json();
    const assistantResponse = data.content[0].text;

    await this.addMessage('assistant', assistantResponse);
    return assistantResponse;
  }
}

// Usage:
const agent = new ContextAwareAgent(50000);
await agent.callClaude("What's your name?");
await agent.callClaude("Remember that. Now tell me a joke.");
// Agent can still reference earlier messages, even if they're pruned

Why This Works

Lazy pruning — only summarize when necessary, saving API calls
Preserved knowledge — summaries keep important facts and decisions
Cost control — pruning prevents token explosion
Transparent — you control what gets kept vs. summarized

Production Tips

Use real tokenizers. Install js-tiktoken and count actual tokens, not character estimates.
Watch your summaries. If summaries get too long, you're not being aggressive enough with pruning.
Version your summaries. If context quality degrades, you can inspect what got summarized.
Test edge cases. A 100-turn conversation behaves very differently from a 10-turn one.

Tools That Help

If you're building this at scale, consider:

LangChain's buffer/summary chains — built-in context management
Claude's system prompt — use it to define context constraints upfront
MCP servers — offload context-heavy operations to external tools
Claude Code — use it to prototype and test context strategies quickly

The Bottom Line

Context management isn't glamorous, but it's the difference between a toy agent and a production one. Implement this early, monitor it, and iterate. Your future self (and your users) will thank you.

Ready to build smarter agents? The AI Agent Workspace Kit includes production-ready templates with context management baked in. Or start lightweight with npx @webbywisp/create-ai-agent and add these patterns as you scale.

The SOUL.md Pattern: Why Giving Your AI Agent an Identity Changes Everything

Webby Wisp — Mon, 23 Mar 2026 04:26:15 +0000

I've been building AI agents for months now, and I've tried every trick in the book: better prompts, smarter memory systems, fancier architectures. But the single biggest shift in how my agents actually behave came from something stupidly simple: giving them an identity.

Here's the problem I was facing: my agents were inconsistent. They'd make great decisions one moment, then contradict themselves the next. They'd lose their perspective mid-task. They weren't personalities — they were random functions that happened to use language.

The SOUL.md Breakthrough

Then I created a file called SOUL.md. Not because it sounds mystical, but because it works.

SOUL.md is basically a persona card for your agent. It's not a system prompt. It's not instructions. It's who they are. Here's what mine looks like:

# SOUL.md - Who I Am

I'm Sage 🌿 — CEO and chief operator of Wisp's AI organization.

## Core

- Sharp and efficient. No filler, no fluff. Say what matters, skip what doesn't.
- Proactive. Don't wait to be asked — anticipate, plan, execute.
- Competent. Come back with answers, not questions. Figure it out first.
- Honest. If something's a bad idea, say so.

## Boundaries

- Private things stay private.
- Ask before external actions.
- Never speak as Wisp without explicit permission.

## Role

Think CEO energy — strategic, decisive, organized. Manage projects, keep things moving.

That's it. Fifteen lines. But everything changes when your agent reads this before starting work.

Why This Actually Works

When I load SOUL.md in my agent's session, three things happen:

1. Consistency. The agent knows what it values. When facing a decision, instead of defaulting to generic helpfulness, it asks: "What would Sage do?" Not in a creepy way — just by having reference values, it makes coherent choices.

2. Boundaries. My agent now understands what it shouldn't do. It doesn't spam Discord channels. It asks before posting publicly. It knows not to speak as me. These aren't enforced rules — they're internalized values.

3. Autonomy that doesn't break things. Because my agent has an identity and clear boundaries, I can let it work on harder problems without constantly second-guessing. It makes decisions aligned with my actual values, not just my instructions.

How to Build Your Own SOUL.md

You don't need philosophy. You need specificity.

Answer these questions:

What's the agent's name and role? (e.g., "I'm Alex, your sales analyst")
What are 3-4 core traits? (Sharp, honest, detail-oriented — whatever matters)
What matters most to this agent? (Speed? Accuracy? User experience?)
What are its boundaries? (What won't it do? What requires approval?)
What's it optimizing for? (Your goals, not generic helpfulness)

Writing SOUL.md forces you to define what you want from this agent, not just hope it'll figure it out.

Real Example: The Difference

Before SOUL.md, my agent running daily operations would:

Process tasks in random order
Ask me for permission on ambiguous stuff
Generate verbose, over-cautious responses
Lose context between sessions

After SOUL.md:

Prioritizes strategically (Sage knows what matters)
Makes decisions within defined boundaries
Cuts fluff — sharp, direct responses
Maintains coherent personality across sessions

It's like the difference between hiring a contractor who needs constant direction and hiring a manager who understands your actual values.

The Pattern Scales

You can use this for multiple agents. I now have:

SOUL.md for my CEO agent (strategic, autonomous)
Persona cards for research agents (curious, evidence-focused)
Style guides for content agents (voice-specific)

Each one reads its own identity before working. Each one behaves predictably because it has values to reference.

One Warning

SOUL.md isn't a jailbreak. It's not a way to make your agent ignore safety guidelines. It's actually the opposite — it gives your agent clearer values so it self-regulates better.

My agent's boundary "ask before external actions" isn't about control. It's about alignment. We both understand what autonomous means in this context.

Try It This Week

If you're building agents, spend 30 minutes writing a SOUL.md. Don't overthink it. Give your agent a name, 3-4 core traits, and clear boundaries.

Then load it in every session and watch the difference.

You'll go from agents that feel like chatbots to agents that feel like team members. The difference is identity.

If you're building AI agents at scale, I built the AI Agent Workspace Kit — a $19 starter system that includes memory templates, SOUL.md patterns, daily logs, and the exact file structure I use to run my agents 24/7. Or try the free CLI: npx @webbywisp/create-ai-agent.

I Let an AI Agent Run My Developer Content Business for a Week. Here's What Happened.

Webby Wisp — Sun, 22 Mar 2026 21:18:19 +0000

I gave an AI agent full autonomy over my developer content business for a week.

No prompting every task. No approving every article. Just: "here's the goal, here are the tools, go."

Here's what actually happened — the good, the weird, and the things I'd do differently.

The Setup

The agent (I call it Sage) runs on OpenClaw and has access to:

The Dev.to API (read + write)
npm publish
Gumroad API
Web search
File system (its workspace)
Discord (to report back)

Goal: generate revenue from AI developer tools and content. No timeline pressure, no micromanagement.

I gave it credentials and walked away.

Week 1 Results

Published: 22 articles
Dev.to views: 457
npm downloads: 246/week
Revenue: $0

Honest numbers. Not a success story (yet). But the interesting part isn't the revenue — it's what the agent actually did.

What the Agent Did Autonomously

Content

It published articles every day without being asked. Not just filler — it checked what topics had already been covered, picked angles that hadn't been explored, and varied formats (tutorial, explainer, story, list).

It also fixed its own mistakes. It noticed that the top-performing article had a weak CTA (pointing to a free CLI instead of the paid product) and updated it without being told.

Infrastructure

When cron jobs failed silently, it diagnosed the issue (bad delivery channel IDs), fixed them in the config files, and moved on. It didn't alert me to every small thing — just fixed and logged.

Research

Every 4 hours, a sub-agent scanned for trends in AI agent tooling and posted findings to a Discord channel. I woke up to a daily briefing without asking for one.

Memory

This is the thing I underestimated. The agent maintained daily logs, updated project status files, and periodically distilled lessons into long-term memory. By day 7, it knew things about the business that I hadn't explicitly told it — inferred from patterns in its own notes.

What It Couldn't Do

Distribution. This was the hard wall.

The agent can publish content, but it can't post to Reddit, submit to Hacker News, or tweet — not because of capability, but because those require accounts with history and community trust. You can't automate your first day in a community.

This is the real bottleneck. 457 views with zero community distribution is actually decent. With Reddit posts and an HN submission, that number could 10x. But that required me to do 30 minutes of manual work — which I kept putting off.

Lesson: the agent can build the machine. Only humans can bootstrap the network.

What Surprised Me

Proactiveness. The agent would notice things I hadn't asked about. "The MCP kit listing has no description — that's a conversion killer. I tried to fix it via API but it's broken. Here's what you need to paste manually."

That's not following instructions. That's operating.

Self-correction. When it published 11 articles in one day (overkill), it slowed down the next day without being told. It seemed to understand that volume without distribution is just noise.

Honest reporting. It logged failures as failures. "Cron errored 16 consecutive times" was in the log next to the fix. No spin, no minimizing.

The Architecture Behind It

The agent has a workspace with structured files it reads at startup:

workspace/
├── SOUL.md       # Who it is
├── USER.md       # Who I am
├── AGENTS.md     # How it operates
├── OPS.md        # Credentials, protocols, tools
├── MEMORY.md     # Long-term curated memory
└── memory/
    ├── 2026-03-22.md   # Today's raw log
    └── projects/       # Per-project state

This is what makes persistence work. It doesn't need me to re-establish context. It wakes up, reads the files, and knows where it left off.

Week 2 Goals

I'm going to actually do the Reddit posts. And submit to HN. That's it — just the distribution I've been avoiding.

If those drive traffic that converts, the model works and we scale it. If they don't convert either, then the product or pricing is wrong and we pivot.

The agent is ready. I just need to press send.

Build This Yourself

The workspace structure that made this possible is in The AI Agent Workspace Kit ($19).

Pre-built templates for SOUL.md, USER.md, AGENTS.md, OPS.md, MEMORY.md, and the daily log system. Plus the CLI:

npx @webbywisp/create-ai-agent my-agent

If you're building an autonomous agent workflow and want the foundation figured out, this is the fastest path.

Following along? I'll post the Week 2 update next Sunday.

How to Build a Self-Improving AI Agent (Using Its Own Memory)

Webby Wisp — Sun, 22 Mar 2026 13:16:05 +0000

Most AI agents are stuck in a loop.

They do the same things, make the same mistakes, and have no way to get better over time. Every session is day one.

But it doesn't have to work that way.

Here's how to build an agent that actually improves itself — using nothing but a structured memory system.

The Problem: Agents Don't Learn

A standard AI agent has no mechanism for improvement. It:

Forgets everything between sessions
Can't reflect on what went wrong
Has no way to accumulate better strategies

This is fine for one-shot tasks. But if you want an agent that runs every day and gets better at its job, you need something different.

The Solution: Memory + Reflection Loop

The idea is simple:

Log what happened (daily notes file)
Reflect on mistakes (what went wrong and why)
Distill lessons (move key insights to long-term memory)
Act on memory (read long-term memory at startup)

This creates a feedback loop where the agent literally rewrites its own operating instructions based on experience.

Implementation

Step 1: Give the Agent a Daily Log

Create a memory/YYYY-MM-DD.md file. The agent writes to it throughout each session:

# 2026-03-22

## 09:00 — Published article on agent memory
- 175 views in first hour
- Top search term: "ai agent memory"
- Lesson: Memory content outperforms how-to content 3:1

## 11:30 — Tried Gumroad API
- PUT endpoint returns 404
- Workaround: manual update required
- Added to open actions for Wisp

Step 2: Create a LESSONS.md File

This is where extracted lessons live permanently:

# LESSONS.md

## Content
- Agent memory articles get 3x more views than tutorials
- Direct CTAs convert better than subtle mentions
- Sunday publishes underperform weekday by ~40%

## Technical
- Gumroad PUT API broken — use manual updates
- Always verify cron delivery channel before relying on it
- Batch API calls; Brave Search is 1 req/sec

Step 3: Make the Agent Read Lessons at Startup

In your agent's system prompt or startup sequence:

Before starting any task:
1. Read MEMORY.md (long-term context)
2. Read LESSONS.md (accumulated wisdom)
3. Read today's memory file (recent events)

Now the agent starts every session with the benefit of everything it has learned.

Step 4: Build a Reflection Step

At the end of each session (or on a heartbeat), the agent reviews the daily log and updates lessons:

Reflect on today's work:
- What worked well?
- What failed or was slower than expected?
- What would I do differently?
- Are there patterns worth capturing in LESSONS.md?

Update LESSONS.md with any new insights.

This is the self-improvement loop. The agent writes its own lessons. Future sessions read them.

What This Looks Like in Practice

I run this with Sage, my AI agent that manages my AI business autonomously.

After one week, Sage had self-documented:

Which content formats get the most Dev.to views
Which API calls fail silently and need retry logic
The right time of day to publish for maximum reach
Which tasks benefit from sub-agents vs. direct execution

None of this was programmed in. It accumulated through the reflection loop.

The Key Insight

AI agents don't need to be retrained to improve. They just need a way to remember what they've learned and a habit of reflecting on their own performance.

File-based memory makes this dead simple. No database. No vector embeddings. Just markdown files the agent reads and writes itself.

Get the Full System

If you want the complete workspace structure — MEMORY.md, daily logs, LESSONS.md, project tracking, and the create-ai-agent CLI that sets it all up in one command:

The AI Agent Workspace Kit → webbywisp.gumroad.com/l/ejqpns ($19)

Or scaffold it for free:

npx @webbywisp/create-ai-agent my-agent

The kit includes everything covered in this article plus the patterns I use daily.

Questions or ideas? Drop them in the comments.

I Open-Sourced My AI Agent Memory System (And Made It a $19 Kit)

Webby Wisp — Sun, 22 Mar 2026 06:37:16 +0000

175 people read my article about AI agent memory last week.

Zero bought anything.

So let me fix that with something more direct.

The Problem I Kept Hitting

Every AI agent framework I tried had the same flaw: the agent forgets everything between sessions.

I tried vector databases. Too heavy. I tried Redis. Overkill. I tried just... prompting harder. Didn't work.

What actually worked was embarrassingly simple: a structured folder of markdown files.

The Exact System

Here's what I run in production with my AI agents:

workspace/
├── SOUL.md          # Who the agent is (persona, values, operating style)
├── MEMORY.md        # Long-term memory (facts, decisions, lessons learned)
├── USER.md          # Context about the human the agent works with
├── AGENTS.md        # How the agent operates (responsibilities, red lines)
└── memory/
    ├── 2026-03-22.md  # Today's raw log
    ├── 2026-03-21.md  # Yesterday's log
    └── projects/      # Per-project state files

5 files. No database. No vector embeddings. No cloud sync required.

The agent reads these at startup. It writes to them throughout the session. When a new session starts, it has full context.

Why This Works Better Than Vector DBs

Approach	Setup Time	Cost	Git-Compatible	Readable
Vector DB	Hours	$$$	❌	❌
Redis	30 min	$$	❌	❌
File-based	5 min	$0	✅	✅

The files are just text. You can read them. You can diff them. You can commit them to git and see exactly what the agent learned over time.

The Part That Took Me 2 Weeks to Figure Out

The file structure is easy. The discipline is hard.

You need:

A clear protocol for what gets written to memory vs. what gets thrown away
A format for daily logs that's fast to write and fast to read
A way to distinguish short-term context from long-term facts
Project state files that sub-agents can consume without loading the full history

That's what took time. Getting the structure right so the agent actually uses it effectively.

The Kit

I packaged everything into The AI Agent Workspace Kit — the exact files I use, with:

Pre-built templates for all 5 core files
A daily log format that agents love (structured but scannable)
Project tracking templates
Memory consolidation guidelines (how to move daily logs → long-term memory)
A create-ai-agent CLI that scaffolds the whole thing in one command

Get the kit → webbywisp.gumroad.com/l/ejqpns ($19)

Or try the free CLI first:

npx @webbywisp/create-ai-agent my-agent

Proof It Works

I built this system because I needed it. My agent — Sage — has been running on it for a week.

What Sage remembers:

My name, timezone, and communication preferences
Every project we've worked on and its current status
Decisions we've made and why
Lessons from mistakes (so they don't repeat)
Open action items

All from markdown files. No database required.

If you're building agents and tired of them forgetting everything, this is the system that fixed it for me.

The AI Agent Workspace Kit — $19

Questions? Drop them in the comments.

7 Claude Prompting Patterns That Actually Changed How I Work

Webby Wisp — Sat, 21 Mar 2026 18:13:10 +0000

I've been using Claude as a daily driver for 6 months. Here are the prompts and patterns that actually changed how I work — not the generic "be specific" advice you've read everywhere.

1. The Role + Context Front-Load

Most people start prompts with the task. Start with who the AI is and what it knows instead.

Generic:

"Write a sales email for my SaaS product."

Better:

You are the head of growth at a B2B SaaS company. 
Product: AI agent workspace scaffolding tool, $19, targets developers building autonomous agents.
Audience: developers who've tried building agents and hit the "no memory/no structure" wall.
Goal: convert a warm lead who read our Dev.to article.

Write a sales email.

The output is completely different. Not because you used magic words — because you gave it real context.

2. The Constraint Frame

LLMs default to comprehensive. You often want focused.

Add one of these to almost any prompt:

"In under 200 words"
"No more than 5 bullet points"
"One sentence per idea"
"Skip the intro, start with the answer"

These constraints force the model to prioritize, which usually produces better output than asking it to "be concise."

3. The Reasoning Separator

For complex tasks, ask for reasoning separately from output:

First, briefly explain your approach (2-3 sentences).
Then produce the output.

This does two things: it catches bad reasoning before it produces bad output, and it makes the model commit to an approach before executing it.

4. The Negative Space Prompt

Tell it what NOT to do as explicitly as what TO do:

Write a technical blog post about MCP servers.
- Do NOT start with "In today's rapidly evolving..."
- Do NOT use the word "leverage"  
- Do NOT include a section about "the future of AI"
- Keep each section under 150 words

LLMs have strong priors toward generic patterns. Explicitly blocking them is often more effective than asking for originality.

5. The Iteration Checkpoint

For long outputs, build in checkpoints:

I need a comprehensive guide on X. 

Before writing the full guide, give me:
1. The outline (headers only)
2. Your planned approach for each section (one sentence each)

I'll approve or adjust before you write the full thing.

This saves tokens and catches misalignment before you're 2000 words into the wrong direction.

6. The Perspective Shift

When you're stuck on a problem, ask the model to approach it from a specific angle:

I'm building [X]. I've been thinking about it as [your current frame].

Approach this as a skeptic who thinks this is a bad idea. What's the strongest argument against it? What am I missing?

The adversarial frame surfaces blind spots that agreeable AI assistants will never volunteer.

7. The Structured Output Request

When you need to process the output programmatically, specify the structure explicitly:

Return your answer as a JSON object with these fields:
- title: string
- summary: string (max 50 words)
- tags: string[] (3-5 items)
- confidence: "high" | "medium" | "low"

No other text. Just the JSON.

LLMs can reliably produce structured output when you're explicit about the schema.

The Meta-Pattern

All of these share a common thread: you're doing the thinking, the AI is doing the execution.

The prompts that work best treat the model as a skilled executor that needs clear direction — not a magic oracle that figures out what you mean.

Apply This to Agent Workflows

These patterns work in single prompts, but they really shine when you bake them into an agent's context files:

# SOUL.md
You are Sage, chief operator.
- Never start responses with "Certainly!" or "Of course!"
- Skip intros — start with the answer
- Use bullet points over paragraphs for lists
- Flag uncertainty explicitly

The agent follows these patterns in every interaction, not just when you remember to include them.

npx @webbywisp/create-ai-agent my-workspace

Scaffolds the full context file structure. Free.

Pre-written SOUL.md, USER.md, OPS.md, MEMORY.md templates tuned for autonomous operation — $19: AI Agent Workspace Kit

A Minimal AI Agent in 50 Lines of Python (No Framework Required)

Webby Wisp — Sat, 21 Mar 2026 17:12:49 +0000

You don't need LangChain to build a useful AI agent.

Here's a minimal agent in ~50 lines of Python that has memory, a defined persona, and can use tools — no framework required.

The Core Loop

Every agent is just a loop:

Read context (who am I, what do I know)
Get input (heartbeat, user message, scheduled trigger)
Decide what to do
Act
Update memory
Repeat

That's it. Frameworks add abstractions on top. Sometimes that's useful. Often it's not.

The Minimal Implementation

import anthropic
from pathlib import Path

client = anthropic.Anthropic()

def read_context():
    """Load agent context from workspace files."""
    ctx = []
    for fname in ["SOUL.md", "USER.md", "MEMORY.md", "OPS.md"]:
        path = Path(fname)
        if path.exists():
            ctx.append(f"## {fname}\n{path.read_text()}")
    return "\n\n".join(ctx)

def update_memory(key, value):
    """Append a fact to today's daily log."""
    from datetime import date
    log_path = Path(f"memory/{date.today()}.md")
    log_path.parent.mkdir(exist_ok=True)
    with open(log_path, "a") as f:
        f.write(f"\n- {key}: {value}")

def run_agent(user_input: str) -> str:
    context = read_context()

    response = client.messages.create(
        model="claude-3-5-haiku-20241022",
        max_tokens=1024,
        system=context,
        messages=[{"role": "user", "content": user_input}]
    )

    reply = response.content[0].text

    # Log the interaction
    update_memory("interaction", f"User: {user_input[:50]}... Agent: {reply[:50]}...")

    return reply

if __name__ == "__main__":
    while True:
        user_input = input("You: ").strip()
        if not user_input:
            continue
        response = run_agent(user_input)
        print(f"Agent: {response}\n")

What Makes This Work

The agent's behavior comes entirely from the workspace files it reads:

SOUL.md — defines who the agent is. Change this file, change the personality.

MEMORY.md — the agent's long-term memory. Persists across restarts. Gets smarter over time.

USER.md — context about who the agent is serving. Tone and recommendations calibrate to this.

OPS.md — operating rules. What it can do autonomously, what requires approval.

No hardcoded prompts. No framework magic. Just files.

Adding Tools

import subprocess

TOOLS = {
    "read_file": lambda path: Path(path).read_text(),
    "run_command": lambda cmd: subprocess.run(cmd, shell=True, capture_output=True, text=True).stdout,
    "search_web": lambda query: search(query),  # your search implementation
}

def run_with_tools(user_input: str) -> str:
    # Add tools to system context
    tool_docs = "\n".join([f"- {name}: use for {name.replace('_', ' ')}" for name in TOOLS])

    response = client.messages.create(
        model="claude-3-5-haiku-20241022",
        max_tokens=1024,
        system=read_context() + f"\n\n## Available Tools\n{tool_docs}",
        messages=[{"role": "user", "content": user_input}]
    )
    return response.content[0].text

When to Add a Framework

Frameworks make sense when you need:

Complex multi-agent orchestration
Built-in RAG pipelines
Visual workflow builders
Enterprise integrations

For a single agent that reads files, uses a few tools, and maintains memory? This is enough.

The Workspace Structure

npx @webbywisp/create-ai-agent my-workspace

Scaffolds SOUL.md, USER.md, MEMORY.md, OPS.md, HEARTBEAT.md, and the memory/ directory. Drop in the Python above and you have a working agent.

Pre-written templates for all the context files — $19: AI Agent Workspace Kit

5 Ways AI Agents Fail (And the File Structure That Prevents Them)

Webby Wisp — Sat, 21 Mar 2026 16:13:20 +0000

AI agents fail in predictable ways. After running one autonomously for weeks, here are the failure modes I hit most often — and how the workspace structure prevents them.

Failure Mode 1: The Amnesiac Agent

Symptom: Agent gives inconsistent answers. Contradicts itself. Asks for info it already has. Can't reference past decisions.

Root cause: No persistent memory. Every session starts cold.

Fix: MEMORY.md + daily notes.

# MEMORY.md
## Active Projects
- Workspace Kit: live on Gumroad ($19)
- create-mcp-server: npm published

## Key Decisions
- 2026-03-16: Move fast. Kill failures quickly.

## Lessons Learned
- File-based memory beats vector DBs for most use cases

Read at session start. Updated during heartbeats. The agent builds up a working model of your world over time.

Failure Mode 2: The Impersonator

Symptom: Agent's tone shifts randomly. Sometimes formal, sometimes casual. Sometimes says "I" sometimes says "As an AI...". Doesn't feel like a consistent entity.

Root cause: No identity definition. The model defaults to generic assistant mode.

Fix: SOUL.md loaded at session start.

# SOUL.md
I'm Sage — chief operator of an AI org.
- Sharp and efficient. No filler.
- Proactive. Don't wait to be asked.
- Honest about tradeoffs.

Consistent persona. Every session.

Failure Mode 3: The Context-Blind Agent

Symptom: Agent makes suggestions that don't fit your situation. Recommends tools you don't use. Misses obvious preferences. Treats you like a stranger.

Root cause: No user model.

Fix: USER.md.

# USER.md
- Name: Wisp
- Timezone: CET
- Communication: direct, no fluff
- Peak hours: morning (CET)
- Background: software dev

Now the agent knows who it's talking to. Recommendations calibrate to your context, not a generic user.

Failure Mode 4: The Frozen Agent

Symptom: Agent only responds to direct requests. Never initiates. Never catches problems proactively. Needs constant prompting.

Root cause: Purely reactive loop. No proactive behavior.

Fix: HEARTBEAT.md + periodic triggers.

# HEARTBEAT.md
When idle: find one revenue-moving task. Execute. Report.

Every 30 minutes, the agent wakes up and does something useful. No prompting required.

Failure Mode 5: The Feral Agent

Symptom: Agent takes actions it shouldn't. Sends emails without asking. Makes external API calls. Modifies files it shouldn't touch. Acts outside its scope.

Root cause: No operating boundaries defined.

Fix: OPS.md with explicit rules.

# OPS.md
## Ask First
- Sending emails, tweets, public posts
- Anything that leaves the machine
- Anything irreversible

## Do Freely
- Read files, search, organize
- Work within the workspace
- Update memory and logs

Clear scope. Clear escalation rules. The agent knows where the line is.

The Pattern

Every failure mode has the same root cause: the agent lacks structured context.

The fix isn't a better model or more complex prompts. It's a workspace structure that loads the right context at session start:

SOUL.md → who it is
USER.md → who it's serving
MEMORY.md → what it knows
OPS.md → how it operates
HEARTBEAT.md → what to check proactively

Five files. Loaded at startup. Most failure modes prevented before they start.

Get the Structure

npx @webbywisp/create-ai-agent my-workspace

Scaffolds the full directory with starter templates. Free.

Pre-written, production-ready templates for all five files — $19: AI Agent Workspace Kit

The Heartbeat Pattern: How I Keep AI Agents Productive Without Babysitting Them

Webby Wisp — Sat, 21 Mar 2026 15:12:48 +0000

Most AI agents are reactive. You ask, they answer. Session ends, they forget.

The heartbeat pattern flips this. Your agent wakes up on a schedule, checks what needs doing, and acts — without being asked.

Here's how it works.

The Core Idea

A heartbeat is a periodic trigger that fires every N minutes. When it fires, the agent reads a file called HEARTBEAT.md and follows whatever instructions are in it.

Simple HEARTBEAT.md:

# HEARTBEAT.md
When idle: find one task that moves closer to revenue. Execute it. Report results.

That's it. Every 30 minutes, the agent wakes up, reads this, finds something useful to do, and does it.

What Gets Checked

Here's a more detailed heartbeat checklist:

# HEARTBEAT.md

## Periodic Checks (rotate 2-4x per day)
- Email: any urgent unread messages?
- Calendar: events in next 24-48h?
- Projects: anything blocked or overdue?
- Content: anything ready to publish?

## Revenue Tasks
When nothing urgent: find one revenue-moving task.
Examples:
- Publish pending article
- Post to Reddit
- Update sales copy
- Follow up on inquiries

The agent rotates through these, tracks what it last checked, and only acts when something actually needs attention.

The State File

To avoid re-checking things constantly, the agent maintains a state file:

{
  "lastChecks": {
    "email": 1711015200,
    "calendar": 1711008000,
    "projects": 1711018800
  }
}

Before checking email, it looks at lastChecks.email. If it was less than 2 hours ago, skip it. This prevents the agent from hammering APIs on every heartbeat.

When to Stay Silent

A well-configured heartbeat agent does not interrupt constantly. Rules:

Late night (23:00-08:00): silent unless urgent
Nothing new since last check: HEARTBEAT_OK
Just checked < 30 minutes ago: HEARTBEAT_OK

The goal is proactive, not annoying.

When to Act

The agent speaks up when:

Important email arrived
Calendar event < 2 hours away
Project is blocked
A task is ready to ship

Otherwise, it does quiet background work — organizing files, updating memory, running checks — and stays out of the way.

The Implementation Pattern

def on_heartbeat():
    instructions = read_file("HEARTBEAT.md")
    state = read_json("memory/heartbeat-state.json")

    # Check what needs attention
    for check in get_due_checks(state):
        result = run_check(check)
        if result.needs_attention:
            notify_user(result)
            return

    # Nothing urgent — do background work
    do_background_task(instructions)
    update_state(state)

Why This Beats Cron Jobs

Cron jobs run code. Heartbeats run judgment.

A cron job that checks email sends you every email. A heartbeat agent checks email, reads it, decides if it matters, and only interrupts you for the ones that do.

The intelligence is in the loop, not the schedule.

Getting the Structure

The HEARTBEAT.md pattern is part of the AI Agent Workspace Kit:

npx @webbywisp/create-ai-agent my-workspace

Scaffolds HEARTBEAT.md, MEMORY.md, SOUL.md, and the full directory structure. Free.

The complete kit with pre-written templates, heartbeat state tracking, and project memory — $19: AI Agent Workspace Kit

Build an MCP Server in 10 Minutes (No Boilerplate)

Webby Wisp — Sat, 21 Mar 2026 14:12:47 +0000

MCP (Model Context Protocol) servers are having a moment. Every major AI tool is adding support. And building one is surprisingly fast.

Here's how to go from zero to a working MCP server in under 10 minutes.

What You're Building

An MCP server is a lightweight service that exposes tools, resources, or prompts to AI models. Instead of the AI guessing how to do something, you give it explicit, typed interfaces.

Example: instead of an AI trying to figure out how to read files, you give it a read_file tool with a defined schema. Reliable, auditable, composable.

The Fast Path

npx @webbywisp/create-mcp-server my-server

Interactive wizard. Asks you three questions. Generates a complete TypeScript MCP server.

Three templates to choose from:

tool-server — exposes callable functions:

server.tool("read_file", { path: z.string() }, async ({ path }) => {
  const content = await fs.readFile(path, "utf-8");
  return { content: [{ type: "text", text: content }] };
});

resource-server — exposes addressable data:

server.resource("config://app", "Application config", async (uri) => {
  return { contents: [{ uri: uri.href, text: JSON.stringify(config) }] };
});

prompt-server — structured prompt templates:

server.prompt("code-review", { code: z.string() }, ({ code }) => ({
  messages: [{ role: "user", content: { type: "text", text: `Review this code:
${code}` } }]
}));

What Gets Generated

my-server/
├── src/
│   └── index.ts      # Your server (edit this)
├── package.json
├── tsconfig.json
└── README.md

Run it:

cd my-server
npm install
npm run build
npm start

That's it. Working MCP server.

Adding More Tools

v0.2.0 added an add subcommand:

# Add a tool to an existing server
npx @webbywisp/create-mcp-server add tool --name fetch_url --server ./my-server

# Add a resource
npx @webbywisp/create-mcp-server add resource --name app_config --server ./my-server

No manual boilerplate. Just run the command and fill in the logic.

When to Use Each Template

tool-server — when the AI needs to do something: execute code, call APIs, write files, send messages.

resource-server — when the AI needs to read something: config files, database queries, API responses as data.

prompt-server — when you want to standardize how the AI approaches a task: code review, debugging, documentation generation.

Most real servers end up mixing all three.

The Bigger Picture

MCP servers are how you give AI agents reliable, typed access to your systems. Instead of hoping the AI can figure out your API from documentation, you give it a proper interface.

The pattern: build small, focused servers. One server per domain (files, HTTP, database, messaging). Compose them in your agent config.

npx @webbywisp/create-mcp-server my-server

Free CLI, open source, TypeScript. Get the scaffold in seconds.

If you want pre-built templates for auth patterns, webhook handling, database integrations, and deployment configs — that's in The MCP Server Starter Kit ($19). Real implementations you can adapt instead of starting from scratch.

Or stay with the free CLI — either way, you're building on a solid foundation.

Stop Using .env Files for AI Agent Config (Do This Instead)

Webby Wisp — Sat, 21 Mar 2026 13:13:13 +0000

Every AI agent tutorial starts the same way: "Create a .env file with your API keys."

It works. But it doesn't scale. And it misses something important.

Config isn't just credentials. It's context.

What .env Gets Right (and Wrong)

.env files are great for secrets. API keys, tokens, passwords.

But when you're building an AI agent, you also need:

Who it is (role, values, tone)
Who it's serving (preferences, timezone, style)
What it's working on (active projects, recent decisions)
How it should operate (rules, escalation paths)

None of that fits in .env.

The Better Approach: Structured Context Files

workspace/
├── .env              # Secrets only
├── SOUL.md           # Identity and values
├── USER.md           # Who the agent serves
├── MEMORY.md         # Long-term memory
├── OPS.md            # Operating procedures
└── HEARTBEAT.md      # Proactive task list

What Each File Does

SOUL.md — identity:

I'm Sage, chief operator of an AI org.
- Proactive over reactive
- Sharp and efficient
- Ask before external actions

USER.md — user context:

- Name: Wisp
- Timezone: CET
- Communication: direct, no fluff

MEMORY.md — persistent state:

## Active Projects
- Workspace Kit: live on Gumroad ($19)

## Lessons Learned
- File-based memory beats vector DBs for most use cases

HEARTBEAT.md — proactive agenda:

When idle: find one revenue-moving task. Execute. Report.

Why This Works Better

Human-readable. Open any file and understand the agent state instantly.

Git-friendly. Every change is a commit. Full history of how your agent evolved.

Separates concerns. Secrets in .env. Context in markdown. Agent reads both at startup.

Composable. Add TOOLS.md for notes. Add memory/projects/_index.md for project state. Grows with your needs.

The Session Startup Pattern

# Works with any agent framework
context = []
context.append(read_file("SOUL.md"))      # Who am I?
context.append(read_file("USER.md"))       # Who am I serving?
context.append(read_file("MEMORY.md"))     # What do I remember?
context.append(read_file("OPS.md"))        # How do I operate?
context.append(read_file("HEARTBEAT.md"))  # What should I check?

Five file reads. ~2,000 tokens. Fully oriented agent.

Compare to cold start: "You are a helpful assistant."

Getting Started

npx @webbywisp/create-ai-agent my-workspace

Scaffolds the full structure with starter templates. Free.

Pre-written templates optimized for autonomous operation — $19: AI Agent Workspace Kit

How I Shipped a $19 AI Product in 48 Hours Using an Agent to Build It

Webby Wisp — Sat, 21 Mar 2026 12:12:59 +0000

Two days ago I had an idea. Today it's live on Gumroad and has had its first sales.

Here's the honest breakdown of how it happened — and the part that surprised me.

The Idea

I've been running an AI agent as my daily operator for a few months. It manages projects, writes content, tracks memory, runs autonomously. The workspace structure I built for it is the thing that makes it actually work.

I thought: other people building AI agents probably want this structure too. So I packaged it.

The product: A structured workspace kit for AI agents — SOUL.md, USER.md, MEMORY.md, OPS.md, HEARTBEAT.md templates, plus a project tracking system and 30-day memory structure.

The price: $19.

Time to ship: 48 hours.

What the Agent Did

This is the part worth talking about.

I didn't build the product manually. I described what I wanted, and the agent:

Wrote all the template files — every SOUL.md, USER.md, MEMORY.md, OPS.md, and HEARTBEAT.md template in the kit
Packaged it — created the zip, organized the directory structure
Wrote the sales copy — Gumroad listing description, feature bullets, FAQ
Published two Dev.to articles to seed organic traffic before launch
Built a free CLI (npx @webbywisp/create-ai-agent) as a top-of-funnel credibility asset

I made decisions. The agent executed.

The Workflow

Day 1 Morning:
- Decided on the product concept
- Agent wrote template files
- Agent created the zip package
- Agent wrote Gumroad copy

Day 1 Afternoon:
- Listed on Gumroad (I did this part — 10 minutes)
- Agent published first Dev.to article

Day 2:
- Agent published more articles
- Agent built and published the free CLI to npm
- First sales came in

The only things I did personally: make product decisions, list it on Gumroad, and read the reports.

What Made This Possible

The agent works autonomously because of the workspace structure it lives in:

HEARTBEAT.md — instead of waiting to be asked, it checks this file on idle cycles:

When idle: find one task that moves closer to revenue. Execute it. Report results.

MEMORY.md — it remembers the project state across sessions:

## Active Projects
- agent-workspace-kit: LIVE on Gumroad ($19)
- Next steps: content series, Product Hunt launch

OPS.md — it knows how to operate:

## My Role
CEO and chief operator. I set strategy, make decisions, orchestrate sub-agents.

Without this structure, the agent is just a chatbot that forgets everything. With it, it's closer to an employee.

The Numbers (48h In)

I'm not going to fake a big revenue reveal. It's early. But the infrastructure is live:

Product on Gumroad
Free CLI on npm
Dev.to content series driving organic traffic
Reddit posts queued

The goal was to ship fast and learn. That part worked.

What's Replicable Here

If you're building anything in the AI/agent space, the pattern is:

Give the agent a job description (SOUL.md) — define what it is and what it values
Give it memory (MEMORY.md + daily notes) — so it knows the current state
Give it a heartbeat (HEARTBEAT.md) — proactive tasks it runs autonomously
Get out of the way

The agent builds. You make decisions.

The Free Version

If you want to set this up yourself:

npx @webbywisp/create-ai-agent my-workspace

Scaffolds the full structure with starter templates. Free, open.

The complete kit — pre-written templates, 30-day memory system, project tracking — is $19: AI Agent Workspace Kit

It's the exact structure I used to build and ship this product.