Start here
Philosophy
Why persistent context works only when paired with surgical execution.
Agent Needle pairs two ideas that are useful only together: persistent context and surgical execution.
Persistent context
Coding sessions are often isolated. The next agent may not know why an architectural choice was made, which checks already failed, or what remains unfinished. Repository-backed memory carries the useful thread forward in plain Markdown.
The repository is a good home for that context because it is visible, reviewable, diffable, and travels with the code it describes.
Surgical execution
More context can create more confidence than the evidence deserves. Agent Needle counters that risk with strict execution discipline:
- State consequential assumptions.
- Prefer the smallest complete implementation.
- Read target code and its callers before editing.
- Preserve unrelated behavior and user changes.
- Verify outcomes rather than merely reporting activity.
Memory is not truth
Memory can be stale, incomplete, or wrong. Agent Needle requires agents to inspect the current system before consequential use. A remembered command is a lead to verify, not permission to run it blindly.
Why “Needle”
A needle is small, precise, and useful because it carries a thread. The metaphor captures both halves of the project: durable continuity and disciplined changes with minimal surface area.