# recall-echo v0.5 — Consume Command & Full Lifecycle Hooks

**Status**: IMPLEMENTED (pending build + deploy)
**Date**: 2026-02-26
**Author**: Echo + D (specced on call)

---

## Problem

recall-echo v0.4 manages two of three memory lifecycle events:
- PreCompact → `recall-echo checkpoint` (saves before context compression)
- SessionEnd → `recall-echo promote` (archives EPHEMERAL.md)

The third event — **session start** — is not managed by the tool. EPHEMERAL.md
consumption (reading last session's context and clearing the file) relies on
protocol instructions that the AI may or may not follow. This makes the memory
system unreliable.

### Root cause
Memory consumption is voluntary (instruction-based) instead of mechanical
(hook-based). The AI must "remember" to read and clear EPHEMERAL.md, which
defeats the purpose of a memory system.

### D's insight
> "It shouldn't be up to you. It's like how my brain works — I don't choose
> what I keep in long memory or short memory. We need to force you to read
> the ephemeral file and then clear it."

---

## Solution

### 1. New command: `recall-echo consume`

Reads EPHEMERAL.md, outputs content to stdout, and clears the file.

**Behavior:**
- If EPHEMERAL.md has content → output it wrapped in memory markers, clear file
- If EPHEMERAL.md is empty or missing → silent exit (exit code 0)
- Idempotent: safe to call multiple times, only first call with content outputs

**Output format:**
```
[MEMORY — Last Session Summary (auto-consumed from EPHEMERAL.md)]
<content of EPHEMERAL.md>
[END MEMORY — EPHEMERAL.md has been cleared. Use this context to orient yourself.]
```

**Why stdout:** Claude Code hooks capture stdout and inject it as context
for the AI. By outputting to stdout, the consumed memory automatically
becomes part of the session context without any additional wiring.

### 2. Updated `recall-echo init`

Now installs three hooks (was two):

| Hook Event   | Command                                        | Purpose                          |
|-------------|------------------------------------------------|----------------------------------|
| PreToolUse  | `recall-echo consume`                          | Consume EPHEMERAL.md on first use |
| PreCompact  | `recall-echo checkpoint --trigger precompact`  | Save before context compression  |
| SessionEnd  | `recall-echo promote`                          | Archive session summary          |

The init command:
- Detects existing consume hook (idempotent)
- Adds PreToolUse entry if missing
- Preserves all existing non-recall-echo hooks

### 3. Updated `recall-echo status`

Now reports on all three hooks:
```
Hooks:  PreToolUse ✓  PreCompact ✓  SessionEnd ✓
```

Warns if consume hook is missing:
```
⚠ PreToolUse hook missing — run recall-echo init
```

---

## Files Changed

| File        | Change                                                        |
|------------|---------------------------------------------------------------|
| `src/consume.rs` | NEW — consume command implementation + 5 tests          |
| `src/main.rs`    | Add `Consume` variant to CLI subcommands                |
| `src/init.rs`    | Add PreToolUse hook installation with `recall-echo consume` |
| `src/status.rs`  | Check and report on consume hook status                 |

---

## Test Coverage

### consume.rs (5 tests)
- `consumes_and_clears_ephemeral` — reads content, clears file
- `silent_on_empty_file` — no output, no error
- `silent_on_whitespace_only` — treats whitespace as empty
- `silent_on_missing_file` — graceful handling
- `idempotent_double_consume` — second call is no-op

### Existing tests (unchanged)
- promote.rs: 7 tests
- checkpoint.rs: tests
- archive.rs: 5 tests
- frontmatter.rs: 6 tests
- status.rs: 3 tests (updated to include consume hook in fixtures)

---

## Install Story (post v0.5)

```bash
cargo install recall-echo
recall-echo init
```

This gives you:
1. Three-layer memory system (MEMORY.md, EPHEMERAL.md, Archive)
2. Automatic consumption at session start (PreToolUse hook)
3. Automatic archiving on context compression (PreCompact hook)
4. Automatic promotion on session end (SessionEnd hook)
5. Protocol rules file loaded into every Claude Code session

No manual configuration. No bash scripts. It just works.

---

## Version Bump

v0.4.0 → v0.5.0

This is a minor version bump because:
- New public command (`consume`)
- Changed behavior of `init` (installs additional hook)
- No breaking changes to existing commands

---

## Deployment

Patches staged at `~/patches/recall-echo/src/`. Deploy commands in
Discord #need-permissions (2026-02-26).

After deploy:
- Delete `~/.claude/hooks/consume-ephemeral.sh` (superseded by native command)
- Run `recall-echo init` to add PreToolUse hook to settings.json
- Run `recall-echo status` to verify all three hooks are green
