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.

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

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

tags

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

--since (optional)

Filter entries created on or after this date. Accepts ISO 8601 date (

2026-04-01

7d

2w

/ralph-memory list --since 7d

Memory Entry Schema

Each entry in

.aiwg/ralph/memory.json

{
  "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)
  def456 — 4 entries (ESM migration, 2026-03-28)
  ghi789 — 1 entry  (Middleware fix, 2026-03-25)

Type 'yes' to confirm:

After clearing:

Al memory cleared. 8 entries deleted.

Memory file reset: .aiwg/ralph/memory.json

Loop-scoped clear:

Cleared 3 memory entries for loop abc123.

Remaining entries: 5 (in other loops)

Memory File Locations

.aiwg/ralph/memory.json

.aiwg/ralph-external/memory.json

.aiwg/ralph-external/loops/<id>.json

learnings

Error Handling

Memory file missing:

No Al memory found at .aiwg/ralph/memory.json.

Al has not accumulated any memory yet. Run a loop first:
  /ralph "your task" --completion "criteria"

Corrupted memory file:

Memory file is not valid JSON: .aiwg/ralph/memory.json

Options:
1. Delete and start fresh: rm .aiwg/ralph/memory.json
2. Inspect manually to repair

Missing --query for query subcommand:

Error: --query is required for the 'query' subcommand.

Usage:
  /ralph-memory query --query "auth mocks"
  /ralph-memory query --query "typescript" --since 7d

Examples

Example 1: List all memory entries

/ralph-memory list

Response: Table of all accumulated Al memory entries, newest first.

Example 2: List entries from the last week

/ralph-memory list --since 7d

Response: Only entries created in the last 7 days.

Example 3: Query for relevant memories before starting a task

/ralph-memory query --query "typescript esm"

Response: Top matching entries about TypeScript ESM, ranked by relevance.

Example 4: List memories from a specific loop

/ralph-memory list --loop-id abc123

Response: Only entries generated during loop

abc123

Example 5: Clear memories from a completed loop

/ralph-memory clear --loop-id abc123

Response: Prompts confirmation, then deletes the 3 entries for loop abc123.

Example 6: Full reset

/ralph-memory clear

Response: Prompts confirmation listing all entries by loop, then deletes everything.

Related

• /ralph

  — Loop that generates memory entries

• /ralph-external

  — External loop with its own memory layer

• /ralph-status

  — Check loop status and iteration history

• /ralph-reflect

  — Deeper reflection and memory promotion

References

• @$AIWG_ROOT/src/cli/handlers/ralph.ts — Al CLI handler
• @$AIWG_ROOT/tools/ralph-external/memory-manager.mjs — Memory storage and retrieval
• @$AIWG_ROOT/tools/ralph-external/lib/semantic-memory.mjs — Semantic memory layer
• @$AIWG_ROOT/tools/ralph-external/lib/memory-retrieval.mjs — Memory query logic
• @$AIWG_ROOT/tools/ralph-external/lib/memory-promotion.mjs — Cross-task memory promotion
• @$AIWG_ROOT/agentic/code/addons/ralph/README.md — Al documentation