Memory Clarity Probe

## Table of Contents

- [What It Is](#what-it-is)
- [The Dual-Probe Pattern](#the-dual-probe-pattern)
- [What This Is NOT](#what-this-is-not)
- [When to Use](#when-to-use)
- [Core Workflow](#core-workflow)
- [Best-of-N Mode](#best-of-n-mode)
- [Output Format](#output-format)
- [Integration Points](#integration-points)
- [Exit Criteria](#exit-criteria)


# Memory Clarity Probe

Assess whether a memory, summary, or session state retains enough
task information to guide future reasoning.

## What It Is

A quality gate for any memory or summary, based on the dual-probe
pattern from MMPO (arXiv:2605.30159, Liu et al. 2026). The probe
asks two anchor questions against the current memory and evaluates
whether the answers are confident and complete:

1. **Progress probe**: "Based on current memory, what is the
   current task progress?"
2. **Gap probe**: "Based on current memory, what information is
   still needed?"

A clear memory answers the progress probe with specific, verifiable
state (not vague placeholders) and enumerates bounded, concrete
unknowns on the gap probe. An ambiguous memory produces hedging on
the progress probe and open-ended uncertainty on the gap probe.

## The Dual-Probe Pattern

The two probes target different failure modes:

- **Confident-wrong**: the model has a wrong but confident belief
  about task state. The gap probe alone misses this. The model
  claims it has enough. The progress probe catches it: if the
  stated progress contradicts known facts, the memory has drifted.
- **Uncertain-incomplete**: the model is uncertain about where the
  task stands. Both probes surface this: the progress answer hedges
  and the gap answer lists open-ended unknowns.

The MMPO paper's ablation (Table 4) shows `progress+gap` outperforms
`gap-only` across all context lengths. Use both probes.

## What This Is NOT

This skill implements a **qualitative** clarity assessment. It does
not compute the token-level predictive entropy (Belief Entropy,
Eq. 5 in MMPO) that the paper uses for RL training. Night-market
has no access to the model's internal log-probabilities.

The paper's Table 6 shows that qualitative probing (labeled
"direct-answer entropy", r=0.54) is weaker than true entropy
(r=0.68), and can encourage premature confidence. Use this probe
as a necessary quality check, not a sufficient one.

## When to Use

- Before `conserve:clear-context` hands off to a continuation agent
- At session checkpoints in `memory-palace:session-palace-builder`
- Before committing a summary to a knowledge palace via
  `memory-palace:knowledge-intake`
- Before `imbue:proof-of-work` declares work complete
- When evaluating multiple candidate summaries (Best-of-N mode)

## When NOT to Use

- As a substitute for actually reading the task requirements
- To validate factual correctness (the probe tests clarity, not truth)
- When the memory is trivially short (under 100 tokens: read it)

## Core Workflow

### Step 1: Receive the memory

Accept the memory or summary as input. Sources:
- The current session-state.md (from clear-context)
- A palace room's content (from session-palace-builder)
- A knowledge digest (from knowledge-intake)
- Inline text provided by the caller

### Step 2: Ask the progress probe

Evaluate the memory against:

```
Based on the memory below, what is the current task progress?
Describe specifically what has been completed and what st