Skip to main content

context-bridge — session memory for AI coding agents

Index. Retrieve. A local-first context layer for the agents you already use.

CI License PyPI Downloads Stars Python Release


The problem

Every AI coding agent forgets between sessions. You re-explain the project, restate architecture decisions, and re-teach preferences every time you start a new one. Notes scattered across sessions are hard to search.

What it does

context-bridge reads the session logs your agent already writes, indexes them into a local SQLite database, and retrieves the relevant context when you start a new session.

It is a manual, offline tool:

  • you run index yourself, when you want — nothing is captured automatically;
  • it never phones home — no cloud, no API keys, no vendor lock-in;
  • the database stays in your home directory.

Supported log formats

Agent Format Recognised by
Claude Code .jsonl, one JSON object per line type is user or assistant
Codex .json, one document with an entries list entries is a list
OpenCode .jsonl, one JSON object per line a top-level message object
Hermes markdown or plain text any non-.json/.jsonl suffix

Format detection reads the file's content, not its path: living under .hermes/ does not make a file a Hermes log. A file whose format cannot be recognised raises an error instead of being silently read as the wrong format.

Limits

  • Per-event cap. Each event's text is truncated to 10 000 characters before it is stored. A very long response is indexed only in part.
  • Only text is indexed. Non-text blocks — tool calls, images — are dropped.
  • Unparsable lines are skipped, with a warning. A half-written trailing line in a .jsonl file is normal for an agent that was killed; the good lines are still indexed and the bad one is named.
  • Indexing is not automatic. Run context-bridge index <path> when you want your sessions searchable.

Quick start

Get started in 5 minutes:

pip install context-bridge-py

# or install from git for the latest development version
pip install git+https://github.com/yunaremaia/context-bridge.git

# Initialize in your project
context-bridge init

# Index existing agent sessions (a Claude Code project)
context-bridge index ~/.claude/projects/

# Query memory
context-bridge recall "How did we handle authentication?"

# Print the retrieved context for a new session
context-bridge inject --agent claude

PyPI name: the distribution is context-bridge-py (the short context-bridge name on PyPI belongs to an unrelated project by another author). The command you run is still context-bridge.

A bounded example

# Index one Claude Code project's logs
context-bridge index ~/.claude/projects/-home-you-code

# Ask about a decision made in an earlier session
context-bridge recall "why did we pin the dependency"

# Print the retrieved context for a new Claude Code session
context-bridge inject --agent claude

Architecture

~/.context-bridge/
├── sessions/           # Captured session transcripts
├── index.db            # SQLite FTS + metadata
├── memories/           # Consolidated memories
└── config.yaml         # Per-project config
  • driftcheck — detect version drift between docs and toolchain files
  • mcp-guard — audit MCP servers for unsafe permissions
  • memwatch — health-check and prune agent memory stores
  • agent-workspace — isolated workspaces per AI agent session

Part of a family of focused, single-purpose developer tools — each one does one thing and does it well.

Sponsoring

context-bridge is MIT licensed and free to use. If it earns a permanent place in your setup, you can support continued maintenance via GitHub Sponsors or by sending SOL to the project treasury wallet:

Eeztv1nCYUt1fwGWpzKC948gaWfjejYCAuLtUMgzDWbW

Funding platforms are configured in .github/FUNDING.yml.

If this tool is useful to you, a star helps other people find it.

License

MIT

Metadata

Release files for context-bridge-py 0.3.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for context-bridge-py 0.3.3
File Size Uploaded Provenance Actions
context_bridge_py-0.3.3.tar.gz 30.4 kB With provenance Details for context_bridge_py-0.3.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for context-bridge-py 0.3.3
File Interpreter ABI Platform Actions
context_bridge_py-0.3.3-py3-none-any.whl Python 3 none any Details for context_bridge_py-0.3.3-py3-none-any.whl

Total release size: 44.0 kB

Release files / context_bridge_py-0.3.3.tar.gz

Download URL context_bridge_py-0.3.3.tar.gz
Size 30.4 kB
Tags Source
SHA-256 checksum
How to use checksums
28ea19174661c881122ad00fc3422aaf436c0cb6f1b442f015161c59252612fc
BLAKE2b-256 checksum
How to use checksums
fa97a7dd58c1bbe147e3562d9d1a4b51eca2a904f13f9719eb8bf526d693c43d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / context_bridge_py-0.3.3-py3-none-any.whl

Download URL context_bridge_py-0.3.3-py3-none-any.whl
Size 13.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1bb68ee5514ba5368ab1642ed90f25287037e89f392e8e77f45421a8b4f5c861
BLAKE2b-256 checksum
How to use checksums
e00f943b0b44996cf85746f40c99ed129b76fce392d7ec56176ab4cd572c5fcd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Security for context-bridge-py 0.3.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for context_bridge_py-0.3.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page