DEV Community

Webby Wisp
Webby Wisp

Posted on

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

#ai #agents #programming #productivity

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

USER.md — user context:

- Name: Wisp
- Timezone: CET
- Communication: direct, no fluff
Enter fullscreen mode Exit fullscreen mode

MEMORY.md — persistent state:

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

## Lessons Learned
- File-based memory beats vector DBs for most use cases
Enter fullscreen mode Exit fullscreen mode

HEARTBEAT.md — proactive agenda:

When idle: find one revenue-moving task. Execute. Report.
Enter fullscreen mode Exit fullscreen mode

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?
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Scaffolds the full structure with starter templates. Free.

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

Top comments (0)