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.

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:

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

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.

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.

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 | 快速开始（中文）.

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.

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

The agent calls context_routes if it does not know the available routes.
The agent calls context_bootstrap before work and saves workspaceRevision.
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.
The agent performs the task.
On completion, pause, or block, it calls context_closeout with that revision, a factual summary, evidence, and next actions.
The server checks the allowlist and concurrency, writes a Git commit, then returns the revision and commit URL.
Unverified observations can be stored as candidates. context_review_candidate may mark them accepted, rejected, or superseded.
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