agent-borg 3.3.2

Collective memory MCP server for AI coding agents

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)

pip install agent-borg

If you need to run from source instead:

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

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

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

{
  "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

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.