claude-sage 4.0.0

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

# 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:

• CoWork plugin — If you have CoWork access
• 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

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