/ralph-memory

namespace: aiwg
name: ralph-memory
platforms: [all]
description: Manage Al semantic memory entries — list, query, and clear lessons learned across loop iterations
commandHint:
  argumentHint: "<list|query|clear> [--loop-id <id>] [--query <text>] [--since <date>]"
  allowedTools: Read, Write
  model: haiku
  category: automation
  platforms: [claude-code, hermes, openclaw]
  modelRole: efficiency
  modelTier: economy

<!-- AIWG-SKILL-CALLOUT --> > **Skill access pattern (post-kernel-pivot, 2026.5+)** > > Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via: > > ```bash > aiwg discover "<capability>" > aiwg show skill <name> --body > ``` > > Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).

Al Memory

Inspect and manage the semantic memory that Al accumulates across loop iterations. Memory entries record lessons learned, failure patterns, and success patterns so that later iterations — and future loops on similar tasks — benefit from what earlier attempts discovered.

HITL authorization checkpoints

Before a removal confirmation below, apply [agent-loop authorization checkpoints](../../docs/hitl-authorization.md) and call `aiwg config authorization check --action-file "$ACTION_FILE" --target "$TARGET_REPO"`. Only `auto-authorized` with a signed receipt skips a workflow prompt. Keep existing prompts/refusals otherwise; platform prompts are never bypassed. Memory deletion without a complete rollback remains irreversible and requires review.

Natural Language Triggers

Users may say:

• "ralph memory"
• "ralph memories"
• "list ralph memory"
• "query ralph memory"
• "what has ralph learned"
• "show ralph lessons"
• "clear ralph memory"

Parameters

Subcommand (required)

One of `list`, `query`, or `clear`.

--loop-id (optional)

Scope the operation to a specific loop's memory. If omitted, operates on the global memory store (`.aiwg/ralph/memory.json`).

/ralph-memory list --loop-id abc123

--query (optional, used with `query` subcommand)

Text to search for in memory entries. Matches against `lesson`, `pattern`, `context`, and `tags` fields.

/ralph-memory query --query "auth mocks"

--since (optional)

Filter entries created on or after this date. Accepts ISO 8601 date (`2026-04-01`) or relative expressions (`7d`, `2w`).

/ralph-memory list --since 7d

Memory Entry Schema

Each entry in `.aiwg/ralph/memory.json` follows this structure:

{
  "id": "mem_a1b2c3",
  "loopId": "abc123",
  "iteration": 2,
  "createdAt": "2026-04-01T10:42:00Z",
  "type": "failure_pattern",
  "lesson": "Auth mocks must be initialized inside beforeEach, not at module scope",
  "context": "src/auth/auth.test.ts iteration 2 failure",
  "tags": ["auth", "mocks", "jest"],
  "confidence": 0.9
}

**Entry types**:

• `lesson_learned` — General insight extracted from an iteration
• `failure_pattern` — Recurring error pattern to avoid
• `success_pattern` — Approach that worked and should be repeated

Behavior

`list` Subcommand

1. Read the memory store (scoped to `--loop-id` if provided, otherwise global) 2. Apply `--since` filter if provided 3. Display a formatted table of all entries, sorted by `createdAt` descending

**Output**:

Al Memory — 8 entries

| ID       | Type            | Loop   | Iter | Lesson                                              | Date       |
|----------|-----------------|--------|------|-----------------------------------------------------|------------|
| mem_a1b2 | failure_pattern | abc123 | 2    | Auth mocks must be in beforeEach, not module scope  | 2026-04-01 |
| mem_c3d4 | lesson_learned  | abc123 | 3    | Use jest.resetAllMocks() in afterEach               | 2026-04-01 |
| mem_e5f6 | success_pattern | def456 | 5    | ESM imports require .js extension in TypeScript     | 2026-03-28 |
| mem_g7h8 | failure_pattern | def456 | 2    | ts-node does not support isolatedModules by default | 2026-03-28 |
...

Use /ralph-memory query --query "<text>" to search.

**If no entries exist**:

No memory entries found.

Al accumulates memory as it runs loops. Start a loop:
  /ralph "your task" --completion "criteria"

`query` Subcommand

1. Read all memory entries (filtered by `--loop-id` and `--since` if provided) 2. Score each entry against the `--query` text using substring and tag matching 3. Return the top matches, ranked by relevance score descending

**Output**:

Al Memory — query: "auth mocks"

3 matching entries (ranked by relevance):

1. [mem_a1b2] failure_pattern — confidence 0.90
   Lesson: Auth mocks must be initialized inside beforeEach, not at module scope
   Context: src/auth/auth.test.ts iteration 2
   Tags: auth, mocks, jest
   Loop: abc123, Iter: 2, Date: 2026-04-01

2. [mem_c3d4] lesson_learned — confidence 0.80
   Lesson: Use jest.resetAllMocks() in afterEach to prevent mock state leakage
   Context: src/auth/auth.test.ts iteration 3
   Tags: auth, jest, cleanup
   Loop: abc123, Iter: 3, Date: 2026-04-01

3. [mem_x9y0] failure_pattern — confidence 0.60
   Lesson: Passport mock must stub req.user before middleware chain
   Context: src/auth/middleware.test.ts
   Tags: auth, passport, mocks
   Loop: ghi789, Iter: 1, Date: 2026-03-25

**No matches**:

No memory entries match "auth mocks".

Try broader terms or list all entries:
  /ralph-memory list

`clear` Subcommand

1. If `--loop-id` is provided, delete only entries belonging to that loop 2. Otherwise, prepare to clear the entire memory store 3. Show a confirmation prompt before deleting

**Confirmation prompt**:

This will permanently delete 8 memory entries.

Entries by loop:
  abc123 — 3 entries (Fix auth tests, 2026-04-01)