claude-sage 4.2.1

Semantic checkpointing for Claude Code

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

• 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