Skip to content

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

Document cross-harness memory workflow

Justin D'Souzac52f2d93403f
diff --git a/README.md b/README.md
index 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.go
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.json
index 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",