# carusiphilip/agent-memory-architecture architecture

> Architecture diagram of the GitHub repository carusiphilip/agent-memory-architecture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/carusiphilip/agent-memory-architecture
- Repository: https://github.com/carusiphilip/agent-memory-architecture

## Overview

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: [`bin/amy_hook.py`](https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy_hook.py) (Hook dispatcher), [`.claude/commands/wrap.md`](https://github.com/carusiphilip/agent-memory-architecture/blob/main/.claude/commands/wrap.md) (Wrap command), [`bin/amy-search`](https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-search) (Memory search), [`bin/amy_lib.py`](https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy_lib.py) (Memory library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Agent protocol"]
  node_instructions["Memory protocol<br/>[CLAUDE.md]"]
  node_wrap["Wrap command<br/>[wrap.md]"]
end

subgraph group_mechanism["Hook mechanism"]
  node_hook_config["Hook definitions<br/>[settings.json]"]
  node_hook["Hook dispatcher<br/>[amy_hook.py]"]
  node_library["Memory library<br/>[amy_lib.py]"]
end

subgraph group_memory["Memory files"]
  node_events[("Event log")]
  node_decisions["Settled decisions"]
  node_open["Current state"]
  node_sessions["Session prose"]
  node_artifacts["Artifact files"]
end

subgraph group_cli["Memory commands"]
  node_search["Memory search"]
  node_decide["Decision promotion"]
  node_session_cli["Session commands"]
  node_events_cli["Event inspection"]
  node_open_cli["Open-state writer"]
  node_artifact_cli["Artifact registry"]
  node_spill_cli["Oversize spill"]
  node_backup_cli["Memory backup"]
end

node_agent(("Coding agent"))

node_agent -->|"reads protocol"| node_instructions
node_agent -->|"invokes wrap"| node_wrap
node_hook_config -->|"dispatches events"| node_hook
node_agent -->|"triggers hooks"| node_hook
node_hook -->|"uses helpers"| node_library
node_hook -->|"appends events"| node_events
node_hook -->|"updates sessions"| node_sessions
node_hook -->|"loads decisions"| node_decisions
node_hook -->|"loads state"| node_open
node_hook -->|"requests backup"| node_backup_cli
node_search -->|"searches history"| node_events
node_search -->|"searches prose"| node_sessions
node_events_cli -->|"reads log"| node_events
node_decide -->|"promotes facts"| node_decisions
node_session_cli -->|"manages sessions"| node_sessions
node_open_cli -->|"writes state"| node_open
node_artifact_cli -->|"registers files"| node_artifacts
node_library -->|"spills large values"| node_artifacts
node_spill_cli -->|"inspects spills"| node_artifacts
node_backup_cli -->|"backs up memory"| node_artifacts
node_wrap -.->|"guides promotion"| node_decide
node_wrap -.->|"guides prose log"| node_sessions
node_wrap -.->|"guides state update"| node_open_cli

click node_instructions "https://github.com/carusiphilip/agent-memory-architecture/blob/main/CLAUDE.md"
click node_wrap "https://github.com/carusiphilip/agent-memory-architecture/blob/main/.claude/commands/wrap.md"
click node_hook_config "https://github.com/carusiphilip/agent-memory-architecture/blob/main/.claude/settings.json"
click node_hook "https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy_hook.py"
click node_library "https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy_lib.py"
click node_search "https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-search"
click node_decide "https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-decide"
click node_session_cli "https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-session"
click node_events_cli "https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-events"
click node_open_cli "https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-open"
click node_artifact_cli "https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-artifact"
click node_spill_cli "https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-spill"
click node_backup_cli "https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-backup"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_instructions,node_wrap toneBlue
class node_hook_config,node_hook,node_library toneAmber
class node_events,node_decisions,node_open,node_sessions,node_artifacts toneMint
class node_search,node_decide,node_session_cli,node_events_cli,node_open_cli,node_artifact_cli,node_spill_cli,node_backup_cli toneRose
class node_agent toneIndigo
```

## Components

### Agent protocol

- [Memory protocol](https://github.com/carusiphilip/agent-memory-architecture/blob/main/CLAUDE.md): `CLAUDE.md`
- [Wrap command](https://github.com/carusiphilip/agent-memory-architecture/blob/main/.claude/commands/wrap.md): `.claude/commands/wrap.md`

### Hook mechanism

- [Hook definitions](https://github.com/carusiphilip/agent-memory-architecture/blob/main/.claude/settings.json): `.claude/settings.json`
- [Hook dispatcher](https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy_hook.py): `bin/amy_hook.py`
- [Memory library](https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy_lib.py): `bin/amy_lib.py`

### Memory files

- **Event log**
- **Settled decisions**
- **Current state**
- **Session prose**
- **Artifact files**

### Memory commands

- [Memory search](https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-search): `bin/amy-search`
- [Decision promotion](https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-decide): `bin/amy-decide`
- [Session commands](https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-session): `bin/amy-session`
- [Event inspection](https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-events): `bin/amy-events`
- [Open-state writer](https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-open): `bin/amy-open`
- [Artifact registry](https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-artifact): `bin/amy-artifact`
- [Oversize spill](https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-spill): `bin/amy-spill`
- [Memory backup](https://github.com/carusiphilip/agent-memory-architecture/blob/main/bin/amy-backup): `bin/amy-backup`

### Other components

- **Coding agent**

## Connections

- 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