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.

SituationActionBuilding a new context systemFollow the Creation workflow and run the builder scriptAuditing an existing agent or productFollow the Audit workflowPackaging or migrating context between tools or teamsFollow 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:

bash

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:

OutputPurposecontext_manifest.yamlArchitecture, ownership, routing, and runtime definitiongovernance_policy.mdMemory rules and policy surfaceeval_scorecard.mdEvaluation and feedback-loop baselinefeedback_log.mdRetrieval misses, corruption risks, governance failures, portability failuresmemory_objects/Typed memory storageartifacts/First-class artifact storetools/build_context_bundle.pyLocal bundle rebuild utilitymcp_server/server.pyWorking MCP server scaffoldmcp_server/requirements.txtRuntime 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:

bash

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:

bash

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:

CapabilityWhy it mattersDescribe context systemConfirms the server sees the manifest and workspaceList memory objectsEnables typed retrievalGet memory objectEnables precise inspectionUpsert memory objectEnables writeback into the context vaultDelete or tombstone memory objectEnables governance and forgettingList artifactsPreserves artifacts as first-class memoryBuild portable bundleKeeps portability live, not theoreticalAppend feedback logMaintains 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:

DeliverablePurposecontext_manifest.yamlArchitecture, ownership, interfaces, and routing summarymemory object definitionsTyped memory modelgovernance policyRules for creation, retention, access, and deletionevaluation scorecardRetrieval, portability, and trust metricsportable bundle manifestReviewable handoff and migration artifactworking MCP server scaffoldLive 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.