Sage

Memory for Claude Code. Research → checkpoint → compaction → auto-restore.

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Research   │───▶│ Checkpoint  │───▶│  Compaction │
│  with Claude│    │  (auto)     │    │  happens    │
└─────────────┘    └─────────────┘    └──────┬──────┘
                                             │
┌─────────────┐    ┌─────────────┐           │
│  Continue   │◀───│ Auto-inject │◀──────────┘
│  seamlessly │    │  context    │
└─────────────┘    └─────────────┘

v4.0 — Invisible Context Hydration: System folders, failure memory, MCP resources, knowledge linking.

Quick Start

Option A: Claude Code Plugin (Recommended)

# 1. Add the marketplace (one-time)
/plugin marketplace add b17z/sage

# 2. Install the plugin
/plugin install sage@sage

Or run /plugin and use the interactive UI to browse and install.

Option B: Manual Install

# 1. Install
pip install claude-sage[mcp]

# 2. Setup (adds MCP server + installs methodology skills)
sage mcp install
sage skills install

# 3. Use Claude - Sage handles the rest
claude

That's it. Claude now has memory across sessions.

How It Works

The problem: You're 2 hours into research. Context fills up, auto-compacts, nuanced findings gone. Tomorrow you start from scratch.

The solution: Sage checkpoints at meaningful moments—not when tokens run out, but when something worth remembering happens:

Each checkpoint captures your thesis, confidence, open questions, sources, and tensions (where experts disagree).

What Gets Saved

# Where do stablecoins win vs traditional rails?

## Thesis (75% confidence)
Integrate, don't replace. Stablecoins win middle-mile,
not POS checkout.

## Open Questions
- Timeline for Stripe's full stack?

## Tensions
- sheel_mohnot vs sam_broner: merchant profitability — unresolved

Checkpoints are Markdown files (Obsidian-compatible) in ~/.sage/checkpoints/ or .sage/checkpoints/ (project-local).

The Three Layers

┌────────────────────────────────────────────────┐
│  Skills (methodology)                          │
│  sage-memory, sage-research, sage-session      │
│  Load on-demand when context matches           │
├────────────────────────────────────────────────┤
│  MCP Server (tools + resources)                │
│  sage_save_checkpoint, sage_recall_knowledge   │
│  @sage://system/objective.md (v4.0)            │
├────────────────────────────────────────────────┤
│  Storage                                       │
│  ~/.sage/checkpoints/, ~/.sage/knowledge/      │
│  .sage/system/, .sage/failures/ (v4.0)         │
└────────────────────────────────────────────────┘

• Skills teach Claude when and how to checkpoint
• MCP gives Claude the tools to save/load, resources for direct access
• Storage persists everything as readable Markdown

CLI Basics

sage checkpoint list          # See your checkpoints
sage checkpoint show <id>     # View one
sage knowledge list           # See stored knowledge
sage knowledge match "query"  # Test what would recall
sage skills list              # Check installed skills
sage watcher start            # Auto-detect compaction

# Configuration
sage config list              # View current settings
sage config set checkpoint_max_age_days 30  # Customize storage
sage config set failure_memory_enabled true # Enable failure memory (v4.0)

Visual Interface

sage ui              # Local web UI at localhost:5555
sage ui --api-only   # REST API for custom frontends

Or use any of these:

• Obsidian — Open ~/.sage/ as vault (it's just Markdown)
• Custom — Build on the REST API

See docs/ui.md for details.

Learn More

• Features — Complete feature reference
• What's New in v4.0 — System folder, failures, resources
• Architecture — System design
• Security — Security measures and threat model
• Skills — How methodology skills work
• Continuity — Session persistence deep-dive
• Maintenance — Storage maintenance and caching
• UI Options — Web UI, API, Obsidian, CoWork plugin

Known Issues

Plugin MCP Tool Naming

When installed as a Claude Code plugin, MCP tools follow the format mcp__plugin_<plugin>_<server>__<tool>. Since both the plugin and MCP server are named "sage", tools appear as mcp__plugin_sage_sage__save_checkpoint rather than the expected mcp__plugin_sage__save_checkpoint.

This is documented Claude Code behavior — the official MCP integration docs show the same pattern with asana_asana as an example. No official plugins currently use MCP servers, so there's no precedent for cleaner naming.

Workaround: The plugin works correctly despite the redundant naming. If this bothers you, install via pip instead (pip install claude-sage[mcp]).

Requirements

• Python 3.12+
• Claude Code CLI

Development

pip install -e ".[dev,mcp]"
pytest tests/ -v  # 1624 tests

Acknowledgments

Output formatting inspired by TOON — a token-efficient notation format for LLMs by @mixeden.

License

MIT