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
Document cross-harness memory workflow
Justin D'Souzac52f2d93403f
diff --git a/README.md b/README.mdindex d0b9cc6a..f427d781 100644--- a/README.md+++ b/README.md@@ -49,6 +49,7 @@ activity into a [single, unified schema](https://docs.asymptotelabs.ai/cli/event| **Broad runtime coverage** | [Local agent runtimes](#local-agents), plus [browser chat, CI, cloud agents, and SDKs](#supported-surfaces) || **One unified schema** | Every session, prompt, tool, command, edit, approval, and token in one event model || **Local-first by default** | Data stays on the machine: durable JSONL and a read-only [dashboard](https://docs.asymptotelabs.ai/cli/dashboard), no account |+| **Reviewed cross-harness memory** | Opt-in trace evaluation and human-approved project memory that future agents can retrieve through MCP or Agent Skills || **Offline threat detection** | `beacon scan` runs open [Threat Rules](spec/threat-rules/SPEC.md) over your logs, with no network || **Forwards where you already work** | Stream the same log to [your SIEM, observability, or object storage](#output-destinations) || **Deploys in one command or fleet-wide** | [One command](https://docs.asymptotelabs.ai/cli/installation) on a laptop, [MDM](#mdm-deployment) across a fleet |diff --git a/cli/beacon/internal/mcpserver/memory_cross_harness_test.go b/cli/beacon/internal/mcpserver/memory_cross_harness_test.gonew file mode 100644index 00000000..f354a2e3--- /dev/null+++ b/cli/beacon/internal/mcpserver/memory_cross_harness_test.go@@ -0,0 +1,45 @@+package mcpserver++import (+ "path/filepath"+ "strings"+ "testing"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/learning"+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"+)++func TestApprovedMemoryFromOneHarnessIsRetrievableForAnother(t *testing.T) {+ logPath := filepath.Join(t.TempDir(), "endpoint", "logs", "runtime.jsonl")+ store := learning.Open(learning.PathForRuntimeLog(logPath))+ project := asymptoteobserve.LearningProjectV1{ID: "project-1"}+ memory := asymptoteobserve.LearningMemoryV1{+ ID: "memory-cross-harness",+ CandidateID: "candidate-claude",+ Kind: asymptoteobserve.LearningMemoryKindDebuggingPattern,+ Title: "Claude Code trace: retry package smoke after transient network failure",+ Body: "When package smoke fails with ECONNRESET, inspect the error and rerun once before changing code.",+ Project: project,+ Evidence: []asymptoteobserve.LearningEvidenceV1{+ {TraceID: "session:claude_code:s1", Summary: "Claude Code solved the package smoke retry workflow"},+ },+ }+ if err := store.PutMemory(memory); err != nil {+ t.Fatal(err)+ }+ server := New(Options{LogPath: logPath})+ result, err := server.callTool(t.Context(), callToolParams{+ Name: "get_memory_context",+ Arguments: map[string]interface{}{+ "project_id": project.ID,+ "task": "package smoke ECONNRESET retry",+ },+ })+ if err != nil {+ t.Fatalf("get_memory_context returned error: %v", err)+ }+ text := result.Content[0].Text+ if !strings.Contains(text, "memory-cross-harness") || !strings.Contains(text, "Claude Code") {+ t.Fatalf("cross-harness memory not returned: %s", text)+ }+}diff --git a/docs/cli/memory.mdx b/docs/cli/memory.mdxnew file mode 100644index 00000000..7a178c97--- /dev/null+++ b/docs/cli/memory.mdx@@ -0,0 +1,106 @@+---+title: "beacon memory"+description: "Evaluate traces, review project memory, and install approved Agent Skills"+---++## Overview++`beacon memory` is the local review workflow for turning selected Beacon traces into+approved project memory.++The commands are grouped by resource:++- `beacon memory evaluations run|list|show`+- `beacon memory candidates list|show|approve|reject|supersede`+- `beacon memory skills preview|install`++## Evaluate traces++Preview selected traces and estimated Jev calls without a network request:++```bash+beacon memory evaluations run --dry-run --limit 10+```++Evaluate one trace with TypeSafe Jev:++```bash+TYPESAFE_API_KEY=... beacon memory evaluations run \+ --trace session:cursor:s1 \+ --jev-model jev-latest+```++Useful flags:++- `--trace <id>` evaluates one trace ID.+- `--harness <name>` filters traces by harness.+- `--since <rfc3339>` and `--until <rfc3339>` bound the trace window.+- `--jev-model <model>` selects the Jev model, such as `jev-latest` or a pinned version.+- `--jev-endpoint <url>` overrides the TypeSafe System One endpoint.+- `--json` prints machine-readable output.++## Review candidates++List generated candidates:++```bash+beacon memory candidates list+```++Inspect one candidate:++```bash+beacon memory candidates show <candidate-id>+```++Approve a candidate into project memory:++```bash+beacon memory candidates approve <candidate-id> --reason "reviewed"+```++Reject or supersede candidates:++```bash+beacon memory candidates reject <candidate-id> --reason "too specific"+beacon memory candidates supersede <candidate-id> --replacement <memory-id>+```++## Install Agent Skills++Preview the skill content without writing:++```bash+beacon memory skills preview <candidate-id>+```++Install the skill into the project:++```bash+beacon memory skills install <candidate-id>+```++Beacon writes:++```text+.agents/skills/<slug>/SKILL.md+```++Existing files are not overwritten unless you pass `--force`.++## MCP retrieval++`beacon mcp serve` exposes approved memory as read-only MCP tools:++- `search_memory`+- `get_memory`+- `get_memory_context`++These tools let future agents retrieve approved project knowledge regardless of which+harness originally produced the trace.++## Network boundary++`beacon memory evaluations run` is the only command in this workflow that can call+Jev, and only when it is not run with `--dry-run`. Beacon hooks and normal endpoint+capture remain local-only and do not call Jev.diff --git a/docs/concepts/cross-harness-memory.mdx b/docs/concepts/cross-harness-memory.mdxnew file mode 100644index 00000000..04e229b3--- /dev/null+++ b/docs/concepts/cross-harness-memory.mdx@@ -0,0 +1,79 @@+---+title: "Cross-Harness Memory"+description: "Turn reviewed Beacon traces into project memory that future agents can reuse"+---++## Overview++Beacon memory is an opt-in, local-first learning loop built on Beacon's existing+cross-harness trace capture.++Beacon already records normalized agent activity across Claude Code, Cursor, Codex,+OpenCode, and other supported harnesses. The memory workflow lets you explicitly+evaluate selected traces, review high-signal candidates, approve them into project+memory, and expose approved knowledge back to future agents through MCP or Agent+Skills.++Nothing in this workflow runs from hooks. Normal endpoint capture stays local and+does not call Jev or any other external evaluator.++## Workflow++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.+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;+they do not automatically rewrite instructions, install skills, or execute actions.++## Jev evaluation++`beacon memory evaluations run` can call TypeSafe Jev's System One API with a+bounded, redacted trace projection. Beacon sends typed yes/no questions such as:++- Did the trace complete the engineering task successfully?+- Does the trace contain a reusable correction or debugging pattern?+- Is the reusable lesson supported by concrete trace evidence?++Jev returns probabilities. Beacon stores those probabilities with the trace+provenance, evaluator model, and usage metadata when the API reports it.++Use `--dry-run` first to preview selected traces and estimated calls without making+a network request.++## Local storage and scope++Learning artifacts are stored in `memory.db` next to the endpoint runtime log base+directory. The database is durable local state, unlike the rebuildable trace index.++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`.++## Reuse surfaces++Beacon exposes approved memory in two local ways:++- `beacon mcp serve` provides `search_memory`, `get_memory`, and `get_memory_context`+ as read-only MCP tools.+- `beacon memory skills preview|install` renders an approved candidate as an Agent+ Skill with Beacon provenance in the frontmatter.++This is what makes the memory portable across harnesses: one agent's reviewed trace+can become project knowledge that another MCP-capable or skill-capable agent can+retrieve later.++## Privacy boundary++- Hooks never call Jev.+- Dry runs do not call Jev.+- Jev calls are made only by the explicit `beacon memory evaluations run` command.+- Trace projections are bounded and redacted before being sent.+- Candidate approval and skill installation are explicit CLI actions.++If your organization forbids external evaluation, skip `beacon memory evaluations run`+or point it at an internal compatible evaluator.diff --git a/docs/docs.json b/docs/docs.jsonindex fef82f51..37734a69 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -73,6 +73,7 @@"concepts/vector-forwarding"]},+ "concepts/cross-harness-memory",{"group": "Unified Telemetry Schema","root": "telemetry-schema/event-schema",@@ -326,6 +327,7 @@"cli/mcp-doctor"]},+ "cli/memory",{"group": "beacon rules","root": "cli/rules",