(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.

Just want to install it? Download here — double-click, done. Works with any AI.

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)
  ├── 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 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

CEREBRUM Dashboard

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

Network Management

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

Settings

What's New in v8.0

Access-control consensus cleanup. The three real bugs levelup surfaced on v7.1 — subdomain grants don't cascade, granting on an unowned domain fails, and a lost-owner domain has no recovery path — all land in a single consensus-rule fork gated behind the v7.5 upgrade machinery. Existing v7.1.x chains upgrade in place: the watchdog auto-proposes activation at app-v2, the fork takes effect at H+1, pre-fork blocks replay byte-identical to v7.1.1.

• Ancestor-walk grants (HasAccessOrAncestor). A grant on pipeline.failures now covers pipeline.failures.pwn_buffer_overflow and every descendant. Walks the dotted path leaf → root, first valid grant wins, 16-segment cap, shared domains (general, self, meta, sage-*) are barriers (NOT inheritable ancestors). HasAccessMultiOrg's same-org clearance and federation paths inherit ancestor semantics via a new ResolveOwningAncestor resolver, so a domain whose ancestor is owned by org-X grants the same access as if the leaf itself were owned by org-X. Levelup's bootstrap script can stop registering every sub-domain by hand.

• Auto-register on grant for unowned domains. processAccessGrant now mirrors processMemorySubmit's auto-register pattern: granting on an unowned non-shared domain makes the granter the owner atomically with the grant. Same-block races resolved by re-checking ownership after ErrDomainAlreadyRegistered (grants can't swallow the error the way submits do — if the granter lost the race, the second grant fails with Code 34 instead of writing for someone else's domain). Composes with the ancestor walk: a single grant on a parent both claims and propagates to all descendants. Shared domains explicitly reject with Code 50 — they're not ownable, ever.

• Governance-gated domain reassign (TxTypeDomainReassign). A new tx type, gated by a 3/4 supermajority gov proposal (typed exception to default 2/3), reassigns domain ownership and atomically clears all existing grants on the reassigned domain. The proposal carries a typed Payload (the same field SDK consumers see as governance_propose(payload=...)) so the on-chain proposal records exactly what the future DomainReassign tx will execute — body mismatch rejects with Code 83. Optional open_to_shared=true writes an on-chain shared_domain:<name> sentinel and the dynamic-shared-domain check goes hot — operators can promote a domain to the shared namespace without a code release.

• REST surface. New POST /v1/domain/reassign wraps the tx build + broadcast_tx_commit so FinalizeBlock rejections (Codes 80-87) surface as HTTP 403 with the upstream Log forwarded. POST /v1/governance/propose accepts an optional payload (base64-encoded bytes) for proposals that carry operation-specific data. Both documented in api/openapi.yaml.

• Python SDK 8.0.0. client.submit_domain_reassign(domain, new_owner_id, proposal_id, parent_domain="", open_to_shared=False) + client.governance_propose(..., payload=dict | bytes | None) on sync + async. Plus a high-level client.reassign_domain(domain, new_owner_id, reason, ...) end-to-end helper that proposes, polls until executed (or surfaces rejected/expired/cancelled as SageAPIError), and submits the reassign — single call to move ownership. pip install sage-agent-sdk>=8.0.0.

• Observability. New sage_fork_branch_total{fork="v8",branch="pre|post"} Prometheus counter, incremented inside each fork-gated handler so the cutover is visible live on dashboards: pre's rate rolls to zero, post starts counting, on the same block.

• Fork-gate plumbing. Shared across all three fixes — SageApp.v8AppliedHeight populated from the v7.5 audit trail (BadgerStore.GetAppliedUpgrade("app-v2")), postV8Fork(height) predicate for consensus handlers (strict > boundary mirrors CometBFT's H+1 semantic), IsPostV8Fork() accessor for REST handlers that don't carry a deterministic block height. Refreshed on NewSageApp boot and on FinalizeBlock activation. Pre-fork branches preserved byte-identical to v7.1.1; unit-test coverage on both branches for every fix.

Older releases

• v7.7 — Agent profile fill-in. GET /v1/agent/me now returns the full profile the OpenAPI schema promised — display_name, domains, accuracy, on_chain_height — so SDK consumers don't round-trip to /v1/agent/{id} plus the validator-score endpoint just to render a profile card.

• v7.6 — Direct-write hooks for Claude Code and Codex. sage-gui hook session-start | session-end signs REST calls to the local SAGE node directly; mcp install and codex install ship the unified 5-script lifecycle set; selfHeal migrates legacy installs and auto-installs hooks on MCP boot for pre-v7.6 projects (v7.6.2).

• v7.5 — Migration substrate. Hands-off in-place chain upgrades — scheduled snapshots with verify-by-restore, upgrade tx types with chain-computed activation height, auto-proposal watchdog, HALT sentinel + supervised rollback. v7.5.0 itself ships zero consensus-rule changes; it's the plumbing every later release rides on.

• v7.1 — Recall quality + second benchmark. Optional cross-encoder reranking and query expansion on /v1/memory/hybrid, LoCoMo benchmark (R@5=0.6394 stock), SAGE adapter shipped upstream to mem0's open-source evaluator. v7.1.1 closed the silent ghost-tx surface on RBAC/governance writes.

• v7.0 — Hybrid recall + ambient capture. BM25 + vector fused via Reciprocal Rank Fusion on a new /v1/memory/hybrid endpoint, direct-write lifecycle hooks for Claude Code, branch-aware memory tagging, LongMemEval-S benchmark at R@5=0.9053.

• v6.8 — Hardening pass. OAuth Dynamic Client Registration + persistent client metadata, mandatory state + HMAC-signed CSRF on /oauth/authorize, strict same-origin on CEREBRUM wizard endpoints, locked-down subprocess test seams. Admin-bootstrap escape hatch (6.8.5), cross-agent visibility hotfix (6.8.4), Windows wizard parity (6.8.1).

• v6.7 — ChatGPT MCP connector. OAuth 2.0 + PKCE wrapper, RFC 8414/7591/9728 discovery and Dynamic Client Registration, in-dashboard ChatGPT setup wizard (6.7.3, Cloudflare zone dropdown 6.7.4), HTTPS-capable HTTP MCP transport (/v1/mcp/sse + /v1/mcp/streamable on :8443) with bearer tokens.

• v6.6 — Tags + multi-org + RBAC fixes. Tags first-class on /v1/memory/submit and /query//search filtering. Multi-org membership reverse index so agents in N orgs no longer silently lose access to N-1 of them. PUT /v1/agent/{id}/permission no longer silent-no-ops for non-admin self/org-admin callers. SQLITE_BUSY silent-drop fix at source (WAL pragma + writeMu-guarded BeginTx). Encrypted CA key in quorum manifest (Argon2id + AES-256-GCM envelope).

• v6.5 — TLS everywhere. Per-quorum ECDSA P-256 CA, dual-listener REST API (TLS :8443 + local HTTP :8080), Python SDK ca_cert parameter. Stuck-proposed deprecation when quorum unreachable. RBAC ownership-theft fix + real broadcast errors surfaced to clients.

• v6.0 — Dynamic validator governance. Add/remove/repower validators without stopping the chain via on-chain governance proposals (2/3 BFT quorum). New internal/governance/ package, in-dashboard Governance section.

• v5.x — Consensus-first writes + FTS5. All submissions go through BFT consensus before they surface in queries. 4-validator Docker cluster with fault injection in CI. FTS5 keyword search fallback. Nonce-based replay protection. Python SDK.

• v4.x — App validators + RBAC + Synaptic Ledger. Sentinel / Dedup / Quality / Consistency validators with 3/4 quorum. Agent isolation, domain-level permissions, clearance levels, multi-org federation. AES-256-GCM encryption with Argon2id key derivation.

• v3.x — Multi-agent networks. Add agents from dashboard, LAN pairing, key rotation, redeployment orchestrator. On-chain agent identity via CometBFT consensus. CEREBRUM dashboard.

Research

Quick Start

git clone https://github.com/l33tdawg/sage.git && cd sage
go build -o sage-gui ./cmd/sage-gui/
./sage-gui setup    # Pick your AI, get MCP config
./sage-gui serve    # SAGE + Dashboard on :8080

Or grab a binary: macOS DMG (signed & notarized) | Windows EXE | Linux tar.gz

Docker

docker pull ghcr.io/l33tdawg/sage:latest
docker run -p 8080:8080 -v ~/.sage:/root/.sage ghcr.io/l33tdawg/sage:latest

Pin a specific version with ghcr.io/l33tdawg/sage:6.0.0.

Upgrading from an older version?

If you installed SAGE before v5.0 and your AI isn't doing turn-by-turn memory updates, re-run the installer in your project directory:

cd /path/to/your/project
sage-gui mcp install

This installs Claude Code hooks that enforce the memory lifecycle (boot, turn, reflect) — even if your .mcp.json is already configured. Restart your Claude Code session after running this.

Documentation

Stack

Go / CometBFT v0.38 / chi / SQLite / Ed25519 + AES-256-GCM + Argon2id / MCP

License

Code: Apache 2.0 | Papers: CC BY 4.0

Author

Dhillon Andrew Kannabhiran (@l33tdawg)