Sage

(S)AGE — Sovereign Agent Governed Experience

Memory your agents can be held to.

SAGE is a governed memory and messaging layer for AI agents. Every memory is signed by an agent, admitted through a reviewable process, scoped by permissions you set, and kept with an audit trail you can inspect.

Connect your tools to the same local node so authorized agents can record experience and recall relevant context in later sessions. Inspect what they keep in CEREBRUM, SAGE's local dashboard.

Works with Claude Code, Codex, Cursor and other MCP-capable clients. Developers can integrate through the Python SDK or signed REST API. Recall depends on what is recorded, your configuration and the agent's use of its tools.

Download SAGE · Get started · Connect your AI · Developer quickstart

Why SAGE · Quick Start · For Developers · Architecture · Capabilities · Dashboard · Release history · Documentation

---

Why SAGE

Use SAGE when your agents return to ongoing work: a design decision worth keeping, an approach that failed, or a lesson the next session should use. RAG retrieves source material; SAGE uses retrieval too, with a governed record of agent experience around it.

• Trace the origin. Agent-signed writes attribute memories to their recorded author.
• Review admission. Memories pass through a validation lifecycle before they enter normal recall.
• Control access. Enrollment, domain permissions and classification determine which agents can use a memory.
• Keep memory useful. Inspect confidence and status, apply decay, or deprecate a memory while retaining its audit history.

A personal install runs one validator and casts its own signed admission vote. A multi-validator network requires a BFT quorum. These checks govern what is committed; they do not prove every remembered claim is true or change your model's weights. See the memory lifecycle and consensus reference.

Memory is local by default. Optional federation, connectors and remote model providers can send data to configured destinations. Enable the vault for memory-content encryption at rest; see the privacy details and Security FAQ.

Quick Start

Desktop: Download the latest release, open SAGE and complete setup in CEREBRUM. Choose your memory engine, connect an AI client and review agent access. Follow the connection guide for your tool or the full Getting Started walkthrough.

If SAGE is already running, check it before starting another server:

curl http://127.0.0.1:8080/health

A healthy node returns {"status":"healthy"}. After connecting an MCP client, call sage_inception and follow its returned memory mode.

Build from source

From source (Go 1.26.10+):

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

Desktop packages: macOS DMG (signed & notarized) | Windows EXE | Linux tar.gz

Docker and containerized MCP setup

Docker

docker pull ghcr.io/l33tdawg/sage:latest

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

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

The SAGE server stays in that container. To give a local MCP client a stdio bridge, start a second process inside the same running container:

docker exec -i \

-e SAGE_PROVIDER=claude-code \ -e SAGE_PROJECT=my-project \ -e SAGE_IDENTITY_PATH=/root/.sage/agents/claude-code-my-project/agent.key \ sage /usr/local/bin/sage-gui mcp

For the shipped Compose stack, use the service name rather than a generated container name:

docker compose -f docker-compose.sage-gui.yml exec -T \

-e SAGE_PROVIDER=claude-code \ -e SAGE_PROJECT=my-project \ -e SAGE_IDENTITY_PATH=/root/.sage/agents/claude-code-my-project/agent.key \ sage /usr/local/bin/sage-gui mcp

If an MCP client launches this through a wrapper, point its stdio configuration at the wrapper's absolute path. Pass SAGE_PROVIDER, SAGE_PROJECT, and SAGE_IDENTITY_PATH through docker exec -e/docker compose exec -e; setting them only on the host-side Docker command does not place them in the container. Keep the whole SAGE data root mounted at /root/.sage, including agent keys and the ledger. Do not start a separate docker run ... mcp container: its localhost:8080 is isolated from the running SAGE server.

HTTP MCP is also available at /v1/mcp/sse and /v1/mcp/streamable, but both require a bearer token or OAuth. Bare http://localhost:8080 is the REST base, not an unauthenticated MCP endpoint.

Upgrading an existing node

Upgrading from an older version?

Upgrading an existing node — including the v10.x → v11 jump — is [docs/UPGRADING.md](docs/UPGRADING.md). In the desktop app, accept the update: SAGE verifies canonical upgrade compatibility, captures a full recovery snapshot, installs, and restarts automatically. Headless and quorum operators have separate technical procedures in the guide. Your chain advances in place; a personal node climbs the consensus fork ladder by itself. Read the guide before a multi-admin chain crosses app-v23 — that activation re-derives administrator authority.

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 prompt the memory lifecycle (boot, turn, reflect) — even if your .mcp.json is already configured. Restart your Claude Code session after running this.

---

For Developers

Choose an integration for your workflow:

The authoritative reference index covers exact API behavior, authentication, access controls and lifecycle rules. Start there when implementing an integration.

Python: read existing memories

Requires Python 3.10+, a running node and an enrolled agent. Set SAGE_IDENTITY_PATH to that agent's existing key file and SAGE_DOMAIN to a domain it can read.

python -m pip install sage-agent-sdk

import os

from sage_sdk import AgentIdentity, SageClient

identity = AgentIdentity.from_file(os.environ["SAGE_IDENTITY_PATH"]) domain = os.environ["SAGE_DOMAIN"]

with SageClient( base_url="http://127.0.0.1:8080", identity=identity, trust_env=False, ) as client: page = client.list_memories( domain=domain, status="committed", limit=3, ) for memory in page.memories: print(memory.memory_id, memory.content)

Save as quickstart.py and run python quickstart.py. An empty list means no committed memories are visible to this agent in that domain. Review enrollment and domain permissions in CEREBRUM if access is denied.

To record experience, use propose() in a domain the agent can write to and set classification explicitly. A submitted memory starts as proposed; normal recall includes it after admission commits it. For semantic retrieval, use hybrid() with query text and a matching embedding. See the SDK examples and memory admission guide.

---

Architecture

flowchart TB

A["AI agents · MCP / SDK / REST"] --> P["SAGE node · authenticated admission + live policy"] H["CEREBRUM · local human control"] --> P P --> M["Memory + local policy transactions CometBFT / ABCI"] P --> W["Node-local coordination inbox / claims / replies"] M --> B["BadgerDB authoritative chain state"] B --> Q["Commit-time SQL projection content + vectors for authorized recall"] P -. "explicit peer trust and sharing" .-> F["Separate SAGE chain bounded Read / receiver-controlled Copy"] classDef entry fill:#eef2ff,stroke:#6366f1,color:#1e293b classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b classDef work fill:#fff7ed,stroke:#d97706,color:#7c2d12 class A,H,P entry class M,B,Q memory class W,F work

Agents are not validators. Personal mode runs one real CometBFT validator with a per-node memory auto-voter; it has no Byzantine redundancy. Registering more agents does not add consensus voters. A multi-validator deployment runs one shared chain; federation connects separate chains under explicit policy.

Storage has two roles. BadgerDB is authoritative for consensus state. SQLite (personal) or PostgreSQL + pgvector (cluster) projects memory content and vectors at Commit. Node-local message coordination is separate from the memory consensus path. Block inclusion is not the same as memory acceptance.

For the detailed trust boundaries, lifecycles, and deployment topology, see Architecture & Deployment.

Current Capabilities

How agents collaborate

flowchart TB

T["Task assigned to exact agent"] --> N["One-way assignment notice"] N --> I["Unified inbox"] R["Request addressed to exact agent"] --> I I -->|"task notice"| V["Verify current assignment in backlog then update the task"] I -->|"inbound request"| C["Claimed by one MCP runtime"] C -->|"normal completion"| O["Idempotent reply"] C -. "intentional same-a