I’ve been thinking a lot about why coming back to projects feels harder than it should.
Or why, when someone new joins a project, it feels like I have to spend an unreasonable amount of time just giving context.
Not because the code is bad.
Not because the stack is unfamiliar.
But because the context is gone.
You open a repo and immediately start asking the same questions:
What does this app actually do right now?
What’s broken?
What was I—or the last person—building?
Why was this decision made?
What keeps failing in production?
None of that lives in the code.
And none of it lives anywhere the app can explain itself.
So every time, we rebuild the mental model from scratch—or worse, we don’t, and we ship blind.
The real problem: apps/projects forget what happened
Most applications already have plenty of tooling:
- logs
- metrics
- error tracking
- tickets
- documentation (maybe)
But none of that is portable context when you clone the repo.
And sure, you probably have a README—which is about as effective as training a cat to fetch or sit.
If a new developer joins, or you return to the app after a few weeks, the system doesn’t explain itself. You’re left reading code, digging through logs, or reverse-engineering intent.
AI-powered IDEs like Windsurf and Cursor have the same problem. They’re excellent at reading and writing code—but they’re blind to runtime behavior, history, and intent.
They don’t know what’s been happening.
They don’t know what matters most.
They don’t know what’s already been tried.
Context matters — so give the app a “mini brain”
Instead of trying to build an AI that magically understands everything, I’ve been exploring something much simpler:
What if every app shipped with a small, living “brain” of context and intent?
Not raw logs.
Not dashboards.
But curated, human-readable memory.
Imagine an app that can tell you:
- what it’s for
- what’s been happening lately
- what keeps breaking
- what users are actually doing
- what’s been learned before (runbooks)
- what should be worked on next
All stored inside the repo, where humans and AI tools can read it.
That’s the idea.
Portable context, not surveillance
This isn’t about hoarding data or watching users.
The model is intentionally conservative:
- capture high-signal events (routes, errors, domain events)
- redact aggressively
- summarize frequently
- store insight, not noise
The app writes down what matters so nobody has to rediscover it later.
It’s not telemetry for dashboards—it’s memory for developers.
The “mini brain” files
The core of this approach is a small set of files that evolve over time:
AGENT_CONTEXT.md
A 60-second overview of what the app does and its current state.
OPEN_ISSUES.md
A ranked list of real problems derived from errors and usage—not guesswork.
RUNBOOK.md
“When this happens, here’s what we did last time.”
AGENT_PLAYBOOK.md
Guardrails that define what an agent can see, suggest, or automate.
Together, these files become:
- onboarding docs for new developers
- instant context for you in the future
- high-signal input for AI-powered IDEs
This is the app explaining itself.
Why this works with AI (and without it)
Here’s the key realization:
AI doesn’t need to learn everything.
It needs clean, current context.
When an IDE opens a repo that already contains:
- the app’s intent
- live issues grounded in reality
- known patterns and past fixes
…it becomes dramatically more useful.
You stop prompting from scratch.
You stop re-explaining the system.
You stop guessing what matters.
Even without any automation, that alone saves time.
This isn’t “AI takes over your app”
That framing is a trap.
The practical version looks like this:
- observe
- summarize
- recommend
- propose changes
- optionally automate small, safe tasks later
Think of it as self-updating developer notes, not autonomous coding.
Who this actually helps
- New developers ramp up faster
- Returning developers avoid context loss
- Solo builders keep momentum across projects
- AI IDEs get grounded, real-world input
- Future you doesn’t have to start over
What I’m building nex
To test this properly, I’m building a small demo app:
- Node.js + Express backend
- Vue.js frontend
- A simple domain (intake / submissions)
- A drop-in “agent core” package that:
- listens to sanitized app events
- summarizes what’s happening
- updates the app’s mini brain files
No hype. No overreach.
Just a tight feedback loop between runtime → memory → IDE.
If it works, every new app I build starts smarter than the last one.
And if nothing else, future me will thank me.