Beacon Memory Distill

Step 5: draft a lesson for each candidate

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

For each candidate, read its evidence trace. Filter to the event types that carry substance and write the JSON to a file before reading it:

beacon endpoint traces show <trace-id> --json --event-type user_message,tool_call,command,tool_result,approval,error --limit 150 > trace-1.json
beacon endpoint traces show <trace-id> --json --event-type user_message,tool_call,command,tool_result,approval,error --offset 151 --limit 150 > trace-2.json
beacon endpoint traces show <trace-id> --json --around-event <n> --before 5 --after 5

How to read what comes back:

• --event-type filters the coarse type field (user_message, tool_call, command, tool_result, approval, error, session, token_usage, metric). Action names such as prompt.submitted match nothing.
• Filter every read. Hooks and OTLP both record, so an unfiltered session is mostly token_usage and session events, and an unfiltered traces show on a large log can take minutes and exceed a tool timeout. Filtered reads return in seconds. range.total_events counts the filtered events, so it tells you how much is left.
• The log usually holds no assistant text and no tool output. For Claude Code, a session's substance is its user_message events (the only ones with a content object), its tool_call and command events (tool name and command line), and whether a tool_result was a failure. The strongest evidence for a lesson is a failed command followed by a different command that succeeded.
• A user_message with content.included false, or only a hash, means Beacon kept metadata only. You cannot draft from a hash; say the trace was unreadable.
• --around-event centres on the unfiltered event number. Combined with --event-type it can return no events at all, so read a small unfiltered window around the number and skip the token_usage and session rows yourself.

Work out, from the events themselves:

• What the task was (the first prompt).
• What went wrong or was non-obvious: a failed command, a correction from the user, a retry, a wrong assumption that got reversed.
• What finally worked, with the specific command, file, flag, or order of steps.
• How the agent confirmed it worked (a passing test, a clean build).

Then check whether it is already known:

beacon memory list --json -q "<two or three distinctive terms>"

Draft each lesson in the shape given in references/lesson-quality.md: title, kind, applicability, body, tags, and the event numbers it rests on. Read that file before writing your first draft.

Recommend reject when the trace has no transferable lesson (it was routine, too specific to one moment, or the fix was later reverted), and supersede when an existing memory already says the same thing.

Step 6: review with the user

Show every draft at once, each with its recommendation (approve, reject, or supersede), the candidate ID, and the trace events that support it. Ask the user to confirm or edit each one. Do not approve, reject, or supersede anything they have not confirmed. Silence is not approval.

Step 7: record the decisions

Approve with the reviewed text. Pass the body on stdin so quoting stays safe:

beacon memory candidates approve <candidate-id> \
  --title "<title>" \
  --kind <workflow|correction|debugging_pattern|gotcha|convention> \
  --applicability "<when this applies>" \
  --tag <tag> --tag <tag> \
  --reason "Reviewed with the user; lesson drafted from trace events <n>-<m>" \
  --body-file - --json <<'LESSON'
<body>
LESSON

beacon memory candidates reject <candidate-id> --reason "<why it is not reusable>"
beacon memory candidates supersede <candidate-id> --replacement <memory-id> --reason "<which memory already covers it>"

Confirm what was stored with beacon memory show <memory-id>, then summarize: approved, rejected, superseded, and the new memory IDs. Mention that any agent in any harness can now recall these with the beacon-memory-recall skill or the Beacon MCP tools, and that a memory worth loading automatically can be installed as a skill with beacon-memory-promote.

Without an evaluator

When scoring is not allowed, there is no evaluator to prefilter, so pick fewer traces (three at most) and only ones the user named or that clearly hold finished work. For each one, read it and draft the lesson exactly as in Step 5, then review the drafts with the user as in Step 6. Only after the user confirms a draft, write it as a candidate:

beacon memory candidates create --trace <trace-id> \
  --title "<title>" \
  --kind <workflow|correction|debugging_pattern|gotcha|convention> \
  --applicability "<when this applies>" \
  --tag <tag> --tag <tag> \
  --body-file - --json <<'LESSON'
<body>
LESSON

The trace's events become the candidate's evidence, and it has no source_evaluation_id. It still waits for approval, so approve it with its candidate ID and a --reason as in Step 7; the text it was created with carries through, so the title, kind, and body flags can be left off. A trace the evaluator scored and did not promote is not a reason to write one by hand: that path is for when there is no evaluator, not for overturning it.

Boundaries

• The evaluation run is the only networked step. Run it only after the dry run and the user's explicit yes, and only on the selection they approved. candidates create is local.
• Memory is shared with every future agent in this project. Never put secrets, tokens, credentials, internal hostnames, customer data, or personal information into a title, body, tag, or reason, even when the trace contains them. Describe them instead ("the staging API key from 1Password").
• Quote trace content sparingly and only to support a draft.
• Never edit memory.db or the runtime log directly. Use the CLI.