Ralph Memories

Persistent learning system for accumulated wisdom across sessions. Storage: .agent/memories.md .

When to Search Memories

Search BEFORE starting work when:

• Entering unfamiliar code area → ralph tools memory search "area-name"

• Encountering an error → ralph tools memory search -t fix "error message"

• Making architectural decisions → ralph tools memory search -t decision "topic"

• Something feels familiar → there might be a memory about it

Search strategies:

• Start broad, narrow with filters: search "api" → search -t pattern --tags api

• Check fixes first for errors: search -t fix "ECONNREFUSED"

• Review decisions before changing architecture: search -t decision

When to Create Memories

Create a memory when:

• You discover how this codebase does things (pattern)

• You make or learn why an architectural choice was made (decision)

• You solve a problem that might recur (fix)

• You learn project-specific knowledge others need (context)

Do NOT create memories for:

• Session-specific state (use tasks instead)

• Obvious/universal practices

• Temporary workarounds

Memory Types

Type Flag Use For

pattern -t pattern

"Uses barrel exports", "API routes use kebab-case"

decision -t decision

"Chose Postgres over SQLite for concurrent writes"

fix -t fix

"ECONNREFUSED on :5432 means run docker-compose up"

context -t context

"ralph-core is shared lib, ralph-cli is binary"

Discover Available Tags

Before searching or adding, check what tags already exist:

See all memories with their tags

ralph tools memory list

Extract unique tags (grep the file directly)

grep -o 'tags: [^|]*' .agent/memories.md | sort -u

Reuse existing tags for consistency. Common tag patterns:

• Component names: api , auth , database , cli

• Concerns: testing , performance , error-handling

• Tools: docker , postgres , redis

Quick Reference

Add memory (creates file if needed)

ralph tools memory add "content" -t pattern --tags tag1,tag2

Search (start broad, narrow with filters)

ralph tools memory search "query" ralph tools memory search -t fix "error message" ralph tools memory search --tags api,auth

List and show

ralph tools memory list ralph tools memory list -t fix --last 10 ralph tools memory show mem-1737372000-a1b2

Delete

ralph tools memory delete mem-1737372000-a1b2

Prime for context injection

ralph tools memory prime --budget 2000 ralph tools memory prime --tags api,auth # Prime specific tags only ralph tools memory prime --recent 7 # Only last 7 days

Best Practices

• Be specific: "Uses barrel exports in each module" not "Has good patterns"

• Include why: "Chose X because Y" not just "Uses X"

• One concept per memory: Split complex learnings

• Tag consistently: Reuse existing tags when possible

Examples

Pattern: discovered codebase convention

ralph tools memory add "All API handlers return Result<Json<T>, AppError>" -t pattern --tags api,error-handling

Decision: learned why something was chosen

ralph tools memory add "Chose JSONL over SQLite: simpler, git-friendly, append-only" -t decision --tags storage,architecture

Fix: solved a recurring problem

ralph tools memory add "cargo test hangs: kill orphan postgres from previous run" -t fix --tags testing,postgres

Context: project-specific knowledge

ralph tools memory add "The /legacy folder is deprecated, use /v2 endpoints" -t context --tags api,migration