claude-sage 1.0.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
pip install claude-sage

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

# Install MCP server and hooks
sage mcp install
sage hooks install

2. Test it

# Start Claude Code
claude

# Have a conversation, do some research
# Watch for checkpoint notifications
# Claude will checkpoint automatically on synthesis moments

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

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 Recall (Embeddings)

Install for smarter matching:

pip install claude-sage[embeddings]  # ~2GB for model + torch

• Model: all-MiniLM-L6-v2 (~80MB, runs locally on CPU)
• Hybrid scoring: 70% semantic + 30% keyword matching (configurable)
• Checkpoint deduplication: Skips saving when thesis is 90%+ similar
• Graceful fallback: Works without embeddings using keyword matching

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

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

# Structural detection (future)
topic_drift_threshold: 0.50

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

# 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_save_checkpoint	Save full checkpoint with thesis, sources, tensions
sage_load_checkpoint	Restore checkpoint context
sage_list_checkpoints	List all 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_remove_knowledge	Delete knowledge items

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
• Checkpoint Methodology — Full framework for semantic checkpointing
• Hooks — Hook system documentation
• Security — Security practices

Development

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

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

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

License

MIT