sage

# (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)
  ├── Memory Auto-Voter (dedup, quality, consistency — one vote per node, signed with the node's consensus key)
  ├── Governance Engine (on-chain validator proposals + voting)
  ├── 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 a per-node memory auto-voter — every memory write goes through pre-validation, a signed vote transaction, and the BFT quorum before committing. One node casts one vote; add more agents from the dashboard and each node votes with its own key, exactly the same consensus pipeline as a multi-node deployment.

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

---

## CEREBRUM Dashboard

![CEREBRUM MRI brain — memories mapped inside a 3D brain with focused related notes](docs/screen-brain.png)

`http://localhost:8080/ui/` — a dashboard-native operator console centered on the 3D MRI memory brain, with chain health, agents, federation, semantic memory, recall tuning, vault recovery, tasks, imports, and updates around it. Every major workflow is available from the browser; the CLI stays there for automation and recovery.

| Control Board | Federation | Recall Engine |
|:---:|:---:|:---:|
| ![CEREBRUM overview dashboard](docs/screen-overview.png) | ![Federation join dashboard](docs/screen-network.png) | ![Recall engine settings](docs/screen-config.png) |
| Chain health, quorum, agents, federation, and embeddings | One trust-only JOIN that prepares Direct and Secure relay automatically, followed by independent Read/Copy choices on each SAGE | Smart-memory setup, managed reranker install, and recall-depth tuning |

The dashboard also includes agent management, domain permissions, key rotation, import/export, software updates, and encryption controls.

---

## What's New in v11.19.13

**The stdio MCP bridge no longer self-installs project hooks into the user’s
home directory.** When `sage-gui mcp` starts with `$HOME` as its working
directory, automatic project repair now returns without writing `.claude`
hooks or project-relative hook registrations into user-global configuration.

Explicit `sage-gui mcp install` and `sage-gui codex install` commands keep their
existing home-directory refusal. Normal project-directory self-healing also
remains unchanged, including when `CLAUDE_CONFIG_DIR` points elsewhere.

This patch changes no consensus rule, AppHash input, key encoding, fork target,
or application version. Existing app-v27 chains replay byte-identically.

Container: `ghcr.io/l33tdawg/sage:11.19.13`. SDK 11.19.13.

## What's New in v11.19.12

**Project-scoped MCP and Codex installs can no longer corrupt user-global host
configuration.** `sage-gui mcp install` and `sage-gui codex install` now refuse
to run when the working directory resolves to the user's home directory. Run
the command from the intended project instead; ordinary project installs are
unchanged.

The native-shell build also refreshes its fail-closed checksum for the official
September `linuxdeploy-plugin-appimage` rebuild. The replacement was produced
by the upstream project's successful scheduled workflow from its unchanged
source commit, and its downloaded SHA-256 matches GitHub's release-asset
digest. An unexpected future replacement will continue to stop the build.

This patch changes no consensus rule, AppHash input, key encoding, fork target,
or application version. Existing app-v27 chains replay byte-identically.

Container: `ghcr.io/l33tdawg/sage:11.19.12`. SDK 11.19.12.

## What's New in v11.19.11

**CEREBRUM now supports operator-configured hostnames behind a local TLS
reverse proxy.** Set `SAGE_ALLOWED_CEREBRUM_HOSTS` to an exact comma-separated
hostname allowlist when Caddy, Traefik, or another loopback proxy preserves the
browser-facing `Host` instead of rewriting it to `localhost`. Ports are
normalized and wildcards are deliberately unsupported.

The trust boundary stays local: the connected peer and every forwarded IP hop
must still be loopback, unconfigured hostnames still fail closed, and browser
origin matching accepts `X-Forwarded-Proto` only when every field-line and
comma-joined token is a valid, case-insensitive `http` or `https` value and all
hops agree. Empty, malformed, or mixed scheme chains are rejected.

This patch changes no consensus rule, AppHash input, key encoding, fork target,
or application version. Existing app-v27 chains replay byte-identically.

Container: `ghcr.io/l33tdawg/sage:11.19.11`. SDK 11.19.11.

## What's New in v11.19.10

**Returning agents can be reviewed normally again.** When app-v26 retirement
has handed an agent's former home domain to the stable Root principal,
CEREBRUM reapproval now binds the existing owner and uses the established
Root-to-agent recovery transfer for that exact recorded home. Fresh or
operator-entered domains never receive an implicit transfer.

Rejecting a pending registration now counts active memories—the same lifecycle
view shown by the recovery panel—instead of treating deprecated audit history
as work the operator can still remediate. Active records continue to block
ordinary rejection unless they are deprecated, transferred, or the explicit
attribution-preserving force path is chosen.

This patch changes no consensus rule, AppHash input, key encoding, fork target,
or application version. Existing app-v27 chains replay byte-identically.

Container: `ghcr.io/l33tdawg/sage:11.19.10`. SDK 11.19.10.

## What's New in v11.19.9

**Codex workspace identity resolution now fails closed at the filesystem
root.** A user-level Codex MCP process launched from `/` can no longer reuse the
retired `global-codex` signer or auto-register the synthetic name `codex//`.
SAGE rejects that broad, untrustworthy boundary before Git discovery,
project-config lookup, key loading, or key generation. Real project and linked
worktree roots continue to resolve to their stable workspace identities;
operators who intentionally need a non-workspace shared identity must pin it
explicitly with `SAGE_IDENTITY_PATH`.

This patch changes no transaction, AppHash input, key encoding, fork target, or
application version. Existing app-v27 chains replay byte-identically.

Container: `ghcr.io/l33tdawg/sage:11.19.9`. SDK 11.19.9.

## What's New in v11.19.8

**Access Groups now discover transferred historical domains, not only each
member's enrollment-time home domain.** CEREBRUM's bounded caller-domain
projection consults the consensus-maintained current-owner index for the caller
and active local group peers. A transferred `user-*` domain therefore appears
as a usable exact recall or write target even when its current owner never
authored a memory there.

Every discovered candidate is still re-authorized against current ownership,
group authority, profile restrictions, and hard denies before it is returned.
Per-record classification checks remain on the memory disclosure path. The
result remains bounded and explicitly reports truncation; it does
not expose a global domain roster, change ownership, copy grants, or weaken
shared-domain and foreign-write restrictions.

This patch changes no transaction, AppHash input, key encoding, fork target, or
application version. Existing app-v27 chains replay byte-identically.

Container: `ghcr.io/l33tdawg/sage:11.19.8`. SDK 11.19.8.

## What's New in v11.19.5

**Claim recovery and host wake coordination now survive real multi-transport
runtimes.** Both exact-local compatibility claim paths—`GET /v1/pipe/inbox`
and explicit `PUT /v1/pipe/{pipe_id}/claim`—atomically bind the session and
create its receipt, so ownership cannot commit without recovery evidence. MCP
claimant identities are durable and transport-scoped across stdio,
Streamable HTTP, and SSE; `claimant_identity_mode` discloses whether the
identity is durable, a safe concurrent ephemeral fallback, inherited, or
unavailable.

Claim transfer remains deliberate. `sage_message_handoff` requires the exact
`claimant_session_id` and `claim_revision` returned by passive history; stale
or A→B→A delayed transfers fail the revisioned compare-and-swap fence. The
direct REST route preserves pre-v11.19.5 clients by treating an omitted
`from_revision` as 0 only, so it can move an untouched first-generation claim
but safely conflicts after any transfer. SAGE never steals a claim merely
because it is old.

The new signed, payload-free `GET /v1/inbox/activity-state` returns exactly
`{version,epoch,seq}` so host hooks can notice fresh task assignments and
replies. The opaque 32-character database-incarnation `epoch` survives process
restarts and backup restore, but changes for a fresh database so an old host
cursor cannot suppress ne