Memory Architecture — Deep Dive
This page describes Clawpy memory as a system architecture: layered storage, governed retrieval, and continuous refinement loops.
It is intentionally rebuild-safe. Internal implementations may evolve, but these behaviors define the platform contract.
Architectural Model
Clawpy memory operates through three cooperating planes:
- Storage plane: session state, structured events, semantic context, and canonical facts
- Retrieval plane: ranking, filtering, and injection of relevant context into active execution
- Learning plane: feedback loops that improve future recall quality and reduce repeated errors
Why this matters: reliable autonomy requires memory that is both expressive and controllable.
Evidence in code
Storage Plane
The storage plane is layered so each memory type has a clear role:
- Fast local context for active turns
- Structured event history for audit and analytics
- Semantic representations for relevance-based recall
- Canonical knowledge for high-confidence project truths
Why this matters: mixing all memory types into one bucket degrades retrieval precision and governance.
Evidence in code
Retrieval Plane
Retrieval combines multiple sources and applies prioritization before context injection.
Core behaviors:
- Relevant context is ranked higher than merely recent context when appropriate
- Canonical facts can anchor retrieval for policy-critical decisions
- Context is bounded to avoid prompt pollution and preserve execution focus
Why this matters: good recall is selective and policy-aware, not maximal.
Evidence in code
Learning Plane
Memory quality improves over time through operational feedback:
- Runtime outcomes generate improvement candidates
- Introspection captures repeat patterns and failure signatures
- Adaptation mechanisms promote validated improvements
Why this matters: memory systems should learn from execution, not only store execution.
Evidence in code
Governance and Safety
Memory is part of the control plane, so safety and governance apply to recall behavior as well as tool execution.
- Operator policy boundaries constrain risky behavior
- Validation and budget controls regulate continuation
- Security layers reduce unsafe context propagation
Why this matters: unsafe memory retrieval can degrade decisions even when tools are sandboxed.
Evidence in code
Practical Reading Order
For implementation and operations teams: