RALPH-MEMORY - Knowledge Management

Query and manage RALPH's persistent cross-session memory.

Commands

| Command | Description | |---------|-------------| | /ralph-memory | Show memory stats and recent insights | | /ralph-memory query "term" | Search memory for a term | | /ralph-memory insights | Show all insights | | /ralph-memory entities | Show all entities | | /ralph-memory add-insight "learning" | Add a manual insight | | /ralph-memory export | Export memory to file | | /ralph-memory cleanup | Clean old entries |

Triggers

/ralph-memory
"show memory"
"what have you learned"
"search memory"

Memory Structure

RALPH stores knowledge in three JSON files:

.ralph/memory/
├── entities.json       # Files, functions, classes, patterns
├── relationships.json  # How entities relate to each other
└── insights.json       # Learnings and gotchas

Entities

Things RALPH knows about:

{
  "type": "file",
  "name": "src/types/user.ts",
  "properties": {
    "exports": ["User", "CreateUserInput"],
    "imports": ["zod"],
    "lastModified": "2026-01-25T10:00:00Z"
  }
}

Entity Types:

file - Source files and their contents
function - Functions and their signatures
class - Classes and their methods
pattern - Architectural patterns used
config - Configuration files
test - Test files and coverage

Relationships

How entities connect:

{
  "fromId": "src/types/user.ts",
  "toId": "src/services/user.service.ts",
  "type": "imports",
  "properties": {
    "symbols": ["User", "CreateUserInput"]
  }
}

Relationship Types:

imports - File imports another
exports - File exports symbols
uses - Function uses another
extends - Class extends another
implements - Class implements interface
tests - Test file tests source

Insights

Learnings from implementation:

{
  "context": "Implementing user authentication",
  "learning": "Always export new types from index.ts immediately",
  "tags": ["types", "exports", "patterns"],
  "occurrences": 3,
  "createdAt": "2026-01-25T10:00:00Z",
  "lastSeen": "2026-01-25T15:00:00Z"
}

Commands

Show Stats (Default)

╔════════════════════════════════════════════════════════════════╗
║                    RALPH Memory                                 ║
╚════════════════════════════════════════════════════════════════╝

Entities: 45 total
  - Files: 28
  - Functions: 12
  - Patterns: 5

Relationships: 67 total
  - imports: 34
  - exports: 22
  - tests: 11

Insights: 15 total
  - Unique tags: 8
  - Total occurrences: 42

Recent Insights:
  1. "Always export new types from index.ts" (×3)
  2. "Use Zod for runtime validation" (×2)
  3. "Prefer async/await over raw promises"

Top Tags: types, patterns, validation, testing, exports

Query Memory

/ralph-memory query "validation"

Output:

╔════════════════════════════════════════════════════════════════╗
║                    Memory Query: "validation"                   ║
╚════════════════════════════════════════════════════════════════╝

Entities (3 matches):
  [file] src/schemas/user.schema.ts
    Properties: uses Zod validation

  [pattern] runtime-validation
    Properties: Use Zod for all runtime checks

  [function] validateUserInput
    Properties: Located in src/services/user.service.ts

Relationships (2 matches):
  src/services/user.service.ts --uses--> src/schemas/user.schema.ts
  src/routes/user.routes.ts --uses--> validateUserInput

Insights (2 matches):
  - "Use Zod for runtime validation" (×2)
    Tags: validation, zod, patterns

  - "Validate inputs at API boundaries"
    Tags: validation, api, security

Show Insights

/ralph-memory insights

Output:

╔════════════════════════════════════════════════════════════════╗
║                    All Insights                                 ║
╚════════════════════════════════════════════════════════════════╝

By Frequency:
  1. "Always export new types from index.ts" (×5)
     Tags: types, exports, patterns
     Context: Multiple type definition tasks

  2. "Use Zod for runtime validation" (×3)
     Tags: validation, zod
     Context: User input validation

  3. "Prefer async/await over raw promises" (×2)
     Tags: async, patterns
     Context: Service layer implementation

By Tag:
  [patterns] 5 insights
  [types] 3 insights
  [validation] 3 insights
  [testing] 2 insights
  [security] 1 insight

Add Manual Insight

/ralph-memory add-insight "Database migrations should be run before tests"

Use AskUserQuestion:

? What was the context for this learning?
> Running integration tests

? Add tags (comma-separated):
> database, migrations, testing

Output:

✓ Insight added:
  "Database migrations should be run before tests"
  Context: Running integration tests
  Tags: database, migrations, testing

Export Memory

/ralph-memory export

Output:

╔════════════════════════════════════════════════════════════════╗
║                    Memory Export                                ║
╚════════════════════════════════════════════════════════════════╝

Exporting to: .ralph/memory-export-2026-01-25.json

Contents:
  - 45 entities
  - 67 relationships
  - 15 insights

✓ Export complete

This file can be:
  - Shared with team members
  - Imported into another project
  - Backed up for safety

Cleanup Memory

/ralph-memory cleanup

Output:

╔════════════════════════════════════════════════════════════════╗
║                    Memory Cleanup                               ║
╚════════════════════════════════════════════════════════════════╝

Analyzing memory entries older than 90 days...

Candidates for removal:
  - 5 entities (not referenced in 90+ days)
  - 8 relationships (orphaned)
  - 2 insights (single occurrence, old)

? Proceed with cleanup?
  ○ Yes, remove old entries
  ○ No, keep everything

Cleanup Results:
  ✓ Removed 5 entities
  ✓ Removed 8 relationships
  ✓ Kept 15 insights (frequently occurring)

Memory size reduced by 12%

Agent Memory Integration

Planner Agent

Queries memory before planning:

Loading memory context...

Relevant patterns found:
  - "Use service layer pattern for business logic"
  - "Separate types from implementation"

Past similar implementations:
  - US-005: User authentication (similar patterns)
  - US-012: Payment processing (related concepts)

Applying learnings to plan...

Coder Agent

Logs patterns during implementation:

Implementation complete.

Insights logged:
  + "This project uses barrel exports (index.ts)"
  + "Error handling uses custom AppError class"

Entities tracked:
  + [file] src/services/payment.service.ts
  + [function] processPayment
  + [function] validateCard

QA Reviewer

Logs recurring issues:

QA validation complete.

Recurring issues detected:
  ⚠ "Missing exports" - 3rd occurrence
    → Consider adding to pre-commit hook

Insight logged:
  + "Export statements should be added immediately after creating types"

Memory Query in Prompts

Agents include memory context in their prompts:

## Memory Context

### Relevant Insights
- "Always export new types from index.ts"
- "Use Zod for runtime validation"
- "Prefer async/await over raw promises"

### Related Entities
- src/types/user.ts (exports User, CreateUserInput)
- src/schemas/user.schema.ts (Zod validation)

### Past Patterns
- Service layer pattern used in src/services/
- Repository pattern for data access

Error Handling

| Error | Action | |-------|--------| | Memory not initialized | Run initMemory() automatically | | Query returns nothing | Suggest broader search terms | | Export fails | Check disk space, permissions | | Cleanup too aggressive | Offer to restore from backup |

Best Practices

LOG LIBERALLY - More insights = smarter future iterations
TAG CONSISTENTLY - Use standard tags for better queries
CLEAN REGULARLY - Remove stale entries every few weeks
EXPORT OFTEN - Backup valuable learnings
SHARE ACROSS PROJECTS - Import proven patterns