/beacon-memory-distill

name: beacon-memory-distill
description: Turn recorded agent sessions (Beacon traces from Claude Code, Cursor, Codex, OpenCode, and other harnesses) into reviewed, reusable project memory. Scores selected traces, reads the source trace behind each high-signal candidate, drafts a grounded lesson, and approves it only after the user confirms. Use when the user asks to "learn from", "remember", "save the lesson from", or "turn into memory" a recent session, fix, or debugging effort, or asks to review Beacon memory candidates.
license: MIT
compatibility: Requires the Beacon CLI (beacon) on PATH with endpoint capture installed. Scoring calls the configured Jev evaluator over the network (hosted TypeSafe by default) and needs TYPESAFE_API_KEY or BEACON_JEV_API_KEY; every other step is local.
metadata:
  author: asymptote-labs
  homepage: https://docs.beacon.sh/concepts/cross-harness-memory
  version: "0.1.0"

Beacon memory distill: traces to memory

Beacon captures what agents do in every supported harness. This skill runs the review loop that turns a few of those sessions into **approved project memory** that any later agent can recall, whichever harness it runs in:

1. Pick traces. 2. Score them with the evaluator (the one networked step, and only with consent), or, where evaluation is not allowed, skip scoring and read the traces yourself. 3. For each candidate, read the source trace and draft the lesson. 4. The user confirms, edits, or rejects each draft. 5. Approve with the reviewed text.

The evaluator returns probabilities only. It says a trace looks reusable; it does not say what the lesson is. **You write the lesson, from the trace, and the user approves it.** Never approve a candidate with its placeholder body ("no lesson text was extracted").

Commands that start from a trace (`evaluations run`, `candidates create`) file the memory under the repository the trace recorded, wherever you run them. Run every other command from inside the repository the memory is for, or pass `--project <path>`.

Step 1: preflight

beacon version
beacon endpoint traces status --json

• If `beacon` is missing, stop and point the user to

https://docs.beacon.sh/get-started/overview. Do not install it yourself.

• If `status` reports `"enabled": false`, there is no local history, and only the last day or

two of sessions are still in the runtime log. Suggest creating the history, which keeps sessions for 90 days and stays on this machine, and run it only if the user agrees: `beacon endpoint traces reindex`.

Step 2: pick traces

Use what the user named: a session, a date, a harness, or a topic. Otherwise list recent traces and propose a short set (up to 10) that look like finished work with a correction, a fix, or a non-obvious procedure.

beacon endpoint traces list --json --limit 20
beacon endpoint traces list --json --limit 20 -q "<topic terms>"
beacon endpoint traces search "<error text or file>" --json --limit 10

Prefer traces from this repository. Skip trivial sessions (a single question, an abandoned attempt) since they cost evaluator calls and yield nothing.

Reading the list:

• Only `session:` IDs are sessions. IDs starting `event:` are single events with no

session, almost always OTLP metric samples such as `claude_code.active_time.total`. They arrive every few seconds and sort to the top, so a short list can be all noise; raise `--limit` or use `--page` until you have sessions, and never select them. `evaluations run` skips them on its own when it selects by `--limit`, but never pass one to `--trace`.

• A session whose `updated_at` is within the last few minutes is still being written.

Leave it for next time: a lesson drafted from half a session is usually wrong about how it ended.

• A session's `repository` is where its memory will be filed. It is null for many

sessions, because not every event carries one, and then Beacon falls back to the current directory. Evaluate or create a candidate for such a session only with an explicit `--project <path>` you can justify from the paths in its commands.

Step 3: dry run, then ask

The dry run is local. It shows the traces selected and the estimated cost:

beacon memory evaluations run --dry-run --trace <trace-id>
beacon memory evaluations run --dry-run --limit 10 --harness <name> --since <rfc3339>

Before the real run, tell the user plainly and **wait for an explicit yes**:

• Each selected trace is sent, as a bounded and redacted projection, to the evaluator at

`BEACON_JEV_ENDPOINT` if that is set, otherwise to the hosted TypeSafe endpoint.

• It costs about the estimate the dry run printed.
• Nothing is approved or written into memory by this step.

Check for a key without printing it:

test -n "${TYPESAFE_API_KEY:-}${BEACON_JEV_API_KEY:-}" && echo "evaluator key present" || echo "no evaluator key"

With no key, stop and tell the user to export `TYPESAFE_API_KEY` (or point `BEACON_JEV_ENDPOINT` at their organization's compatible evaluator). Never ask them to paste a key into the chat, and never pass `--jev-api-key` on the command line. If the user or their organization does not allow external evaluation, or has no key and does not want one, skip Steps 3 and 4 and go to [Without an evaluator](#without-an-evaluator).

Step 4: score

Repeat the exact selection the user approved, without `--dry-run`:

beacon memory evaluations run --trace <trace-id> --json
beacon memory evaluations run --limit 10 --harness <name> --since <rfc3339> --json

A trace becomes a candidate only when `task_success` is at least 0.50 and the mean score is at least 0.60. Report how many were scored and how many became candidates. The text output names why each trace was not promoted; do not try to overturn that.

Step 5: draft a lesson for each candidate

beacon memory candidates list --state candidate --json
beacon memory candidates show <candidate-id> --json