agent-context-bridge 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agent_context_bridge-0.2.0/.github/workflows/ci.yml +28 -0
- agent_context_bridge-0.2.0/.github/workflows/release.yml +62 -0
- agent_context_bridge-0.2.0/.gitignore +12 -0
- agent_context_bridge-0.2.0/CHANGELOG.md +29 -0
- agent_context_bridge-0.2.0/CONTRIBUTING.md +31 -0
- agent_context_bridge-0.2.0/LICENSE +21 -0
- agent_context_bridge-0.2.0/PKG-INFO +194 -0
- agent_context_bridge-0.2.0/README.md +166 -0
- agent_context_bridge-0.2.0/SECURITY.md +22 -0
- agent_context_bridge-0.2.0/docs/demo.gif +0 -0
- agent_context_bridge-0.2.0/docs/social-preview.png +0 -0
- agent_context_bridge-0.2.0/pyproject.toml +54 -0
- agent_context_bridge-0.2.0/src/agent_context_bridge/__init__.py +50 -0
- agent_context_bridge-0.2.0/src/agent_context_bridge/adapters.py +105 -0
- agent_context_bridge-0.2.0/src/agent_context_bridge/cli.py +229 -0
- agent_context_bridge-0.2.0/src/agent_context_bridge/core.py +208 -0
- agent_context_bridge-0.2.0/src/agent_context_bridge/hooks.py +156 -0
- agent_context_bridge-0.2.0/src/agent_context_bridge/utils.py +33 -0
- agent_context_bridge-0.2.0/tests/test_adapters.py +37 -0
- agent_context_bridge-0.2.0/tests/test_cli.py +40 -0
- agent_context_bridge-0.2.0/tests/test_core.py +61 -0
- agent_context_bridge-0.2.0/tests/test_e2e_multiagent.py +114 -0
- agent_context_bridge-0.2.0/tests/test_hardening.py +168 -0
- agent_context_bridge-0.2.0/tests/test_hooks.py +105 -0
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
name: CI & Tests
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [ main, master ]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [ main, master ]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
strategy:
|
|
13
|
+
matrix:
|
|
14
|
+
python-version: ["3.10", "3.11", "3.12"]
|
|
15
|
+
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v4
|
|
18
|
+
- name: Set up Python ${{ matrix.python-version }}
|
|
19
|
+
uses: actions/setup-python@v5
|
|
20
|
+
with:
|
|
21
|
+
python-version: ${{ matrix.python-version }}
|
|
22
|
+
- name: Install dependencies
|
|
23
|
+
run: |
|
|
24
|
+
python -m pip install --upgrade pip
|
|
25
|
+
pip install .[dev]
|
|
26
|
+
- name: Run Test Suite
|
|
27
|
+
run: |
|
|
28
|
+
pytest -v
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
name: Release to PyPI
|
|
2
|
+
|
|
3
|
+
# Publishes agent-context-bridge to public PyPI on every v* tag,
|
|
4
|
+
# using PyPI Trusted Publishing (OIDC) โ no API token stored in CI.
|
|
5
|
+
#
|
|
6
|
+
# One-time setup (PyPI, ~2 min, by the package owner):
|
|
7
|
+
# 1. Open https://pypi.org/manage/project/agent-context-bridge/settings/publishing/
|
|
8
|
+
# (or "Add a new pending publisher" on pypi.org if the project has no release yet)
|
|
9
|
+
# 2. Publisher: GitHub โ Owner: shenn667
|
|
10
|
+
# Repository: agent-context-bridge
|
|
11
|
+
# Workflow name: release.yml
|
|
12
|
+
# Environment name: (leave empty)
|
|
13
|
+
# 3. Push a tag (git tag v0.2.0 && git push origin v0.2.0) โ this workflow
|
|
14
|
+
# builds, checks TestPyPI optionally, and publishes to PyPI automatically.
|
|
15
|
+
|
|
16
|
+
on:
|
|
17
|
+
push:
|
|
18
|
+
tags:
|
|
19
|
+
- "v*"
|
|
20
|
+
|
|
21
|
+
permissions:
|
|
22
|
+
contents: read
|
|
23
|
+
|
|
24
|
+
jobs:
|
|
25
|
+
build-and-publish:
|
|
26
|
+
runs-on: ubuntu-latest
|
|
27
|
+
permissions:
|
|
28
|
+
contents: read
|
|
29
|
+
id-token: write # required for Trusted Publishing (OIDC)
|
|
30
|
+
steps:
|
|
31
|
+
- uses: actions/checkout@v4
|
|
32
|
+
|
|
33
|
+
- name: Set up Python
|
|
34
|
+
uses: actions/setup-python@v5
|
|
35
|
+
with:
|
|
36
|
+
python-version: "3.12"
|
|
37
|
+
|
|
38
|
+
- name: Install build backend
|
|
39
|
+
run: |
|
|
40
|
+
python -m pip install --upgrade pip
|
|
41
|
+
pip install build twine
|
|
42
|
+
|
|
43
|
+
- name: Run tests before release
|
|
44
|
+
run: |
|
|
45
|
+
pip install .[dev]
|
|
46
|
+
pytest -q
|
|
47
|
+
|
|
48
|
+
- name: Verify tag matches package version
|
|
49
|
+
run: |
|
|
50
|
+
TAG="${GITHUB_REF_NAME#v}"
|
|
51
|
+
PKG=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
|
|
52
|
+
echo "tag=$TAG package=$PKG"
|
|
53
|
+
test "$TAG" = "$PKG" || { echo "::error::tag v$TAG != pyproject version $PKG"; exit 1; }
|
|
54
|
+
|
|
55
|
+
- name: Build sdist + wheel
|
|
56
|
+
run: python -m build
|
|
57
|
+
|
|
58
|
+
- name: Check distributions
|
|
59
|
+
run: twine check dist/*
|
|
60
|
+
|
|
61
|
+
- name: Publish to PyPI (Trusted Publishing)
|
|
62
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `agent-context-bridge` are documented here.
|
|
4
|
+
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|
5
|
+
|
|
6
|
+
## [Unreleased]
|
|
7
|
+
### Added
|
|
8
|
+
- `acb --version` (single source of truth: installed dist metadata, fallback `__version__`).
|
|
9
|
+
- Native hooks: `acb hooks claude --print|--install`, `acb hooks hermes --print`,
|
|
10
|
+
`acb hooks run --target <hermes|claude|opencode|codex>` (stdin-draining, exit 0, 1-command test).
|
|
11
|
+
- README: 3-command local demo + 1-command hook wiring docs.
|
|
12
|
+
### Fixed
|
|
13
|
+
- CI badge now reflects the real workflow status (dynamic `ci.yml` badge) instead of a static "passing" shield.
|
|
14
|
+
|
|
15
|
+
## [0.2.0] - 2026-11-15
|
|
16
|
+
### Added
|
|
17
|
+
- Automated PyPI release workflow (Trusted Publishing / OIDC, tag `v*` โ PyPI).
|
|
18
|
+
- Dynamic PyPI version badge in README.
|
|
19
|
+
### Fixed
|
|
20
|
+
- Package was never published to PyPI despite the badge (first real public release).
|
|
21
|
+
|
|
22
|
+
## [0.1.0] - 2026-11-15
|
|
23
|
+
### Added
|
|
24
|
+
- Initial release: file-backed offline context store (`.agent_bridge/` with `records.jsonl` + `SHARED_CONTEXT.md`).
|
|
25
|
+
- CLI `acb` / `agent-bridge`: `init`, `record`, `list`, `inject`, `export`.
|
|
26
|
+
- Adapters: Hermes, Claude Code (SessionStart hook format), OpenCode, Codex.
|
|
27
|
+
- Zero runtime dependencies (stdlib only: `argparse`, `json`, `dataclasses`, `datetime`).
|
|
28
|
+
- Test suite (6 tests) + CI matrix Python 3.10โ3.12.
|
|
29
|
+
- MIT license.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Thanks for your interest in `agent-context-bridge`!
|
|
4
|
+
|
|
5
|
+
## Quick start
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
git clone https://github.com/shenn667/agent-context-bridge.git
|
|
9
|
+
cd agent-context-bridge
|
|
10
|
+
python -m venv .venv && source .venv/bin/activate
|
|
11
|
+
pip install -e .[dev]
|
|
12
|
+
pytest -v
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Ground rules
|
|
16
|
+
|
|
17
|
+
- Python โฅ 3.10, stdlib only at runtime (no new dependencies without discussion).
|
|
18
|
+
- Offline-first: no network calls, no daemon, no telemetry.
|
|
19
|
+
- Every behavior change ships with a test (`pytest`).
|
|
20
|
+
- Every user-facing change updates `CHANGELOG.md` (Unreleased section) and `README.md` if needed.
|
|
21
|
+
|
|
22
|
+
## Pull requests
|
|
23
|
+
|
|
24
|
+
1. Fork, branch from `main` (`feat/<scope>`, `fix/<scope>`).
|
|
25
|
+
2. Keep PRs small and focused; describe the problem, the fix, and how you tested it.
|
|
26
|
+
3. `pytest -v` must be green. CI runs Python 3.10 / 3.11 / 3.12.
|
|
27
|
+
|
|
28
|
+
## Reporting issues
|
|
29
|
+
|
|
30
|
+
Include: ACB version (`acb export` header or `pip show`), Python version, OS,
|
|
31
|
+
minimal reproduction steps, and the content of `.agent_bridge/records.jsonl` (redacted if sensitive).
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 shenn667 <lehdev@yandex.com>
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: agent-context-bridge
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: A lightweight, zero-dependency universal context & memory bridge for autonomous coding agents (Hermes, Claude Code, OpenCode, Codex).
|
|
5
|
+
Project-URL: Homepage, https://github.com/shenn667/agent-context-bridge
|
|
6
|
+
Project-URL: Repository, https://github.com/shenn667/agent-context-bridge
|
|
7
|
+
Project-URL: Issues, https://github.com/shenn667/agent-context-bridge/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/shenn667/agent-context-bridge/blob/main/CHANGELOG.md
|
|
9
|
+
Author-email: shenn667 <lehdev@yandex.com>
|
|
10
|
+
License: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: agents,ai,claude-code,context,developer-tools,hermes,memory,multi-agent,opencode
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
22
|
+
Classifier: Topic :: Software Development :: Build Tools
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
|
|
26
|
+
Requires-Dist: pytest>=7.0.0; extra == 'dev'
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# ๐ Agent Context Bridge (ACB)
|
|
30
|
+
|
|
31
|
+
[](https://pypi.org/project/agent-context-bridge/)
|
|
32
|
+
[](https://opensource.org/licenses/MIT)
|
|
33
|
+
[](https://www.python.org/)
|
|
34
|
+
[](https://github.com/shenn667/agent-context-bridge/actions/workflows/ci.yml)
|
|
35
|
+
|
|
36
|
+
> **Universal, zero-dependency context & memory bridge for autonomous coding agents.**
|
|
37
|
+
> Seamlessly share project decisions, architectural constraints, and task progress between **Hermes Agent**, **Claude Code**, **OpenCode**, and **Codex**.
|
|
38
|
+
|
|
39
|
+
> โฑ๏ธ **The 10-second version:** every AI coding tool starts blind โ decisions made in one agent are lost to the next. ACB records them once (`acb record`) and replays them in each agent's native format (`acb inject`).
|
|
40
|
+
|
|
41
|
+

|
|
42
|
+
|
|
43
|
+
*50s, no audio: `init` โ `record` โ `list` โ `inject` for Claude & Hermes. One store (`.agent_bridge/`) โ every agent.*
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## ๐ก The Problem: Multi-Agent Context Fragmentation
|
|
48
|
+
|
|
49
|
+
When switching between modern AI developer tools (e.g., Claude Code in terminal, Hermes swarm running in background, OpenCode in IDE):
|
|
50
|
+
1. **Each agent starts blind**: Context learned by one agent in a prior turn is lost to the next.
|
|
51
|
+
2. **Token waste**: Agents re-read entire repository trees to rediscover decisions already made.
|
|
52
|
+
3. **No persistent audit trail**: Critical architectural choices disappear with session resets.
|
|
53
|
+
|
|
54
|
+
**Agent Context Bridge** solves this with a lightweight, file-backed offline store (`.agent_bridge/`) and dedicated adapter templates for each agent's native prompt hook format.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## โจ Features
|
|
59
|
+
|
|
60
|
+
- **Zero Runtime Dependencies**: Pure Python standard library (`argparse`, `json`, `dataclasses`, `datetime`). Fast and crash-resilient.
|
|
61
|
+
- **Offline & Local-First**: No background daemon, no external database, no network calls. Works 100% offline.
|
|
62
|
+
- **Multi-Agent Adapters**: Native formatters for **Hermes Agent**, **Claude Code**, **OpenCode**, and **Codex**.
|
|
63
|
+
- **Human-Readable & Machine-Parseable**: Automatically maintains both `records.jsonl` (structured) and `SHARED_CONTEXT.md` (markdown view).
|
|
64
|
+
- **Fast CLI**: Simple `agent-bridge` (`acb`) command for CI, shell hooks, or direct agent execution.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## ๐ฆ Installation
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
pip install agent-context-bridge
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Or install locally from source:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
git clone https://github.com/shenn667/agent-context-bridge.git
|
|
78
|
+
cd agent-context-bridge
|
|
79
|
+
pip install -e .
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## ๐ Quickstart
|
|
85
|
+
|
|
86
|
+
### 1. Initialize a Workspace
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
acb init
|
|
90
|
+
```
|
|
91
|
+
Creates `.agent_bridge/records.jsonl` and `.agent_bridge/SHARED_CONTEXT.md`.
|
|
92
|
+
|
|
93
|
+
### 2. Record a Context Decision
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
acb record \
|
|
97
|
+
--agent hermes-dev \
|
|
98
|
+
--topic "Database Engine" \
|
|
99
|
+
--summary "Adopted SQLite WAL mode for local agent state storage" \
|
|
100
|
+
--details "PostgreSQL required Docker containers; SQLite provides zero-latency offline access." \
|
|
101
|
+
--tag db --tag architecture
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### 3. List Shared Context
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
acb list
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### 4. Inject Context into an Agent Session
|
|
111
|
+
|
|
112
|
+
Output prompt-ready context tailored for your target agent:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
# For Claude Code SessionStart hook:
|
|
116
|
+
acb inject --target claude
|
|
117
|
+
|
|
118
|
+
# For Hermes Agent system context:
|
|
119
|
+
acb inject --target hermes
|
|
120
|
+
|
|
121
|
+
# For OpenCode:
|
|
122
|
+
acb inject --target opencode
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## โ
Demo locale (3 commandes)
|
|
128
|
+
|
|
129
|
+
Reproductible depuis une clone fraรฎche โ prouve install + record/inject + version cohรฉrente :
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
pip install -e .
|
|
133
|
+
acb init --dir /tmp/acb-demo && acb record --dir /tmp/acb-demo --agent hermes-dev --topic "Demo" --summary "Bridge OK" && acb inject --dir /tmp/acb-demo --target hermes
|
|
134
|
+
acb --version
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Attendu : `agent-bridge 0.2.0` (identique ร `pyproject.toml`, `__init__.__version__` et au tag `v0.2.0` โ le workflow `release.yml` refuse la publication si tag โ version).
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## ๐ช Hooks natifs (1 commande chacun)
|
|
142
|
+
|
|
143
|
+
### Claude Code โ SessionStart
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
acb hooks claude --print # affiche le snippet .claude/settings.json
|
|
147
|
+
acb hooks claude --install # รฉcrit/fusionne <workspace>/.claude/settings.json (idempotent)
|
|
148
|
+
echo '{}' | acb hooks run --target claude # teste le hook : exit 0 + contexte sur stdout
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Le hook enregistrรฉ est `acb inject --target claude` : Claude Code l'exรฉcute ร chaque
|
|
152
|
+
SessionStart (payload JSON sur stdin, ignorรฉ) et le stdout est injectรฉ en contexte de session.
|
|
153
|
+
|
|
154
|
+
### Hermes Agent โ inject
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
acb hooks hermes --print # snippet de cรขblage (prรฉambule de session)
|
|
158
|
+
acb inject --target hermes # inject 1-commande, prรชt pour le system context
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## ๐๏ธ Architecture
|
|
164
|
+
|
|
165
|
+
```
|
|
166
|
+
โโโโโโโโโโโโโโโโโโโโโโโโ
|
|
167
|
+
โ Your Project Repo โ
|
|
168
|
+
โโโโโโโโโโโโฌโโโโโโโโโโโโ
|
|
169
|
+
โ
|
|
170
|
+
.agent_bridge/SHARED_CONTEXT.md
|
|
171
|
+
.agent_bridge/records.jsonl
|
|
172
|
+
โ
|
|
173
|
+
โโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโ
|
|
174
|
+
โผ โผ โผ
|
|
175
|
+
โโโโโโโโโโโโโ โโโโโโโโโโโโโ โโโโโโโโโโโโโ
|
|
176
|
+
โ Hermes โ โClaude Codeโ โ OpenCode โ
|
|
177
|
+
โ Adapter โ โ Adapter โ โ Adapter โ
|
|
178
|
+
โโโโโโโโโโโโโ โโโโโโโโโโโโโ โโโโโโโโโโโโโ
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## ๐งช Running Tests
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
pytest -v
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## ๐ License
|
|
192
|
+
|
|
193
|
+
This project is open-source under the [MIT License](LICENSE).
|
|
194
|
+
Authored by **shenn667** ([lehdev@yandex.com](mailto:lehdev@yandex.com)).
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# ๐ Agent Context Bridge (ACB)
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/agent-context-bridge/)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
[](https://www.python.org/)
|
|
6
|
+
[](https://github.com/shenn667/agent-context-bridge/actions/workflows/ci.yml)
|
|
7
|
+
|
|
8
|
+
> **Universal, zero-dependency context & memory bridge for autonomous coding agents.**
|
|
9
|
+
> Seamlessly share project decisions, architectural constraints, and task progress between **Hermes Agent**, **Claude Code**, **OpenCode**, and **Codex**.
|
|
10
|
+
|
|
11
|
+
> โฑ๏ธ **The 10-second version:** every AI coding tool starts blind โ decisions made in one agent are lost to the next. ACB records them once (`acb record`) and replays them in each agent's native format (`acb inject`).
|
|
12
|
+
|
|
13
|
+

|
|
14
|
+
|
|
15
|
+
*50s, no audio: `init` โ `record` โ `list` โ `inject` for Claude & Hermes. One store (`.agent_bridge/`) โ every agent.*
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## ๐ก The Problem: Multi-Agent Context Fragmentation
|
|
20
|
+
|
|
21
|
+
When switching between modern AI developer tools (e.g., Claude Code in terminal, Hermes swarm running in background, OpenCode in IDE):
|
|
22
|
+
1. **Each agent starts blind**: Context learned by one agent in a prior turn is lost to the next.
|
|
23
|
+
2. **Token waste**: Agents re-read entire repository trees to rediscover decisions already made.
|
|
24
|
+
3. **No persistent audit trail**: Critical architectural choices disappear with session resets.
|
|
25
|
+
|
|
26
|
+
**Agent Context Bridge** solves this with a lightweight, file-backed offline store (`.agent_bridge/`) and dedicated adapter templates for each agent's native prompt hook format.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## โจ Features
|
|
31
|
+
|
|
32
|
+
- **Zero Runtime Dependencies**: Pure Python standard library (`argparse`, `json`, `dataclasses`, `datetime`). Fast and crash-resilient.
|
|
33
|
+
- **Offline & Local-First**: No background daemon, no external database, no network calls. Works 100% offline.
|
|
34
|
+
- **Multi-Agent Adapters**: Native formatters for **Hermes Agent**, **Claude Code**, **OpenCode**, and **Codex**.
|
|
35
|
+
- **Human-Readable & Machine-Parseable**: Automatically maintains both `records.jsonl` (structured) and `SHARED_CONTEXT.md` (markdown view).
|
|
36
|
+
- **Fast CLI**: Simple `agent-bridge` (`acb`) command for CI, shell hooks, or direct agent execution.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## ๐ฆ Installation
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
pip install agent-context-bridge
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Or install locally from source:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
git clone https://github.com/shenn667/agent-context-bridge.git
|
|
50
|
+
cd agent-context-bridge
|
|
51
|
+
pip install -e .
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## ๐ Quickstart
|
|
57
|
+
|
|
58
|
+
### 1. Initialize a Workspace
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
acb init
|
|
62
|
+
```
|
|
63
|
+
Creates `.agent_bridge/records.jsonl` and `.agent_bridge/SHARED_CONTEXT.md`.
|
|
64
|
+
|
|
65
|
+
### 2. Record a Context Decision
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
acb record \
|
|
69
|
+
--agent hermes-dev \
|
|
70
|
+
--topic "Database Engine" \
|
|
71
|
+
--summary "Adopted SQLite WAL mode for local agent state storage" \
|
|
72
|
+
--details "PostgreSQL required Docker containers; SQLite provides zero-latency offline access." \
|
|
73
|
+
--tag db --tag architecture
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### 3. List Shared Context
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
acb list
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### 4. Inject Context into an Agent Session
|
|
83
|
+
|
|
84
|
+
Output prompt-ready context tailored for your target agent:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
# For Claude Code SessionStart hook:
|
|
88
|
+
acb inject --target claude
|
|
89
|
+
|
|
90
|
+
# For Hermes Agent system context:
|
|
91
|
+
acb inject --target hermes
|
|
92
|
+
|
|
93
|
+
# For OpenCode:
|
|
94
|
+
acb inject --target opencode
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## โ
Demo locale (3 commandes)
|
|
100
|
+
|
|
101
|
+
Reproductible depuis une clone fraรฎche โ prouve install + record/inject + version cohรฉrente :
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
pip install -e .
|
|
105
|
+
acb init --dir /tmp/acb-demo && acb record --dir /tmp/acb-demo --agent hermes-dev --topic "Demo" --summary "Bridge OK" && acb inject --dir /tmp/acb-demo --target hermes
|
|
106
|
+
acb --version
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Attendu : `agent-bridge 0.2.0` (identique ร `pyproject.toml`, `__init__.__version__` et au tag `v0.2.0` โ le workflow `release.yml` refuse la publication si tag โ version).
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## ๐ช Hooks natifs (1 commande chacun)
|
|
114
|
+
|
|
115
|
+
### Claude Code โ SessionStart
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
acb hooks claude --print # affiche le snippet .claude/settings.json
|
|
119
|
+
acb hooks claude --install # รฉcrit/fusionne <workspace>/.claude/settings.json (idempotent)
|
|
120
|
+
echo '{}' | acb hooks run --target claude # teste le hook : exit 0 + contexte sur stdout
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Le hook enregistrรฉ est `acb inject --target claude` : Claude Code l'exรฉcute ร chaque
|
|
124
|
+
SessionStart (payload JSON sur stdin, ignorรฉ) et le stdout est injectรฉ en contexte de session.
|
|
125
|
+
|
|
126
|
+
### Hermes Agent โ inject
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
acb hooks hermes --print # snippet de cรขblage (prรฉambule de session)
|
|
130
|
+
acb inject --target hermes # inject 1-commande, prรชt pour le system context
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## ๐๏ธ Architecture
|
|
136
|
+
|
|
137
|
+
```
|
|
138
|
+
โโโโโโโโโโโโโโโโโโโโโโโโ
|
|
139
|
+
โ Your Project Repo โ
|
|
140
|
+
โโโโโโโโโโโโฌโโโโโโโโโโโโ
|
|
141
|
+
โ
|
|
142
|
+
.agent_bridge/SHARED_CONTEXT.md
|
|
143
|
+
.agent_bridge/records.jsonl
|
|
144
|
+
โ
|
|
145
|
+
โโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโ
|
|
146
|
+
โผ โผ โผ
|
|
147
|
+
โโโโโโโโโโโโโ โโโโโโโโโโโโโ โโโโโโโโโโโโโ
|
|
148
|
+
โ Hermes โ โClaude Codeโ โ OpenCode โ
|
|
149
|
+
โ Adapter โ โ Adapter โ โ Adapter โ
|
|
150
|
+
โโโโโโโโโโโโโ โโโโโโโโโโโโโ โโโโโโโโโโโโโ
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## ๐งช Running Tests
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
pytest -v
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## ๐ License
|
|
164
|
+
|
|
165
|
+
This project is open-source under the [MIT License](LICENSE).
|
|
166
|
+
Authored by **shenn667** ([lehdev@yandex.com](mailto:lehdev@yandex.com)).
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
## Supported versions
|
|
4
|
+
|
|
5
|
+
| Version | Supported |
|
|
6
|
+
| ------- | --------- |
|
|
7
|
+
| 0.1.x | Yes |
|
|
8
|
+
|
|
9
|
+
## Reporting a vulnerability
|
|
10
|
+
|
|
11
|
+
Please **do not** open a public issue for security reports.
|
|
12
|
+
Contact the maintainer directly: <lehdev@yandex.com>.
|
|
13
|
+
|
|
14
|
+
Include: description, impact, minimal reproduction, and affected version.
|
|
15
|
+
We aim to acknowledge within 72h and ship a fix as a patch release.
|
|
16
|
+
|
|
17
|
+
## Design notes (relevant to review)
|
|
18
|
+
|
|
19
|
+
- `agent-context-bridge` is fully offline: no network, no daemon, no exfiltration path by design.
|
|
20
|
+
- Storage is local flat files under `.agent_bridge/` (`records.jsonl`, `SHARED_CONTEXT.md`); writes are atomic (`os.replace` via temp file).
|
|
21
|
+
- CLI `--dir` resolves to an absolute path; the tool only writes inside `<workspace>/.agent_bridge/`.
|
|
22
|
+
- Agent-supplied strings (agent/topic/summary/details) are rendered into markdown prompts โ consumers should treat injected context as untrusted data, not instructions.
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "agent-context-bridge"
|
|
7
|
+
version = "0.2.0"
|
|
8
|
+
description = "A lightweight, zero-dependency universal context & memory bridge for autonomous coding agents (Hermes, Claude Code, OpenCode, Codex)."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "shenn667", email = "lehdev@yandex.com" }
|
|
14
|
+
]
|
|
15
|
+
keywords = [
|
|
16
|
+
"agents",
|
|
17
|
+
"ai",
|
|
18
|
+
"memory",
|
|
19
|
+
"context",
|
|
20
|
+
"hermes",
|
|
21
|
+
"claude-code",
|
|
22
|
+
"opencode",
|
|
23
|
+
"multi-agent",
|
|
24
|
+
"developer-tools"
|
|
25
|
+
]
|
|
26
|
+
classifiers = [
|
|
27
|
+
"Development Status :: 4 - Beta",
|
|
28
|
+
"Intended Audience :: Developers",
|
|
29
|
+
"Topic :: Software Development :: Build Tools",
|
|
30
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
31
|
+
"License :: OSI Approved :: MIT License",
|
|
32
|
+
"Programming Language :: Python :: 3",
|
|
33
|
+
"Programming Language :: Python :: 3.10",
|
|
34
|
+
"Programming Language :: Python :: 3.11",
|
|
35
|
+
"Programming Language :: Python :: 3.12",
|
|
36
|
+
"Operating System :: OS Independent",
|
|
37
|
+
]
|
|
38
|
+
dependencies = []
|
|
39
|
+
|
|
40
|
+
[project.optional-dependencies]
|
|
41
|
+
dev = [
|
|
42
|
+
"pytest>=7.0.0",
|
|
43
|
+
"pytest-cov>=4.0.0",
|
|
44
|
+
]
|
|
45
|
+
|
|
46
|
+
[project.scripts]
|
|
47
|
+
agent-bridge = "agent_context_bridge.cli:main"
|
|
48
|
+
acb = "agent_context_bridge.cli:main"
|
|
49
|
+
|
|
50
|
+
[project.urls]
|
|
51
|
+
Homepage = "https://github.com/shenn667/agent-context-bridge"
|
|
52
|
+
Repository = "https://github.com/shenn667/agent-context-bridge"
|
|
53
|
+
Issues = "https://github.com/shenn667/agent-context-bridge/issues"
|
|
54
|
+
Changelog = "https://github.com/shenn667/agent-context-bridge/blob/main/CHANGELOG.md"
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""Agent Context Bridge (ACB)
|
|
2
|
+
|
|
3
|
+
Universal, zero-dependency context & memory bridge for multi-agent workflows.
|
|
4
|
+
Enables transparent context handoff between Hermes Agent, Claude Code, OpenCode, and Codex.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
__version__ = "0.2.0"
|
|
8
|
+
__author__ = "shenn667"
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def get_version() -> str:
|
|
12
|
+
"""Single source of truth for the package version.
|
|
13
|
+
|
|
14
|
+
Prefers installed dist metadata (correct after ``pip install`` even if
|
|
15
|
+
the source tree was bumped), falls back to ``__version__`` for
|
|
16
|
+
source-tree / editable edge cases. Zero-dependency (stdlib only).
|
|
17
|
+
"""
|
|
18
|
+
try:
|
|
19
|
+
from importlib.metadata import version, PackageNotFoundError
|
|
20
|
+
|
|
21
|
+
try:
|
|
22
|
+
return version("agent-context-bridge")
|
|
23
|
+
except PackageNotFoundError:
|
|
24
|
+
pass
|
|
25
|
+
except Exception:
|
|
26
|
+
pass
|
|
27
|
+
return __version__
|
|
28
|
+
|
|
29
|
+
from agent_context_bridge.core import (
|
|
30
|
+
ContextRecord,
|
|
31
|
+
MemoryStore,
|
|
32
|
+
BridgeSnapshot,
|
|
33
|
+
)
|
|
34
|
+
from agent_context_bridge.adapters import (
|
|
35
|
+
HermesAdapter,
|
|
36
|
+
ClaudeCodeAdapter,
|
|
37
|
+
OpenCodeAdapter,
|
|
38
|
+
CodexAdapter,
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
__all__ = [
|
|
42
|
+
"ContextRecord",
|
|
43
|
+
"MemoryStore",
|
|
44
|
+
"BridgeSnapshot",
|
|
45
|
+
"HermesAdapter",
|
|
46
|
+
"ClaudeCodeAdapter",
|
|
47
|
+
"OpenCodeAdapter",
|
|
48
|
+
"CodexAdapter",
|
|
49
|
+
"get_version",
|
|
50
|
+
]
|