Portable Agent Memory: Do Not Lock Context Into One Harness

Readable files do not guarantee recall

After months with one coding agent, you may have taught it why invoice retries need an idempotency key, which test environment is unreliable and how you prefer review comments. Switching harnesses exposes a dependency: some of that knowledge may live outside the repository and outside the next agent’s startup routine. The files can still exist while the new session behaves as though those conversations never happened.

Claude Code’s memory documentation distinguishes authored instructions from automatically recorded notes. Its default auto-memory directory is ~/.claude/projects/<project>/memory/, with a MEMORY.md index and topic files. The documentation describes those notes as machine-local Markdown. Cursor’s rules documentation instead describes project instructions in .cursor/rules, using .mdc files and inclusion metadata. These are readable representations with different loading conventions.

The architectural consequence is that copying text addresses storage portability. Preserving useful recall also requires an explicit loading contract. Treat those as separate acceptance criteria when choosing where accumulated context belongs.

Give remembered facts an identity outside the harness

Start with records whose meaning survives the loss of the original conversation. A useful memory explains the fact, where it applies, who owns it and what evidence supports it. “Retries are dangerous” is too vague. “The billing importer’s retry path must preserve the original idempotency key, according to decision ADR-42” gives another agent something it can check.

The following is a proposed export record for a hypothetical project, not an MCP standard or a vendor’s memory schema:

{
  "schemaVersion": 1,
  "id": "billing/retry-idempotency",
  "scope": "workspace",
  "project": "billing-importer",
  "owner": "payments-team",
  "kind": "decision",
  "body": "Retries preserve the original idempotency key.",
  "source": "docs/decisions/ADR-42.md",
  "reviewedAt": "2026-10-27",
  "status": "active"
}

Keep these fields through every export and import. Stable identifiers let a correction update the same memory rather than create a competing copy. Preserve readable text even if retrieval also uses embeddings; otherwise replacing the embedding model becomes entangled with recovering what the team actually recorded.

Put access behind a contract each client can use

For one developer on one machine, an explicitly configured shared directory may be sufficient. When the same context must reach laptops, disposable VMs and CI jobs, a remotely accessible service avoids making a home-directory copy the distribution mechanism. The service should own record storage and access checks; each harness should own only its connection and loading behavior.

MCP supplies a documented tool interface. In the 2025-11-25 tools specification, clients discover server-defined tools with tools/list and invoke them with tools/call. The server’s schemas define memory operations; the discovery method does not establish a universal memory format.

Claude Code documents this command shape for an HTTP server. Replace the example hostname with your deployed memory service:

claude mcp add --transport http team-memory https://memory.example.com/mcp

For an OAuth-enabled service, complete authentication through /mcp in an interactive Claude Code session. Registering the endpoint establishes access. Verify separately that the client discovers the intended retrieval tools and that the agent uses them for a question whose answer exists only in the memory store.

Keep the loading adapter smaller than the memory

Define a small adapter contract for every harness you support: identify the calling person and project, obtain a bounded memory index, retrieve relevant records, and present their provenance alongside their contents. The implementation can differ between clients. What must remain stable is the meaning of the selected records and the access boundary around them.

Keep this adapter free of the accumulated project knowledge. If a client-specific instruction file contains hundreds of remembered decisions, switching clients still requires translating that file. Prefer a short instruction explaining when to retrieve context and where authoritative project documentation lives. For the instruction-file side of this boundary, see keeping agent instructions in sync.

Also specify what happens when retrieval fails. A practical policy is to report that remembered context is unavailable and continue only where the task can proceed without it. An empty search result and an unreachable service must be distinguishable during migration testing; otherwise a broken adapter can look like successful recall with nothing relevant to say.

Migrate decisions, then rehearse a switch

Do an initial migration around a small set of useful facts rather than a complete transcript archive. Choose decisions the replacement harness cannot reliably infer from source code: a deployment exception, a customer-specific constraint approved by the team, or a preference the developer repeatedly corrected. Review their scope before importing them.

1. Inventory the original harness’s memory files and identify which records are personal, shared or obsolete. Keep a read-only snapshot while checking the migration.
2. Normalize the selected records into the export representation. Preserve source references and mark uncertain claims for review instead of silently strengthening them.
3. Connect the replacement harness with read access. Use a fresh session and working directory without the original memory directory available.
4. Ask project questions without including the answers in the prompts. Record which memory identifiers were retrieved and whether the response retained the original qualifications.
5. Correct one record, then repeat the question in both harnesses. Check that neither presents its stale local copy as the current decision.

For example, ask what must remain stable when retrying an invoice import. Success requires retrieving the idempotency decision and its reference, not merely producing plausible advice about retries. The memory recall evaluation guide develops that distinction further.

Preserve ownership when context changes hands

Portability should preserve the audience of a memory. A developer’s preference about review tone can stay personal; an approved billing constraint can be shared. A replacement harness should receive records because its caller is allowed to read them, not because the migration flattened everyone’s notes into one directory.

Start the replacement client with retrieval access and enable writes deliberately. Define how conflicting updates are reviewed before two agents can revise the same decision. Keep recalled observations distinguishable from authored instructions: a transcript-derived note about a past workaround should not silently become permission to bypass today’s deployment checks. These are design requirements for the memory service and adapter, rather than properties obtained merely by choosing Markdown or MCP.

Keeping context reachable through SPYN3

SPYN3 exposes opt-in workspace memory and skills through MCP tools including context_list, context_read and context_search at https://api.spyn3.com/agent/mcp. Personal and shared memories use separate paths. Reads need call:tools; writes need write:memory. Any MCP client can use the tools. Its Claude Code and Codex plugin adds automatic recall through lifecycle hooks; other clients need their own loading behavior. To try this approach, an admin enables Memory & skills in Settings, then connects a client to the workspace endpoint.

Make departure part of the acceptance test

Before making any memory store authoritative, export the trial records and read them without its original harness. Recreate the retrieval workflow with a second client, preserve the ownership fields, and verify that a correction reaches both clients. If replacing the store would require recovering facts from opaque session state, the exit path is incomplete.

The test is practical: can a fresh agent explain the billing retry decision, show where it came from and notice when it changes? Passing that test makes the accumulated knowledge useful beyond the tool that first recorded it. For the broader architecture connecting tools and remembered context, continue with an agent-agnostic context layer.