hot-swap-context-as-MCP

Buildable Bring Your Own Context system for AI agents. Use for: creating user-owned or org-owned context vaults, scaffolding typed memory systems, generating MCP-native context layers, building portable bundle workflows, migrating context across runtimes, and auditing long-running agent memory systems.

Portable Context OS

Use this skill to build, audit, or migrate a Bring Your Own Context system for agents. Treat durable context as infrastructure that should outlive any one model, chat product, or agent runtime.

Use this skill when the user wants any of the following:

1. A real context vault or external memory layer for agents.
2. A move from vendor-native memory to user-owned or organization-owned context.
3. Chat history, artifacts, and preferences turned into typed memory objects.
4. An MCP-native or otherwise model-agnostic context interface.
5. A portable bundle that can move working context between runtimes.
6. An audit of whether an existing memory system is brittle, noisy, or weakly governed.

Do not use this skill for simple one-chat personalization. Use it when the problem is architectural, portable, or long-running.

Core rule

Do not stop at guidance when the user wants a working system. Build the workspace, generate the MCP server, validate the output, and leave behind runnable artifacts.

The six paradigm shifts

Apply these shifts before building anything.

1. Move from prompt state to context infrastructure. Treat durable context as a system layer, not as hidden prompt residue.
2. Move from vendor memory to owned context. Separate memory ownership from model usage.
3. Move from chat logs to typed memory objects. Store preferences, workflows, artifacts, state, and evaluations as distinct classes.
4. Move from full-context loading to just-in-time retrieval. Route only what the active task needs.
5. Move from personalization to governed memory contracts. Add review, permissions, deletion, auditability, and portability.
6. Move from static agents to context flywheels. Improve memory schema, routing quality, and evaluation after every run.

Workflow decision

Choose the path that matches the task.

Situation	Action
Building a new context system	Follow the Creation workflow and run the builder script
Auditing an existing agent or product	Follow the Audit workflow
Packaging or migrating context between tools or teams	Follow the Migration workflow

Creation workflow

Follow these steps in order.

Step 1: Map the context surface

Identify the ownership mode first: personal, team, or enterprise.

Then map the six minimum design inputs:

1. Primary actor.
2. Core workflows.
3. Artifact types.
4. Memory types.
5. Governance constraints.
6. Portability target.

Read references/context_architecture.md before proposing any storage or retrieval design.

Step 2: Define the memory taxonomy

Do not allow the system to collapse into one generic memory blob.

Define at least these categories unless there is a clear reason not to:

• identity memory
• preference memory
• workflow memory
• domain memory
• relationship memory
• artifact memory
• execution memory
• evaluative memory

Use templates/memory_object.md to define each memory object class.

Step 3: Build the runtime, not just the documents

Specify the following components explicitly:

• context vault
• retrieval router
• writeback or update engine
• artifact store
• policy layer
• interface layer such as MCP, API, or CLI

Use templates/context_manifest.yaml to record the architecture and ownership model.

When the user wants a real system, run:

python /home/ubuntu/skills/portable-context-os/scripts/init_context_os.py <output_dir> --name <system_name> --ownership <personal|team|enterprise> --goal <goal> --source-runtime <source> --target-runtime <target>

This builder must generate all of the following inside the target workspace:

Output	Purpose
context_manifest.yaml	Architecture, ownership, routing, and runtime definition
governance_policy.md	Memory rules and policy surface
eval_scorecard.md	Evaluation and feedback-loop baseline
feedback_log.md	Retrieval misses, corruption risks, governance failures, portability failures
memory_objects/	Typed memory storage
artifacts/	First-class artifact store
tools/build_context_bundle.py	Local bundle rebuild utility
mcp_server/server.py	Working MCP server scaffold
mcp_server/requirements.txt	Runtime dependency list

Step 4: Define governance before automation

Write rules for:

• memory creation
• human review
• redaction
• retention
• forgetting or deletion
• export and import
• access control
• audit trail

Use templates/governance_policy.md and read references/evaluation_and_governance.md.

Step 5: Validate the generated MCP server

Do not declare success after file generation alone. Validate that the generated server loads and can inspect the workspace.

Run:

python <workspace>/mcp_server/server.py --dry-run

If the user wants the server fully runnable in the current environment, install runtime dependencies and validate again.

Step 6: Build a portable bundle

Run:

python <workspace>/tools/build_context_bundle.py <workspace>

Use the generated bundle manifest for handoff, migration, or review.

Step 7: Customize the seeded workspace

Replace placeholder values, refine routing rules, add real memory objects, and populate the artifact store. Treat the generated workspace as a working starter system, not as final truth.

Audit workflow

Use this path when the user already has an agent, product, or memory system.

1. Read references/evaluation_and_governance.md.
2. Identify where durable context currently lives.
3. Determine whether the memory is platform-scoped, user-scoped, or organization-scoped.
4. Identify whether retrieval is typed and just-in-time or indiscriminate and prompt-heavy.
5. Check whether artifacts, preferences, and execution state are separated.
6. Check whether deletion, export, and audit semantics are real or only nominal.
7. Produce a gap analysis against the six paradigm shifts.
8. Convert the findings into a revised context_manifest.yaml and eval_scorecard.md.
9. If the user wants a fix, build a replacement workspace and MCP server with init_context_os.py.

Migration workflow

Use this path when the user wants to move context across models, tools, teams, or employers.

1. Identify the source memories and artifacts.
2. Separate raw exports from live operational context.
3. Normalize the memories into typed objects.
4. Redact or re-scope organization-bound memories when ownership changes.
5. Package the result as a portable bundle.
6. Define what the receiving agent may read, update, or not retain.
7. If the target environment needs an active interface, generate a new MCP server-backed workspace and import the normalized materials into it.

Use scripts/build_context_bundle.py after normalizing the source materials.

Generated MCP server expectations

The generated MCP server should expose a usable BYOC interface rather than a placeholder.

At minimum, the generated server should support:

Capability	Why it matters
Describe context system	Confirms the server sees the manifest and workspace
List memory objects	Enables typed retrieval
Get memory object	Enables precise inspection
Upsert memory object	Enables writeback into the context vault
Delete or tombstone memory object	Enables governance and forgetting
List artifacts	Preserves artifacts as first-class memory
Build portable bundle	Keeps portability live, not theoretical
Append feedback log	Maintains the self-improving loop

Prefer tools for state changes, resources for readable workspace files, and prompts for controlled memory-review flows.

Self-improving feedback loop

Activate this loop whenever the skill runs.

1. Record retrieval misses: what the agent needed but did not retrieve.
2. Record memory corruption risks: stale, duplicated, or over-generalized memories.
3. Record governance failures: missing deletion paths, weak permissions, weak auditability.
4. Record portability failures: what could not move cleanly between runtimes.
5. Update the context manifest, memory taxonomy, routing rules, and server defaults.
6. Re-run the evaluation scorecard before declaring the design stable.

Output requirements

When using this skill, produce deliverables that are inspectable, editable, and runnable.

At minimum, aim to leave behind:

Deliverable	Purpose
context_manifest.yaml	Architecture, ownership, interfaces, and routing summary
memory object definitions	Typed memory model
governance policy	Rules for creation, retention, access, and deletion
evaluation scorecard	Retrieval, portability, and trust metrics
portable bundle manifest	Reviewable handoff and migration artifact
working MCP server scaffold	Live interface into the owned context system

Resources

Read resources only when needed.

• Read references/context_architecture.md when designing the system shape.
• Read references/paradigm_shifts.md when the user wants the deeper conceptual framing or a strategy memo.
• Read references/evaluation_and_governance.md when auditing trust, deletion, portability, or evaluation.
• Use templates/ files as editable starting points.
• Run scripts/init_context_os.py to build a new workspace and MCP server.
• Run scripts/build_context_bundle.py to summarize and package a workspace.

Working rule

Optimize for owned, typed, governed, portable context. Do not optimize for the illusion of memory if the resulting system still traps the user inside one runtime.