--- title: "Memories & Tasks" description: "Ralph uses two complementary systems for persistent state: memories for cross-session learning, and tasks for runtime work tracking." type: skill canonical_url: https://claudary.paisolsolutions.com/skills/memories-and-tasks source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T11:30:56.801Z license: CC-BY-4.0 attribution: "Memories & Tasks — Claudary (https://claudary.paisolsolutions.com/skills/memories-and-tasks)" --- # Memories & Tasks Ralph uses two complementary systems for persistent state: memories for cross-session learning, and tasks for runtime work tracking. ## Overview # Memories & Tasks Ralph uses two complementary systems for persistent state: memories for cross-session learning, and tasks for runtime work tracking. ## Overview | System | Storage | Purpose | |--------|---------|---------| | **Memories** | `.ralph/agent/memories.md` | Accumulated wisdom across sessions | | **Tasks** | `.ralph/agent/tasks.jsonl` | Runtime work items | Both are enabled by default and work together to replace the legacy scratchpad. ## Memories Memories persist learning across sessions. They capture patterns, decisions, fixes, and context that Ralph should remember. ### Memory Types | Type | Use For | |------|---------| | `pattern` | Codebase conventions discovered | | `decision` | Architectural choices and rationale | | `fix` | Solutions to recurring problems | | `context` | Project-specific knowledge | ### Creating Memories ```bash # Pattern: discovered convention ralph tools memory add "All API handlers return Result, AppError>" \\ -t pattern --tags api,error-handling # Decision: architectural choice ralph tools memory add "Chose JSONL over SQLite: simpler, git-friendly" \\ -t decision --tags storage,architecture # Fix: recurring problem solution ralph tools memory add "cargo test hangs: kill orphan postgres" \\ -t fix --tags testing,postgres # Context: project knowledge ralph tools memory add "The /legacy folder is deprecated, use /v2" \\ -t context --tags api,migration ``` ### Searching Memories ```bash # Broad search ralph tools memory search "api" # Filter by type ralph tools memory search -t fix "error" # Filter by tags ralph tools memory search --tags api,auth # List all memories ralph tools memory list # List recent fixes ralph tools memory list -t fix --last 10 ``` ### Memory Injection Memories are automatically injected at the start of each iteration: ```yaml memories: enabled: true inject: auto # auto, manual, or none budget: 2000 # Max tokens to inject filter: types: [] # Filter by type (empty = all) tags: [] # Filter by tags (empty = all) recent: 0 # Days limit (0 = no limit) ``` ### Memory Best Practices 1. **Be specific** — "Uses barrel exports" not "Has good patterns" 2. **Include why** — "Chose X because Y" not just "Uses X" 3. **One concept per memory** — Split complex learnings 4. **Tag consistently** — Reuse existing tags ## Tasks Tasks track runtime work items during orchestration. ### Creating Tasks ```bash # Basic task ralph tools task add "Implement user authentication" # With priority (1-5, 1 = highest) ralph tools task add "Fix critical bug" -p 1 # With dependency ralph tools task add "Deploy to production" --blocked-by setup-infra ``` ### Managing Tasks ```bash # List all tasks ralph tools task list # List unblocked tasks only ralph tools task ready # Close a completed task ralph tools task close task-123 ``` ### Task Workflow 1. Ralph creates tasks from the prompt/plan 2. Tasks are worked in priority order 3. Dependencies are respected (blocked tasks wait) 4. Completed tasks are closed 5. Loop ends when no tasks remain ### Task Closure Rules Tasks must only be closed when: 1. Implementation is actually complete 2. Tests pass 3. Build succeeds (if applicable) 4. Evidence of completion exists ```bash # Good: Close with evidence cargo test # passes ralph tools task close task-123 # Bad: Close without verification ralph tools task close task-123 # No tests run! ``` ## Memories vs Tasks | Aspect | Memories | Tasks | |--------|----------|-------| | **Persistence** | Cross-session | Single session | | **Purpose** | Learning | Work tracking | | **When created** | When something is learned | When work is identified | | **When removed** | Rarely | When completed | ## Legacy Scratchpad Mode To disable memories and tasks (legacy mode): ```yaml memories: enabled: false tasks: enabled: false ``` In this mode, `.agent/scratchpad.md` is used for all state. In hat-based configurations, scratchpad is configurable per-hat. Each hat can set a custom scratchpad path, disable scratchpad entirely, or inherit the global `core.scratchpad` setting. See [Per-Hat Scratchpads](../guide/configuration.md#with-per-hat-scratchpads) for details. ## File Formats ### memories.md ```markdown # Memories ## Patterns ### mem-1737372000-a1b2 > All API handlers return Result, AppError> ## Decisions ### mem-1737372100-c3d4 > Chose JSONL over SQLite for simplicity ``` ### tasks.jsonl ```json {"id":"task-001","title":"Implement auth","priority":2,"status":"open","created":"2024-01-20T10:00:00Z"} {"id":"task-002","title":"Add tests","priority":3,"status":"open","blocked_by":["task-001"],"created":"2024-01-20T10:01:00Z"} ``` ## Integration with Hats Hats can use memories and tasks: ```yaml hats: builder: triggers: ["task.start"] instructions: | 1. Check memories for relevant patterns 2. Pick a task from `ralph tools task ready` 3. Implement the task 4. Record learnings as memories 5. Close the task with `ralph tools task close ` ``` ## Next Steps - Learn about [Backpressure](backpressure.md) for quality gates - See [Configuration](../guide/configuration.md) for full options - Explore the [Memory System](../advanced/memory-system.md) in depth --- Source: [Claudary](https://claudary.paisolsolutions.com/skills/memories-and-tasks) · https://claudary.paisolsolutions.com