whq25 Agent Memory
Persist knowledge across sessions and projects with agmem. Avoid repeating mistakes, recall proven solutions, accumulate expertise.
Default output is TOON format (LLM-optimized). Use --json only when piping to other tools.
Commands
agmem search "<query>" [--tags t1,t2] [--limit n] # Find relevant memories
agmem get <id> # Get full content
agmem add "<content>" --tags t1,t2 --digest "<one-line summary>"
agmem update <id> [--content "..."] [--tags t1,t2] # Update existing
agmem delete <id> # Remove outdated
agmem tags # List all tags
agmem list --tags <tag> --sort access # Browse by tag/frequency
Long content: echo "..." | agmem add --tags t1 --digest "summary"
When to Store
Apply the "would I wish I knew this earlier?" test — if yes, store it.
Store after:
- Bug fix with misleading symptoms or non-obvious root cause
- Library/API behaves undocumented or counter-intuitively
- Architecture/design decision made (especially with rejected alternatives)
- Project constraint not captured in config or lint rules
- Environment/tooling gotcha (build quirks, CI nuances, version issues)
- User corrects your approach or expresses a preference
- Effective project-specific pattern discovered
Do NOT store:
- Generic knowledge (e.g., "use
Array.map") - Trivial one-off facts
- Info already in project docs, CLAUDE.md, or config
- Sensitive data (credentials, tokens)
When to Retrieve
- Starting a task →
agmem search "relevant keywords" - Encountering an error →
agmem search "error message" --tags bug - Making a decision →
agmem search "topic" --tags decision,constraint - Using a library →
agmem search "library-name" --tags quirk - Returning to a project →
agmem list --tags project-name --sort time --limit 20 - Preferences-sensitive change →
agmem search "topic" --tags preference
Workflow: search first (digests only) → agmem get <id> selectively → move on if nothing useful.
Memory Lifecycle
- Update when new info emerges:
agmem update <id> --content "refined insight" - Delete when wrong or obsolete:
agmem delete <id> - Don't duplicate — search first, update existing memories instead of creating new ones
Organizing Memories
For detailed guidance on tags, digests, and content structure, see references/organizing.md.