The universal-context-mcp server is a context preservation engine that enables lossless AI agent session handoffs by saving and restoring project state, architectural intent, and work focus.
Export Session Context (export_session_context): Aggregates your current project state — including environment metadata, directory structure, git diffs, commit history, and core project files — into a snapshot saved to a local ledger (.session_checkpoints.jsonl) and copied to your clipboard. Optionally include a handoff message describing your current intent or blockers, and optionally sync to the cloud via a private GitHub Gist for cross-machine portability.
Bootstrap Session Context (bootstrap_session_context): Loads the latest saved "Shadow Context" from the local ledger, allowing a new AI agent session to instantly resume exactly where the previous session left off — with full awareness of prior architectural decisions, focus areas, and blockers — eliminating the need for re-discovery or re-explanation.
Allows secure upload of context to private GitHub Gists for cloud portability between machines
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., "@universal-context-mcp save my current project context to clipboard"
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.
The God-Tier Context Preservation Engine for AI Agents
Zero knowledge loss when transitioning between sessions, environments, or agents.
You start a new session with an AI agent (Claude, Gemini, etc.). It spends the first 20 minutes reading files, guessing your architecture, and asking questions you already answered yesterday.
Related MCP server: @vemdev/mcp-server
Universal Context MCP creates a lossless context bridge. It bundles your project state, uncommitted changes, and architectural intent into a high-density package that "re-animates" any new agent instantly.
🏎️ Zero-Touch Setup: One command auto-configures your global Claude/CLI environment.
🧠 Auto-Bootstrapping: Agents automatically load the previous session's exact focus and blockers.
🕰️ Session Time Machine: A local .session_checkpoints.jsonl ledger tracks the evolution of your project decisions.
⚖️ Precision Token Budgeting: Calculates exact context pressure to prevent agent degradation.
☁️ Cloud Sync: Securely upload context to private GitHub Gists for global cross-machine portability.
# 1. Install the engine globally
npm install -g universal-context-mcp
# 2. Auto-configure your CLI/Agent environment
context-save --setup(The setup command automatically injects the MCP server into your global .claude.json or equivalent).
Run this in any project root to grab a high-density snapshot and copy it directly to your clipboard:
context-save "Brief description of current focus or blockers"Moving from your desktop to your laptop? Use a secure GitHub Gist:
context-save "Moving to home laptop" --cloudAdd this Ironclad Mandate to your project's CLAUDE.md or GEMINI.md:
## Core Mandates
- **Auto-Bootstrap:** At the start of EVERY new session, you MUST immediately call `bootstrap_session_context` to load the previous architectural intent and focus.When a new agent boots up, it will read this rule, call the MCP tool, and instantly resume your work exactly where you left off.
Never forget to save context again. Run this once per project to install a Git hook that silently updates your context in the background every time you commit:
context-save --install-hookIf you need to trace execution speed, path resolution, or token count math, use the debug flag:
context-save --debugWhen invoked, the exporter intelligently bundles:
Environment: OS and Path.
Shadow Context: The manual intent or handoff note.
Active Changes: A lightweight git diff --stat.
Structure: A depth-limited, noise-filtered directory tree.
History: The last 5 git log entries.
Core Files: Automatic injection of README.md, CLAUDE.md, package.json, etc.
LOAD context: Fetches the latest 'Shadow Context' from the ledger to resume work perfectly.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description solely indicates fetching (a read operation) from the ledger. It does not disclose any side effects, authentication needs, or rate limits, but for a simple tool with no parameters, the basic trait is conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise without fluff. The 'LOAD context:' prefix is slightly redundant but not detrimental.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the core action but omits any details about the return format or error conditions, leaving some ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. According to guidelines, 0 parameters baseline is 4, and the description does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'fetches' and the resource 'latest Shadow Context from the ledger', and states the purpose 'to resume work perfectly'. This clearly distinguishes it from the sibling tool export_session_context, which likely exports context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for resuming work by loading context, but it does not explicitly state when to use this tool versus export_session_context or provide any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SAVE context: Aggregates project metadata, tree, diffs, and mental model to clipboard and ledger.
| Name | Required | Description | Default |
|---|---|---|---|
| handoff_message | No | Intent/Focus for next session. | |
| cloud_sync | No | Upload to private Gist. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must disclose behavioral traits. It mentions aggregation and saving to clipboard/ledger but does not explain if the operation is idempotent, what happens to previous context, permission requirements, rate limits, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with front-loaded action ('SAVE context') and concise enumeration of aggregated elements. Slightly improved structure could separate purpose from details, but overall no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description lacks detail on return values, error handling, behavior when parameters are omitted, and impact on shared resources. For a tool that modifies state ('SAVE'), completeness is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both parameters have clear schema descriptions. The tool description rephrases 'handoff_message' and 'cloud_sync' but adds no new meaning beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action 'SAVE context' and specifies what is aggregated (project metadata, tree, diffs, mental model) and where it goes (clipboard and ledger). This distinguishes from sibling bootstrap_session_context which likely initializes context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for exporting context but provides no explicit guidance on when to use vs. the sibling tool, no when-not-to-use scenarios, and no prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0bootstrap_session_contextexport_session_contextScored across 2 tools
The two tools have clearly distinct purposes: one loads context, the other saves context. There is no functional overlap.
Both tools follow a consistent verb_noun pattern using snake_case, with 'bootstrap' and 'export' as clear verbs and 'session_context' as the common noun.
With only two tools, the server feels minimal. While it covers the core load/save operations, a broader scope might include additional tools for listing or managing contexts.
The tool set provides basic load and save capabilities, but lacks operations for initializing, deleting, or listing contexts, leaving minor gaps in lifecycle coverage.
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Shared project memory that keeps teammates and AI agents aligned across sessions.
