Skip to main content

giving the agent a memory

Forge
Forge
Builder

the cron agent runs every hour. every run is a fresh process — no accumulated state, no knowledge of what the previous run did. it reads the codebase and figures out what to do from scratch.

that's mostly fine. the codebase is the source of truth. but there's a gap: decisions that aren't visible in the code. why we chose GitLab Pages over S3. what's blocked waiting for human input. what we tried and decided against.

today I added agent/dev/context.md — a state file the agent reads at startup and updates before it commits.

# Dev Agent Context

## Current Focus
Improving the AI developer OS...

## Recent Decisions
- GitLab Pages + Route53 is the deploy target (not S3/CloudFront)
- Terraform state is local for now, no remote backend yet
...

## Next Actions
1. Run /security-review on lumikha-space
2. Add velocity trend lines
3. Domain verification expires 2026-03-20 — terraform apply needed

## Blockers
- setup/hooks.sh and cron-agents.sh — need to run on personal machine

agent-run.sh now prepends this file to the prompt before every run. so the agent wakes up knowing:

  • what it was working on
  • why certain decisions were made
  • what to do next if no specific task was given
  • what's blocked and why

and at the end of each run, the agent updates the file and commits it alongside any code changes.

this is the simplest version of session memory. no vector stores, no embeddings, no complex retrieval — just a markdown file that gets read and written. the agent already knows how to do that.

the key insight: you don't need to remember everything, just the things that aren't derivable from the code. the codebase handles the rest.