claude-sage 2.5.0

Semantic checkpointing for Claude Code

Sage

Stop losing context. Start checkpointing your AI research.

Sage is a Claude Code plugin that gives your AI assistant memory across sessions. When you're deep in research or complex problem-solving, Sage helps Claude automatically save semantic checkpoints—capturing what matters (conclusions, tensions, discoveries) and discarding what doesn't (the meandering path to get there).

The Problem

You're 2 hours into a research session with Claude. You've explored 15 sources, validated 3 hypotheses, found a critical disagreement between experts, and synthesized a thesis. Then:

• Context window fills up → auto-compaction loses your nuanced findings
• You close the session → tomorrow you start from scratch
• You switch projects → that research thread is orphaned

The result: You become the orchestration layer, manually maintaining state across fragmented chat sessions like a conspiracy board.

The Solution

Sage teaches Claude to checkpoint proactively—not when tokens run out, but when something meaningful happens:

• Hypothesis validated or invalidated
• Critical constraint discovered
• Synthesis moment ("putting this together...")
• Branch point ("we could either X or Y")
• You say "checkpoint" or "save this"

Each checkpoint captures:

• Core question — What decision is this driving toward?
• Thesis + confidence — Your current synthesized position
• Open questions — What's still unknown
• Sources — Decision-relevant summaries (not full content)
• Tensions — Where credible sources disagree (high value!)
• Unique contributions — What YOU discovered, not just aggregated

Quick Start

1. Install

# From PyPI (recommended)
pip install claude-sage[mcp]

# Or from source
git clone https://github.com/b17z/sage.git
cd sage
pip install -e ".[mcp]"

2. Configure Claude Code

Add to your .mcp.json (project or ~/.claude/.mcp.json for global):

{
  "mcpServers": {
    "sage": {
      "command": "sage-mcp"
    }
  }
}

Or install hooks for auto-checkpoint detection:

sage hooks install

3. Test it

# Start Claude Code
claude

# Have a conversation, do some research
# Sage MCP tools are now available to Claude
# Claude will checkpoint automatically on synthesis moments

# Later, list your checkpoints:
sage checkpoint list
sage checkpoint show <checkpoint-id>

4. Add to Your Project (Recommended)

Add this to your project's CLAUDE.md to ensure Claude uses Sage:

## Sage Memory

You have Sage MCP tools for persistent memory. **Use them.**

### Session Start
Call `sage_health()` to check for continuity from previous sessions.

### After Web Searches
Call `sage_autosave_check(trigger_event="web_search_complete", core_question="...", current_thesis="...", confidence=0.X)`

### When Synthesizing
Call `sage_autosave_check(trigger_event="synthesis", ...)` when concluding.

### Before Topic Changes
Call `sage_autosave_check(trigger_event="topic_shift", ...)` before moving on.

### Save Knowledge
Call `sage_save_knowledge(knowledge_id="...", content="...", keywords=[...])` for reusable insights.

### Recall Knowledge
Call `sage_recall_knowledge(query="...")` before starting work.

See docs/CLAUDE_SNIPPET.md for the full snippet.

Features

Auto-Checkpoint (MCP Server)

Claude automatically saves checkpoints when meaningful events occur:

Trigger	When	Confidence
synthesis	Claude combines sources into a conclusion	0.5
web_search_complete	After research with findings	0.3
topic_shift	Conversation changes direction	0.4
branch_point	Decision point identified	0.4
constraint_discovered	Critical limitation found	0.4
precompact	Before context compaction	0.0 (always)
manual	You say "checkpoint"	0.0 (always)

Knowledge Persistence

Store and recall facts across sessions:

# Save knowledge
sage knowledge add "GDPR requires consent" --id gdpr-consent --keywords gdpr,consent

# Query knowledge (auto-recalls on matching keywords)
sage knowledge match "What about GDPR?"

# List all knowledge
sage knowledge list

Semantic Embeddings

Sage uses local embeddings for semantic matching:

• Model: BAAI/bge-large-en-v1.5 (~1.3GB, downloaded on first use)
• Hybrid scoring: 70% semantic + 30% keyword matching (configurable)
• Checkpoint deduplication: Skips saving when thesis is 90%+ similar
• Query prefix support: Optimized retrieval for BGE models

Project-Local Checkpoints

Checkpoints can be stored per-project:

# In a project directory
mkdir .sage  # Checkpoints go here instead of ~/.sage

# Or explicitly
sage checkpoint list --project /path/to/project

Checkpoint Templates

Customize checkpoint format:

sage templates list                    # List available templates
sage_save_checkpoint(..., template="decision")  # Use decision template

Built-in templates: default, research, decision, code-review

Knowledge Types

Different recall behavior by type:

Type	Threshold	Use Case
knowledge	0.70	General facts
preference	0.30	User preferences (aggressive recall)
todo	0.40	Persistent reminders
reference	0.80	On-demand reference

sage todo list      # List todos
sage todo done <id> # Mark complete

Session Continuity (v2.4+)

Never lose context to compaction again. When Claude's context window fills up and auto-compacts, Sage preserves your research state:

1. Before compaction: Sage saves a checkpoint with your current thesis and open questions
2. Next session: Context is automatically injected when you call any Sage tool

No manual intervention needed—just keep working.

Proactive Recall (v2.5+)

Sage automatically recalls relevant knowledge when you start a session:

• Detects project context (directory name, git remote, package.json/pyproject.toml)
• Matches stored knowledge against project signals
• Injects matching knowledge on first Sage tool call

Example: Working in a payments project? Sage automatically surfaces your saved knowledge about payment APIs, compliance notes, etc.

Compaction Watcher (v2.4+, opt-in)

For automatic compaction detection, run the watcher daemon:

sage watcher start    # Start monitoring for compaction
sage watcher status   # Check if running
sage watcher stop     # Stop the daemon

The watcher monitors Claude Code's transcript files and triggers continuity checkpoints when compaction is detected.

Configurable Thresholds

Tune retrieval and detection via ~/.sage/tuning.yaml or .sage/tuning.yaml:

# Retrieval thresholds
recall_threshold: 0.70      # Knowledge recall sensitivity (0-1)
dedup_threshold: 0.90       # Checkpoint deduplication threshold
embedding_weight: 0.70      # Weight for semantic similarity
keyword_weight: 0.30        # Weight for keyword matching

# Embedding model
embedding_model: BAAI/bge-large-en-v1.5

Project config overrides user config. See sage config commands.

Storage Format

Checkpoints are stored as Markdown with YAML frontmatter (Obsidian-compatible):

---
id: 2026-01-16T14-30-00_payment-rails-synthesis
type: checkpoint
confidence: 0.75
trigger: synthesis
skill: crypto-payments
---

# Where do stablecoins win vs traditional payment rails?

## Thesis
Integrate, don't replace. Stablecoins win middle-mile + new primitives,
not POS checkout. Most companies have pieces but not packaging.

## Open Questions
- What's the unified customer object strategy?
- Timeline for Stripe's full stack vs current fragmentation?

## Sources
- **sheel_mohnot** (person): No forcing function for stablecoin POS — _contradicts_
- **simon_taylor** (person): Not about price—about TAM expansion — _nuances_

## Tensions
- **sheel_mohnot** vs **sam_broner**: Whether merchant profitability is sufficient — _unresolved_

## Unique Contributions
- **discovery**: Platform team didn't know about existing SDK integration

Checkpoints live in ~/.sage/checkpoints/ (global) or .sage/checkpoints/ (project-local).

CLI Reference

# Checkpoints
sage checkpoint list              # List all checkpoints
sage checkpoint show <id>         # Show checkpoint details
sage checkpoint rm <id>           # Delete a checkpoint

# Knowledge
sage knowledge list               # List all knowledge items
sage knowledge add <file>         # Add knowledge from file
sage knowledge match "query"      # Test what would be recalled
sage knowledge rm <id>            # Remove knowledge item

# Session Continuity
sage watcher start                # Start compaction watcher daemon
sage watcher stop                 # Stop the watcher
sage watcher status               # Check watcher status
sage continuity status            # Check pending continuity

# Config
sage config list                  # Show current config
sage config set <key> <value>     # Set a value (user-level)
sage config set <key> <value> --project  # Set project-level
sage config reset                 # Reset tuning to defaults

# MCP/Hooks
sage mcp install                  # Install MCP server
sage hooks install                # Install Claude Code hooks

# Admin
sage admin rebuild-embeddings     # Rebuild all embeddings

MCP Tools

Available to Claude via MCP:

Tool	Purpose
sage_health	System diagnostics + auto-inject continuity/proactive recall
sage_version	Version and config info
sage_save_checkpoint	Save full checkpoint with thesis, sources, tensions
sage_load_checkpoint	Restore checkpoint context
sage_list_checkpoints	List all checkpoints
sage_search_checkpoints	Semantic search across checkpoints
sage_autosave_check	Auto-checkpoint with confidence thresholds
sage_save_knowledge	Persist facts with keyword triggers
sage_recall_knowledge	Query knowledge base semantically
sage_list_knowledge	List knowledge items
sage_update_knowledge	Edit existing knowledge item
sage_remove_knowledge	Delete knowledge items
sage_continuity_status	Check/inject session continuity

Hooks

Claude Code hooks for automatic detection:

Hook	Purpose
post-response-semantic-detector.sh	Detects synthesis, branch points, constraints, topic shifts
post-response-context-check.sh	Triggers checkpoint at 70% context usage
pre-compact.sh	Checkpoints before /compact (approves auto-compact)

Hooks have:

• Priority ordering: topic_shift > branch_point > constraint > synthesis
• Cooldown mechanism: Prevents duplicate triggers
• Meta-ban list: Avoids trigger loops on hook discussion

Prerequisites

• Python 3.11+
• Claude Code CLI
• jq (for hooks)

Documentation

• Architecture — System design and data flow
• Features — Complete feature reference
• Session Continuity — Compaction recovery and session persistence
• Checkpoint Methodology — Full framework for semantic checkpointing
• Hooks — Hook system documentation
• Security — Security practices

Development

# Install dev dependencies
pip install -e ".[dev,mcp]"

# Run tests (884 tests)
pytest tests/ -v

# Lint and format
ruff check sage/ --fix
black sage/

License

MIT