How SkillOpt‑Sleep Gives Your AI Coding Assistant a Memory Palace

What SkillOpt‑Sleep Does

SkillOpt‑Sleep is a deployment companion for Microsoft’s open‑source SkillOpt project. It adds a nightly "sleep" cycle that collects Claude Code (or Codex) session history from ~/.claude, mines repeated task patterns, replays them offline, reflects on the results, applies bounded edits, and presents proposals for manual review. Only proposals that pass a verification gate are written to protected blocks in CLAUDE.md or SKILL.md.

Nightly Cycle

collect ~/.claude history → mine repeated task patterns → offline replay
→ reflect + bounded edit + verification gate → generate proposal → user reviews & adopts

The verification gate distinguishes SkillOpt‑Sleep from simple memory tools: edits are persisted only after explicit acceptance.

Runtime Commands

/sleep dry-run

– preview a report of what would be learned; no files are changed. /sleep run – generate staged edit proposals after gate verification; files remain untouched. /sleep status – display run logs and details of the latest proposals. /sleep adopt – after user confirmation, write the accepted rules into protected LEARNED blocks in CLAUDE.md / SKILL.md.

Adopted Content Example

<!-- SLOW_UPDATE_START -->
- Write API interfaces with type and boundary checks.
- Use a unified error response format { code, message }.
- Wrap database queries in try‑catch and return 500 on failure.
- Name components in PascalCase; file names in kebab-case.
<!-- SLOW_UPDATE_END -->

Characteristics of the LEARNED block:

Written inside a protected region, never overwriting hand‑crafted rules.

Automatic backup before each adopt.

Rules are distilled from actual successful or failed sessions, not fabricated.

Installation

Prerequisites

Python 3.10+

Claude Code CLI ( claude) or Codex CLI ( codex) installed and on

PATH

Claude Code

# 1. Clone the repository
git clone https://github.com/microsoft/SkillOpt.git
cd SkillOpt

# 2. Add the plugin to Claude Code
/plugin marketplace add ./skillopt-sleep-plugin
/plugin install skillopt-sleep@skillopt-sleep

# 3. Verify installation
/sleep status

Codex

# 1. Clone the repository (same as above)
git clone https://github.com/microsoft/SkillOpt.git
cd SkillOpt

# 2. Run the install script
bash plugins/codex/install.sh

# 3. Verify
/sleep status

Using with Cursor

Method A – run the Python CLI directly in Cursor’s built‑in terminal:

# Dry‑run
python -m skillopt_sleep run --project "$(pwd)" --backend mock

# Real run
python -m skillopt_sleep run --project "$(pwd)" --backend claude

Method B (recommended) – code in Cursor, run the nightly sleep in a separate Claude Code terminal. The generated CLAUDE.md / SKILL.md blocks are then read by Cursor on the next session.

Method C – register the provided Copilot MCP server and let Cursor call it via the MCP protocol (experimental).

Supported Backends

mock

– deterministic simulation, zero cost. claude – invokes the claude -p CLI. codex – invokes the codex exec CLI.

The plugin does not call external APIs directly; it shells out to the respective CLI tools. SkillOpt’s core supports Qwen and MiniMax, but the Sleep plugin currently lacks those backends.

Privacy & Security

Collected Data

SkillOpt‑Sleep reads local JSONL files under ~/.claude/projects/. Extracted fields: user_prompts – all raw user questions (used in prompts). assistant_finals – last five assistant replies (used in prompts). project – project path (not used in prompts). git_branch – current Git branch (not used in prompts). tools_used – tools invoked during the session (not used in prompts). files_touched – list of edited files (not used in prompts). feedback_signals – positive/negative feedback tokens such as "thanks" or "still broken" (indirectly used).

Security Guarantees

Purely local execution – no network transmission of ~/.claude files.

Harvest phase is read‑only; original files are never modified.

API keys in prompts are redacted before being sent to the optimizer model.

Proposals are written only after the user runs /sleep adopt.

Final output consists of distilled rules, not raw dialogue.

Usage Workflow in Claude Code

# Step 1: Safe preview (no changes)
/sleep dry-run

# Step 2: Formal run (creates staged proposals)
/sleep run

# Step 3: Inspect learned rules
/sleep status

# Step 4: Adopt if satisfied
/sleep adopt

Each step can be stopped independently.

Direct CLI Invocation

# Zero‑cost trial (mock backend)
python -m skillopt_sleep run --project "$(pwd)" --backend mock

# Real optimization with Claude
python -m skillopt_sleep run --project "$(pwd)" --backend claude

# Real optimization with Codex
python -m skillopt_sleep run --project "$(pwd)" --backend codex

Nightly Automation

# Print a crontab line (add manually)
"${CLAUDE_PLUGIN_ROOT}/scripts/install-cron.sh" "$(pwd)"

Adding the line to crontab runs SkillOpt‑Sleep automatically each night.

Advanced Configuration

Verification Gate

# Enable gate (default) – keep only truly effective edits
python -m skillopt_sleep run --project "$(pwd)" --gate on

# Disable gate – greedy mode, edits bypass the hard gate but still report score changes
python -m skillopt_sleep run --project "$(pwd)" --gate off

Budget Control

# Token budget (e.g., 60 000 tokens)
python -m skillopt_sleep run --project "$(pwd)" --budget-tokens 60000

# Time budget (e.g., 30 minutes)
python -m skillopt_sleep run --project "$(pwd)" --budget-minutes 30

The engine automatically plans depth (number of nights × rollouts per task) to fit the budget.

Multiple Rollouts for Reflection

# Replay each task 3 times and compare high‑score vs low‑score attempts
python -m skillopt_sleep run --project "$(pwd)" --rollouts-k 3 --backend claude

This "imagination core" extracts what makes a good attempt and what a bad one lacks.

User Preferences Injection

python -m skillopt_sleep run --project "$(pwd)" \
  --preferences "code comments in Chinese, variable names in English, prefer concise style" \
  --backend claude

Preferences are injected as a prior into the optimizer’s reflection prompt, steering rule generation.

Optimizer / Target Model Separation (Advanced)

# Strong optimizer (Sonnet) with cheap target model (Haiku)
python -m skillopt_sleep run --project "$(pwd)" \
  --optimizer-backend claude --optimizer-model sonnet \
  --target-backend claude --target-model haiku

Empirical results show a stronger optimizer yields higher‑quality rules, while a weaker target keeps costs low.

Ensuring Meaningful Conclusions

Low‑quality output usually stems from low‑quality input. Six strategies improve results:

Expand the look‑back window – default is 72 hours ( lookback_hours: 72). Example to use 30 days:

{
  "lookback_hours": 720
}

Enable the LLM miner (default on) so the optimizer analyses the full conversation instead of only the first user prompt.

Inject preferences to guide the optimizer toward domains you care about.

Few‑but‑deep tasks > many trivial tasks – set max_tasks_per_night to a modest number (e.g., 10).

Focus on failure sessions – repeated corrections reveal systematic weaknesses.

Strong optimizer + weak target – a powerful model abstracts general principles from noisy data.

Real‑World Case Study: e‑sign Project

Background

The e‑sign project is an electronic signing system with API integration, contract flow, and parameter mapping. Daily Claude Code sessions include bug fixes, feature iterations, and API documentation.

Four Runs

Run 1 – backend mock, 17 sessions, 17 tasks, score 0→0, gate rejected.

Run 2 – backend claude, 16 sessions, 16 tasks, score 0→0, gate rejected.

Run 3 – backend claude, 19 sessions, 4 tasks, score 0→0, gate rejected.

Run 4 – backend claude, 19 sessions, 5 tasks, score 0→0.056, gate accepted.

The first three runs were blocked by the verification gate; the fourth passed, confirming the gate works as intended.

Rules Extracted in Run 4

Each change involving shared files or utility functions must include a section titled "Impact Analysis".

Analysis: The engine noticed repeated requests for impact assessment and codified it.

When discussing API contracts, parameters, or flow scenarios, the response must contain the terms ‘bType’, ‘contract’, ‘esignCId’.

Analysis: A mechanical keyword checklist useful only for this project.

The "Impact Analysis" section must contain one of the tags: ‘no impact’, ‘compatible’, ‘does not affect’, etc.

Analysis: Forces the AI to give a clear compatibility verdict – highly practical.

Every JSON example of API parameters must include the field ‘bizType’.

Analysis: Valuable for the e‑sign codebase but overly specific for other contexts.

Takeaways

Valuable: the engine correctly identified core workflow (API integration & impact analysis) and produced two genuinely reusable rules.

Limited: two rules are overly specific; overall held‑out score improvement is modest (0.056).

Input data was scarce (19 sessions, only 5 meaningful tasks).

Practical Advice from the Case

Adopt rules 1 and 3 – they are general and high‑value.

Skip rules 2 and 4 – too mechanical; better to write manually.

Accumulate deeper sessions before the next run – complex features or hard‑to‑fix bugs provide richer data.

When to Use SkillOpt‑Sleep

Frequent daily use of Claude Code or Codex on substantial codebases.

Repeatedly correcting the same AI mistakes.

Desire for the assistant to remember project conventions and personal coding habits.

Willingness to give the AI a growth period.

Less suitable scenarios:

Occasional, lightweight AI assistance.

Highly sensitive projects that cannot send any data to external APIs (unless using --backend mock).

One‑off projects with no expectation of rule reuse.

Typical start: run a dry‑run with --backend mock on the most active project; if the learned rules look promising, enable a nightly cron.

Multi‑Project Management

SkillOpt‑Sleep binds to a single project directory via --project "$(pwd)". It does not traverse sub‑directories automatically.

Solution: Loop Script

#!/bin/bash
# sleep-all.sh – run SkillOpt‑Sleep for each project
PARENT_DIR="/path/to/your/projects"

for project in "$PARENT_DIR"/*/; do
  if [ ! -d "$project/.claude" ] && [ ! -f "$project/CLAUDE.md" ]; then
    echo "Skipping $project (not a Claude Code project)"
    continue
  fi
  echo "Processing: $project"
  cd "$project" || continue
  python -m skillopt_sleep run --project "$(pwd)" --backend claude
  echo "$project completed"
  echo "---"
done

Alternatively, add a separate cron entry for each project.

Privacy Details

Data source: local session JSONL files under ~/.claude/projects/. Collected fields are listed above. When using --backend claude or --backend codex, the extracted TaskRecord (including a summary of user prompts) is sent as part of the optimizer prompt. Keys are redacted, but the intent and gist of the queries are transmitted.

For highly sensitive projects, use --backend mock (no network request) and run /sleep dry-run first to inspect what would be harvested.

Advanced Options Summary

Verification gate: --gate on (default) or --gate off.

Budget: --budget-tokens or --budget-minutes.

Rollouts: --rollouts-k N for multiple replay attempts.

Preferences: --preferences "..." to steer rule generation.

Optimizer/target separation: specify backends and model names for each.

Summary

SkillOpt‑Sleep is most valuable when you have high‑frequency, high‑quality interaction histories with Claude Code or Codex, especially where you repeatedly correct the same mistakes. Start with the mock backend to validate the workflow, then move to a real backend and schedule nightly runs. The tool’s strength lies in its verification gate and its ability to turn concrete failure experiences into reusable, long‑term rules.