The Problem

AI agents lose session context the moment a conversation ends. Cursor, Claude Code, and Codex each maintain isolated, ephemeral transcripts — no structured memory, no cross-client persistence, no portable identity. Re-onboarding means re-explaining the same architectural decisions, preferences, and codebase context every time. SharedContext addresses this by providing a local-first, encrypted memory layer that persists across sessions and machines, synced via Arweave so the agent's context travels with the user.

What This Does

SharedContext is an MCP server that AI clients connect to for fact storage and conversation recall. It consists of a TypeScript codebase (37 files) organized into core modules (src/core/) and CLI/tools (src/cli/). A background watcher (src/core/watcher.ts) monitors conversation directories — Cursor, Claude Code, and Codex transcripts — and feeds facts into SQLite (src/core/db.ts), which stores three tables: facts, pending_deletes, and meta. Encryption happens client-side via src/core/crypto.ts (AES-256-GCM with Argon2id-derived keys), and synced facts become Arweave upload operations through src/core/arweave.ts. Identity is derived from a 12-word recovery phrase into a secp256k1 keypair (src/core/identity.ts), with the private key stored encrypted in the OS keychain. The MCP server entry point is src/mcp/server.ts, which exposes tools for fact management, conversation retrieval, and shard sync.

How It Is Wired

Execution starts at src/core/watcher.ts:137 (the start entry point), which discovers conversation files and feeds them into the system, but the primary operational flow begins when the MCP server starts: startMcpServer (src/mcp/server.ts:59) reaches 15 functions and is called from 1 place. The critical data path is startMcpServer → openDatabase → initSchema [db via db.exec], followed by syncDirtyFacts → setMeta [db via db.prepare("INSERT INTO meta (key, value) VALUES (?, ?)"]]. The import graph contains 3 circular dependencies: src/cli/util.ts, src/cli/init.ts, and src/cli/setup.ts — participants in a mutually reachable cycle that complicates changes. The hub module is src/types.ts, depended on by 16 other modules; volatility here has blast-radius effects. The most connected functions are openDatabase (10 call sites), setMeta (5 call sites), and decrypt (6 call sites). The oversized file is src/core/bip39-words.ts at 2050 lines, hard to modify without wide ripples. Two files have high branching density: src/core/arweave.ts and src/core/parsers/claude-code.ts (134 branch points over 475 lines). Duplicated 6-line blocks appear across src/cli/init.ts, src/test/passphrase.test.ts, src/core/parsers/claude-code.ts, and src/core/parsers/cursor.ts.

How To Use It

Setup:

pnpm install

No build script is defined beyond tsc; the project compiles to TypeScript. The package.json implies pnpm is the package manager.

Configuration: No environment variables or config files are present in the detected structure. The README references ~/.sharedcontext/identity.enc for encrypted key storage and OS keychain for the recovery phrase, but no .env or config file is documented in the repo.

Running it:

pnpm start

or via the MCP server entry point. The CLI commands are defined in src/cli/ — init, share, list, sync — but the exact invocation pattern (e.g., sharedcontext init) is not mapped in the repository structure beyond the source files.

Real-World Use

An AI agent running through Cursor connects to the SharedContext MCP server. The user runs sharedcontext init to establish an identity (12-word phrase → secp256k1 keypair → encrypted keychain storage). As the agent works, it stores structured facts via MCP tools — e.g., storeFact({key: "arch.decision", value: "use tRPC", confidence: 0.9}) — which write to src/core/db.ts and mark dirty for sync. A background loop in src/core/sync.ts collects dirty facts, converts them to shard operations (buildShardTags, pushShard), and uploads encrypted blobs to Arweave via src/core/arweave.ts. On a new machine, the user recovers the same context by entering the 12-word phrase, which derives the same keypair, decrypts the stored identity, and restores the SQLite schema and Arweave-synced data. To share a conversation, the user invokes sharedcontext share, which encodes an encrypted token (src/cli/share.ts:encodeShareToken) the recipient imports with one command.

Code Health & Issues

  • [HIGH] Add a LICENSE — no licence file at the repository root; redistribution rights are undefined, so this code cannot legally be reused.
  • [HIGH] Add a CI/CD workflow — 37 source files, no CI configuration; every change merges with nobody having run the build.
  • [MEDIUM] Enable Dependabot or Renovate — 1 manifest, no update bot configured; published advisories sit unpatched until manual audit.
  • Import cycle members: src/cli/util.ts, src/cli/init.ts, src/cli/setup.ts participate in circular dependencies, limiting refactor safety.
  • Oversized file: src/core/bip39-words.ts at 2050 lines increases cognitive load and ripple risk.
  • High branching density: src/core/arweave.ts and src/core/parsers/claude-code.ts (134 branch points over 475 lines) decompose poorly.
  • Duplicated code blocks: 3 repeated 6-line patterns across 6 files (src/cli/init.ts, src/test/passphrase.test.ts, src/core/parsers/claude-code.ts, src/core/parsers/cursor.ts, etc.).

The Bottom Line

This is a functional local-first memory layer for AI agents with solid encryption, SQLite sync, and Arweave persistence — the kind of infrastructure that saves real time when running across multiple clients or machines. The import cycles, missing license, and absent CI are blockers for team adoption or client engagements, but the core design is sound and the test coverage (10 test files) gives confidence the logic works. Use it if you need portable agent memory and are comfortable running the sync infrastructure yourself; hold off until a license and CI gate are in place for anything beyond personal experimentation.