Using Claude Code seriously has made me think people use the word “portable” too loosely when they talk about agents.Copying a prompt is not portability.Exporting a transcript is not portability.Shipping a full machine snapshot usually isn’t portability either.Once you start working with things like AGENTS.md, MCP servers, repo-local tools, and long-running coding workflows, the question becomes more concrete: if I move an Agent to another machine or environment, what is actually supposed to survive the move? Its operating rules? Its recent continuity? Its durable knowledge? Its tool / MCP structure? Its identity? Its secrets? Its raw runtime state? In a lot of setups, there isn’t a clean answer, because those layers are still blurred together. My current view is that portability is mainly a state-architecture problem, not a packaging feature. For something I’d call a portable Agent, I want at least these layers to be clearly separated:policy: the standing instructions and operating rulesruntime truth: what the runtime actually owns about executioncontinuity: the short-horizon context needed to safely resume workdurable memory: facts, procedures, preferences, and references that deserve to survive beyond a single runIf those layers all collapse into transcript history or one generic “memory” bucket, portability gets weak by definition.The reason I’ve been thinking about this so much is that a repo I’ve been building forced me to make those boundaries explicit in a way that feels pretty relevant to Claude Code style workflows.Roughly speaking, the split looks like:human-authored instructions in AGENTS.mdruntime plan/config in workspace.yamlruntime-owned execution truth centered in state/runtime.dbdurable readable memory under memory/ What I like about that split is that each layer is allowed to mean something different. AGENTS.md is an operating surface for human-authored instructions. workspace.yaml describes the runtime shape. state/runtime.db is where runtime-owned execution truth lives. memory/ is not “the whole transcript” but a durable memory surface with readable bodies. That feels like a much better starting point than the usual “chat history + retrieval + tool calls” blob. The conceptual distinction that matters most to me is: continuity is not the same thing as memory. Continuity is about safe resume. Memory is about durable recall. Portable systems need both, but they should not be treated as the same job. If one layer tries to fake both, the Agent either forgets too much or drags too much stale context forward. My own default split is: Should move:policy / operating shapetool and app structureselected durable knowledge Should usually stay local:raw scratch stateauth artifactslocal secretsevery transient execution detail I am not claiming this problem is solved. The repo still has obvious caveats. Some flows still depend on hosted services. Desktop platform support is still uneven. And the current workspace runtime is centered around a single active Agent, not some fully general multi-agent system. But that is also why I think it is a useful case study. Not because it proves portable Agents are solved. More because it makes the category inspectable. So my current view is: a portable Agent is not just an exported prompt, not just a transcript, and not just a zipped repo. It is an Agent whose operating context has a clean enough state model to survive movement. To me that makes “portable” an architecture term, not a marketing term. Curious how people here think about this in Claude Code style setups.If you had to define a portable coding Agent rigorously, what should move with it by default, and what should stay local?I won’t put the repo link in the body because I don’t want this to read like a promo post. If anyone wants to inspect the implementation, I’ll put it in the comments. The part I’d actually want feedback on is the state model itself: what belongs in instruction files, what should stay runtime-owned, why resume context is not the same thing as durable memory, and which pieces should never travel across machines. submitted by /u/Dangerous-Guava-9232
Originally posted by u/Dangerous-Guava-9232 on r/ClaudeCode