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

Security Scan

The skill's files and instructions are consistent with a developer-facing toolkit for building portable context (BYOC) workspaces and an MCP server; nothing requests unrelated secrets or external downloads, but the skill assumes running local Python scripts and starting a server, so exercise normal operational caution.

Purpose & Capability

Name and description (portable BYOC/MCP scaffold) match the bundled templates and source-text builder/server scripts. There are no unrelated credential requests or surprising binaries declared.

Instruction Scope

SKILL.md instructs the agent to read documentation, scaffold a workspace, run generator and validation scripts, and optionally start an MCP server. These actions are in-scope for the stated purpose, but the guidance references running local Python scripts and an absolute path (/home/ubuntu/skills/portable-context-os/scripts/init_context_os.py) while the package includes .txt mirrors (source_text/*.py.txt). This packaging convention is documented in README but means the agent or user must rename/move files before executing; the absolute-path example could lead an agent to probe unexpected filesystem locations if followed literally.

Install Mechanism

There is no install spec and no network downloads in the package. The skill is instruction-only and includes plain-text copies of Python scripts and templates. That is the lowest-risk install model, though running the scripts will install or require dependencies (mcp[cli]) if the user chooses to run them.

Credentials

The skill does not declare required environment variables, credentials, or config paths. The optional generated MCP server has an example requirements file and optional env example, which is proportional to running a local service.

Persistence & Privilege

always:false (normal). The skill allows the agent to produce files and a runnable server binary if the user chooses to scaffold and run the server. Autonomous model invocation is permitted by default (platform default); this increases the impact if the agent is allowed to execute on the host, so run in a controlled environment.

Scan Findings in Context

[no_regex_findings] expected: The regex-based scanner had no findings — the package is instruction-only with text mirrors of scripts, so there was nothing executable for the scanner to analyze. The included source_text files are plain-text mirrors of builder and server scripts; their behavior should be reviewed before executing.

Assessment

This package is a developer-focused scaffold: it contains templates and plain-text (.txt) mirrors of Python scripts that can build a BYOC workspace and a small MCP server. Before running anything: (1) review the source_text files for any code you don't expect; (2) note that files are shipped as .txt mirrors (README explains this) — rename them back to .py and place them where you intend before executing; (3) run dependency installs (mcp) in an isolated virtual environment; (4) validate with --dry-run and inspect generated files (context_manifest.yaml, governance_policy.md, memory_objects/) before starting any server; (5) avoid running the server with network transports (streamable-http) on untrusted networks — it can expose local data; (6) the SKILL.md examples use an absolute path that may not match where you unpacked the package, so do not let an agent autonomously probe arbitrary filesystem locations to locate scripts. If you want extra assurance, run the scaffolding in an isolated VM or container and review the generated workspace for sensitive content before sharing or exposing it.

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.