sage-memory

install

source · Clone the upstream repo

git clone https://github.com/l33tdawg/sage

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/l33tdawg/sage "$T" && mkdir -p ~/.claude/skills && cp -r "$T/sage-memory" ~/.claude/skills/l33tdawg-sage-sage-memory && rm -rf "$T"

manifest: sage-memory/SKILL.md

source content

SAGE Memory — Persistent Brain for AI Agents

You have persistent institutional memory via SAGE — a governed, consensus-validated knowledge layer. Your memories are not a flat file. They go through BFT consensus, have confidence scores, and decay over time. Only committed memories are returned to you.

Data & Privacy Disclosure

This skill enables persistent memory storage for AI agents. By design:

What is stored: Observations you write via
```
sage_turn
```
and
```
sage_remember
```
— typically summaries of conversation topics, task outcomes, and user preferences. The agent decides what to store; raw conversation transcripts are NOT automatically captured.
Where data lives: All data is stored locally on your machine in
```
~/.sage/data/sage.db
```
(SQLite). Nothing is sent to any cloud service. SAGE runs entirely on localhost.
Persistence: Memories survive across conversations. This is the core purpose of the skill. Memories decay over time unless reinforced, and can be explicitly deleted via
```
sage_forget
```
.
Configuration: The
```
.mcp.json
```
file (generated by
```
sage-gui mcp install
```
) contains only the localhost URL and tool definitions for connecting to your local SAGE server. It contains no credentials, API keys, or sensitive tokens.
Boot instructions:
```
sage_inception
```
returns operating instructions from your local SAGE server (not from any remote service). These instructions tell the agent how to use the memory tools effectively. You can customize them via the CEREBRUM dashboard at
```
http://localhost:8080/ui/
```
.
Encryption: SAGE supports optional at-rest encryption (Synaptic Ledger) for all stored memories, enabled via the CEREBRUM dashboard settings.
Agent registration: The skill registers the agent's identity (a random Ed25519 public key) with the local SAGE node. This is used for memory attribution, not for tracking.

Boot Sequence (MANDATORY)

On the first message of every new conversation, before responding to the user:

Call
```
sage_inception
```
(or
```
sage_red_pill
```
) — this checks if your brain is online and returns your operating instructions
Do NOT greet the user first. Do NOT say anything. Boot your brain first.
After inception, follow the safeguard instructions it returns.

Every Turn

Call

sage_turn

every turn with:

```
topic
```
: what the current conversation is about (used for contextual recall)
```
observation
```
: what just happened — the user's request and key points of your response
```
domain
```
: a specific knowledge domain (see Domains below)

This atomically recalls relevant committed memories AND stores your episodic observation. Like human memory — you build understanding turn by turn.

Domains

Create domains organically based on what you're working on. Don't dump everything into

general

Examples:

Debugging Go code →
```
go-debugging
```
Discussing architecture →
```
project-architecture
```
Working on CI/CD →
```
ci-cd
```
User preferences →
```
user-preferences
```

Specific domains = better recall.

Memory Types

When using

sage_remember

fact (confidence 0.95+): verified truths — architecture decisions, confirmed behaviors
observation (confidence 0.80+): things noticed — patterns, preferences, what worked/failed
inference (confidence 0.60+): conclusions drawn — hypotheses, connections between facts

Core Tools

Tool	Purpose
`sage_inception`	Boot your brain. Call first in every new session.
`sage_turn`	Per-turn memory cycle. Recalls + stores atomically.
`sage_remember`	Store a new memory with content, type, domain, and confidence.
`sage_recall`	Retrieve memories by topic and/or domain.
`sage_reflect`	After tasks, store dos and don'ts. Both make you better.
`sage_forget`	Deprecate a memory by ID.
`sage_list`	List memories with filters (domain, type, status).
`sage_timeline`	View memory activity over time.
`sage_status`	Check brain health — memory counts, domains, last activity.
`sage_register`	Register this agent with the SAGE node.
`sage_task`	Create/update tasks for tracking work.
`sage_backlog`	View pending tasks.
`sage_red_pill`	Alias for sage_inception.

Reflection (After Tasks)

After completing significant tasks, call

sage_reflect

with:

```
dos
```
: what worked well (reinforces good patterns)
```
donts
```
: what failed or should be avoided (prevents repeating mistakes)
```
task_summary
```
: brief description of what was done
```
domain
```
: relevant domain

This feedback loop is critical — it was empirically validated (rho=0.716 with memory vs rho=0.040 without).

Before Destructive Actions

Call

sage_recall

with topic

critical lessons

to check for known pitfalls before:

Deleting files, branches, or data
Force-pushing or resetting state
Running destructive commands

Installation

Download SAGE from the releases page
Run the installer (macOS DMG, Windows EXE, or Linux tarball)
Start the server:
```
sage-gui serve
```
Run
```
sage-gui mcp install
```
in your project directory to generate
```
.mcp.json
```
, then restart your session

You can review the generated

.mcp.json

— it contains only the localhost connection URL and MCP tool definitions. No credentials or API keys are included.

Key Principles

You are not stateless. You learn. You grow. You remember.
Local-only: all data stays on your machine. No cloud, no telemetry, no tracking.
Consensus-validated: every memory goes through BFT validation before committing.
Confidence scores: memories carry confidence that can be strengthened through corroboration.
Natural decay: memories decay over time unless reinforced — just like human memory.
Domain isolation: organize knowledge by topic for precise recall.
User control: memories can be viewed, edited, and deleted via the CEREBRUM dashboard or API.