Agent Context Hub

English | 简体中文

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.

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 | 资源边界（中文）.

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 before describing a client or device path as live validated.

Quick start

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

The stdio server is ready to add to an MCP client. It does not print normal console output after startup.

For a guided first setup, start with Quick start | 快速开始（中文）.

Create your private workspace

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

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 | 部署指南（中文）
• OpenClaw setup | OpenClaw 配置（中文）
• Client compatibility | 客户端兼容性（中文）
• Workspace setup | Workspace 初始化（中文）
• Agent prompts | Agent 提示词（中文）
• Resource boundary | 资源边界（中文）
• Phase-by-phase Prompt Pack | 分阶段提示词包（中文）
• Tailscale guide | Tailscale 教程（中文）
• Background service | 后台与开机启动（中文）
• Troubleshooting | 故障排查（中文）
• Real multi-device validation | 真实多设备验收（中文）
• Security model

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.

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

npm test
npm run typecheck
npm run build

License

MIT