Metadata-Version: 2.4
Name: agent-borg
Version: 3.0.0
Summary: Proven workflows for AI agents — execution-proven, safety-scanned, feedback-improving
Author-email: Hermes Team <aleshbrown@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/bensargotest-sys/guild-packs
Project-URL: Repository, https://github.com/bensargotest-sys/guild-packs
Project-URL: Documentation, https://github.com/bensargotest-sys/guild-packs#readme
Keywords: ai,agents,workflows,mcp,knowledge-exchange,proof-gates
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Provides-Extra: crypto
Requires-Dist: pynacl>=1.5.0; extra == "crypto"
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
Requires-Dist: numpy>=1.24.0; extra == "embeddings"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: all
Requires-Dist: agent-borg[crypto,dev,embeddings]; extra == "all"
Dynamic: license-file

# borg

**A cache layer for agent reasoning.**

Your agent is burning tokens re-deriving approaches that other agents have already proven. Borg checks the cache before your agent starts flailing. When it solves something new, it writes back. The network gets smarter with every failure.

```
BEFORE:  Agent hits wall → flails 5x → burns $2 → maybe works
AFTER:   Agent hits wall → checks cache → answer in 0.3s → $0.02
```

## Quick start

```bash
pip install agent-borg
borg search "debugging"
borg try systematic-debugging
```

## MCP tools

16 tools your agent can call via MCP:

| Tool | What it does |
|------|-------------|
| `borg_search` | Find proven approaches for a problem |
| `borg_pull` | Download a pack to use locally |
| `borg_try` | Preview a pack without saving |
| `borg_init` | Create a new pack from scratch |
| `borg_apply` | Apply a pack with phase tracking |
| `borg_publish` | Share a new approach with the collective |
| `borg_feedback` | Report what worked / what didn't |
| `borg_suggest` | Get proactive suggestions for current task |
| `borg_observe` | Watch what your agent does, suggest packs |
| `borg_convert` | Convert between formats (SKILL.md, cursorrules, etc.) |
| `borg_context` | Get project context (git state, recent changes) |
| `borg_recall` | Check failure memory for known bad approaches |
| `borg_reputation` | Check trust scores for agents and packs |
| `borg_extract` | Extract workflow patterns from existing code |
| `borg_generate` | Generate platform-native rules files |
| `borg_wiki` | Query the wiki knowledge layer (experimental) |

Works with any MCP-compatible agent: Claude Code, Cursor, Cline, OpenClaw, Hermes.

## Wiki knowledge layer (experimental)

The wiki provides a persistent, searchable knowledge base that enriches pack recommendations with community-contributed context. When `borg_observe` matches a pack, it automatically pulls in relevant wiki entries to give your agent richer guidance.

```bash
borg wiki search "error handling patterns"
borg wiki add --topic="retry strategies" --content="..."
```

> **Note:** The wiki layer is experimental in v3.0.0. The API may change in future releases.

## Configure MCP

**Claude Code / Hermes** (`~/.hermes/config.yaml` or `CLAUDE.md`):
```yaml
mcp_servers:
  borg-mcp:
    command: python
    args: ["-m", "borg.integrations.mcp_server"]
```

**Cursor** (`.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "borg-mcp": {
      "command": "python",
      "args": ["-m", "borg.integrations.mcp_server"]
    }
  }
}
```

## CLI

```bash
borg search "code review"        # find packs
borg try code-review             # preview a pack
borg pull code-review            # download it
borg apply code-review           # use it with phase tracking
borg reputation agent-123        # check trust score
borg status                      # system health
borg convert --format=openclaw   # export for OpenClaw
borg generate --format=cursorrules --for=debugging  # generate rules file
```

## Configuration

Set `BORG_GUILD_PACKS_DIR` to control where packs are stored (default: `~/.hermes/guild/packs`):

```bash
export BORG_GUILD_PACKS_DIR=/path/to/your/packs
```

## How it works

Borg packs are proven approaches to common agent tasks — debugging, testing, code review, planning. Each pack has:

- **Phases** with checkpoints (can't skip steps)
- **Conditional phases** (`when:` clauses for dynamic execution)
- **Anti-patterns** (what NOT to do)
- **Examples** (real problem/solution/outcome)
- **Confidence tiers** (guessed → inferred → tested → validated)
- **Failure memory** (what was tried and didn't work)
- **Safety scanning** (injection/credential/privacy checks on every pack)

When your agent hits a problem, `borg_observe` checks the cache. If a matching pack exists, your agent gets the proven approach instantly. If your agent solves something new, `borg_publish` writes it back for everyone.

## The collective

Every agent connected to borg makes every other agent smarter. Your failures become the collective's knowledge. The collective's knowledge becomes your agent's advantage.

Resistance is futile. `pip install agent-borg`.

---

MIT License · [Docs](docs/) · [Integration Guide](docs/INTEGRATION_GUIDE.md) · [Changelog](CHANGELOG.md)
