---
title: "Memory Compiler — Lesson Signal Format & Built-in Memory Distinction"
aliases: [lesson-signal, memory-compiler-lesson, flush-lesson-format]
tags: [concepts, claude-code, memory-compiler, self-improvement]
created: 2026-05-06
updated: 2026-05-06
sources: [daily/2026-05-06.md]
---

# Memory Compiler — Lesson Signal Format & Built-in Memory Distinction

## Key Takeaways

- Claude Code's built-in auto-memory folder (`~/.claude/projects/-Users-.../memory/`) is **empty and unused** — the real self-improvement loop runs through `~/.claude/memory-compiler/` hooks.
- To guarantee a lesson is captured by the flush-LLM, explicitly write `Lesson: <rule> — Reason: <cause>` in the final reply of the session.
- Skills with the same short name (`code-reviewer`) exist in multiple plugins — always use the **fully-qualified name (FQN)** to avoid silent fallback to the wrong skill.

## Details

### Two Memory Systems — Only One Active

| System | Path | Status |
|--------|------|--------|
| Claude Code built-in auto-memory | `~/.claude/projects/-Users-ai-leed/memory/` | Empty — not used |
| Memory Compiler pipeline | `~/.claude/memory-compiler/` hooks | **Active** |

The built-in memory folder is created automatically by Claude Code but Vadym's self-improvement loop does **not** use it. All lesson capture flows through:

1. `hooks/session-start.py` — injects `wiki/_master-index.md` at session start
2. `scripts/flush.py` — PreCompact / SessionEnd hook; parses transcript via LLM and appends to `daily/YYYY-MM-DD.md`
3. `scripts/compile.py` — runs after 21:00; compiles daily logs into `wiki/concepts/`, `wiki/qa/`, etc.

### Lesson Signal Format

The flush-LLM scans the transcript for an explicit signal in the final Claude reply:

```
Lesson: <rule as imperative sentence> — Reason: <why this matters>
```

**Examples:**

```
Lesson: Never use deploy.sh for BAIC updates — Reason: it targets first-time setup, has the wrong service name, and uses interactive prompts.
Lesson: Always use FQN for skills with duplicate short names — Reason: three plugins expose "code-reviewer"; short name resolves ambiguously.
```

Without this signal, minor corrections may be missed if the conversation is long or the flush-LLM deprioritises them. With it, the lesson is guaranteed to appear in `daily/YYYY-MM-DD.md`.

> [!warning] Do NOT create ad-hoc lesson files
> Never create `tasks/lessons.md` or similar manual files. The pipeline handles persistence automatically — just emit the signal in the final reply.

### FQN Requirement for Duplicate Skill Names

The `code-reviewer` skill exists in (at least) three plugins:

| Plugin | FQN |
|--------|-----|
| `fullstack-dev-skills` | `fullstack-dev-skills:code-reviewer` |
| `pr-review-toolkit` | `pr-review-toolkit:review-pr` |
| `code-review` | `code-review:code-review` |

Rule: for **diff/file review** → `fullstack-dev-skills:code-reviewer`; for **whole-PR review** → `pr-review-toolkit:review-pr`.

If a listed FQN stops resolving after a plugin update — update `CLAUDE.md`, do not silently fall back to a short name.

## Related

- [[wiki/concepts/memory-compiler-mac-migration]] — migrating the pipeline between Mac users
- [[wiki/concepts/claude-code-schedule-skill-account-type]] — other Claude Code pipeline caveats
