# 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，而不是依赖模型内建记忆。

```mermaid
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

## 安装

核心服务：

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

启用 MCP HTTP bridge：

```bash
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+`

## 快速开始

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

打开：

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

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

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

## MCP 接入示例

启动 MCP HTTP bridge：

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

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

```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`，先做整库并入，再启动服务

整合旧库到正式库：

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

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

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

只预览、不写库：

```bash
python scripts/migrate_local_memories.py --dry-run
```

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

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

实际导入：

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

## CLI

```bash
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 启动检索的投影层

同步命令：

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

建议时机：

- 新增或修改方法论规则后立即同步
- 在需要跨 session 或跨 runtime 生效前同步
- 将规则变更视为“文件修改 + RelayCore 同步”两步都完成才算完成

## 测试

```bash
pytest
```

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

## 致谢

- 本项目参考了 [EastSword/EchoMemory](https://github.com/EastSword/EchoMemory) 的公开项目思路。

## 许可证

MIT，见 [LICENSE](LICENSE)。

<details>
<summary>English</summary>

## 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.

```mermaid
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

```bash
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

```bash
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`

</details>