sage-code

sage-code

Self-Adapting Generative Engine for Code
A Claude Code plugin that makes Claude autonomously learn and improve within each project.

---

Grounded in peer-reviewed research: Reflexion (NeurIPS 2023), Contextual Experience Replay (ACL 2025), SAGE (Neurocomputing 2025), and the ICML 2025 position on metacognitive learning.

What it does

SAGE-Code observes your Claude Code sessions and builds project-specific knowledge over time:

• Captures corrections, tool outcomes, and patterns during sessions via hooks
• Reflects on what worked and what didn't, extracting reusable heuristics via subagents
• Replays relevant knowledge at the start of each session based on git context
• Self-evaluates whether its learned rules actually help, pruning ineffective ones

Everything is fully autonomous — no manual intervention needed.

Installation

/plugin marketplace add umxr/sage-code
/plugin install sage-code@sage-code-marketplace

Or add to your ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "sage-code-marketplace": {
      "source": { "source": "github", "repo": "umxr/sage-code" }
    }
  },
  "enabledPlugins": {
    "sage-code@sage-code-marketplace": true
  }
}

On your first session in any project, SAGE will automatically initialize a .sage/ directory and begin learning.

Commands

Command	Description
/sage-status	View what SAGE has learned about your project
/sage-reflect	Manually trigger reflection on current session
/sage-meta	Run meta-evaluation to score and prune heuristics

Architecture

┌─────────────────────────────────────────────────────┐
│  Layer 5: META-LEARNING (Self-Evaluation)           │
│  Periodic subagent evaluates rule effectiveness     │
│  Promotes, demotes, prunes heuristics               │
├─────────────────────────────────────────────────────┤
│  Layer 4: REPLAY (Session Start)                    │
│  Scores knowledge against current task context      │
│  Injects top 10-15 relevant heuristics              │
├─────────────────────────────────────────────────────┤
│  Layer 3: KNOWLEDGE (Evolving Files)                │
│  Structured markdown files with confidence scores   │
│  Categories: pitfalls, strategies, preferences...   │
├─────────────────────────────────────────────────────┤
│  Layer 2: REFLECTION (Subagent)                     │
│  Analyzes session events at session end             │
│  Extracts and generalizes heuristics                │
├─────────────────────────────────────────────────────┤
│  Layer 1: CAPTURE (Hooks)                           │
│  Passively observes session events                  │
│  Writes structured JSONL event log                  │
└─────────────────────────────────────────────────────┘

How it works

1. SessionStart hook initializes the event log, gathers git context, and triggers the replay skill
2. PostToolUse hook captures outcomes of state-changing tools (Write, Edit, Bash)
3. UserPromptSubmit hook detects corrections ("no, use X instead") and praise ("perfect, exactly")
4. Stop hook writes a session summary and marks the log for deferred reflection
5. sage-replay skill (next session) processes pending reflections, then injects relevant heuristics
6. Meta-evaluator (every 10 sessions) scores rules against outcomes and prunes ineffective ones

Project data

SAGE creates a .sage/ directory in your project:

.sage/
├── knowledge/        # Learned heuristics (committed to git)
│   ├── pitfalls.md   # Errors and anti-patterns to avoid
│   ├── strategies.md # Proven effective approaches
│   ├── preferences.md# User style and workflow preferences
│   ├── architecture.md# Project structure knowledge
│   └── conventions.md# Coding conventions
├── events/           # Session logs (gitignored, personal)
├── meta/             # Scores, config, history (committed)
└── README.md         # Auto-generated summary

Knowledge lifecycle

Heuristics progress through confidence levels based on evidence: