Content
# RelayCore
> A shared memory, evidence tracing, and structured decision control plane for local or self-hosted AI runtimes.
`English summary below`
## Project Overview
RelayCore provides a lightweight, self-hosted control plane that allows multiple AI runtimes to share long-term memory, event timelines, structured command flows, and traceable decision evidence, rather than relying on one-time chat context passing.
The current core evolution direction is:
- `Shared State`: Shared Memory, Command, Event, Mission Control
- `Shared Intelligence`: Adding trace recovery, task canvas, canonical memory, rejected knowledge, and decision governance on top of shared state
The current repository publicly includes:
- SQLite shared storage
- Structured command bus
- Append-only event timeline with digest
- Traceable digest, Mermaid task canvas, and evidence trace refs
- MCP-style memory / command tools
- Mission Control Web UI
- Memory browsing, Trace Inspector, Rejected Knowledge, and conflict resolution interfaces
- Export, backup, audit, metrics, CORS, and token-related interfaces
- Local history migration scripts
## Core Capabilities
- Use a unified storage layer to carry long-term memory across runtimes
- Use a structured command bus to distribute tasks, declare permissions, and record state
- Use event timelines, digests, and Mermaid task canvas to track execution processes
- Use `trace_refs` / `artifact_refs` to look up summaries, decisions, and memories back to original evidence
- Use memory levels, rejected knowledge, and decision ledger to precipitate organization knowledge
- Use REST API, CLI, MCP HTTP bridge, and Web UI to provide multiple access methods
- Use local migration scripts to import historical memories into RelayCore
## Installation
Core service:
```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
```
Enable MCP HTTP bridge:
```bash
python3.12 -m venv .venv-mcp
source .venv-mcp/bin/activate
pip install -e .[mcp]
```
Note:
- Core service supports `Python 3.9+`
- `relaycore mcp-http` depends on the official MCP Python SDK, requiring `Python 3.10+`
## Quick Start
```bash
relaycore init-db
relaycore serve --host 127.0.0.1 --port 8080
```
Open:
- `http://127.0.0.1:8080/mission-control`
Alternatively, use the module entry:
```bash
python -m relaycore init-db
python -m relaycore serve --host 127.0.0.1 --port 8080
```
## MCP Access Example
Start MCP HTTP bridge:
```bash
relaycore mcp-http --host 127.0.0.1 --port 9090 --db ~/.relaycore/relaycore.db
```
Merge the example configuration into `~/.codex/config.toml`:
```toml
[mcp_servers.relaycore]
url = "http://127.0.0.1:9090/mcp"
```
Example file:
- `examples/codex/config.toml.example`
Validation:
- `codex mcp get relaycore`
- `codex mcp list`
## Migrate Historical Memories
Preview only, no writing to database:
```bash
python scripts/migrate_local_memories.py --dry-run
```
Explicitly include historical summaries and supported runtime stores:
```bash
python scripts/migrate_local_memories.py --dry-run --include-history --include-runtime-store
```
Actual import:
```bash
python scripts/migrate_local_memories.py --session-id local-memory-migration
```
## CLI
```bash
relaycore init-db
relaycore serve
relaycore export
relaycore mcp-http
```
## Repository Contents
- `relaycore/`: Core runtime code
- `scripts/`: Migration and auxiliary scripts
- `tests/`: Automated tests
- `examples/`: Publicly available configuration examples
- `docs/ROADMAP.md`: Future planning
- `docs/GITHUB_RELEASE_v1.1.0.md`: Current release documentation
## Testing
```bash
pytest
```
Current local test results (July 19, 2026): `55 passed`
## Acknowledgements
- This project referenced the public project ideas from [EastSword/EchoMemory](https://github.com/EastSword/EchoMemory).
## License
MIT, see [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
## Quick Start
```bash
relaycore init-db
relaycore serve --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`.
## Validation
- `pytest`
- Local status on July 19, 2026: `55 passed`
</details>
