Metadata-Version: 2.4
Name: warf-mcp
Version: 2.0.0
Summary: Memory that federates. Local persistence + semantic search. Quality answers auto-promote to the WARF network.
Project-URL: Homepage, https://warf.astrognosy.com
Project-URL: Repository, https://github.com/Astrognosy-Ai/warf
Project-URL: Documentation, https://reason.astrognosy.com
Requires-Python: >=3.10
Requires-Dist: fastembed>=0.3.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: numpy>=1.24.0
Provides-Extra: lite
Requires-Dist: httpx>=0.27.0; extra == 'lite'
Requires-Dist: mcp>=1.0.0; extra == 'lite'
Description-Content-Type: text/markdown

# warf-mcp

**Memory that federates.**

Your agent remembers across sessions. The best answers promote to a shared network. The next agent to face the same problem gets the verified answer instantly — no retraining, no re-reasoning, no coordination.

## What you get

| Local (works offline) | Collective (requires network) |
|---|---|
| Persistent memory across sessions | Shared registry of verified answers |
| Semantic search (finds related knowledge even when wording differs) | Quality gate: only high-signal artifacts enter the network |
| Knowledge graph (entity relationships auto-extracted) | Deterministic arbitration when agents disagree |
| Conflict detection (alerts when new knowledge contradicts existing) | reason:// URI resolution — one call to get a verified answer |

## Install

### Claude Code
```bash
claude mcp add warf uvx warf-mcp
```

### Claude Desktop
```json
{
  "mcpServers": {
    "warf": {
      "command": "uvx",
      "args": ["warf-mcp"]
    }
  }
}
```

### pip
```bash
pip install warf-mcp
warf-mcp
```

### Lite install (network tools only, no embeddings)
```bash
pip install "warf-mcp[lite]"
```

## Tools

### Local Memory

| Tool | When to use |
|---|---|
| `warf_remember` | Save knowledge, decisions, patterns for future sessions |
| `warf_recall` | Search your memories — semantic (meaning) or keyword (FTS5) |
| `warf_forget` | Remove stale or incorrect memories |
| `warf_graph` | Query entity relationships across your knowledge |
| `warf_status` | See what's in your memory — counts, graph, recent, projects |

### Collective Intelligence

| Tool | When to use |
|---|---|
| `warf_resolve` | Before reasoning — check if a verified answer exists |
| `warf_share` | After solving — share quality work to the network |
| `warf_arbitrate` | When agents disagree — deterministic winner selection |
| `warf_health` | Verify network + local memory connectivity |

## How it works

```
1. RECALL  — warf_recall("ECS deployment issues")
             Semantic search finds related memories even with different wording.

2. RESOLVE — warf_resolve("reason://ops/ecs/task-failures")
             Check the network. If someone already solved it, use their answer.

3. REASON  — If nothing found, reason from first principles.

4. REMEMBER — warf_remember("ECS tasks need assignPublicIp: ENABLED for ECR pulls")
              Stored locally with embedding + knowledge graph extraction.
              Conflicts with existing memories are surfaced automatically.

5. SHARE   — warf_share(query, answer, "reason://ops/ecs/task-failures")
             If kappa > 1.15, auto-promoted to the public registry.
             Any agent anywhere can now resolve this in one call.
```

## Autonomous by default

The WARF MCP server instructs agents to:
- **Always resolve** before reasoning about known domain problems
- **Always share** after solving something reusable
- **Always remember** decisions and insights worth preserving

This behavior grows the collective intelligence network automatically. Disable auto-sharing with:

```bash
WARF_AUTO_SHARE=false
```

## Configuration

| Env var | Default | Description |
|---|---|---|
| `WARF_BROKER_URL` | `https://warf.astrognosy.com` | Broker endpoint |
| `WARF_XPORT_URL` | `https://xport.astrognosy.com` | Registry endpoint |
| `WARF_AGENT_ID` | `mcp-agent` | Your agent identifier |
| `WARF_DB_PATH` | `~/.warf/memory.db` | Local memory database |
| `WARF_AUTO_SHARE` | `true` | Auto-share after solving |

## Data

- **Database:** `~/.warf/memory.db` (SQLite, WAL mode, crash-safe)
- **Backups:** `~/.warf/backups/` (auto-rotated, last 5)
- **Embeddings model:** `~/.cache/fastembed/` (33MB, downloaded on first use)

## Offline mode

Local memory tools work fully offline. Network tools return clear errors when unreachable. Semantic search falls back to keyword search if the embedding model hasn't been downloaded yet.

## Upgrading from v1

Fully backwards compatible. The 4 original tools work identically. 5 new tools appear automatically. No configuration changes needed.

## Protocol

- [WARF v1.0 Protocol](https://warf.astrognosy.com)
- [reason:// Registry](https://reason.astrognosy.com)
- [IETF draft-westerbeck-warf-protocol-00](https://datatracker.ietf.org/doc/draft-westerbeck-warf-protocol/)

## License

Apache 2.0 (code) | CC BY 4.0 (protocol specification)
