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:
| Trigger | Example |
|---|
| Synthesis | "Therefore, the answer is..." |
| Branch point | "We could either X or Y..." |
| Constraint | "This won't work because..." |
| Topic shift | Conversation changes direction |
| Manual | You say "checkpoint this" |
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
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.