Skip to content

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

Install approved memory as Agent Skills

Justin D'Souza76d18fa2edc7
diff --git a/cli/beacon/cmd/memory.go b/cli/beacon/cmd/memory.go
index f52b03c8..2e16412d 100644
--- a/cli/beacon/cmd/memory.go
+++ b/cli/beacon/cmd/memory.go
@@ -39,6 +39,7 @@ var memoryOpts struct {
kind string
reason string
replacement string
+ force bool
}
var memoryCmd = &cobra.Command{
@@ -117,6 +118,27 @@ var memoryCandidatesSupersedeCmd = &cobra.Command{
RunE: runMemoryCandidatesSupersede,
}
+var memorySkillsCmd = &cobra.Command{
+ Use: "skills",
+ Short: "Preview and install approved memory as Agent Skills",
+}
+
+var memorySkillsPreviewCmd = &cobra.Command{
+ Use: "preview <candidate-id>",
+ Short: "Preview the Agent Skill for an approved candidate",
+ Args: cobra.ExactArgs(1),
+ SilenceUsage: true,
+ RunE: runMemorySkillsPreview,
+}
+
+var memorySkillsInstallCmd = &cobra.Command{
+ Use: "install <candidate-id>",
+ Short: "Install the Agent Skill for an approved candidate",
+ Args: cobra.ExactArgs(1),
+ SilenceUsage: true,
+ RunE: runMemorySkillsInstall,
+}
+
type evaluationRunResult struct {
DryRun bool `json:"dry_run"`
Project asymptoteobserve.LearningProjectV1 `json:"project"`
@@ -133,6 +155,7 @@ func init() {
rootCmd.AddCommand(memoryCmd)
memoryCmd.AddCommand(memoryEvaluationsCmd)
memoryCmd.AddCommand(memoryCandidatesCmd)
+ memoryCmd.AddCommand(memorySkillsCmd)
memoryEvaluationsCmd.AddCommand(memoryEvaluationsRunCmd)
memoryEvaluationsCmd.AddCommand(memoryEvaluationsListCmd)
memoryEvaluationsCmd.AddCommand(memoryEvaluationsShowCmd)
@@ -141,8 +164,10 @@ func init() {
memoryCandidatesCmd.AddCommand(memoryCandidatesApproveCmd)
memoryCandidatesCmd.AddCommand(memoryCandidatesRejectCmd)
memoryCandidatesCmd.AddCommand(memoryCandidatesSupersedeCmd)
+ memorySkillsCmd.AddCommand(memorySkillsPreviewCmd)
+ memorySkillsCmd.AddCommand(memorySkillsInstallCmd)
- for _, c := range []*cobra.Command{memoryEvaluationsRunCmd, memoryEvaluationsListCmd, memoryEvaluationsShowCmd, memoryCandidatesListCmd, memoryCandidatesShowCmd, memoryCandidatesApproveCmd, memoryCandidatesRejectCmd, memoryCandidatesSupersedeCmd} {
+ for _, c := range []*cobra.Command{memoryEvaluationsRunCmd, memoryEvaluationsListCmd, memoryEvaluationsShowCmd, memoryCandidatesListCmd, memoryCandidatesShowCmd, 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")
@@ -160,6 +185,7 @@ func init() {
c.Flags().StringVar(&memoryOpts.reason, "reason", "", "Review reason recorded with the candidate")
}
memoryCandidatesSupersedeCmd.Flags().StringVar(&memoryOpts.replacement, "replacement", "", "Approved memory ID that supersedes this candidate")
+ memorySkillsInstallCmd.Flags().BoolVar(&memoryOpts.force, "force", false, "Overwrite an existing generated skill")
memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.harness, "harness", "", "Filter traces by harness")
memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.traceID, "trace", "", "Evaluate a single trace ID")
memoryEvaluationsRunCmd.Flags().StringVar(&memoryOpts.since, "since", "", "RFC3339 lower time bound, inclusive")
@@ -347,6 +373,40 @@ func runMemoryCandidatesSupersede(cmd *cobra.Command, args []string) error {
return nil
}
+func runMemorySkillsPreview(cmd *cobra.Command, args []string) error {
+ candidate, memory, err := learning.CandidateMemoryForSkill(memoryStore(), args[0])
+ if err != nil {
+ return err
+ }
+ content := learning.RenderSkill(candidate, memory)
+ result := learning.SkillInstallResult{Slug: learning.SkillSlug(memory), Content: content}
+ if memoryOpts.jsonOutput {
+ return json.NewEncoder(cmd.OutOrStdout()).Encode(result)
+ }
+ fmt.Fprint(cmd.OutOrStdout(), content)
+ return nil
+}
+
+func runMemorySkillsInstall(cmd *cobra.Command, args []string) error {
+ candidate, memory, err := learning.CandidateMemoryForSkill(memoryStore(), args[0])
+ if err != nil {
+ return err
+ }
+ projectPath := memoryOpts.projectPath
+ if projectPath == "" {
+ projectPath = firstNonEmpty(memory.Project.Path, candidate.Project.Path)
+ }
+ result, err := learning.InstallSkill(projectPath, candidate, memory, memoryOpts.force)
+ if err != nil {
+ return err
+ }
+ if memoryOpts.jsonOutput {
+ return json.NewEncoder(cmd.OutOrStdout()).Encode(result)
+ }
+ fmt.Fprintf(cmd.OutOrStdout(), "Installed %s\n", result.Path)
+ return nil
+}
+
func selectedEvaluationInputs(project asymptoteobserve.LearningProjectV1) ([]learning.EvaluationInput, error) {
logPath := memoryLogPath()
if memoryOpts.traceID != "" {
diff --git a/cli/beacon/cmd/memory_test.go b/cli/beacon/cmd/memory_test.go
index 10aa7147..253875fe 100644
--- a/cli/beacon/cmd/memory_test.go
+++ b/cli/beacon/cmd/memory_test.go
@@ -28,6 +28,8 @@ func TestMemoryEvaluationCommandsRegistered(t *testing.T) {
{"memory", "candidates", "approve"},
{"memory", "candidates", "reject"},
{"memory", "candidates", "supersede"},
+ {"memory", "skills", "preview"},
+ {"memory", "skills", "install"},
} {
cmd, _, err := rootCmd.Find(path)
if err != nil || cmd == nil {
@@ -136,6 +138,44 @@ func TestMemoryCandidatesApproveCommand(t *testing.T) {
}
}
+func TestMemorySkillsPreviewAndInstallCommands(t *testing.T) {
+ logPath, project := writeMemoryCommandFixture(t)
+ resetMemoryOpts(t)
+ memoryOpts.userMode = true
+ memoryOpts.logPath = logPath
+ memoryOpts.projectPath = project
+ candidate, memory := testApprovedCommandMemory()
+ store := memoryStore()
+ if err := store.PutCandidate(candidate); err != nil {
+ t.Fatal(err)
+ }
+ if err := store.PutMemory(memory); err != nil {
+ t.Fatal(err)
+ }
+
+ var preview bytes.Buffer
+ cmd := &cobra.Command{}
+ cmd.SetOut(&preview)
+ if err := runMemorySkillsPreview(cmd, []string{candidate.ID}); err != nil {
+ t.Fatalf("runMemorySkillsPreview returned error: %v", err)
+ }
+ if !strings.Contains(preview.String(), "beacon_memory_id") || !strings.Contains(preview.String(), "Retry package smoke") {
+ t.Fatalf("preview output = %s", preview.String())
+ }
+
+ var install bytes.Buffer
+ cmd.SetOut(&install)
+ if err := runMemorySkillsInstall(cmd, []string{candidate.ID}); err != nil {
+ t.Fatalf("runMemorySkillsInstall returned error: %v", err)
+ }
+ if !strings.Contains(install.String(), ".agents") {
+ t.Fatalf("install output = %s", install.String())
+ }
+ if _, err := os.Stat(filepath.Join(project, ".agents", "skills", "beacon-debugging-pattern-retry-package-smoke", "SKILL.md")); err != nil {
+ t.Fatalf("installed skill missing: %v", err)
+ }
+}
+
func writeMemoryCommandFixture(t *testing.T) (string, string) {
t.Helper()
dir := t.TempDir()
@@ -200,6 +240,7 @@ func resetMemoryOpts(t *testing.T) {
kind string
reason string
replacement string
+ force bool
}{userMode: true, limit: 25, page: 1, jevEndpoint: learning.DefaultJevEndpoint, jevModel: learning.DefaultJevModel, jevCost: learning.DefaultCostPerTrace}
t.Cleanup(func() { memoryOpts = previous })
}
@@ -229,3 +270,30 @@ func testCommandCandidate(t *testing.T) asymptoteobserve.LearningCandidateV1 {
}
return candidate
}
+
+func testApprovedCommandMemory() (asymptoteobserve.LearningCandidateV1, asymptoteobserve.LearningMemoryV1) {
+ project := asymptoteobserve.LearningProjectV1{ID: "project-1"}
+ evidence := []asymptoteobserve.LearningEvidenceV1{{TraceID: "trace-1", Summary: "Retry fixed a transient failure"}}
+ candidate := asymptoteobserve.LearningCandidateV1{
+ ID: "candidate-approved",
+ MemoryID: "memory-approved",
+ State: asymptoteobserve.LearningCandidateStateApproved,
+ Kind: asymptoteobserve.LearningMemoryKindDebuggingPattern,
+ Title: "Debugging pattern: Retry package smoke",
+ Body: "Rerun package smoke once after confirming the error is transient.",
+ Project: project,
+ Evidence: evidence,
+ }
+ memory := asymptoteobserve.LearningMemoryV1{
+ ID: candidate.MemoryID,
+ CandidateID: candidate.ID,
+ Kind: candidate.Kind,
+ Title: candidate.Title,
+ Body: candidate.Body,
+ Applicability: "when package smoke fails transiently",
+ Tags: []string{"beacon", "debugging_pattern"},
+ Project: project,
+ Evidence: evidence,
+ }
+ return candidate, memory
+}
diff --git a/cli/beacon/internal/learning/skills.go b/cli/beacon/internal/learning/skills.go
new file mode 100644
index 00000000..01307aba
--- /dev/null
+++ b/cli/beacon/internal/learning/skills.go
@@ -0,0 +1,160 @@
+package learning
+
+import (
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+ "unicode"
+
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+type SkillInstallResult struct {
+ Path string `json:"path"`
+ Slug string `json:"slug"`
+ Written bool `json:"written"`
+ Content string `json:"content,omitempty"`
+}
+
+func CandidateMemoryForSkill(store *Store, candidateID string) (asymptoteobserve.LearningCandidateV1, asymptoteobserve.LearningMemoryV1, error) {
+ candidate, ok, err := store.GetCandidate(candidateID)
+ if err != nil {
+ return asymptoteobserve.LearningCandidateV1{}, asymptoteobserve.LearningMemoryV1{}, err
+ }
+ if !ok {
+ return asymptoteobserve.LearningCandidateV1{}, asymptoteobserve.LearningMemoryV1{}, fmt.Errorf("candidate not found: %s", candidateID)
+ }
+ if candidate.State != asymptoteobserve.LearningCandidateStateApproved || candidate.MemoryID == "" {
+ return asymptoteobserve.LearningCandidateV1{}, asymptoteobserve.LearningMemoryV1{}, fmt.Errorf("candidate %s is not approved", candidateID)
+ }
+ memory, ok, err := store.GetMemory(candidate.MemoryID)
+ if err != nil {
+ return asymptoteobserve.LearningCandidateV1{}, asymptoteobserve.LearningMemoryV1{}, err
+ }
+ if !ok || memory.SupersededBy != "" {
+ return asymptoteobserve.LearningCandidateV1{}, asymptoteobserve.LearningMemoryV1{}, fmt.Errorf("approved memory not found: %s", candidate.MemoryID)
+ }
+ return candidate, memory, nil
+}
+
+func RenderSkill(candidate asymptoteobserve.LearningCandidateV1, memory asymptoteobserve.LearningMemoryV1) string {
+ slug := SkillSlug(memory)
+ var b strings.Builder
+ b.WriteString("---\n")
+ b.WriteString("name: " + slug + "\n")
+ b.WriteString("description: " + yamlQuote(firstSentence(memory.Title)) + "\n")
+ b.WriteString("beacon_memory_id: " + yamlQuote(memory.ID) + "\n")
+ b.WriteString("beacon_candidate_id: " + yamlQuote(candidate.ID) + "\n")
+ if len(memory.Tags) > 0 {
+ b.WriteString("tags:\n")
+ for _, tag := range memory.Tags {
+ b.WriteString(" - " + yamlQuote(tag) + "\n")
+ }
+ }
+ b.WriteString("---\n\n")
+ b.WriteString("# " + memory.Title + "\n\n")
+ if memory.Applicability != "" {
+ b.WriteString("Use this skill " + ensureTrailingPeriod(memory.Applicability) + "\n\n")
+ }
+ b.WriteString("## Guidance\n\n")
+ b.WriteString(strings.TrimSpace(memory.Body))
+ b.WriteString("\n\n")
+ if len(memory.Evidence) > 0 {
+ b.WriteString("## Beacon Evidence\n\n")
+ for _, evidence := range memory.Evidence {
+ b.WriteString("- Trace `" + evidence.TraceID + "`")
+ if evidence.Summary != "" {
+ b.WriteString(": " + evidence.Summary)
+ }
+ b.WriteString("\n")
+ }
+ }
+ return b.String()
+}
+
+func InstallSkill(projectPath string, candidate asymptoteobserve.LearningCandidateV1, memory asymptoteobserve.LearningMemoryV1, force bool) (SkillInstallResult, error) {
+ if strings.TrimSpace(projectPath) == "" {
+ projectPath = firstNonEmpty(memory.Project.Path, candidate.Project.Path)
+ }
+ if strings.TrimSpace(projectPath) == "" {
+ return SkillInstallResult{}, fmt.Errorf("project path is required to install a skill")
+ }
+ slug := SkillSlug(memory)
+ path := filepath.Join(projectPath, ".agents", "skills", slug, "SKILL.md")
+ if !force {
+ if _, err := os.Stat(path); err == nil {
+ return SkillInstallResult{}, fmt.Errorf("skill already exists: %s (use --force to overwrite)", path)
+ } else if !os.IsNotExist(err) {
+ return SkillInstallResult{}, err
+ }
+ }
+ if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+ return SkillInstallResult{}, err
+ }
+ content := RenderSkill(candidate, memory)
+ if err := os.WriteFile(path, []byte(content), 0644); err != nil {
+ return SkillInstallResult{}, err
+ }
+ return SkillInstallResult{Path: path, Slug: slug, Written: true}, nil
+}
+
+func SkillSlug(memory asymptoteobserve.LearningMemoryV1) string {
+ base := strings.TrimSpace(memory.Title)
+ if base == "" {
+ base = memory.ID
+ }
+ var out strings.Builder
+ lastDash := false
+ for _, r := range strings.ToLower(base) {
+ switch {
+ case unicode.IsLetter(r) || unicode.IsDigit(r):
+ out.WriteRune(r)
+ lastDash = false
+ case !lastDash:
+ out.WriteByte('-')
+ lastDash = true
+ }
+ if out.Len() >= 48 {
+ break
+ }
+ }
+ slug := strings.Trim(out.String(), "-")
+ if slug == "" {
+ slug = "beacon-memory"
+ }
+ if !strings.HasPrefix(slug, "beacon-") {
+ slug = "beacon-" + slug
+ }
+ return slug
+}
+
+func yamlQuote(value string) string {
+ escaped := strings.ReplaceAll(value, `\`, `\\`)
+ escaped = strings.ReplaceAll(escaped, `"`, `\"`)
+ return `"` + escaped + `"`
+}
+
+func firstSentence(value string) string {
+ value = strings.TrimSpace(value)
+ if value == "" {
+ return "Beacon approved project memory."
+ }
+ for _, sep := range []string{".", "\n"} {
+ if idx := strings.Index(value, sep); idx > 0 {
+ return strings.TrimSpace(value[:idx])
+ }
+ }
+ return value
+}
+
+func ensureTrailingPeriod(value string) string {
+ value = strings.TrimSpace(value)
+ if value == "" {
+ return ""
+ }
+ if strings.HasSuffix(value, ".") {
+ return value
+ }
+ return value + "."
+}
diff --git a/cli/beacon/internal/learning/skills_test.go b/cli/beacon/internal/learning/skills_test.go
new file mode 100644
index 00000000..4f2e4679
--- /dev/null
+++ b/cli/beacon/internal/learning/skills_test.go
@@ -0,0 +1,104 @@
+package learning
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+func TestRenderSkillIncludesProvenance(t *testing.T) {
+ candidate, memory := testApprovedSkillMemory()
+ content := RenderSkill(candidate, memory)
+ for _, want := range []string{
+ `name: beacon-debugging-pattern-retry-package-smoke`,
+ `beacon_memory_id: "memory-1"`,
+ `beacon_candidate_id: "candidate-1"`,
+ "# Debugging pattern: Retry package smoke",
+ "Trace `trace-1`",
+ } {
+ if !strings.Contains(content, want) {
+ t.Fatalf("rendered skill missing %q:\n%s", want, content)
+ }
+ }
+}
+
+func TestInstallSkillWritesAndRefusesOverwrite(t *testing.T) {
+ project := t.TempDir()
+ candidate, memory := testApprovedSkillMemory()
+ result, err := InstallSkill(project, candidate, memory, false)
+ if err != nil {
+ t.Fatalf("InstallSkill returned error: %v", err)
+ }
+ if !result.Written || result.Path == "" {
+ t.Fatalf("result = %#v", result)
+ }
+ data, err := os.ReadFile(result.Path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(string(data), "Retry package smoke") {
+ t.Fatalf("skill content = %s", string(data))
+ }
+ if _, err := InstallSkill(project, candidate, memory, false); err == nil {
+ t.Fatal("InstallSkill should refuse overwrite without force")
+ }
+ if _, err := InstallSkill(project, candidate, memory, true); err != nil {
+ t.Fatalf("InstallSkill force returned error: %v", err)
+ }
+ if got, want := result.Path, filepath.Join(project, ".agents", "skills", "beacon-debugging-pattern-retry-package-smoke", "SKILL.md"); got != want {
+ t.Fatalf("path = %s, want %s", got, want)
+ }
+}
+
+func TestCandidateMemoryForSkillRequiresApprovedCandidate(t *testing.T) {
+ store := Open(filepath.Join(t.TempDir(), "memory.db"))
+ candidate, memory := testApprovedSkillMemory()
+ candidate.State = asymptoteobserve.LearningCandidateStateCandidate
+ if err := store.PutCandidate(candidate); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := CandidateMemoryForSkill(store, candidate.ID); err == nil {
+ t.Fatal("candidate memory lookup should require approval")
+ }
+ candidate.State = asymptoteobserve.LearningCandidateStateApproved
+ candidate.MemoryID = memory.ID
+ if err := store.PutCandidate(candidate); err != nil {
+ t.Fatal(err)
+ }
+ if err := store.PutMemory(memory); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := CandidateMemoryForSkill(store, candidate.ID); err != nil {
+ t.Fatalf("CandidateMemoryForSkill returned error: %v", err)
+ }
+}
+
+func testApprovedSkillMemory() (asymptoteobserve.LearningCandidateV1, asymptoteobserve.LearningMemoryV1) {
+ project := asymptoteobserve.LearningProjectV1{ID: "project-1", Path: "/repo"}
+ evidence := []asymptoteobserve.LearningEvidenceV1{{TraceID: "trace-1", Summary: "Retry fixed a transient package smoke failure"}}
+ candidate := asymptoteobserve.LearningCandidateV1{
+ ID: "candidate-1",
+ MemoryID: "memory-1",
+ State: asymptoteobserve.LearningCandidateStateApproved,
+ Kind: asymptoteobserve.LearningMemoryKindDebuggingPattern,
+ Title: "Debugging pattern: Retry package smoke",
+ Body: "When package smoke fails with a transient network error, inspect the error and rerun once before changing code.",
+ Project: project,
+ Evidence: evidence,
+ }
+ memory := asymptoteobserve.LearningMemoryV1{
+ ID: "memory-1",
+ CandidateID: candidate.ID,
+ Kind: candidate.Kind,
+ Title: candidate.Title,
+ Body: candidate.Body,
+ Applicability: "when package smoke fails with a transient network error",
+ Tags: []string{"beacon", "debugging_pattern"},
+ Project: project,
+ Evidence: evidence,
+ }
+ return candidate, memory
+}