How carusiphilip/agent-memory-architecture works
Amy is a local, file-based memory system for a coding agent: deterministic hooks protect and record memory, while agent instructions describe best-effort review and promotion. The principal workflow is session start and memory loading, event capture during work, then session-end recording and later review/promotion. Search and artifact access provide retrieval without loading old history wholesale. The README documents additional CLI capabilities; sampled hook and library excerpts support the core recording and loading links, but not every CLI’s internal wiring.
Main entry points: amy_hook.py Hook dispatcher · wrap.md Wrap command · amy-search Memory search · amy_lib.py Memory library
Components 19
Agent protocol
- Memory protocol
CLAUDE.md - Wrap command
.claude/commands/wrap.md
Hook mechanism
- Hook definitions
.claude/settings.json - Hook dispatcher
bin/amy_hook.py - Memory library
bin/amy_lib.py
Memory files
- Event log
- Settled decisions
- Current state
- Session prose
- Artifact files
Memory commands
- Memory search
bin/amy-search - Decision promotion
bin/amy-decide - Session commands
bin/amy-session - Event inspection
bin/amy-events - Open-state writer
bin/amy-open - Artifact registry
bin/amy-artifact - Oversize spill
bin/amy-spill - Memory backup
bin/amy-backup
Other components
- Coding agent
Connections 23
- Coding agent → Memory protocol: reads protocol
- Coding agent → Wrap command: invokes wrap
- Hook definitions → Hook dispatcher: dispatches events
- Coding agent → Hook dispatcher: triggers hooks
- Hook dispatcher → Memory library: uses helpers
- Hook dispatcher → Event log: appends events
- Hook dispatcher → Session prose: updates sessions
- Hook dispatcher → Settled decisions: loads decisions
- Hook dispatcher → Current state: loads state
- Hook dispatcher → Memory backup: requests backup
- Memory search → Event log: searches history
- Memory search → Session prose: searches prose
- Event inspection → Event log: reads log
- Decision promotion → Settled decisions: promotes facts
- Session commands → Session prose: manages sessions
- Open-state writer → Current state: writes state
- Artifact registry → Artifact files: registers files
- Memory library → Artifact files: spills large values
- Oversize spill → Artifact files: inspects spills
- Memory backup → Artifact files: backs up memory
- Wrap command → Decision promotion: guides promotion
- Wrap command → Session prose: guides prose log
- Wrap command → Open-state writer: guides state update