l33tdawg/sage

**Stop re-explaining your project.**
SAGE gives AI agents a persistent memory of project decisions, failed approaches
and useful lessons. 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:
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.9+):**
Desktop packages: macOS DMG (signed & notarized) | Windows EXE | Linux tar.gz
Docker and containerized MCP setup
Docker
Pin a specific version with ghcr.io/l33tdawg/sage:11.23.24.
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**:
For the shipped Compose stack, use the service name rather than a generated
container name:
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.** 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:
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:
| Integration | Use it for | Start here |
| --- | --- | --- |
| MCP | Giving an existing AI client memory and coordination tools | Connection guide · MCP reference |
| Python SDK | Building a memory-aware agent or application with sync/async clients | Developer quickstart · SDK reference |
| Signed REST API | Integrating from another language over HTTP | REST reference |
The authoritative reference index covers exact API
behavior, authentication, access controls and lifecycle rules. Start there
when implementing an integration.
Python: read existing memories