# Agent Context Hub

[English](README.md) | [简体中文](README.zh-CN.md)

Agent Context Hub is a reusable MCP server for shared, versioned context across AI agents and devices. It is not tied to OpenClaw: Codex, Claude Code, Hermes, Cursor, OpenClaw, and any client that supports Streamable HTTP MCP can connect to the same workspace.

> **Not a personal workbench.** Agent Context Hub is not a dashboard, task manager, chat UI, or a new agent. It is shared-context infrastructure: the private Workspace is the data and facts layer; Agent Context Hub is the access, synchronization, permission, and revision layer.

It keeps human-readable Markdown and YAML in a **private GitHub workspace repository** and exposes a small MCP interface. This public repository contains only server code, tests, documentation, and generic examples.

## What it solves

- Different agents and devices read the same current profile, rules, skills, and project state.
- GitHub `main` stays the source of truth instead of chat history or opaque agent memory.
- Each device has its own token and can be revoked independently.
- Task closeouts write only allowed project-state files and reject stale concurrent updates.

## First real setup (recommended)

If this is your first **real installation and use** of Agent Context Hub, do not treat `templates/agent-context-workspace` as your real Workspace and do not put personal data in the public repository. That directory is only a public starter template / local smoke-test dataset.

If you are using Codex, Claude Code, Hermes, OpenClaw, or another execution-capable Agent, the simplest entry point is to give it this repository and say:

```text
Help me install and use this project for the first time:
https://github.com/zyplong/agent-context-hub
```

The Agent should interpret this as a **real first-time setup**, read [`prompts/00-master-setup-wizard.md`](prompts/00-master-setup-wizard.md), and then proceed phase by phase: environment check → private Workspace → profile prefill → onboarding → Hub → private networking → Device Token → client configuration → MCP registration → first read-only test → cross-Agent synchronization test.

If a local checkout of this repository already exists, the Agent should verify and reuse it instead of cloning another copy. Real personal data belongs only in your own **private Workspace repository**.

For manual setup, continue with [Quick start](docs/QUICK_START.md).

## Resource boundary

Agent Context Hub manages **shared operational context**, not a general-purpose RAG knowledge base. It may keep lightweight metadata about important external resources so a new agent knows what exists, why it matters, where it lives, and whether the current client can access it.

The bundled workspace template includes `resources/RESOURCE_REGISTRY.yaml` for this purpose. Store references and concise summaries there, not full PDFs, document chunks, embeddings, datasets, credentials, or signed download URLs.

When a required resource is unavailable, the agent should report that the current context is insufficient and ask the user to upload the resource, grant access to its existing location, or use an external retrieval/RAG system that owns it.

See [Resource boundary](docs/RESOURCE_BOUNDARY.md) | [资源边界（中文）](docs/zh-CN/RESOURCE_BOUNDARY.md).

## MCP tools

| Tool | Purpose |
| --- | --- |
| `context_routes` | Discover projects, aliases, and routes. |
| `context_bootstrap` | Load minimal task context and return a workspace revision. |
| `context_query` | Search selected workspace scopes with source paths. |
| `context_closeout` | Write an evidence-backed closeout to approved files. |
| `context_review_candidate` | Accept, reject, or supersede one pending candidate without auto-promoting it to formal state. |

## Client support status

The server is **protocol-compatible** with Streamable HTTP MCP clients. Protocol compatibility does not automatically mean that every client has completed live integration testing.

| Client | Status |
| --- | --- |
| OpenClaw | Configuration documented; live validation should still be recorded per release. |
| Codex | Protocol compatible; live integration validation pending unless documented in the validation report. |
| Hermes | Protocol compatible; live integration validation pending unless documented in the validation report. |
| Claude Code | Protocol compatible; live integration validation pending unless documented in the validation report. |

Use the [real multi-device validation guide](docs/REAL_MULTI_DEVICE_VALIDATION.md) before describing a client or device path as live validated.

## Local demo / developer smoke test

The following path only verifies the code, dependencies, and local stdio MCP reads. **It is not the real first-time setup flow, and you should not put personal data into the example Workspace.**

```bash
git clone https://github.com/YOUR_ACCOUNT/agent-context-hub.git
cd agent-context-hub
npm install
npm test

export PERSONAL_CONTEXT_WORKSPACE="$PWD/templates/agent-context-workspace"
npm run dev
```

This connects the stdio MCP server to the public example Workspace for demo / smoke testing. Passing this test does not mean that a private Workspace, remote Hub, cross-device path, or cross-Agent synchronization has been deployed.

For real use, return to “First real setup” above or read [Quick start](docs/QUICK_START.md) | [快速开始（中文）](docs/zh-CN/QUICK_START.md).

## Create your private workspace

Use [`templates/agent-context-workspace`](templates/agent-context-workspace) as the starter for a new **private** GitHub repository. Replace the sample profile, rules, projects, route map, and resource registry with your own information.

Never publish that workspace. Do not put tokens, private keys, passwords, personal documents, or chat transcripts in it.

`context-map.yaml` is the important control file. It declares exactly which files a route can read and which project files a closeout may write.

```yaml
common:
  always_read:
    - profile/RESPONSE_PREFERENCES.md
    - rules/EVIDENCE_POLICY.md
    - resources/RESOURCE_REGISTRY.yaml

routes:
  sample_project_code:
    project_id: sample-project
    aliases: [sample-project, Sample Project]
    task_aliases: [code, fix, review]
    read:
      - projects/sample-project/CURRENT_STATE.yaml
      - projects/sample-project/NEXT_ACTIONS.md
    write:
      - projects/sample-project/CURRENT_STATE.yaml
      - projects/sample-project/NEXT_ACTIONS.md
```

## Remote deployment

For cross-device use, run the HTTP server on one trusted machine or server and connect clients through HTTPS.

- [Deployment guide](docs/DEPLOYMENT.md) | [部署指南（中文）](docs/zh-CN/DEPLOYMENT.md)
- [OpenClaw setup](docs/OPENCLAW.md) | [OpenClaw 配置（中文）](docs/zh-CN/OPENCLAW.md)
- [Client compatibility](docs/CLIENTS.md) | [客户端兼容性（中文）](docs/zh-CN/CLIENTS.md)
- [Workspace setup](docs/WORKSPACE_SETUP.md) | [Workspace 初始化（中文）](docs/zh-CN/WORKSPACE_SETUP.md)
- [Agent prompts](docs/AGENT_PROMPTS.md) | [Agent 提示词（中文）](docs/zh-CN/AGENT_PROMPTS.md)
- [Resource boundary](docs/RESOURCE_BOUNDARY.md) | [资源边界（中文）](docs/zh-CN/RESOURCE_BOUNDARY.md)
- [Phase-by-phase Prompt Pack](prompts/README.md) | [分阶段提示词包（中文）](prompts/zh-CN/README.md)
- [Tailscale guide](docs/TAILSCALE.md) | [Tailscale 教程（中文）](docs/zh-CN/TAILSCALE.md)
- [Background service](docs/BACKGROUND_SERVICE.md) | [后台与开机启动（中文）](docs/zh-CN/BACKGROUND_SERVICE.md)
- [Troubleshooting](docs/TROUBLESHOOTING.md) | [故障排查（中文）](docs/zh-CN/TROUBLESHOOTING.md)
- [Real multi-device validation](docs/REAL_MULTI_DEVICE_VALIDATION.md) | [真实多设备验收（中文）](docs/zh-CN/REAL_MULTI_DEVICE_VALIDATION.md)
- [Security model](SECURITY.md)

The server reads GitHub through a GitHub App installed only on the private workspace repository. The app needs `Contents: Read and write` only if you enable `context_closeout`.

```bash
cp .env.example .env
# Fill in your own GitHub App and device-token values. Never commit .env.
npm run build
npm run http:start
```

## Task lifecycle

1. The agent calls `context_routes` if it does not know the available routes.
2. The agent calls `context_bootstrap` before work and saves `workspaceRevision`.
3. The agent checks whether the returned context is sufficient for the task. If a required external resource is missing or inaccessible, it asks for that resource instead of inventing content.
4. The agent performs the task.
5. On completion, pause, or block, it calls `context_closeout` with that revision, a factual summary, evidence, and next actions.
6. The server checks the allowlist and concurrency, writes a Git commit, then returns the revision and commit URL.
7. Unverified observations can be stored as candidates. `context_review_candidate` may mark them `accepted`, `rejected`, or `superseded`.
8. **Accepted does not mean formal state was updated.** An accepted candidate only becomes eligible for a later evidence-backed formal update through a fresh bootstrap and closeout.

Agents should not upload full conversations or source documents into the Hub. Only concise, evidence-backed project state and lightweight resource metadata belong in the workspace.

## Verify

```bash
npm test
npm run typecheck
npm run build
```

## License

[MIT](LICENSE)