Metadata-Version: 2.4
Name: agent-borg
Version: 3.3.2
Summary: Collective memory MCP server for AI coding agents
License: MIT
Project-URL: Homepage, https://github.com/bensargotest-sys/borg
Project-URL: Repository, https://github.com/bensargotest-sys/borg
Project-URL: Issues, https://github.com/bensargotest-sys/borg/issues
Project-URL: Documentation, https://github.com/bensargotest-sys/borg/tree/main/docs
Keywords: mcp,ai-agents,debugging,collective-memory,workflow
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.2.0; extra == "semantic"
Requires-Dist: numpy>=1.24.0; extra == "semantic"
Requires-Dist: scikit-learn>=1.3.0; extra == "semantic"
Dynamic: license-file

# Borg  The Read-Through Cache for Agent Reasoning

Borg is an MCP server that gives AI coding agents a shared cache of debugging traces. Before an agent burns tool calls on an error, Borg surfaces what worked in prior sessions.

## Status (live-gated)

Borg production readiness is decided by hard gates, not static README text.
Canonical artifacts:

- `PROJECT_STATUS.md` (scoreboard + gate breakdown)
- `GO_NO_GO_DECISION.md` (binary rollout verdict)
- `eval/gate_run_snapshot.json` and `eval/uat_scoreboard_snapshot.json` (machine-readable source of truth)
- `docs/VALUE_ANALYSIS_REPORT.md` and `eval/value_analysis_snapshot.json` (plain-English value/adoption report + machine snapshot)

Gate policy defaults to **strict** for experiment evidence (packet required + integrity pass + SHIP policy). Relaxed mode is only for local debugging via `BORG_ALLOW_RELAXED_EXPERIMENT_PACKET=1` and must never be used for production claims.

## Install (first-user path)

```bash
pip install agent-borg
```

If you need to run from source instead:

```bash
git clone https://github.com/bensargotest-sys/borg.git
cd borg
pip install -e .
```

See [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) for full setup (MCP config for Claude Desktop / Cursor / Claude Code / Cline).

MCP config (Claude Desktop / Cursor / Cline / Claude Code):

```json
{
  "mcpServers": {
    "borg": {
      "command": "python3",
      "args": ["-m", "borg.integrations.mcp_server"],
      "env": { "BORG_HOME": "~/.borg" }
    }
  }
}
```

## How it works

Agent calls `borg_observe(task, context)` before attempting a fix. Borg returns up to 5 results, each with a `source_tier`:

- `real`  organic agent-authored trace from live sessions
- `synthetic`  seed-pack / golden-seed / curated coverage (fallback when no real match)

After the fix, `borg_rate(helpful=True/False)` updates helpfulness scoring.

## What's real vs what's not

Phase 0 (this commit) enforces a hard separation:

- `traces` table  only agent-authored organic data. Write path (`save_trace`) rejects `source` in `seed_pack`/`golden_seed`/`curated` and raises `ValueError`.
- `seed_traces` table  synthetic and scripted-sprint coverage. Retrieval falls back here only when organic yields fewer than `limit` results.

## Performance claims

**None yet.** Public performance numbers require `borg-bench` (Phase 1) running on a held-out benchmark dataset. See `Borg_PRD_v4.md` 7 for the metrics contract and 11 for launch gates.

Prior materials that cited "27% fewer tool calls" and "67% higher success rate" were computed on synthetic seed packs and are not reproducible on real traffic. Those claims are withdrawn pending Phase 1 measurement.

## Trace format

Open format documented in `BORG_TRACE_FORMAT_v1.md`. Any agent framework that writes Borg-compatible traces can contribute.

## Invariants (CI-enforced)

| # | Invariant | Status |
|---|---|---|
| I1 | First query hits in <30s on fresh install | Pending Phase 1 harness |
| I2 | README performance numbers reproducible from `borg-bench` | Pending Phase 1 |
| I3 | `traces` and `seed_traces` architecturally separate | LIVE |
| I4 | PII never ships | LIVE |
| I5 | Exported traces validate against `BORG_TRACE_FORMAT_v1` | Pending JSON schema |

## Verification

```bash
BORG_HOME=~/.borg python3 -m pytest borg/tests/test_invariants.py -v
```

Expected: 4 passed, 3 skipped.

## Roadmap

- **Phase 0 (done):** data hygiene, real/synthetic separation, invariant tests, honest claims
- **Phase 1:** `borg-bench` with WILD-200 held-out dataset, dead-end re-ranker, MCP tool rename (`borg_observe`  `error_lookup`), invited beta (5 users)
- **Phase 2+:** public launch, trace format adoption by other agent frameworks, governance

## License

MIT (code) / CC0 (trace format specification)

## Maintainer

Single-maintainer project. Not affiliated with any company. Issues and PRs welcome but response time is best-effort.
