Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Let reviewers write memory candidates from a trace

Lawrence Jonese9ce46d55c0f
diff --git a/cli/beacon/cmd/memory.go b/cli/beacon/cmd/memory.go
index 48a7e82b..ae805570 100644
--- a/cli/beacon/cmd/memory.go
+++ b/cli/beacon/cmd/memory.go
@@ -115,6 +115,19 @@ var memoryCandidatesShowCmd = &cobra.Command{
RunE: runMemoryCandidatesShow,
}
+var memoryCandidatesCreateCmd = &cobra.Command{
+ Use: "create",
+ Short: "Write a memory candidate for a trace you have reviewed",
+ Long: `Write a memory candidate for a trace you have reviewed.
+
+Unlike "evaluations run", no evaluator is involved: you read the trace and state the
+lesson. The candidate records the trace and its events as evidence and waits for
+"candidates approve" like any other. Memory is scoped to the trace's repository when
+it recorded one, otherwise to --project or the current directory.`,
+ SilenceUsage: true,
+ RunE: runMemoryCandidatesCreate,
+}
+
var memoryCandidatesApproveCmd = &cobra.Command{
Use: "approve <candidate-id>",
Short: "Approve a candidate into project memory",
@@ -184,19 +197,28 @@ func init() {
memoryEvaluationsCmd.AddCommand(memoryEvaluationsShowCmd)
memoryCandidatesCmd.AddCommand(memoryCandidatesListCmd)
memoryCandidatesCmd.AddCommand(memoryCandidatesShowCmd)
+ memoryCandidatesCmd.AddCommand(memoryCandidatesCreateCmd)
memoryCandidatesCmd.AddCommand(memoryCandidatesApproveCmd)
memoryCandidatesCmd.AddCommand(memoryCandidatesRejectCmd)
memoryCandidatesCmd.AddCommand(memoryCandidatesSupersedeCmd)
memorySkillsCmd.AddCommand(memorySkillsPreviewCmd)
memorySkillsCmd.AddCommand(memorySkillsInstallCmd)
- for _, c := range []*cobra.Command{memoryListCmd, memoryShowCmd, memoryEvaluationsRunCmd, memoryEvaluationsListCmd, memoryEvaluationsShowCmd, memoryCandidatesListCmd, memoryCandidatesShowCmd, memoryCandidatesApproveCmd, memoryCandidatesRejectCmd, memoryCandidatesSupersedeCmd, memorySkillsPreviewCmd, memorySkillsInstallCmd} {
+ for _, c := range []*cobra.Command{memoryListCmd, memoryShowCmd, memoryEvaluationsRunCmd, memoryEvaluationsListCmd, memoryEvaluationsShowCmd, memoryCandidatesListCmd, memoryCandidatesShowCmd, memoryCandidatesCreateCmd, memoryCandidatesApproveCmd, memoryCandidatesRejectCmd, memoryCandidatesSupersedeCmd, memorySkillsPreviewCmd, memorySkillsInstallCmd} {
c.Flags().BoolVar(&memoryOpts.userMode, "user", true, "Use per-user endpoint paths")
c.Flags().BoolVar(&memoryOpts.systemMode, "system", false, "Use system endpoint paths")
c.Flags().StringVar(&memoryOpts.logPath, "log-path", "", "Runtime JSONL log path")
c.Flags().BoolVar(&memoryOpts.jsonOutput, "json", false, "Print machine-readable JSON")
- c.Flags().StringVar(&memoryOpts.projectPath, "project", "", "Project path for memory scoping (defaults to current directory)")
- }
+ c.Flags().StringVar(&memoryOpts.projectPath, "project", "", "Project path for memory scoping (defaults to the trace's repository, then the current directory)")
+ }
+ memoryCandidatesCreateCmd.Flags().StringVar(&memoryOpts.traceID, "trace", "", "Trace ID the lesson was learned from (required)")
+ _ = memoryCandidatesCreateCmd.MarkFlagRequired("trace")
+ memoryCandidatesCreateCmd.Flags().StringVar(&memoryOpts.title, "title", "", "Title for the memory (required)")
+ memoryCandidatesCreateCmd.Flags().StringVar(&memoryOpts.body, "body", "", "Lesson text (required unless --body-file is given)")
+ memoryCandidatesCreateCmd.Flags().StringVar(&memoryOpts.bodyFile, "body-file", "", "Read the lesson text from a file, or - for stdin")
+ memoryCandidatesCreateCmd.Flags().StringVar(&memoryOpts.applies, "applicability", "", "When the memory applies, such as \"when package smoke fails on macOS\"")
+ memoryCandidatesCreateCmd.Flags().StringVar(&memoryOpts.kind, "kind", "", "Memory kind: workflow, correction, debugging_pattern, gotcha, or convention (required)")
+ memoryCandidatesCreateCmd.Flags().StringSliceVar(&memoryOpts.tags, "tag", nil, "Tag for the memory; repeat or comma-separate (defaults to beacon, the kind, and the harness)")
for _, c := range []*cobra.Command{memoryListCmd, memoryEvaluationsRunCmd, memoryEvaluationsListCmd, memoryCandidatesListCmd} {
c.Flags().IntVar(&memoryOpts.limit, "limit", 25, "Limit returned traces or evaluations")
c.Flags().IntVar(&memoryOpts.page, "page", 1, "Page number for collection output")
@@ -286,7 +308,7 @@ func runMemoryEvaluationsRun(cmd *cobra.Command, args []string) error {
return err
}
store := memoryStore()
- inputs, err := selectedEvaluationInputs(project)
+ inputs, err := selectedEvaluationInputs()
if err != nil {
return err
}
@@ -421,6 +443,39 @@ func runMemoryCandidatesShow(cmd *cobra.Command, args []string) error {
return nil
}
+func runMemoryCandidatesCreate(cmd *cobra.Command, args []string) error {
+ if strings.TrimSpace(memoryOpts.traceID) == "" {
+ return fmt.Errorf("--trace is required")
+ }
+ lesson, err := memoryApprovalEdits(cmd)
+ if err != nil {
+ return err
+ }
+ show, ok, err := dashboard.ShowTrace(memoryLogPath(), memoryOpts.traceID, dashboard.TraceQuery{Limit: 2000})
+ if err != nil {
+ return err
+ }
+ if !ok {
+ return fmt.Errorf("trace not found: %s", memoryOpts.traceID)
+ }
+ project, err := learning.ProjectForTrace(memoryOpts.projectPath, show.Trace)
+ if err != nil {
+ return err
+ }
+ candidate, err := learning.CandidateFromTrace(project, show, lesson)
+ if err != nil {
+ return err
+ }
+ if err := memoryStore().PutCandidate(candidate); err != nil {
+ return err
+ }
+ if memoryOpts.jsonOutput {
+ return json.NewEncoder(cmd.OutOrStdout()).Encode(candidate)
+ }
+ fmt.Fprintf(cmd.OutOrStdout(), "Created candidate %s (%s) for project %s\n", candidate.ID, candidate.Kind, firstNonEmpty(project.Path, project.ID))
+ return nil
+}
+
func runMemoryCandidatesApprove(cmd *cobra.Command, args []string) error {
edits, err := memoryApprovalEdits(cmd)
if err != nil {
@@ -525,7 +580,12 @@ func runMemorySkillsInstall(cmd *cobra.Command, args []string) error {
return nil
}
-func selectedEvaluationInputs(project asymptoteobserve.LearningProjectV1) ([]learning.EvaluationInput, error) {
+// selectedEvaluationInputs picks the traces to evaluate. Each trace is scoped to its
+// own repository through ProjectForTrace unless --project pins one. Without --trace,
+// traces that are a single event with no session, such as OTLP metric samples, are
+// skipped: they carry nothing to learn from and would otherwise crowd out sessions
+// because each fresh sample sorts to the top.
+func selectedEvaluationInputs() ([]learning.EvaluationInput, error) {
logPath := memoryLogPath()
if memoryOpts.traceID != "" {
show, ok, err := dashboard.ShowTrace(logPath, memoryOpts.traceID, dashboard.TraceQuery{Limit: 2000})
@@ -535,6 +595,10 @@ func selectedEvaluationInputs(project asymptoteobserve.LearningProjectV1) ([]lea
if !ok {
return nil, fmt.Errorf("trace not found: %s", memoryOpts.traceID)
}
+ project, err := learning.ProjectForTrace(memoryOpts.projectPath, show.Trace)
+ if err != nil {
+ return nil, err
+ }
return []learning.EvaluationInput{{Project: project, Trace: show}}, nil
}
query := dashboard.TraceQuery{
@@ -558,6 +622,9 @@ func selectedEvaluationInputs(project asymptoteobserve.LearningProjectV1) ([]lea
}
inputs := make([]learning.EvaluationInput, 0, len(traces.Traces))
for _, summary := range traces.Traces {
+ if strings.HasPrefix(summary.ID, "event:") {
+ continue
+ }
show, ok, err := dashboard.ShowTrace(logPath, summary.ID, dashboard.TraceQuery{Limit: 2000})
if err != nil {
return nil, err
@@ -565,6 +632,10 @@ func selectedEvaluationInputs(project asymptoteobserve.LearningProjectV1) ([]lea
if !ok {
continue
}
+ project, err := learning.ProjectForTrace(memoryOpts.projectPath, show.Trace)
+ if err != nil {
+ return nil, err
+ }
inputs = append(inputs, learning.EvaluationInput{Project: project, Trace: show})
}
return inputs, nil
diff --git a/cli/beacon/cmd/memory_test.go b/cli/beacon/cmd/memory_test.go
index ebfe658b..6f48e988 100644
--- a/cli/beacon/cmd/memory_test.go
+++ b/cli/beacon/cmd/memory_test.go
@@ -28,6 +28,7 @@ func TestMemoryEvaluationCommandsRegistered(t *testing.T) {
{"memory", "evaluations", "show"},
{"memory", "candidates", "list"},
{"memory", "candidates", "show"},
+ {"memory", "candidates", "create"},
{"memory", "candidates", "approve"},
{"memory", "candidates", "reject"},
{"memory", "candidates", "supersede"},
@@ -372,14 +373,139 @@ func writeMemoryCommandFixture(t *testing.T) (string, string) {
Message: "Fix flaky package smoke",
Repository: project,
}
- line, err := json.Marshal(event)
+ // A later OTLP metric sample with no session: it forms a single-event trace that
+ // sorts above the session and must not be selected for evaluation.
+ metric := schema.Event{
+ Timestamp: "2026-09-21T02:00:00Z",
+ Vendor: schema.Vendor,
+ Product: schema.Product,
+ SchemaVersion: schema.SchemaVersion,
+ Event: schema.EventInfo{ID: "metric-1", Kind: "agent_runtime", Action: "metric.observed", Category: "metric"},
+ Severity: schema.SeverityInfo,
+ Endpoint: schema.EndpointInfo{OS: "darwin"},
+ Harness: schema.HarnessInfo{Name: "cursor"},
+ Message: "cursor.active_time.total",
+ }
+ var lines []byte
+ for _, item := range []schema.Event{event, metric} {
+ line, err := json.Marshal(item)
+ if err != nil {
+ t.Fatal(err)
+ }
+ lines = append(append(lines, line...), '\n')
+ }
+ if err := os.WriteFile(logPath, lines, 0644); err != nil {
+ t.Fatal(err)
+ }
+ return logPath, project
+}
+
+func TestMemoryEvaluationsRunSkipsSessionlessTraces(t *testing.T) {
+ logPath, project := writeMemoryCommandFixture(t)
+ resetMemoryOpts(t)
+ memoryOpts.logPath = logPath
+ memoryOpts.projectPath = project
+ memoryOpts.dryRun = true
+ memoryOpts.jsonOutput = true
+
+ var out bytes.Buffer
+ cmd := &cobra.Command{}
+ cmd.SetOut(&out)
+ if err := runMemoryEvaluationsRun(cmd, nil); err != nil {
+ t.Fatalf("runMemoryEvaluationsRun returned error: %v", err)
+ }
+ var result evaluationRunResult
+ if err := json.Unmarshal(out.Bytes(), &result); err != nil {
+ t.Fatalf("decode result: %v\n%s", err, out.String())
+ }
+ if result.TraceCount != 1 || len(result.Previews) != 1 || result.Previews[0].TraceID != "session:cursor:s1" {
+ t.Fatalf("expected only the session trace to be selected, got %#v", result)
+ }
+}
+
+func TestMemoryCandidatesCreateScopesToTraceRepository(t *testing.T) {
+ logPath, project := writeMemoryCommandFixture(t)
+ resetMemoryOpts(t)
+ memoryOpts.logPath = logPath
+ // No --project: the trace recorded its repository, so memory must land there and
+ // not in the reviewer's working directory.
+ memoryOpts.traceID = "session:cursor:s1"
+ memoryOpts.kind = asymptoteobserve.LearningMemoryKindDebuggingPattern
+ memoryOpts.title = "Retry package smoke once"
+ memoryOpts.bodyFile = "-"
+ memoryOpts.tags = []string{"smoke", "smoke", " "}
+ memoryOpts.jsonOutput = true
+
+ var out bytes.Buffer
+ cmd := &cobra.Command{}
+ cmd.SetOut(&out)
+ cmd.SetIn(strings.NewReader("Rerun package smoke once after confirming the failure is transient.\n"))
+ if err := runMemoryCandidatesCreate(cmd, nil); err != nil {
+ t.Fatalf("runMemoryCandidatesCreate returned error: %v", err)
+ }
+ var candidate asymptoteobserve.LearningCandidateV1
+ if err := json.Unmarshal(out.Bytes(), &candidate); err != nil {
+ t.Fatalf("decode candidate: %v\n%s", err, out.String())
+ }
+ want, err := learning.ResolveProject(project)
if err != nil {
t.Fatal(err)
}
- if err := os.WriteFile(logPath, append(line, '\n'), 0644); err != nil {
+ if candidate.Project.ID != want.ID {
+ t.Fatalf("candidate project = %#v, want %#v", candidate.Project, want)
+ }
+ if candidate.State != asymptoteobserve.LearningCandidateStateCandidate || candidate.SourceEvaluationID != "" {
+ t.Fatalf("candidate = %#v", candidate)
+ }
+ if candidate.Body != "Rerun package smoke once after confirming the failure is transient." {
+ t.Fatalf("body = %q", candidate.Body)
+ }
+ if len(candidate.Evidence) != 1 || candidate.Evidence[0].TraceID != "session:cursor:s1" || len(candidate.Evidence[0].EventIDs) != 1 {
+ t.Fatalf("evidence = %#v", candidate.Evidence)
+ }
+ if strings.Join(candidate.Tags, ",") != "smoke" {
+ t.Fatalf("tags = %#v", candidate.Tags)
+ }
+
+ stored, err := memoryStore().ListCandidates(learning.Query{ProjectID: want.ID})
+ if err != nil {
t.Fatal(err)
}
- return logPath, project
+ if len(stored) != 1 || stored[0].ID != candidate.ID {
+ t.Fatalf("stored candidates = %#v", stored)
+ }
+
+ // The authored candidate approves like any other, and the memory carries its text.
+ memoryOpts.kind, memoryOpts.title, memoryOpts.bodyFile, memoryOpts.tags = "", "", "", nil
+ memoryOpts.reason = "reviewed"
+ var approved bytes.Buffer
+ cmd.SetOut(&approved)
+ if err := runMemoryCandidatesApprove(cmd, []string{candidate.ID}); err != nil {
+ t.Fatalf("runMemoryCandidatesApprove returned error: %v", err)
+ }
+ if !strings.Contains(approved.String(), `"approved"`) || !strings.Contains(approved.String(), "Rerun package smoke once") {
+ t.Fatalf("approve output = %s", approved.String())
+ }
+}
+
+func TestMemoryCandidatesCreateRejectsUnknownKind(t *testing.T) {
+ logPath, project := writeMemoryCommandFixture(t)
+ resetMemoryOpts(t)
+ memoryOpts.logPath = logPath
+ memoryOpts.projectPath = project
+ memoryOpts.traceID = "session:cursor:s1"
+ memoryOpts.kind = "anecdote"
+ memoryOpts.title = "t"
+ memoryOpts.body = "b"
+ cmd := &cobra.Command{}
+ cmd.SetOut(&bytes.Buffer{})
+ err := runMemoryCandidatesCreate(cmd, nil)
+ if err == nil || !strings.Contains(err.Error(), "unknown memory kind") {
+ t.Fatalf("expected unknown kind error, got %v", err)
+ }
+ if _, statErr := os.Stat(learning.PathForRuntimeLog(logPath)); !os.IsNotExist(statErr) {
+ t.Fatalf("a rejected candidate must not create the store, stat err=%v", statErr)
+ }
}
func resetMemoryOpts(t *testing.T) {
diff --git a/cli/beacon/internal/learning/authored.go b/cli/beacon/internal/learning/authored.go
new file mode 100644
index 00000000..d779da44
--- /dev/null
+++ b/cli/beacon/internal/learning/authored.go
@@ -0,0 +1,65 @@
+package learning
+
+import (
+ "fmt"
+ "strings"
+
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// CandidateFromTrace builds a review candidate from a trace and a lesson written by
+// whoever read it. No evaluator is involved: the reviewer states the lesson and the
+// candidate records the trace and its event IDs as evidence. SourceEvaluationID stays
+// empty, which is how an authored candidate is told apart from a Jev-scored one.
+//
+// Unlike ApproveCandidateWithEdits, where every field is optional because the
+// candidate supplies defaults, here the kind, title and body are required: there is
+// no evaluator text to fall back on.
+func CandidateFromTrace(project asymptoteobserve.LearningProjectV1, trace asymptoteobserve.TraceShowResultV1, lesson ApprovalEdits) (asymptoteobserve.LearningCandidateV1, error) {
+ if strings.TrimSpace(trace.Trace.ID) == "" {
+ return asymptoteobserve.LearningCandidateV1{}, fmt.Errorf("trace id is required")
+ }
+ kind := strings.TrimSpace(lesson.Kind)
+ title := strings.TrimSpace(lesson.Title)
+ body := strings.TrimRight(lesson.Body, " \t\r\n")
+ if kind == "" {
+ return asymptoteobserve.LearningCandidateV1{}, fmt.Errorf("--kind is required (want workflow, correction, debugging_pattern, gotcha, or convention)")
+ }
+ if !ValidMemoryKind(kind) {
+ return asymptoteobserve.LearningCandidateV1{}, fmt.Errorf("unknown memory kind %q (want workflow, correction, debugging_pattern, gotcha, or convention)", kind)
+ }
+ if title == "" {
+ return asymptoteobserve.LearningCandidateV1{}, fmt.Errorf("--title is required")
+ }
+ if strings.TrimSpace(body) == "" {
+ return asymptoteobserve.LearningCandidateV1{}, fmt.Errorf("a body is required; pass --body or --body-file")
+ }
+ applicability := strings.TrimSpace(lesson.Applicability)
+ if applicability == "" {
+ applicability = "When a future agent in this project hits a similar workflow, regardless of harness."
+ }
+ defaultTags := []string{"beacon", kind}
+ if trace.Trace.Harness.Name != "" {
+ defaultTags = append(defaultTags, trace.Trace.Harness.Name)
+ }
+ evidence := asymptoteobserve.LearningEvidenceV1{
+ TraceID: strings.TrimSpace(trace.Trace.ID),
+ Summary: strings.TrimSpace(trace.Trace.Title),
+ }
+ for _, event := range trace.Events {
+ evidence.EventIDs = append(evidence.EventIDs, event.ID)
+ }
+ candidate := asymptoteobserve.LearningCandidateV1{
+ SchemaVersion: asymptoteobserve.LearningSchemaVersion,
+ State: asymptoteobserve.LearningCandidateStateCandidate,
+ Kind: kind,
+ Title: title,
+ Body: body,
+ Applicability: applicability,
+ Tags: approvedTags(lesson.Tags, defaultTags),
+ Project: project,
+ Evidence: []asymptoteobserve.LearningEvidenceV1{evidence},
+ }
+ candidate.ID = CandidateID(candidate)
+ return candidate, nil
+}
diff --git a/cli/beacon/internal/learning/authored_test.go b/cli/beacon/internal/learning/authored_test.go
new file mode 100644
index 00000000..59592f70
--- /dev/null
+++ b/cli/beacon/internal/learning/authored_test.go
@@ -0,0 +1,138 @@
+package learning
+
+import (
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+func authoredTestTrace() asymptoteobserve.TraceShowResultV1 {
+ return asymptoteobserve.TraceShowResultV1{
+ Trace: asymptoteobserve.TraceSummaryV1{
+ ID: "session:claude_code:s1",
+ Title: "Fix the flaky smoke test",
+ Harness: asymptoteobserve.TraceHarnessV1{Name: "claude_code"},
+ },
+ Events: []asymptoteobserve.TraceEventV1{{ID: "e1"}, {ID: "e2"}},
+ }
+}
+
+func TestCandidateFromTraceRecordsEvidenceAndDefaults(t *testing.T) {
+ project := asymptoteobserve.LearningProjectV1{ID: "project-1", Path: "/repo"}
+ candidate, err := CandidateFromTrace(project, authoredTestTrace(), ApprovalEdits{
+ Kind: asymptoteobserve.LearningMemoryKindGotcha,
+ Title: " Smoke needs a warm cache ",
+ Body: "Run smoke twice after a clean checkout.\n\n",
+ })
+ if err != nil {
+ t.Fatalf("CandidateFromTrace: %v", err)
+ }
+ if !strings.HasPrefix(candidate.ID, "candidate_") {
+ t.Fatalf("id = %q", candidate.ID)
+ }
+ if candidate.State != asymptoteobserve.LearningCandidateStateCandidate || candidate.SourceEvaluationID != "" {
+ t.Fatalf("candidate = %#v", candidate)
+ }
+ if candidate.Title != "Smoke needs a warm cache" || candidate.Body != "Run smoke twice after a clean checkout." {
+ t.Fatalf("title=%q body=%q", candidate.Title, candidate.Body)
+ }
+ if candidate.Project.ID != "project-1" {
+ t.Fatalf("project = %#v", candidate.Project)
+ }
+ if len(candidate.Evidence) != 1 || candidate.Evidence[0].TraceID != "session:claude_code:s1" ||
+ strings.Join(candidate.Evidence[0].EventIDs, ",") != "e1,e2" || candidate.Evidence[0].Summary != "Fix the flaky smoke test" {
+ t.Fatalf("evidence = %#v", candidate.Evidence)
+ }
+ if strings.Join(candidate.Tags, ",") != "beacon,gotcha,claude_code" {
+ t.Fatalf("tags = %#v", candidate.Tags)
+ }
+ if candidate.Applicability == "" {
+ t.Fatal("applicability should default when not provided")
+ }
+}
+
+func TestCandidateFromTraceUsesReviewerTags(t *testing.T) {
+ candidate, err := CandidateFromTrace(asymptoteobserve.LearningProjectV1{ID: "p"}, authoredTestTrace(), ApprovalEdits{
+ Kind: asymptoteobserve.LearningMemoryKindWorkflow,
+ Title: "t",
+ Body: "b",
+ Tags: []string{"smoke", " smoke ", ""},
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ if strings.Join(candidate.Tags, ",") != "smoke" {
+ t.Fatalf("tags = %#v", candidate.Tags)
+ }
+}
+
+func TestCandidateFromTraceValidates(t *testing.T) {
+ project := asymptoteobserve.LearningProjectV1{ID: "project-1"}
+ cases := map[string]ApprovalEdits{
+ "missing kind": {Title: "t", Body: "b"},
+ "unknown kind": {Kind: "anecdote", Title: "t", Body: "b"},
+ "missing title": {Kind: asymptoteobserve.LearningMemoryKindWorkflow, Body: "b"},
+ "missing body": {Kind: asymptoteobserve.LearningMemoryKindWorkflow, Title: "t", Body: " \n"},
+ }
+ for name, lesson := range cases {
+ if _, err := CandidateFromTrace(project, authoredTestTrace(), lesson); err == nil {
+ t.Errorf("%s: expected an error", name)
+ }
+ }
+ if _, err := CandidateFromTrace(project, asymptoteobserve.TraceShowResultV1{}, ApprovalEdits{Kind: "workflow", Title: "t", Body: "b"}); err == nil {
+ t.Error("empty trace: expected an error")
+ }
+}
+
+func TestAuthoredCandidateApprovesLikeAnyOther(t *testing.T) {
+ store := Open(filepath.Join(t.TempDir(), "memory.db"))
+ candidate, err := CandidateFromTrace(asymptoteobserve.LearningProjectV1{ID: "p"}, authoredTestTrace(), ApprovalEdits{
+ Kind: "gotcha", Title: "Smoke needs a warm cache", Body: "Run smoke twice.",
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := store.PutCandidate(candidate); err != nil {
+ t.Fatal(err)
+ }
+ approved, memory, err := ApproveCandidate(store, candidate.ID, "reviewed")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if approved.State != asymptoteobserve.LearningCandidateStateApproved || memory.Body != "Run smoke twice." || memory.Title != candidate.Title {
+ t.Fatalf("approved=%#v memory=%#v", approved, memory)
+ }
+}
+
+func TestProjectForTracePrefersExplicitPathThenRepository(t *testing.T) {
+ repo := t.TempDir()
+ trace := asymptoteobserve.TraceSummaryV1{Repository: &asymptoteobserve.TraceRepositoryV1{Path: repo}}
+ fromTrace, err := ProjectForTrace("", trace)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if fromTrace.Path != filepath.Clean(repo) {
+ t.Fatalf("expected trace repository %q, got %#v", repo, fromTrace)
+ }
+ explicit := t.TempDir()
+ fromFlag, err := ProjectForTrace(explicit, trace)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if fromFlag.Path != filepath.Clean(explicit) {
+ t.Fatalf("expected explicit path %q, got %#v", explicit, fromFlag)
+ }
+ cwd, err := ResolveProject("")
+ if err != nil {
+ t.Fatal(err)
+ }
+ fromCwd, err := ProjectForTrace("", asymptoteobserve.TraceSummaryV1{})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if fromCwd.ID != cwd.ID {
+ t.Fatalf("expected working-directory fallback %#v, got %#v", cwd, fromCwd)
+ }
+}
diff --git a/cli/beacon/internal/learning/store.go b/cli/beacon/internal/learning/store.go
index 025c5e54..a678d049 100644
--- a/cli/beacon/internal/learning/store.go
+++ b/cli/beacon/internal/learning/store.go
@@ -184,6 +184,18 @@ func ResolveProject(path string) (asymptoteobserve.LearningProjectV1, error) {
return project, nil
}
+// ProjectForTrace resolves the project a trace's memory belongs to. An explicit path
+// wins. Otherwise the trace's own repository path is used when it recorded one, so
+// memory lands with the repository the agent was working in rather than wherever the
+// reviewer happened to run the command. With neither, it falls back to the working
+// directory like ResolveProject.
+func ProjectForTrace(path string, trace asymptoteobserve.TraceSummaryV1) (asymptoteobserve.LearningProjectV1, error) {
+ if strings.TrimSpace(path) == "" && trace.Repository != nil {
+ path = strings.TrimSpace(trace.Repository.Path)
+ }
+ return ResolveProject(path)
+}
+
func ProjectID(project asymptoteobserve.LearningProjectV1) string {
key := firstNonEmpty(project.RemoteURL, project.Path)
if key == "" {
diff --git a/docs/cli/memory.mdx b/docs/cli/memory.mdx
index 94d5b247..a360d294 100644
--- a/docs/cli/memory.mdx
+++ b/docs/cli/memory.mdx
@@ -12,7 +12,7 @@ The commands are grouped by resource:
- `beacon memory list|show` for approved memory
- `beacon memory evaluations run|list|show`
-- `beacon memory candidates list|show|approve|reject|supersede`
+- `beacon memory candidates list|show|create|approve|reject|supersede`
- `beacon memory skills preview|install`
All subcommands accept the common endpoint and project-scope flags:
@@ -22,7 +22,7 @@ All subcommands accept the common endpoint and project-scope flags:
| `--user` | Use per-user endpoint paths. Enabled by default |
| `--system` | Use system endpoint paths |
| `--log-path <path>` | Runtime JSONL log path |
-| `--project <path>` | Project path for memory scoping. Defaults to the current directory |
+| `--project <path>` | Project path for memory scoping. Defaults to the trace's repository, then the current directory |
| `--json` | Print machine-readable JSON |
Beacon stores learning artifacts in `memory.db` next to the resolved endpoint base
@@ -30,6 +30,12 @@ directory for the runtime log. The store is durable local state and is scoped by
the resolved project ID, so approved memory for one repository is not automatically
returned for another.
+Commands that start from a trace (`evaluations run` and `candidates create`) scope
+the result to the repository the trace recorded, so memory lands with the project the
+agent was working in rather than wherever you ran the command. A linked git worktree
+resolves to the same project as its main checkout. Pass `--project` to override.
+Commands that list or look up records use `--project` or the current directory.
+
## Evaluate traces
Preview selected traces and estimated Jev calls without a network request:
@@ -89,6 +95,12 @@ probabilities. A trace becomes a review candidate only when both hold:
Text output lists each completed evaluation that was not promoted with the
reason, for example `Not promoted: eval_... (task_success 0.27 is below 0.50)`.
+Without `--trace`, the selection skips traces that are a single event with no
+session, such as OTLP metric samples. They carry nothing to learn from, and each
+fresh sample would otherwise sort above the real sessions and consume the run's
+Jev calls. `--limit` counts traces before the skip, so a run can select fewer
+sessions than the limit.
+
List and inspect stored evaluations:
```bash
@@ -96,6 +108,31 @@ beacon memory evaluations list --limit 25
beacon memory evaluations show <evaluation-id>
```
+## Write a candidate yourself
+
+Jev scores a trace; it does not read it. When you, or an agent acting for you, have
+read a trace and know the lesson, write the candidate directly. No evaluator is
+called, so this also works where external evaluation is not allowed:
+
+```bash
+beacon memory candidates create \
+ --trace session:claude_code:03d6d4a7-... \
+ --kind gotcha \
+ --title "Package smoke needs a warm cache" \
+ --applicability "when the first smoke run after a clean checkout fails" \
+ --body-file lesson.md
+```
+
+`--trace` is the trace the lesson came from; its events become the candidate's
+evidence. `--kind`, `--title`, and a body from `--body` or `--body-file` are required.
+`--applicability` and `--tag` take the same forms as on `candidates approve`, below;
+without tags Beacon records `beacon`, the kind, and the harness.
+
+The candidate waits for `candidates approve` like any other, and the same
+[lesson shape](/concepts/cross-harness-memory) applies. It has no
+`source_evaluation_id`, which is how you tell an authored candidate from a Jev-scored
+one in `candidates list --json`.
+
## Review candidates
List generated candidates:
diff --git a/docs/concepts/cross-harness-memory.mdx b/docs/concepts/cross-harness-memory.mdx
index 03f6f54e..939b5a8d 100644
--- a/docs/concepts/cross-harness-memory.mdx
+++ b/docs/concepts/cross-harness-memory.mdx
@@ -22,9 +22,11 @@ does not call Jev or any other external evaluator.
The loop is:
1. Capture traces from local agent harnesses.
-2. Run `beacon memory evaluations run` on selected traces.
-3. Review generated candidates with `beacon memory candidates`.
-4. Approve candidates into project memory.
+2. Produce candidates, either by scoring traces with `beacon memory evaluations run`
+ or by reading a trace and writing the lesson with `beacon memory candidates create`.
+3. Review candidates with `beacon memory candidates`.
+4. Approve candidates into project memory, supplying the lesson text for a scored
+ candidate as you do.
5. Reuse approved memory through Beacon MCP or install it as an Agent Skill.
This is deliberately review-gated. Jev probabilities help rank and classify traces;
@@ -70,9 +72,12 @@ Approved memory is scoped to the resolved project. Cross-project or user-global
memory is not automatic. If you install a skill, Beacon writes it under the current
project's `.agents/skills/<slug>/SKILL.md`.
-Project scope is derived from the current working directory by default. Use
-`--project <path>` when reviewing a trace for a different repository or when a
-client needs to retrieve memory for a specific project.
+When a command starts from a trace, project scope comes from the repository the trace
+recorded, so a session in one repository becomes memory for that repository even if
+you run the command from another, and a linked worktree counts as its main checkout.
+Commands that list or look up records scope to the current working directory. Use
+`--project <path>` to override either, for example when a client needs to retrieve
+memory for a specific project.
## Reuse surfaces