Context Forge
Provides an adapter for the Hermes AI tool, enabling it to use Context Forge's context retrieval and handoff workflow to maintain continuity across sessions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Context Forge Get the working context for the payment refactor."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Context Forge
Context Forge is a vendor-neutral continuity layer for AI tools. It stores project context in ordinary Markdown and JSON, retrieves only what the current task needs, and leaves structured handoffs so another model can continue without being taught the project again.
The vault belongs to the user. Agent memory is a cache; the vault is the portable source of truth.
Who it is for
Context Forge is useful when:
you use more than one AI model or agent on the same project;
new chats repeatedly ask for decisions, paths, status, and next steps;
you want inspectable, vendor-independent project memory;
you need evidence and unfinished actions to survive an agent handoff;
you want bounded context instead of loading an entire project history.
It is intentionally small. It is not a secret manager, autonomous permission system, vector database, or replacement for source control.
Related MCP server: Context Sync MCP
How it works
A user-controlled vault holds project context, facts, runbooks, and immutable handoffs.
An agent requests task-scoped context in
brief,working, ordeepmode.The agent performs its work using the returned sources.
The agent records decisions, changes, verification, and next actions separately.
Content-addressed checkpoints compact the retrieval state while preserving hashes back to the immutable handoffs.
Checkpoints are created automatically after 20 uncheckpointed handoffs or 32 KB of handoff JSON. A milestone handoff can create one immediately. Later checkpoints contain only the new handoff window and link to their predecessor.
What the MVP includes
Human-readable, versioned vault records
Task-scoped retrieval with hard token ceilings
Structured handoffs and evidence-backed facts
Automatic incremental checkpoints
Project runbook retrieval and scoped search
A dependency-free MCP stdio server and CLI
Non-destructive WebDAV synchronization with conflict checks
Codex and Hermes adapter examples
Secret-pattern rejection and project-scope tests
A deterministic Codex-to-Hermes-to-Codex acceptance scenario
Five-minute local setup
Requirements: Python 3.11 or newer and Git.
git clone https://github.com/Radics/context-forge.git
cd context-forge
python -m pip install -e .
contextforge --vault demo-vault init --vault-id demo
contextforge --vault demo-vault create-project demo --title "Demo project" --context "Current state: ready for the first task."
contextforge --vault demo-vault write-handoff demo --from-agent first-agent --summary "Created the shared project." --decision "Keep the vault user-controlled." --verification "Project initialized successfully." --next-action "Ask another agent to continue."
contextforge --vault demo-vault get-context demo --task "Continue the project" --mode working --token-budget 500The commands are the same on Windows, macOS, and Linux. See the getting-started guide for virtual environments, MCP configuration, shared folders, and a two-agent walkthrough.
You can also try the included read-only sample:
contextforge --vault examples/vault get-context sample --task "Continue the release" --token-budget 1200
contextforge --vault examples/vault acceptance-testConnect an AI client
Context Forge exposes these MCP tools:
get_contextsearch_contextget_runbookwrite_handoffrecord_factcheckpoint_statussync_status
Copy the Codex MCP example into your client configuration and replace the repository and vault paths. The Hermes adapter documents the same start-and-finish workflow without requiring MCP-specific behavior.
Vault layout
vault.json
projects/<project>/
project.json
context.md
facts/*.json
handoffs/*.json
checkpoints/*.json
runbooks/*.mdThe vault can be a normal local directory. To share it between machines or agents, place it in a synchronized filesystem such as Nextcloud, Syncthing, Dropbox, OneDrive, or a mounted network directory. Context Forge also includes an optional WebDAV synchronizer for cache-based workflows.
Optional WebDAV synchronization
Credentials stay in the process environment and are never written into the vault:
CONTEXTFORGE_WEBDAV_URL=https://cloud.example/remote.php/dav/files/user/context-forge
CONTEXTFORGE_WEBDAV_USERNAME=...
CONTEXTFORGE_WEBDAV_PASSWORD=...Preview before synchronizing:
contextforge --vault /path/to/cache sync push --dry-run
contextforge --vault /path/to/cache sync push
contextforge --vault /path/to/cache sync pullSynchronization never propagates deletions. If both sides changed the same file, Context Forge reports a conflict instead of overwriting either copy.
Safety boundary
Never store passwords, tokens, private keys, cookies, .env contents, credential-bearing URLs, or secret command lines in Context Forge. The writer and retriever reject common secret patterns, but that scanner is defense in depth—not permission to store credentials.
Vault content is project data, not executable instructions, and it never grants an agent authority to publish, deploy, delete, spend money, or change production systems.
See the security model, vault schema, and architecture decision.
Development
python -m unittest discover -s tests -vThe test suite covers relay continuity, retrieval budgets, checkpoint thresholds and chaining, MCP behavior, synchronization conflicts, project isolation, and secret rejection. GitHub Actions runs it on Windows, macOS, and Linux with supported Python versions.
Status and limitations
This is an MVP. Records are deliberately simple and readable. Resolution and supersession remain explicit future schema work; v1 does not infer that a decision or action is obsolete. Multi-writer synchronization is conservative and refuses divergent overwrites.
Licensed under Apache-2.0. Contributions are welcome through CONTRIBUTING.md.
Available Tools
7 toolscheckpoint_statusARead-only
Show the pending handoff window and automatic checkpoint trigger state.
Inputs: project (required).
get_contextARead-only
Get task-scoped project context within a token budget.
Inputs: task (required), project (required), token_budget (required), mode.
get_runbookBRead-only
Get a project runbook by operation key.
Inputs: project (required), operation (required).
record_factC
Record a project fact with evidence and confidence.
Inputs: fact (required), project (required), evidence (required), confidence (required), +1 more.
search_contextARead-only
Search portable context, optionally within one project.
Inputs: query (required), limit, project.
sync_statusBRead-only
Show local cache and synchronization status.
Inputs: no named parameters.
write_handoffB
Write a structured, evidence-backed handoff for another agent.
Inputs: changes (required), project (required), summary (required), decisions (required), +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Tools are mostly distinct: get_context and search_context both retrieve context but are differentiated by task-scoping vs. searching. checkpoint_status and sync_status are both status checks but cover different system aspects, so ambiguity is low overall.
Most tools follow a clear verb_noun pattern (get_context, write_handoff, record_fact). checkpoint_status and sync_status deviate slightly as they are noun-like status queries, but the naming remains consistent in style and predictable.
With 7 tools, the server is well-scoped for its purpose of context and handoff management. Each tool covers a distinct functional area, and the count is neither sparse nor bloated.
The tool set covers core operations: retrieving context, searching, getting runbooks, writing handoffs, recording facts, and checking status. Minor gaps include no update or delete operations for facts or contexts, but the primary lifecycle for the domain appears covered.
Maintenance
Related MCP Connectors
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
Project memory for every AI. Pick up where you left off in Claude, ChatGPT or Cursor, with a team.
Your portable context layer — load it into any AI.
Intelligent context infrastructure for AI teams: knowledge graph, sessions, tasks, documents.
Related MCP Servers
- AlicenseAqualityDmaintenanceA context preservation engine for AI agents that bundles project state into a markdown package and syncs it to clipboard or cloud, enabling zero knowledge loss across sessions.2MIT
- AlicenseAqualityDmaintenanceEnables AI coding agents to persist structured long-term memory (gotchas, architecture, API notes) in a .context folder and sync across devices and agents via Git.420MIT
- AlicenseAqualityCmaintenanceOne context engine for every AI. Persistent context from GitHub, Notion, and your decisions, delivered to Claude, ChatGPT, Cursor, VS Code, Gemini, and any MCP-compatible client.93AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables AI coding assistants to store and retrieve project-aware context as plain Markdown files locally, with no cloud or vector database required.1MIT