agent-beacon README

The project's README from github.com/Asymptote-Labs/agent-beacon. As one markdown file: README.md.

Beacon

GitHub release Homebrew GitHub Workflow Status MIT license Docs Discord

Website · Docs · Discord · Install · Commands

Beacon captures agent session history across Claude Code, Cursor, Codex, OpenCode, and 20+ other harnesses, then turns useful workflows, corrections, and debugging patterns into reusable knowledge for future agents.

A problem solved by one agent shouldn't need to be learned from scratch by another.

Beacon Overview

Beacon is an open-source memory layer for AI coding agents that learns from your work across Claude Code, Cursor, Codex, OpenCode, and 20+ other harnesses. It captures full session history, identifies useful workflows, corrections, and debugging patterns, and makes that knowledge reusable by future agents. Built for developers who want agent knowledge to compound across tools instead of disappearing when a session ends.

Key Capabilities:

🚀 Quick Start

Beacon is open source and local-first. Interactive endpoint setup signs in through beacon.sh and preselects Beacon Managed, with an explicit Local opt-out. Signing in forwards nothing; confirming Managed installs Beacon and connects this machine in the same command, and the confirm screen says so before you accept. System, package, MDM, and CI installation paths remain noninteractive and account-free.

1. Install Beacon

macOS 
brew trust asymptote-labs/tap
brew tap asymptote-labs/tap
brew install beacon

beacon endpoint install
Linux

Download the .deb or .rpm from the latest release.

sudo apt install ./beacon_<version>_linux_amd64.deb

or:

sudo dnf install ./beacon_<version>_linux_amd64.rpm
Windows

Download the x64 MSI from the latest release.

msiexec /i BeaconEndpointAgent-<version>-x64.msi

For silent installation:

msiexec /i BeaconEndpointAgent-<version>-x64.msi /qn

2. Use your agents normally

Open Claude Code, Cursor, Codex, or any other supported harness.

Beacon continuously captures your session history in the background

3. Explore your history

beacon traces

This opens a local terminal browser for traces, event timelines, token usage, and retained content. Nothing is sent anywhere. To use the local web view instead:

beacon endpoint dashboard

Or inspect the raw event stream:

~/.beacon/endpoint/logs/runtime.jsonl

[!NOTE] Signing in does not enable forwarding. Confirming the preselected Beacon Managed option does: the wizard says so on the confirm screen, names what your chosen privacy mode sends, and connects the endpoint after the install succeeds. Choose Local to keep everything on this machine, and disconnect any time with beacon endpoint disconnect.

Inspect the account used during interactive setup:

beacon whoami

🧠 Turn Session History Into Memory

Every agent session contains potentially useful knowledge about your codebase.

Beacon creates a loop around that history:

Run agents
    ↓
Capture session history
    ↓
Evaluate what worked
    ↓
Extract useful knowledge
    ↓
Review + approve
    ↓
Reuse across future agents

That could be:

Instead of disappearing into old sessions, that knowledge becomes reusable.

🔀 Cross-Harness by Design

Most agent memory belongs to a single harness.

Beacon sits across the harness layer.

Claude Code ─┐
Cursor ──────┤
Codex ───────┼──→ Beacon ──→ shared project knowledge
OpenCode ────┤
Cline ───────┘

Because Beacon captures and normalizes session history across tools, knowledge learned through Claude Code doesn't have to stay in Claude Code.

Your Cursor sessions can improve Codex.
Your Codex sessions can improve OpenCode.
Your history keeps compounding even as you switch tools.

Your agent session history belongs to you, not the harness.

🔎 One Trace Format for Every Agent

Beacon captures agent execution where it happens and normalizes it into a common OpenTelemetry-based event model.

That includes:

Instead of separate proprietary histories for every coding tool, you get one dataset you can inspect, search, learn from, and build on.

🖥️ Local Dashboard

Beacon ships with a local, read-only dashboard:

beacon endpoint dashboard

Use it to explore session history across harnesses and understand what your agents actually did.

The underlying JSONL remains directly accessible, so you're never dependent on the UI.

Supported Agents

Beacon supports local agents, browser agents, cloud agents, CI workflows, and agent SDKs.

Local Agent Coverage

Runtime Collection Session Prompt Tool Command File Approval MCP Tokens
Antigravity CLI Hooks ✅ ✅ ✅ ✅ ✅ – – –
Claude Code OTLP + hooks + poll ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Claude Cowork OTLP ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Cline Plugin + poll ✅ ✅ ✅ ✅ ✅ – ✅ ✅
Codex CLI OTLP + hooks + poll ✅ ✅ ✅ ✅ – ✅ – ✅
Codex Desktop OTLP ✅ ✅ ✅ ✅ – ✅ – ✅
Cursor Hooks + poll ✅ ✅ ✅ ✅ ✅ ✅ ✅ –
DeepSeek Harness Hooks + poll ✅ ✅ ✅ ✅ ✅ – ✅ ✅
Devin CLI Hooks ✅ ✅ ✅ ✅ ✅ ✅ ✅ –
Devin Desktop Hooks – ✅ ✅ ✅ ✅ – ✅ –
Factory Droid OTLP + hooks + poll ✅ ✅ ✅ – ✅ ✅ – –
fx (Vercel Labs) Poll ✅ ✅ ✅ ✅ ✅ – ✅ ✅
Gemini CLI OTLP – ✅ ✅ – ✅ ✅ ✅ –
GitHub Copilot CLI OTLP + poll ✅ ✅ ✅ ✅ ✅ ✅ – ✅
goose Adapter only; manual hooks/OTLP ✅ ✅ ✅ ✅ ✅ – ✅ ✅
Grok Build Hooks + poll ✅ ✅ ✅ ✅ ✅ ✅ – –
Hermes Agent Hooks + poll ✅ ✅ ✅ ✅ ✅ ✅ ✅ –
Kimi Code Hooks ✅ ✅ ✅ ✅ ✅ ✅ ✅ –
Kiro Hooks ✅ ✅ ✅ ✅ ✅ – ✅ –
Muse Code Hooks ✅ ✅ ✅ ✅ ✅ ✅ – –
Oh My Pi Extension ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
OpenClaw Gateway Plugin + OTLP + poll ✅ ✅ ✅ ✅ ✅ – ✅ ~
OpenCode Plugin + poll ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
OpenHands Hooks ✅ ✅ ✅ ✅ ✅ – ✅ –
Pi Extension + poll ✅ ✅ ✅ ✅ ✅ – ✅ ✅
Prime Agent Extension + poll ✅ ✅ ✅ ✅ ✅ – – ✅
Qwen Code Hooks ✅ ✅ ✅ ✅ ✅ ✅ – –
Senpi Extension ✅ ✅ ✅ ✅ ✅ – – ✅
VS Code OTLP + hooks ✅ ✅ ✅ ~ ~ – ~ –

Browser Chat

Site Collection Prompt Response Tool Tokens
Claude.ai Chromium + Firefox extension → local OTLP ✅ ✅ ✅ ~
ChatGPT Chromium + Firefox extension → local OTLP ✅ ✅ ✅ –

Cloud Agents

Runtime Collection Session Prompt Tool Command File Tokens
Claude Code Cloud Agents Sandbox hooks → GCS or S3 ✅ ✅ ✅ ✅ ✅ –
Cursor Cloud Agents Sandbox hooks → GCS or S3 – ✅ ✅ ✅ ✅ –
Devin Cloud Agents API poll → GCS ✅ ✅ – – – ✅
CI jobs beacon ci exec → temporary local collector ✅ ✅ ✅ ✅ ✅ ✅

SDK Instrumentation

SDK Surface Collection Captures
Anthropic OpenLLMetry through @asymptote/sdk Model call spans, errors, and OTel attributes
OpenAI OpenLLMetry through @asymptote/sdk Model call spans, errors, and OTel attributes
Claude Agent SDK Observe.wrapClaudeAgentQuery() Query root spans with Beacon-compatible prompt attributes
Vercel AI SDK experimental_telemetry tracer handoff Model call and tool spans where telemetry is enabled

Output Destinations

Beacon writes endpoint telemetry to local JSONL by default.

You can also forward the same normalized session history into infrastructure you already use:

Splunk · Datadog · Elastic · Microsoft Sentinel · CrowdStrike Falcon LogScale · Sumo Logic · Wazuh · AWS S3 · GCS · CloudWatch

Destination Category Support Path
Local JSONL Local Default endpoint log and local dashboard source
Beacon Managed Hosted forwarding Signed-in device enrollment with Standard or Metadata-only privacy
CrowdStrike Falcon LogScale HEC SIEM Endpoint forwarding with LogScale ingest tokens
Microsoft Sentinel SIEM Azure Monitor Agent and Data Collection Rule content pack
Rapid7 InsightIDR SIEM Custom Logs webhook content pack
Splunk HEC SIEM Endpoint forwarding during install or repair
Sumo Logic SIEM HTTP Logs & Metrics Source content pack
Wazuh SIEM Localfile configuration and Beacon content pack
AWS CloudWatch Logs Log aggregation Vector content pack
Datadog Log aggregation Datadog Agent custom log collection
Elastic Log aggregation Filebeat or Elastic Agent
Customer-managed pipelines Log aggregation Forward directly from local Beacon JSONL
AWS S3 Object storage Vector, CI upload, or cloud-agent snapshots
Google Cloud Storage Object storage Vector, CI upload, or cloud-agent snapshots

Architecture

Beacon captures activity where agents actually run and normalizes it into one shared event model.

Local agents ───────┐
Browser chat ───────┤
CI ─────────────────┼──→ Beacon ──→ unified session history
Cloud agents ───────┤                    │
Agent SDKs ─────────┘                    ├──→ local JSONL
                                         ├──→ reviewed memory
                                         ├──→ MCP / Agent Skills
                                         └──→ your own infrastructure

See the documentation for the full architecture breakdown.

Documentation

Read the docs for:

Read the docs →

Contributing

Contributions are welcome.

Open an issue, submit a pull request, or join the Discord.

License

MIT

Star History

Star History Chart

agent-beacon (Asymptote-Labs/agent-beacon)

Searching Database…

1.8K ·GitHub
Agent-beacon
这是什么?一个面向 AI 编程 agent 的开源记忆层:它可以记录 Claude Code、Cursor、Codex、OpenCode 等 20 多个工具的会话历史,然后把有用的工作流程、纠错和调试经验整理成知识,供以后的 agent 复用。
那它是每个 agent 都要装一个插件,还是在电脑上装一份就行?每台电脑装一份即可。Beacon 位于各个工具的上层:它在 agent 活动真正发生的地方进行采集(根据不同工具,通过 hooks、OTLP、插件或轮询),并把这些数据统一成一套共享的事件模型。
我怎么把它跑起来?从最新发布版本安装一个安装包——macOS/Linux 上是 .deb 或 .rpm,Windows 上是 x64 MSI——然后照常用你的 agent 就行,Beacon 会在后台记录历史。系统级、软件包、MDM 和 CI 安装都是无人值守的,也不需要账号。
它到底支持哪些 agent?支持 20 多个本地工具,包括 Claude Code、Cursor、Codex、OpenCode、Cline、Gemini CLI、GitHub Copilot CLI、goose、Devin、Kimi Code、Kiro、Qwen Code 和 Hermes Agent——另外通过浏览器扩展支持 Claude.ai 和 ChatGPT,还支持云端 agent、CI 任务,以及 Anthropic、OpenAI、Claude Agent SDK 和 Vercel AI SDK 的埋点采集。
它对每个 agent 的记录详细程度都一样吗?不一样——支持程度因运行环境而异。Claude Code 能记录全部内容,包括审批、MCP 活动和 token 用量,但 Codex CLI 不记录文件和 MCP 活动,Gemini CLI 不记录会话和 token 数据,VS Code 的支持也大部分不完整,所以请查看针对你的 agent 的支持表格。
我的会话数据会不会被发送到我的电脑之外?默认情况下,所有数据都以 JSONL 格式保存在本地,不会发送到任何地方。只有在你登录并明确确认选择 Beacon Managed 之后才会开始转发;选择 Local 则一切留在本机,而且随时可以断开 beacon endpoint 连接。
为什么不直接用 Claude Code 或 Cursor 自带的记忆功能?大多数 agent 的记忆只属于某一个工具。而 Beacon 把各个工具的历史统一了起来,通过 Claude Code 学到的知识也能提升 Cursor 或 OpenCode 的表现——即使你换工具,历史经验也在不断积累,而且这些数据属于你,不属于某个工具。
我怎么查看我的 agent 到底做了什么?有一个本地终端浏览器可以查看 trace、事件时间线和 token 用量,另外还有一个本地的只读网页控制台。底层的 JSONL 数据也始终可以直接访问,所以你永远不会被界面绑死。
一条会话 trace 里具体包含什么?提示词和回复、工具调用、命令、文件操作、审批、MCP 交互和 token 用量——在 agent 运行的地方采集,并统一成基于 OpenTelemetry 的通用事件模型,所以每个工具产出的数据格式都一样。
What are similar projects?okf-agent-memory, holaOS, lean-ctx, jevmem, OpenAPPA, Agentlas-OS, ai-memory, engram
Which topics is it in?session-replay, agent-security, jev, telemetry, agent-harness, browser-extension, agent-memory, memory, ci, knowledge-base, observability, cursor
Creator
Asymptote-Labs
Size
66.6 MB
Stars
1.8K
Updated
CommitOct 18Releasev1.3.42Oct 16
Age
5mo
Commits · 90 Days