sharedcontext

SharedContext is an MCP server that provides a local-first, encrypted memory layer for AI agents. It stores structured facts, recallable conversations, and enables encrypted, cross-machine memory persistence by syncing data to Arweave. Agents interact with the MCP via the available tools exposed by the package (store_fact, recall_context, recall_conversation, and share/recover flows). To get started, install the CLI, initialize SharedContext on a machine, and let the MCP auto-detect and configure connected AI clients (Cursor, Claude, Codex). Once running, your agent can store facts like preferences or architectural decisions, recall relevant context on demand, and retrieve past conversations for continuity across sessions and devices. The system supports sharing a specific conversation through an encrypted link, and you can restore your entire context on a new machine using a 12-word recovery phrase.

Core capabilities include:

• Fact memory: store and recall structured facts with tags and scope
• Conversation recall: fetch past conversations to continue discussions
• Encrypted sync: all data is encrypted locally before upload
• Arweave persistence: encrypted shards are stored permanently on Arweave
• Cross-machine restore: recover context via a 12-word phrase
• Share context: securely share conversations via encrypted links
• Auto-setup: automatic configuration for detected AI clients on init

Prerequisites:

• Node.js and npm installed on your machine
• Access to npm (or ability to install global npm packages)

Installation steps:

1. Install the SharedContext CLI globally (recommended):

npm install -g ai-sharedcontext

2. Initialize SharedContext on the local machine (creates config and identity; auto-detects clients):

sharedcontext init

3. Start or ensure the MCP server is available to your AI clients. Depending on your setup, you may run via the CLI or an orchestrated process. For the MCP integration in this repository, you can verify the CLI is accessible:

sharedcontext --help

4. If you prefer using npx to run without a global install:

npx -y ai-sharedcontext init

Notes:

• The first run generates a 12-word recovery phrase. Store it securely; it restores your context on another machine.
• This server relies on client-side encryption and Arweave for persistence. Ensure you have network access for initial syncs.

Tips and considerations:

• Security: your phrase and private keys are stored locally; the recovery phrase is the only way to reconstruct context on a new machine.
• Offline usage: reads are performed locally; write/sync operations occur when online.
• If you encounter issues with auto-setup, you can manually configure clients using the provided setup commands (e.g., sharedcontext setup --cursor, --claude, --codex).
• Sharing a conversation produces a URL token that unlocks an encrypted blob on Arweave; the recipient must use the URL to import the shared data.
• Environment considerations: ensure Arweave access is available for shard uploads; there are no per-user API keys required for normal operation.