io.github.l33tdawg/sage

Install

Config snippet generator goes here (5 client tabs)

README

# (S)AGE — Sovereign Agent Governed Experience

**Persistent, consensus-validated memory infrastructure for AI agents.**

SAGE gives AI agents institutional memory that persists across conversations, goes through BFT consensus validation, carries confidence scores, and decays naturally over time. Not a flat file. Not a vector DB bolted onto a chat app. Infrastructure — built on the same consensus primitives as distributed ledgers.

The architecture is described in [Paper 1: Agent Memory Infrastructure](papers/Paper1%20-%20Agent%20Memory%20Infrastructure%20-%20Byzantine-Resilient%20Institutional%20Memory%20for%20Multi-Agent%20Systems.pdf).

> **Just want to install it?** [Download here](https://l33tdawg.github.io/sage/) — double-click, done. Works with any AI.

<a href="https://glama.ai/mcp/servers/l33tdawg/s-age">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/l33tdawg/s-age/badge" alt="(S)AGE MCP server" />
</a>

---

## Architecture

```
Agent (Claude, ChatGPT, DeepSeek, Gemini, etc.)
  │ MCP / REST
  ▼
sage-gui
  ├── ABCI App (validation, confidence, decay, Ed25519 sigs)
  ├── App Validators (sentinel, dedup, quality, consistency — BFT 3/4 quorum)
  ├── CometBFT consensus (single-validator or multi-agent network)
  ├── SQLite + optional AES-256-GCM encryption
  ├── CEREBRUM Dashboard (SPA, real-time SSE)
  └── Network Agent Manager (add/remove agents, key rotation, LAN pairing)
```

Personal mode runs a real CometBFT node with 4 in-process application validators — every memory write goes through pre-validation, signed vote transactions, and BFT quorum before committing. Same consensus pipeline as multi-node deployments. Add more agents from the dashboard when you're ready.

Full deployment guide (multi-agent networks, RBAC, federation, monitoring): **[Architecture docs](docs/ARCHITECTURE.md)**

---

## CEREBRUM Dashboard

![CEREBRUM — Neural network memory visualization](docs/screen-brain.png)

`http://localhost:8080/ui/` — force-directed neural graph, domain filtering, semantic search, real-time updates via SSE.

### Network Management

![Network — Multi-agent management](docs/screen-network.png)

Add agents, configure domain-level read/write permissions, manage clearance levels, rotate keys, download bundles — all from the dashboard.

### Settings

| Overview | Security | Configuration | Update |
|:---:|:---:|:---:|:---:|
| ![Overview](docs/screen-overview.png) | ![Security](docs/screen-security.png) | ![Config](docs/screen-config.png) | ![Update](docs/screen-update.png) |
| Chain health, peers, system status | Synaptic Ledger encryption, export | Boot instructions, cleanup, tooltips | One-click updates from dashboard |

---

## What’s New in v5.1.0

- **Agent Rename Fix** — Renaming an agent in the dashboard (Network → Agents → Edit) now reliably syncs to on-chain state. Previously, the CometBFT broadcast was fire-and-forget and could silently fail, causing `sage_inception` to return the old auto-generated name.
- **Self-Healing Name Reconciliation** — If on-chain and display names ever diverge, `sage_inception` automatically detects and repairs the mismatch on the agent’s next boot.
- **Broadcast Error Feedback** — The dashboard now warns you if an on-chain sync fails instead of silently swallowing the error.

### v5.0.12

- **MCP Identity Fix** — `sage-gui mcp` and `sage-gui mcp install --token` now respect `SAGE_IDENTITY_PATH` environment variable as the **highest priority** (exactly matching the SDK’s `AgentIdentity.default()`).
- Auto-creates directories + keypair if missing. Added clear INFO logs. 100% backward compatible.
- Enables clean multi-agent setups (e.g. multiple Claude Code instances in tmux). Closes the identity collision issue.

## What’s New in v5.0.11

- **Docker Fix** — Container no longer stuck in restart loop. Default entrypoint changed from MCP stdio mode to `serve` (persistent REST API + dashboard). MCP stdio still available via `docker run -i ghcr.io/l33tdawg/sage mcp`. Fixes #14.

### v5.0.10

- **Multi-Agent Identity** — New `SAGE_IDENTITY_PATH` env var and `AgentIdentity.default()` for running multiple Claude Code agents on the same machine without key collisions. (Community PR by @emx)
- **Dashboard Fix** — "Synaptic Ledger" label in overview settings now reads "Synaptic Ledger Encryption" to clarify it refers to the encryption state, not the ledger itself.

### v5.0.9

- **Upgrade Hang Fix** — Fixed CometBFT startup hang after drag-and-drop upgrades. Stale consensus WAL files left behind during migration caused a 60-second timeout and prevented the REST API from starting. Now cleaned up automatically at both migration and startup time.

### v5.0.7

- **Agent Pipeline** — Inter-agent message bus (`sage_pipe`) for direct agent-to-agent communication. Send messages, check results, coordinate work across agents in real-time.
- **Python Agent SDK** — `sage-agent-sdk` on PyPI with full v5 API coverage for building SAGE-integrated agents. CI-tested on every r