sage

# (S)AGE — Sovereign Agent Governed Experience

![SAGE: governed memory for AI agents, with a lavender neural brain](docs/brand/sage-twitter-cover.png)

**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](https://github.com/l33tdawg/sage/releases/latest) ·
[Get started](https://l33tdawg.github.io/sage/#get-started) ·
[Connect your AI](https://l33tdawg.github.io/sage/connect.html) ·
[Developer quickstart](https://l33tdawg.github.io/sage/#developers)

[Why SAGE](#why-sage) · [Quick Start](#quick-start) · [For Developers](#for-developers) · [Architecture](#architecture) ·
[Capabilities](#current-capabilities) · [Dashboard](#cerebrum-dashboard) ·
[Release history](#release-history) · [Documentation](#documentation)

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

---

## 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](docs/reference/concepts/memory-lifecycle.md)
and [consensus reference](docs/reference/concepts/consensus-confidence-decay.md).

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](https://l33tdawg.github.io/sage/privacy.html)
and [Security FAQ](SECURITY_FAQ.md).

## Quick Start

**Desktop:** [Download the latest release](https://github.com/l33tdawg/sage/releases/latest),
open SAGE and complete setup in CEREBRUM. Choose your memory engine, connect an
AI client and review agent access. Follow the
[connection guide](https://l33tdawg.github.io/sage/connect.html) for your tool or
the full [Getting Started](docs/GETTING_STARTED.md) walkthrough.

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

```bash
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.

<details>
<summary>Build from source</summary>

**From source (Go 1.26.9+):**

```bash
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
```

</details>

Desktop packages: [macOS DMG](https://github.com/l33tdawg/sage/releases/latest) (signed & notarized) | [Windows EXE](https://github.com/l33tdawg/sage/releases/latest) | [Linux tar.gz](https://github.com/l33tdawg/sage/releases/latest)

<details>
<summary>Docker and containerized MCP setup</summary>

### Docker

```bash
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.24.0`.

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**:

```bash
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:

```bash
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.

</details>

<details>
<summary>Upgrading an existing node</summary>

### 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:

```bash
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.

</details>

---

## For Developers

Choose an integration for your workflow:

| Integration | Use it for | Start here |
| --- | --- | --- |
| MCP | Giving an existing AI client memory and coordination tools | [Connection guide](https://l33tdawg.github.io/sage/connect.html) · [MCP reference](docs/reference/mcp-tools.md) |
| Python SDK | Building a memory-aware agent or application with sync/async clients | [Developer quickstart](https://l33tdawg.github.io/sage/#developers) · [SDK reference](docs/reference/python-sdk.md) |
| Signed REST API | Integrating from another language over HTTP | [REST reference](docs/reference/rest-api.md) |

The [authoritative reference index](docs/reference/INDEX.md) 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.

```bash
python -m pip install sage-agent-sdk
```

```python
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](docs/reference/python-sdk.md) and
[memory admission guide](docs/reference/concepts/voter-operations.md).

---

## Architecture

```mermaid
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<br/>CometBFT / ABCI"]
    P --> W["Node-local coordination<br/>inbox / claims / replies"]
    M --> B["BadgerDB<br/>authoritative chain state"]
    B --> Q["Commit-time SQL projection<br/>content + vectors for authorized recall"]
    P -. "explicit peer trust and sharing" .-> F["Separate SAGE chain<br/>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