sage-research

Sage Research Methodology

Checkpoint at state transitions, not token pressure.

When to Checkpoint

Trigger	Signal	Confidence
synthesis	"Therefore...", "In summary...", "The answer is..."	0.5+
web_search_complete	After processing search results	0.3+
branch_point	"We could either X or Y..."	0.4+
constraint_discovered	"This won't work because..."	0.4+
topic_shift	Conversation changing direction	0.4+
manual	User says "checkpoint" or "save this"	0.0 (always)

Signal Detection

Signal	Example Phrases
Conclusion reached	"So the answer is...", "This means...", "Therefore..."
Hypothesis validated	"This confirms...", "This rules out..."
Branch point	"We could either X or Y", "Two approaches..."
Constraint discovered	"Wait, that changes things...", "I didn't realize..."
Topic transition	Shift in focus, new entity/concept
User validation	"That makes sense", "Let's go with that", "Agreed"
Explicit request	"checkpoint", "save this", "remember this"

The Research Workflow

WebSearch -> synthesize findings -> sage_autosave_check -> respond to user

A research task is NOT complete until sage_autosave_check is called.

What to Capture

sage_autosave_check(
    trigger_event="synthesis",           # What triggered this
    core_question="What are we solving?", # The driving question
    current_thesis="Our current position", # 1-2 sentence synthesis
    confidence=0.7,                       # How confident (0-1)
    open_questions=["What's still unknown?"],
    key_evidence=["Concrete facts supporting thesis"],
)

Responding to Hook Detections

When you see these messages from hooks, act immediately:

• Synthesis detected -> sage_autosave_check(trigger_event='synthesis', ...)
• Branch point detected -> sage_autosave_check(trigger_event='branch_point', ...)
• Constraint discovered -> sage_autosave_check(trigger_event='constraint_discovered', ...)
• Topic shift detected -> sage_autosave_check(trigger_event='topic_shift', ...)

Never ignore hook detection messages. They indicate checkpoint-worthy moments.

Before Changing Topics

Always checkpoint before moving to a new subject:

sage_autosave_check(
    trigger_event="topic_shift",
    core_question="Previous topic question",
    current_thesis="Where we landed",
    confidence=0.6,
)

Autosave Triggers (Game Analogy)

Think of checkpointing like a game's autosave system:

Trigger Event	When	Game Analogy
research_start	User asks research question	Entering boss room
web_search_complete	After processing web search results	Picked up item
synthesis	You say "So...", "Therefore...", "In summary..."	Quest complete
topic_shift	User pivots to new topic	Switching levels
user_validated	User confirms your finding	Checkpoint reached
constraint_discovered	New info changes approach	Plot twist
branch_point	Multiple viable paths identified	Fork in road

Checkpoint Schema

When checkpointing, this data is captured:

id: [timestamp]_[short-description]
trigger: [manual | synthesis | branch_point | constraint | transition]

core_question: |
  What decision or action is this research driving toward?

thesis: |
  Current synthesized position (1-2 sentences)
confidence: [0.0-1.0]

open_questions:
  - What's still unknown?
  - What needs more research?

sources:
  - id: [identifier]
    type: [person | document | api | observation]
    take: [Decision-relevant summary, 1-2 sentences]
    relation: [supports | contradicts | nuances]

tensions:
  - between: [source1, source2]
    nature: What they disagree on
    resolution: [unresolved | resolved | moot]

unique_contributions:
  - type: [discovery | experiment | synthesis | internal_knowledge]
    content: What WE found that isn't in external sources

action:
  goal: What's being done with this research
  type: [decision | output | learning | exploration]

Compression Principles

1. Compress for decisions, not completeness - "Would this change the decision?"
2. Preserve tensions - Disagreements between credible sources are high-value
3. Elevate unique contributions - Your discoveries are differentiated value
4. Drop re-derivable content - Keep conclusions, not the reasoning chain

Restoration

When continuing from a checkpoint, inject it as context:

# Research Context (Restored from Checkpoint)

## Core Question
[core_question]

## Current Thesis (confidence: X%)
[thesis]

## Open Questions
[open_questions as bullets]

## Key Sources
[sources with relation indicators: [+] supports, [-] contradicts, [~] nuances]

## Tensions
[unresolved disagreements]

## Unique Discoveries
[unique_contributions]

Saving Reusable Knowledge

When you learn something worth remembering across sessions:

sage_save_knowledge(
    knowledge_id="kebab-case-id",
    content="The insight in markdown",
    keywords=["trigger", "words", "for", "recall"],
)

Recalling Knowledge

Before starting work, check what's already known:

sage_recall_knowledge(query="what you're working on")

Presenting Checkpoints

When loading or listing checkpoints, format them nicely for the user:

Single Checkpoint

## 📍 Authentication Flow Analysis
*Saved 2026-02-14 | Confidence: 85%*

**Question:** How does the authentication flow work in this codebase?

**Thesis:** Authentication uses JWT tokens with refresh rotation. The flow
starts in auth/login.py, validates credentials against the user service,
and issues tokens via auth/tokens.py.

**Key Evidence:**
- Access tokens expire in 15 minutes
- Refresh tokens stored in httponly cookies

**Open Questions:**
- How does token revocation work?
- Is there rate limiting on login attempts?

**Sources:**
- [+] auth/login.py — Entry point for login
- [+] auth/tokens.py — JWT generation
- [+] RFC 7519 — JWT standard followed

Checkpoint List

Found **3 checkpoints**:

| Checkpoint | Confidence | When |
|------------|------------|------|
| authentication-flow | 85% | Feb 14 |
| rate-limiting-design | 70% | Feb 13 |
| api-structure | 90% | Feb 12 |

Use `sage_load_checkpoint("authentication-flow")` to restore context.

Relation Icons

• [+] supports — Source confirms the thesis
• [-] contradicts — Source challenges the thesis
• [~] nuances — Source adds complexity/conditions

Behavior

• Proactive: Call autosave checks at trigger moments. Don't wait to be asked.
• Lightweight: Brief notification, don't disrupt flow.
• Cumulative: Each checkpoint builds on previous, creating a research trail.