The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Let reviewers write memory candidates from a trace
Lawrence Jonese9ce46d55c0f
diff --git a/cli/beacon/cmd/memory.go b/cli/beacon/cmd/memory.goindex 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) ([]leaif !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) ([]leaif !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, nildiff --git a/cli/beacon/cmd/memory_test.go b/cli/beacon/cmd/memory_test.goindex 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.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 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.mdxindex 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 bythe resolved project ID, so approved memory for one repository is not automaticallyreturned 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 tracesPreview 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 thereason, 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 25beacon 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 candidatesList generated candidates:diff --git a/docs/concepts/cross-harness-memory.mdx b/docs/concepts/cross-harness-memory.mdxindex 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-globalmemory is not automatic. If you install a skill, Beacon writes it under the currentproject'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