RelayCore

面向本地或自托管 AI runtime 的共享记忆、证据追溯与结构化决策控制面。

中文为主 | English summary below

项目简介

RelayCore 提供一套轻量、可自托管的控制平面，让多个 AI runtime 共享长期记忆、事件时间线、结构化命令流和可追溯决策证据，而不是依赖一次性聊天上下文传话。

当前项目的核心演进方向是：

• Shared State：共享 Memory、Command、Event、Mission Control

• Shared Intelligence：在共享状态之上增加 trace recovery、task canvas、canonical memory、rejected knowledge 和 decision governance

当前仓库公开包含：

• SQLite 共享存储

• 结构化 command bus

• append-only event timeline 与 digest

• traceable digest、Mermaid task canvas 与 evidence trace refs

• MCP-style memory / command tools

• Mission Control Web UI

• 记忆浏览、Trace Inspector、Rejected Knowledge 与冲突处理界面

• export、backup、audit、metrics、CORS、token 相关接口

• 本地历史记忆迁移脚本

• 版本化规则文档与规则同步 CLI

启动时记忆自主获取流程

RelayCore 的“自主获取记忆”指的是 runtime 在任务开始时主动调用 memory_auto_prepare，自动完成建/续 task、拉取压缩后的记忆上下文，以及补最近 digest，而不是依赖模型内建记忆。

sequenceDiagram
    participant Runtime as "AI Runtime"
    participant MCP as "RelayCore MCP"
    participant Store as "记忆存储"
    participant Digest as "Digest 存储"

    Runtime->>MCP: memory_auto_prepare(session_id, runtime, query)
    MCP->>MCP: memory_begin_task()
    MCP->>Store: 获取或创建会话
    MCP->>Store: 追加 task_begin 与 heartbeat
    MCP->>MCP: memory_context()
    MCP->>Store: 拉取候选记忆(limit=500)
    MCP->>MCP: 过滤 active/pending/rejected
    Note over MCP: 默认排除 legacy migration 记忆
    MCP->>MCP: 按 session 相关性、active 状态、\nrule/decision/lesson 类型、rejected 上下文、\nquery 相似度排序
    MCP->>Digest: session_digest_get(limit=3)
    MCP-->>Runtime: 返回 session、压缩上下文与最近 digests

核心能力

• 用统一存储层承载跨 runtime 的长期记忆

• 用结构化命令总线分发任务、声明权限和记录状态

• 用事件时间线、digest 和 Mermaid task canvas 追踪执行过程

• 用 trace_refs / artifact_refs 把摘要、决策和记忆反查回原始证据

• 用 memory levels、rejected knowledge 和 decision ledger 沉淀组织知识

• 用 REST API、CLI、MCP HTTP bridge 与 Web UI 提供多种接入方式

• 用本地迁移脚本把历史记忆导入 RelayCore

安装

核心服务：

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

启用 MCP HTTP bridge：

python3.12 -m venv .venv-mcp
source .venv-mcp/bin/activate
pip install -e .[mcp]

说明：

• 核心服务支持 Python 3.9+

• relaycore mcp-http 依赖官方 MCP Python SDK，需要 Python 3.10+

快速开始

relaycore init-db
relaycore serve --host 127.0.0.1 --port 8080

打开：

• http://127.0.0.1:8080/mission-control

也可以直接使用模块入口：

python -m relaycore init-db
python -m relaycore serve --db ~/.relaycore/relaycore.db --host 127.0.0.1 --port 8080

MCP 接入示例

启动 MCP HTTP bridge：

relaycore mcp-http --host 127.0.0.1 --port 9090 --db ~/.relaycore/relaycore.db

将示例配置合并到 ~/.codex/config.toml：

[mcp_servers.relaycore]
url = "http://127.0.0.1:9090/mcp"

示例文件：

• examples/codex/config.toml.example

验证方式：

• codex mcp get relaycore

• codex mcp list

多 Runtime 拓扑

RelayCore 的推荐接法是“一套共享后端，多端接入”：

• 同一台机器上的 Codex、Claude Code、Hermes 等 runtime，可以共用一个 relaycore mcp-http

• 同机跨终端不需要每个终端各起一份服务；只要都连到同一个 http://127.0.0.1:9090/mcp 即可

• Mission Control Web UI 主要用于查看状态、调试和手动干预，不是 agent 调 MCP 工具的必需前提

• 真正共享的是 MCP bridge 和它后面的 ~/.relaycore/relaycore.db，不是某个单独 agent 的本地聊天上下文

接入时请区分这几层：

• 各 runtime 自己的 prompt、skill、wrapper 或客户端配置，仍然要分别安装或接入

• 只要这些 runtime 都支持 MCP，或能通过适配层调用 MCP，它们就可以共享同一个 RelayCore 后端

• 如果是跨机器、跨容器或其他彼此隔离的环境，需要把 RelayCore 部署成所有参与方都能访问到的共享服务，而不是依赖某个本地终端里的私有进程

协作时的身份约定：

• 需要共享同一个任务上下文时，使用同一个 session_id

• 不同 runtime 或不同实例应使用不同的 agent_id

• runtime 字段应反映实际来源，例如 codex、claude，未知 runtime 也可以使用自己的规范化名字

迁移历史记忆

本地运行现在采用单库约束：

• 正式运行统一使用 ~/.relaycore/relaycore.db

• relaycore serve 和 relaycore mcp-http 会拒绝把运行时指向别的 SQLite 文件

• 如果工作目录下还有带数据的 relaycore.db 或旧的 echomemory.db，先做整库并入，再启动服务

整合旧库到正式库：

relaycore consolidate-db --source echomemory.db --target ~/.relaycore/relaycore.db

如果之前误把服务跑在仓库里的 ./relaycore.db，也用同一个命令并入正式库：

relaycore consolidate-db --source ./relaycore.db --target ~/.relaycore/relaycore.db

只预览、不写库：

python scripts/migrate_local_memories.py --dry-run

显式包含历史摘要和支持的 runtime store：

python scripts/migrate_local_memories.py --dry-run --include-history --include-runtime-store

实际导入：

python scripts/migrate_local_memories.py --session-id local-memory-migration

CLI

relaycore init-db
relaycore serve --db ~/.relaycore/relaycore.db
relaycore export
relaycore mcp-http --db ~/.relaycore/relaycore.db
relaycore consolidate-db
relaycore sync-rules --rules-file RULES.md

仓库内容

• relaycore/：核心运行时代码

• scripts/：迁移与辅助脚本

• tests/：自动化测试

• examples/：公开可用配置示例

• AGENTS.md / CLAUDE.md：项目级 runtime memory 约束

• RULES.md：版本化规则源，会同步投影到 RelayCore rule memory

• docs/ROADMAP.md：后续规划

• docs/GITHUB_RELEASE_v1.2.0.md：当前 release 文案

项目级 Memory 约束

如果你希望 Codex、Claude 等 runtime 对这个项目统一走 RelayCore 而不是依赖各自内建 memory，请把下面两份文件作为项目级约束入口：

• AGENTS.md

• CLAUDE.md

核心原则：

• durable project memory 只认 RelayCore

• built-in memory 不作为项目记忆源

• 开始任务优先 memory_auto_prepare

• 如果 memory_auto_prepare 不可用，再退回 memory_begin_task + memory_context

• 规划前先做简短 preflight，确认相关 rule / decision / lesson 已加载

• 结束任务前 memory_commit_task

• 同机多 runtime 可以共用一个 RelayCore MCP 后端

• 多个 runtime 共享任务时复用同一个 session_id，但保留各自独立的 agent_id

Rule Sync

如果你希望仓库内的人类可审阅规则稳定影响运行时行为，请使用双层结构：

• RULES.md 作为版本化、可代码审阅的规则源

• RelayCore rule memory 作为 runtime 启动检索的投影层

同步命令：

relaycore sync-rules --rules-file RULES.md

建议时机：

• 新增或修改方法论规则后立即同步

• 在需要跨 session 或跨 runtime 生效前同步

• 将规则变更视为“文件修改 + RelayCore 同步”两步都完成才算完成

测试

pytest

当前本地测试结果（2026-07-29）：81 passed

致谢

• 本项目参考了 EastSword/EchoMemory 的公开项目思路。

许可证

MIT，见 LICENSE。

Overview

RelayCore is a lightweight shared-memory and structured command relay for local or self-hosted AI runtimes.

This public repository includes:

• SQLite-backed shared storage

• a structured command bus

• an append-only event timeline with digests

• MCP-style memory and command tools

• a Mission Control web UI

• a memory viewer and conflict-resolution workflow

• export, backup, audit, metrics, CORS, and token-related surfaces

• local history migration scripts

Startup Memory Retrieval Flow

RelayCore's "autonomous memory retrieval" means a runtime starts work by calling memory_auto_prepare, which bootstraps the task session, loads compact memory context, and fetches recent digests instead of relying on built-in model memory.

sequenceDiagram
    participant Runtime as "AI Runtime"
    participant MCP as "RelayCore MCP"
    participant Store as "Memory Store"
    participant Digest as "Digest Store"

    Runtime->>MCP: memory_auto_prepare(session_id, runtime, query)
    MCP->>MCP: memory_begin_task()
    MCP->>Store: get_session() or create_session()
    MCP->>Store: append task_begin and heartbeat
    MCP->>MCP: memory_context()
    MCP->>Store: list_memory_candidates(limit=500)
    MCP->>MCP: filter active/pending/rejected
    Note over MCP: exclude legacy migration memory by default
    MCP->>MCP: rank by session affinity, active status,\nrule/decision/lesson type, rejected context,\nand optional query similarity
    MCP->>Digest: session_digest_get(limit=3)
    MCP-->>Runtime: session + compact context + recent digests

Quick Start

relaycore init-db
relaycore serve --db ~/.relaycore/relaycore.db --host 127.0.0.1 --port 8080

Open http://127.0.0.1:8080/mission-control.

MCP Bridge

relaycore mcp-http --host 127.0.0.1 --port 9090 --db ~/.relaycore/relaycore.db

For Codex, merge the example from examples/codex/config.toml.example into ~/.codex/config.toml.

Multi-Runtime Topology

RelayCore is designed for one shared backend with multiple runtime clients:

• Codex, Claude Code, Hermes, and similar runtimes on the same machine can share one relaycore mcp-http process

• Multiple local terminals should point to the same http://127.0.0.1:9090/mcp endpoint instead of starting separate per-terminal services

• Mission Control is optional for agent MCP calls; it is mainly the operator UI

• The shared state is the MCP bridge plus the canonical ~/.relaycore/relaycore.db, not any individual runtime's native chat memory

Keep these identity rules consistent during collaboration:

• Use the same session_id when multiple runtimes should share one task context

• Use different agent_id values for different runtimes or instances

• Set runtime to the actual caller, such as codex, claude, or another normalized runtime name

Validation

• pytest

• Local status on July 29, 2026: 81 passed