Portable Context

A shared memory operated through your agent: import selected conversations, preserve native relationships, build an evidence-linked Markdown wiki, and continue the work from another client.

Status: 0.2, with a tested two-client MCP workflow and synthetic fixtures. No personal account exports or native agent installations have been tested yet. This is not a promise to recover deleted, hidden, inaccessible, or unexported context. See coverage and gaps.

Start with the user journey · Русское введение · Connector coverage · Data contract · Agent skill

Architecture

flowchart LR
    U[User request] --> A[Agent + skill]
    A <--> M[MCP workspace]
    X[Local exports / host history tools] --> J[Selected import jobs]
    M --> J
    P[Optional collector outbox] --> J
    J --> S[Messages + revisions + structural graph]
    S --> E[Resumable enrichment tasks]
    A <--> E
    E --> W[Wiki + semantic graph + citations]
    W --> O[Obsidian]
    S --> O

MCP receives only what the client sends. Connecting MCP alone does not record conversations. Continuous capture requires a collector, persisted-message hook, or periodic export. Original transcripts, manually curated memory, and model inferences stay distinguishable. No external model, embedding service, telemetry, or API key is required by the core. The connected agent performs semantic analysis using its own model. Native history access is a separate capability; an MCP connection does not grant an application's full account history.

Related MCP server: knowledge-base-server

Install

Python 3.11+ with SQLite FTS5. From this repository:

python -m venv .venv
# Linux/macOS:
. .venv/bin/activate
# Windows PowerShell instead:
# .\.venv\Scripts\Activate.ps1
python -m pip install -e ".[mcp]"
portable-context --home /absolute/private/memory init

The core also runs without dependencies: python -m pip install -e .. Keep the memory directory outside this public repository. It contains private originals, messages, media inside ZIPs, and notes. .gitignore is a backup precaution, not a privacy boundary.

Ask your connected agent

Explain how to use this memory and what history you can access.

Import the Atlas conversations and their forks.

Build a wiki of the decisions, then connect related topics.

Resume the work from the other agent and add new discussions.

memory_status identifies the shared workspace and actual source access. preview_source lets the agent select conversations. Import and enrichment are separate resumable jobs. The agent can read complete source revisions, update existing pages with conflict checks, and commit typed links. Read the complete user journey before configuring individual adapters.

Register a source once

For a server-local file, explicitly register it with the local CLI:

portable-context --home /private/memory connect claude-personal --format claude --instance claude-personal --location /private/exports/claude.zip
portable-context --home /private/memory preview claude-personal

Alternatively, allow an export folder using repeatable mcp --source-root /private/exports or PC_SOURCE_ROOTS (OS path-list separator); the connected agent can then register files inside it. MCP local paths refer to the server, not the remote client's disk. Hosts with their own history tools register a host source without a path, then send selected records through stage_records.

Selection-aware jobs retain selected normalized records and raw message fields only. They never copy a mixed source ZIP containing unselected chats. Small text exports can use stage_export; larger exports should be registered server-locally or sent as selected record batches by a host bridge.

Legacy full-archive import and inspection

An instance is a stable, non-secret account/device/server name. Reuse it on later imports; give distinct instances distinct names. Do not use a new random name for each run.

portable-context --home /private/memory import claude-export.zip --format claude --instance claude-personal
portable-context --home /private/memory import chatgpt-export.zip --format chatgpt --instance chatgpt-personal
portable-context --home /private/memory import result.json --format telegram --instance telegram-personal
portable-context --home /private/memory import takeout.zip --format gemini --instance gemini-personal
portable-context --home /private/memory import /path/to/codex/sessions --format codex --instance codex-laptop
portable-context --home /private/memory search "project name"
portable-context --home /private/memory stats
portable-context --home /private/memory vault

Open /private/memory/vault as an Obsidian vault. INDEX.md links conversations, the graph and wiki. wiki/*.md contains agent-maintained knowledge with source revisions; memory/*.md preserves legacy 0.1 notes. Manual edits are immediately visible through the corresponding MCP read tools. Generated transcript edits are preserved: subsequent projections write .incoming.md and report conflicts. Merge them manually if wanted. No Obsidian plugin is required.

Reports show inserted/revised/unchanged counts, source archive hashes, warnings and errors. Each input member is transactional. Errors yield exit code 1; successful earlier members remain committed, and originals remain available for inspection. ZIP imports retain all media in the original ZIP; directory imports retain selected data files only. No attachment OCR or extraction yet. A single text file/member is limited to 128 MiB; selected ZIP members total at most 512 MiB.

Connect an agent

Use the absolute executable from the environment where the package is installed:

{
  "mcpServers": {
    "portable-context": {
      "command": "/absolute/repo/.venv/bin/portable-context",
      "args": ["--home", "/absolute/private/memory", "mcp"]
    }
  }
}

This is the common MCP shape, not a claim that every host uses the same configuration file. Windows command example: C:\\tools\\portable-context\\.venv\\Scripts\\portable-context.exe. For Codex, the corresponding TOML section is:

[mcp_servers.portable_context]
command = "/absolute/repo/.venv/bin/portable-context"
args = ["--home", "/absolute/private/memory", "mcp"]

Main workflow tools: memory_status, connect_source, preview_source, start_import, stage_records, run_import, get_job, start_enrichment, claim_enrichment, read_source_revision, search_wiki, read_wiki, commit_enrichment, inspect_graph, check_memory, refresh_vault. The 0.1 message and note tools remain compatible. Call schemas and examples are in the skill protocol reference.

Install/copy the skill into your agent's supported skills directory, or use its instructions directly. It describes citation and memory-writing practice; it is not a substitute for a collector or a native plugin for every host.

For a server shared by your agents, set PC_MCP_TOKEN to a random secret (at least 24 characters) and use mcp --transport streamable-http --port 8766. Clients send Authorization: Bearer <token>. It binds 127.0.0.1 only: use an SSH tunnel or HTTPS gateway for remote clients. This is bearer authentication for clients that support custom headers; OAuth-only web clients need a compatible gateway. No OAuth issuer is bundled. --allow-unauthenticated-local explicitly opts out on trusted loopback setups. This is a single-owner workspace; sources and filters are not per-user ACLs.

Optional continuous capture

The primary workflow is on demand. Existing source integrations can use enqueue_batch and /v1/batches to feed exactly the same resumable import jobs as interactive clients. Register the producer as a host source first. Automatic capture and automatic semantic reasoning are separate: new data becomes pending work, and a connected agent can enrich it later. No background model worker or native capture hook is installed by default.

For local JSONL sessions (not Codex's newer paginated storage):

portable-context --home /private/memory watch /path/to/codex/sessions --format codex --instance codex-laptop

Run a second watcher for archived sessions. --once is suitable for a scheduler. A file hash checkpoint is saved only after commit. Incomplete JSONL files are retried on the next pass. The first version rescans changed files and archives complete snapshots: robust for moderate histories but potentially expensive for large growing logs. Set a sensible interval and monitor disk. Vault projection is explicit (vault / refresh_vault); database search is current immediately.

For Ouroboros or another controllable agent, call the producer example from the point where the agent has persisted a message. See examples/producer.py. Each server has a separate instance ID and a private outbox. An independent worker retries delivery:

# Set PC_INGEST_TOKEN to the same random secret on receiver and producer.
portable-context --home /private/memory serve-ingest --port 8765
portable-context flush --outbox /private/outbox --endpoint http://127.0.0.1:8765 --loop

For separate servers, forward loopback via SSH or an authenticated HTTPS proxy. The receiver binds loopback and requires a bearer token of at least 24 characters. Generate it locally with python -c "import secrets; print(secrets.token_urlsafe(32))"; don't commit or paste it into chat. Completed batches become .sent; failed batches remain .json. Stable message IDs make retries idempotent. Run one delivery worker per outbox. A service manager must restart workers after crashes/reboots; this package does not silently install background services.

The producer adapter and shared-job delivery are functional, but wiring them into a particular Ouroboros/Hermes/OpenClaw version is a deployment task. No native integration is claimed tested in this release.

Portability and recovery

portable-context --home /private/memory export /private/current-events.jsonl
portable-context --home /private/memory export /private/all-revisions.jsonl --revisions

The JSONL contract preserves roles, IDs, branches, timestamps, attachment references, and raw message fields. A complete backup is the whole memory directory: SQLite, originals and vault. Stop writers before a filesystem copy, or use SQLite's backup API and separately back up originals and Markdown. JSONL alone does not include originals, wiki/semantic graph history, jobs or import audit metadata. There is no account-wide sync, encryption, retention/deletion UI or multi-user isolation yet.

Upgrading from 0.1 adds tables and backfills structural links from current records. Legacy notes and originals are preserved. Back up the complete memory directory before upgrading; do not run an older writer against an upgraded memory. Wiki database commits are authoritative and Markdown projection can be repaired with vault after a crash. Manual file edits require reconciliation.

Development

python -m pip install -e ".[mcp]"
python -m unittest discover -s tests -v

Tests use generated synthetic records only. They exercise replay, revisions, transaction rollback, parallel writers, branch preservation, Unicode search, manual edits, original ZIP retention, watcher recovery, authenticated delivery, two-client handoff, selective-import privacy, leases, wiki/graph transaction rollback, stale source detection and authenticated HTTP MCP.

python examples/agent_workflow_demo.py --home /new/private/demo-directory

The demo is scripted synthetic content; it does not make model calls or access real accounts.

MIT licensed. Contributions should include anonymized minimal fixtures for schema differences; never attach real conversation archives to public issues. Read CONTRIBUTING.md.