Portable Context
Projects the memory workspace into an Obsidian-compatible vault with INDEX, conversation, graph, and wiki Markdown files, allowing users to browse and edit the shared memory in Obsidian without requiring a plugin.
Imports Telegram export JSON files into the shared memory workspace, making selected conversations searchable and available for downstream wiki enrichment and graph linking.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.9.0. Mixed-message authorship, selective wiki review and resume, bounded dialogue evidence, and efficient repeat delivery. See release notes. See 0.8 upgrade notes and the approved backlog. Self-contained restic recovery, storage controls and selected project folders remain supported. A real Codex conversation has been imported into the owner-operated Cloud.ru pilot. Broader provider adapters still depend on available exports and fixtures. 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
Start with your assistant
Send your assistant this repository link and say: “Help me start using Portable Context.” The assistant should read the skill, help you connect an existing memory or create a new one, and guide you one step at a time. It can also help if you are unsure whether you already have a memory. Automated installation needs terminal and file access; otherwise the assistant can guide the manual steps. Each user connects their own storage.
For local Claude Code sessions or selective claude.ai archives, use the client guide. The client prepares selected data on your computer; the MCP server stores it in your existing memory. See the 0.7 release and migration notes, recovery and folders and capture controls.
Related MCP server: knowledge-base-server
Deploy your own memory
Ask an agent with terminal access: “Install this skill and deploy my memory in my Cloud.ru account” or “Set it up on my existing server.” Follow the agent deployment guide (Russian).
The installer in deploy/setup.py provisions a VM, persistent disk, restricted SSH access,
private S3 bucket and bucket-scoped backup credentials. It separates a reviewed paid Terraform
plan from apply, keeps state on the owner's computer, and resumes failed server installation.
The desktop agent connects over SSH/stdio; no domain or public HTTP MCP is required. Existing
Linux servers use the same installer without Terraform. Each owner runs and pays for their own instance.
bootstrap verifies pinned Terraform/provider downloads. install verifies backup restoration
(including an S3 upload/download when configured), and check verifies the MCP workspace identity.
Credentials, state and personal data must remain outside this repository. A real Cloud.ru pilot
has verified provisioning, Windows-to-Linux MCP access, S3 upload/download/restore, and daily cron setup.
This is one tested account/configuration, not coverage of every region, image or client.
Automatic setup targets Ubuntu 24.04 / Linux with Python 3.11+, OpenSSH and cron.
Client setup, local imports, memory and MCP support Windows, macOS and Linux. The CI matrix covers macOS on Intel and Apple Silicon, Windows x64, and Linux x64; core tests also run on Linux ARM64. Cloud.ru provider 2.1.6 has no native Linux ARM64 binary, so provision from a supported client or use the existing-server SSH path. The managed server installer targets Linux.
For VPN access, deploy/network.py provides inspect, plan, apply, repair and remove
on all three client OSes. It uses exact IPv4 host routes, records ownership, preserves unrelated
routes, and refuses stale plans. Changes require OS administrator/root privileges. After reboot
or a network change, run a fresh repair plan; no privileged background service is installed.
See the network guide.
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 --> OMCP 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.
Install
First choose where memory and MCP will live: storage and setup guide
(Russian, with runnable local/server examples). Each user runs their own instance; this repository
does not provide hosted storage. SQLite runs on the server filesystem; optional S3 holds verified
attachment objects and backup archives. MCP-only clients can read portable-context://setup.
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 initThe 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.
Capture files while their context is available
The exporter preserves project identity, file purpose/role/status and exact source-message revisions
before losing source access. Every imported attachment gets a passport, including missing files;
every conversation gets a project entry (explicitly unclassified if no project is known).
Use memory_project for user selection or agent inference; native project remains source evidence.
python -m portable_context.capture create --records selected.json --destination private-capture --source-root /authorized/files
freezes selected normalized records, referenced local files, project pages and file passports into a
portable directory. It does not crawl the workspace. Transfer the directory to the memory server and
call import_file_capture, or stage records and use store_attachment for each selected original.
See the file capture and retrieval guide for exact shapes,
cross-platform commands, limits and S3 configuration.
Byte-identical files share one SHA256-addressed original; filenames never prove identity or finality.
Each original is included in backups. The owner-operated installer also enables private S3 objects at
attachments/<sha256> using the existing bucket; successful transfer verifies downloaded bytes.
Record-job completion, original transfer, S3 delivery, text extraction and wiki enrichment are separate
states. Import reports expose missing originals rather than silently treating references as uploads.
Recall starts with list_projects / read_project, then list_files / read_file, bounded text search
and excerpts, and original bytes only when needed. UTF-8 text files <=2 MiB have automatic extraction;
PDF/Office/images/audio require an external extractor or agent through add_file_excerpts, with a
page/sheet/frame locator and method attribution. No bundled universal OCR is claimed.
Backups currently contain full copies of registered originals. Deduplication within the live store does not deduplicate successive ZIPs. The installer retains seven local archives; remote retention remains owner-configured. Bulk multi-gigabyte imports should account for this storage multiplier.
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-personalAlternatively, 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 vaultOpen /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-laptopRun 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 --loopFor 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 --revisionsThe 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 whole-directory filesystem copy. Alternatively, python -m portable_context.backup
creates a consistent SQLite snapshot, copies referenced originals, and keeps Markdown in a separate
recovery folder; restore validates checksums and regenerates the canonical wiki in a new directory.
Optional .[backup] dependencies enable S3 delivery. 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 -vTests 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-directoryThe 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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Hosted agent memory: store, search, and recall facts across sessions from any MCP client.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to share persistent, self-improving memory by ingesting, classifying, synthesizing, and retrieving knowledge from sources such as Obsidian vaults, code, transcripts, bookmarks, and terminal sessions through MCP and REST APIs.10 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to share persistent, self-improving memory by ingesting, classifying, synthesizing, and retrieving knowledge from Obsidian vaults, code, documents, transcripts, bookmarks, and sessions through MCP and REST interfaces with token-optimized search.10 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to share persistent, searchable memory by capturing, classifying, synthesizing, and retrieving knowledge from sources like Obsidian, code, transcripts, bookmarks, and sessions via MCP and REST with token-optimized context.10 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to share a persistent, self-improving memory by ingesting sources such as Obsidian vaults, code, transcripts, and bookmarks, then classifying, promoting, synthesizing, and retrieving that knowledge through token-optimized search across MCP and REST interfaces. Agents can capture sessions and fixes so context compounds across sessions and across Claude, Codex, Gemini, and any other MCP client.10 npmMIT