Coding agents are good at using context. They are terrible at keeping it consistent.
Tools like GitHub Copilot Memory are doing great work on the individual side. Copilot remembers your preferences, your patterns, your stack. That's a real step forward for developer experience.
But there's a layer that built-in memory doesn't cover: shared, reviewable, version-controlled project context. The stuff that lives in your repo and works across every agent your team uses. Teams still hit the same walls:
- The "rules of the repo" live in chat threads and tribal knowledge
- A new agent or subagent starts without the constraints that matter
- The agent learns something once, then you can't review it like code
- Context drifts because nobody promotes stable decisions into a shared source of truth
This project is a small, boring fix. It doesn't replace built-in memory. It complements it. Built-in memory handles what the tool learns about you. This handles what every agent needs to know about your project. It makes that context explicit, reviewable, and portable.
Two markdown files. One committed, one gitignored. The agent reads both at the start of every session and updates the local one at the end.
AGENTS.mdis your project's source of truth. Committed and shared. Always in the agent's prompt..agents.local.mdis your personal scratchpad. Gitignored. It grows over time as the agent logs what it learns each session.
That's it. No plugins, no infrastructure, no background processes. The convention lives inside the files themselves, and the agent follows it.
your-repo/
├── AGENTS.md # Committed. Always loaded. Under 120 lines.
├── .agents.local.md # Gitignored. Personal scratchpad.
├── agent-context # CLI: init, validate, promote commands.
├── agent_docs/ # Deeper docs. Read only when needed.
│ ├── conventions.md
│ ├── architecture.md
│ └── gotchas.md
├── scripts/
│ └── init-agent-context.sh # Wrapper → calls agent-context init (for npx skills)
└── CLAUDE.md # Symlink → AGENTS.md (created by init)
./agent-context initThis creates AGENTS.md, .agents.local.md, symlinks, and adds gitignore entries. See setup docs for all install options.
| Doc | What's in it |
|---|---|
| Setup | All install options (Copilot, OpenClaw, manual, template, fork) |
| How It Works | Knowledge flow, session logging, promotion workflow |
| Architecture | File structure, AGENTS.md and .agents.local.md templates |
| Agent Compatibility | Supported agents, Claude Code auto memory, subagent context |
| Research | Instruction budgets, Vercel evals, context lifecycle |
| Security | What's committed vs gitignored, team considerations |
| FAQ | Common questions |
Agents can now observe during sessions and reflect at session end, automatically surfacing patterns worth promoting to AGENTS.md. Inspired by Mastra's Observational Memory, adapted for the file-based world — zero infrastructure, works with any agent.
Automatic memory consolidation inspired by claude-code's auto-dream system.
Daily logs are consolidated into topic files automatically when:
- ≥24 hours since last consolidation
- ≥5 sessions accumulated
- No other consolidation in progress
4-phase process: Orient → Gather → Consolidate → Prune
Compression: ~9:1 ratio (107 KB → 11.6 KB validated)
Structure: Daily logs (append-only) + topic files (curated) + index (200 lines max)
MIT