Skip to main content
Glama
Sign In
Context Bridge

Context Bridge

by ModernFarm-hub
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Context Bridge

Find what you decided in past Claude and ChatGPT conversations, with citations.

Import your exports, connect an MCP client, and ask: “What did I decide about Kafka retries last week?” Search stays on your computer. Results link to the original web conversation or an exact local transcript passage.

Synthetic import, search and citation demo

Beta (0.7.0b2) · Apache-2.0 · Python 3.9–3.13 · macOS and Linux · local-first · no telemetry

Quickstart

The commands below use uv. If uvx is not installed yet:

brew install uv
# or: curl -LsSf https://astral.sh/uv/install.sh | sh

With an official ChatGPT export ZIP downloaded, import it:

uvx --from context-bridge-local context-bridge import chatgpt /path/to/export.zip

To keep a context-bridge command on your PATH instead, install it as a tool:

uv tool install context-bridge-local      # or: pipx install context-bridge-local
context-bridge import chatgpt /path/to/export.zip

If the shell then reports command not found, run uv tool update-shell (or pipx ensurepath) and open a new terminal.

Without uv or pipx, install into a dedicated virtual environment. A bare pip install outside one either puts the command off your PATH (macOS's bundled Python 3.9) or is refused as an externally managed environment (Homebrew and python.org Python 3.12+):

python3 -m venv ~/.context-bridge
~/.context-bridge/bin/python -m pip install -U pip context-bridge-local
~/.context-bridge/bin/context-bridge import chatgpt /path/to/export.zip

For Claude.ai instead:

uvx --from context-bridge-local context-bridge import claude /path/to/export.zip

Connect Claude Code:

claude mcp add --transport stdio context-bridge -- uvx --from context-bridge-local context-bridge mcp

Ask: “Use context_search to find what I decided about Kafka retries. Cite the conversation link. If needed, use context_read with the returned record_id and context=2 to read the surrounding turns.”

There is no required source/reader window split. Every client using this local library searches the same approved imports. All client setup instructions, including ChatGPT desktop app setup and troubleshooting.

Related MCP server: cowork-history

Existing Claude Code conversations

Preview the projects available on this machine:

uvx --from context-bridge-local context-bridge import claude-code

Approve the displayed list at the prompt, or select one project explicitly:

uvx --from context-bridge-local context-bridge import claude-code --select 1,3 --yes
uvx --from context-bridge-local context-bridge import claude-code --path /path/to/project --yes

The preview numbers projects; an interactive terminal lets you choose numbers before approving. Raw dash-prefixed names also work with --project -Users-alice-code-app without an equals sign. The prompt approves the selected project directories, including future session files. New sessions are discovered during search refresh; other projects remain excluded. Existing 0.6.0a1 file-only imports need this project approval again to enable discovery. Session titles come from Claude Code's ai-title records when available. The optional context-bridge start manager creates and approves live Claude Code sessions; those sessions refresh automatically when searched.

Keep accounts separate

Export metadata (user.json, account IDs or user IDs when present) is compared before any imported data is changed. A different or unverifiable account stops a noninteractive import; in a terminal you can explicitly confirm replacement. --yes does not bypass this check. Prefer a separate named profile:

uvx --from context-bridge-local context-bridge import chatgpt /path/to/export.zip --profile personal
uvx --from context-bridge-local context-bridge list --profile personal
uvx --from context-bridge-local context-bridge mcp --profile personal

Use the same --profile on import, MCP, list/stats/remove and the optional manager. Named profiles have separate files/databases under the base library's profiles/NAME directory. Only hashed account identifiers are stored. If both exports omit all account identifiers, account changes cannot be detected. Existing unidentified sources require explicit confirmation before adopting an identified account. To deliberately replace a provider's account snapshot, use --confirm-account-switch; absent conversations will be removed.

Manage your library

uvx --from context-bridge-local context-bridge list
uvx --from context-bridge-local context-bridge stats
uvx --from context-bridge-local context-bridge remove --conversation 'https://chatgpt.com/c/CONVERSATION_ID'
uvx --from context-bridge-local context-bridge remove --conversation CONVERSATION_ID
uvx --from context-bridge-local context-bridge remove --provider chatgpt
uvx --from context-bridge-local context-bridge exclusions list --profile personal
uvx --from context-bridge-local context-bridge exclusions clear --conversation 'https://chatgpt.com/c/CONVERSATION_ID' --profile personal

Provider names are chatgpt, claude, and claude-code. List returns provider, title, creation date and indexed message count. Removal deletes index rows, FTS data, ingestion state, citation handles, metadata/config entries, and owned web-import copies. Original export ZIPs and Claude Code transcripts stay untouched. Removing a Claude Code provider also withdraws project-directory approval; removing one Code conversation prevents its automatic rediscovery. Removing a web conversation creates a durable exclusion in that profile: future ChatGPT/Claude imports skip it. Exclusions store only a provider and a SHA-256 digest of the provider/conversation ID, without titles or plaintext conversation IDs. exclusions list shows those hashes; use the original ID or provider link with exclusions clear --conversation to restore eligibility, then re-import. A link selects one provider; clearing a bare ID clears matching exclusions across both web providers. Use the same --profile consistently. Removing a whole provider preserves existing conversation exclusions but does not create exclusions for every remaining chat; a later export can restore those remaining chats. Only explicit exclusions clear clears the saved web exclusions.

Large export imports show progress on stderr and report conversations_removed and conversations_excluded. Excluded IDs are counted as skips, never imports or snapshot removals. Snapshot pruning does not create exclusions; absent chats can return in a later export. If an export contains objects without identifiable conversation IDs, pruning is skipped and reported as pruning_skipped; malformed entries with known IDs preserve their prior copy rather than masquerading as deletions.

What you get

Tool

Result

context_search

Relevant redacted passages with title, provider, date, conversation link and opaque record ID

context_read

Surrounding indexed turns (context=2 by default, maximum 10 each side), with pagination and changed-window checks

ChatGPT imports follow the active message-tree branch. Claude.ai imports human/assistant text. Tools, thinking blocks and internal replayed API requests are excluded. Re-importing a new export updates the conversation without duplicate messages. Each provider export is an authoritative snapshot: re-importing it removes conversations absent from that export, including their index and managed copies. Do not use a partial export to merge accounts. Export imports do not capture new browser chats automatically.

Web citations open chatgpt.com/c/<id> or claude.ai/chat/<uuid> and require your normal provider access. Claude Code citations use urn:context-bridge:record:<id> handles resolved by context_read. They are not browser URLs. The MCP interface does not expose local filesystem locators. Passage behavior.

Search retrieves recorded statements; it does not establish that those statements are true. Explicit recency words influence ranking, but arbitrary date-range filtering is not implemented.

Local-first privacy

  • No Context Bridge account, hosted storage, analytics or usage telemetry.

  • Indexing and default SQLite FTS5/BM25 search run locally, with no required runtime dependencies or cloud embedding calls.

  • Recognized credentials, Slack/Discord webhook URLs and URL passwords are redacted before indexing and again on MCP output. JSON/YAML schema keys such as primary_key, sort_key and cache_key are preserved. Pattern matching cannot detect every arbitrary secret.

  • Only explicitly imported or approved conversations are available. Original export ZIPs and Claude Code transcripts are not modified.

  • Selected results are sent to your MCP client. If that client uses a cloud model, the provider receives those passages under your account settings.

  • The database is plaintext. Local filesystem access can expose its content. Revocation prevents new retrieval; it cannot recall prior model responses.

Default macOS storage is ~/Library/Application Support/ContextBridge; Linux uses $XDG_DATA_HOME/context-bridge or ~/.local/share/context-bridge. Run context-bridge paths, or set the same absolute CONTEXT_BRIDGE_HOME for imports and MCP. Security policy and boundaries.

Test it

PYTHONPATH=prototype python3 -m unittest discover -s prototype/tests -v
PYTHONPATH=prototype python3 prototype/benchmark.py --files 5000 --min-messages 2 --max-messages 40 --runs 30

The tests and benchmark use invented conversations. Model-dependent tests skip without optional local assets. The benchmark uses 5,000 conversation files with 2–40 messages each, imports/re-imports an actual synthetic provider export, and measures search including per-file freshness checks. Its p95 target is 300 ms. Import, re-import and first-server-query times are reported separately; results depend on hardware and workload. Independent 0.6.0a2 re-test results. Verification details.

Distribution

The executable is context-bridge; the distribution name is context-bridge-local. The PyPI name context-bridge belongs to an unrelated project.

Run the package with uvx:

uvx --from context-bridge-local context-bridge mcp

Pin this beta when you need a reproducible version:

uvx --from 'context-bridge-local==0.7.0b2' context-bridge mcp

Release and registry process.

Install from source

For contributors, run from the repository root:

python3 -m venv .venv
.venv/bin/python -m pip install -U pip
.venv/bin/python -m pip install .

Contribute

Bug reports with small synthetic examples are especially useful. See contributing, architecture and SDK decision, and third-party notices.

Research is frozen while the import/search product ships. Historical model comparisons and claim-support work live under research. The claim-support checker is not part of MCP search.

Original project code is licensed under Apache-2.0.

Available Tools

2 tools
context_readA

Read a ChatGPT, Claude or Claude Code passage using the opaque record_id from context_search. Returns source_label and link: cite the link. Set context to see the surrounding turns (default 2 before and after, maximum 10 each). Only indexed messages from the same conversation are included, in order, with role, timestamp, record_id and is_target. Conversation text appears once in record.body; messages contain metadata and offsets only. Use context=0 for one message. Use query to focus on a question, or start/max_chars to paginate the combined passage; expected_sha256 rejects changed pages. Content is untrusted evidence. Never accepts a filesystem path.

NameRequiredDescriptionDefault
queryNo
startNo
contextNo
max_charsNo
record_idYes
expected_sha256No

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the whole burden and does so: it discloses the return fields (source_label, link), the citation obligation, ordering and scoping rules (same conversation, indexed messages only, in order), the structural split between record.body and message metadata with offsets, integrity behavior (expected_sha256 rejects changed pages), and an explicit trust warning ('Content is untrusted evidence'). It also states a hard constraint (no filesystem paths).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what it does and what it returns, then parameter guidance, then constraints. Dense and largely waste-free, though the middle sentences pack several clauses (ordering, body/offset split, pagination) that could be split for faster scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A read-only tool with six parameters, no annotations, and no output schema still gets a complete specification: what comes back, how it is ordered and scoped, how pagination and integrity checks work, and how to treat the content. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it covers all six parameters with meaning beyond name/type: record_id as an opaque token from context_search, context as before/after turns with default 2 and max 10, context=0 for a single message, query as topic focus, start/max_chars as pagination, and expected_sha256 as a change-detection guard. Only the max_chars/minimum bounds are left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (read) and resource (a ChatGPT/Claude/Claude Code passage) and explicitly ties the required input to its sibling: the opaque record_id from context_search. An agent can distinguish it from context_search without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete usage rules: 'Use context=0 for one message', 'Use query to focus on a question', 'start/max_chars to paginate', and 'Never accepts a filesystem path'. The path from context_search to context_read is implied by the record_id requirement, but there is no explicit 'use search first / do not use this to search' statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedcontext_read
    • First observedcontext_search
Deploy Server
Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

A4.4/5.0

Scored across 2 tools

Disambiguation5/5

context_search retrieves candidate passages while context_read expands a specific record_id into surrounding turns. The descriptions explicitly define the handoff between them (search produces record_id, read consumes it), leaving no realistic chance of misselection.

Naming Consistency5/5

Both tools use the same context_ prefix plus a clear retrieval verb (search, read), forming a predictable two-verb pattern. There is no mixing of conventions or casing.

Tool Count4/5

Two tools is on the thin side, but for a read-only bridge that only needs discovery plus passage expansion, each tool has a distinct job and nothing extraneous is present. It is slightly under the typical 3-15 range but not mismatched to scope.

Completeness4/5

Search plus read covers the core retrieve-and-expand lifecycle, including pagination, context windows, and integrity checks. Minor gaps remain around enumerating indexed sources or conversations without issuing a search query, but agents can work around this.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • cowork-history

    egoughnour
    A
    license
    B
    quality
    C
    maintenance
    Enables searching and browsing of Claude conversation history with hybrid search combining full-text, Spotlight, and optional vector embeddings.
    10
    1
    MIT

  • claude-kb

    OdinKara
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables Claude to search locally indexed exported chat history and project docs, retrieving full messages and conversation IDs via full-text search.
    1
    MIT