Give your coding agents useful memory without giving memory control.

Capture while agents work. Consolidate when they stop. Promote only what you approve.

Sleep adds a reviewable memory cycle to Pi, OmO, and Claude Code. It records useful observations during a session, turns them into provisional memory after the session, and keeps permanent memory behind an explicit human approval step.

Automatic capture. Hooks and the Pi extension collect useful observations while you work.

Budgeted consolidation. Sleep runs only after the record and time gates pass.

Review before permanence. New memories stay provisional until you promote or refuse them.

Nightly dream cycle. Mine repeated preferences, consolidate recent observations, and measure memory effects while you are away.

Measured replay. Run the same task with memory off and on before deciding whether a memory helps.

Repeated preference detection. mine finds instructions you gave in multiple sessions without a model call.

Project isolation. A project's provisional memory is injected only into that project.

Safety gates. Secrets are redacted, hostile text is quarantined, and machine-generated prompts cannot claim user provenance.

Install

Requirements:

./install.sh --dry-run # show every change without writing ./install.sh # install the shared skill and Claude Code hooks ./install.sh --extension # also install the Pi/OmO extension ./install.sh --launchd # also schedule the nightly pass on macOS

The installer runs the test suite first, creates backups before configuration changes, and is safe to run again.

Pi and OmO require Sleep's user-installed extension for automatic integration:

./install.sh --extension

The installer links this repository's extension/ directory to:

~/.omo/agent/extensions/sleep

The extension loads on the next Pi or OmO session and performs three jobs:

omo -p 'hi' >/dev/null 2>&1 tail -4 ~/.sleep/logs/extension.log

The log should contain session_start, publish, and agent_settled entries.

Without this extension, the Sleep CLI still works when you run commands manually, and Claude Code can still use its own hooks. Pi and OmO, however, will not capture sessions, inject provisional memory, or trigger sleep automatically.

Sleep also ships as the npm package pi-sleep-agent, so Pi and OmO can use

the extension without cloning the repository. Install it through the pi install

pi install npm:pi-sleep-agent

or, for a specific published version

pi install npm:pi-sleep-agent@0.1.0

The package contains the extension (pi.extensions), the Sleep skill

(pi.skills), and the Python runtime behind it, so the CLI works from the

installed package too. Pi manages the package under its own directory; do not

guess that path. The extension resolves its own runtime from the package and

records it in the log, so the verification below proves it loaded the installed

omo -p 'hi' >/dev/null 2>&1 tail -4 ~/.sleep/logs/extension.log # session_start, publish, agent_settled

Those three log lines are the proof that the packaged extension loaded and its

Python runtime ran. If they do not appear, reload the extension (pi install it

again, or restart the session); do not dig under the package directory and guess

Verify the tarball contract locally without publishing:

npm run pack:check # what npm pack would ship, as JSON npm run smoke:package # install the tarball into an isolated Pi home and prove it loads

To remove Sleep and restore the backed-up configuration:

./uninstall.sh

Quick start

Check the installation:

./sleep.py status -v ./sleep.py doctor ./sleep.py sleep --dry-run

Capture a useful observation manually when needed:

./sleep.py capture --text "The staging gateway requires X-Route: blue." --kind fact --source user

Run a consolidation pass:

./sleep.py sleep --dry-run ./sleep.py sleep --force

Review the resulting candidate before making it permanent:

./sleep.py status -v ./sleep.py show <candidate-id> ./sleep.py promote <candidate-id> --dry-run ./sleep.py promote <candidate-id>

Reject an incorrect candidate without deleting its audit trail:

./sleep.py refuse <candidate-id> --note "Incorrect for the current deployment."

Day-to-day workflow

After installation, normal sessions need no extra commands:

session activity -> T0 buffer -> gated sleep -> T1 provisional memory | review or replay | explicit promote | T2 permanent memory

Dream cycle

Dream is Sleep's unattended reflection phase. It does not update model weights and it never writes permanent memory on its own.

Every result stays reviewable. Candidates remain in T1 until you explicitly run promote.

Preview the complete dream pass without model calls or writes:

./sleep.py nightly --dry-run

Run it now:

./sleep.py nightly --force

Run the two dream components separately when you want more control:

./sleep.py mine --dry-run ./sleep.py mine

./sleep.py replay --limit 3 # show the replay plan ./sleep.py replay --run --limit 3 --budget 0.10

--budget is the maximum cost per task across both replay arms. Dream reports are written under $SLEEP_HOME/reports/ and never trigger promotion automatically.

Command Purpose

./sleep.py status -v Show buffer, candidate, quarantine, and permanent-memory status

./sleep.py sleep --dry-run Check whether the sleep gate would run

./sleep.py sleep --force Run consolidation now

./sleep.py show <id> Inspect a candidate and its rendered context

./sleep.py promote <id> Move an approved candidate to permanent memory

./sleep.py refuse <id> --note "..." Record that a candidate is incorrect

./sleep.py replay --run --limit 3 Compare selected tasks with memory off and on

./sleep.py mine --dry-run Find preferences repeated across sessions

./sleep.py nightly --dry-run Preview the unattended nightly workflow

./sleep.py doctor Find duplicate or overlapping memory records

./sleep.py inject --project "$PWD" Print provisional context for the current project

Run ./sleep.py <command> --help for command-specific options.

Agent Integration

Claude Code UserPromptSubmit, PostToolUse, Stop, and PreCompact hooks

Pi / OmO Required user-installed extension: ./install.sh --extension

Both integrations share $SLEEP_HOME, so candidates reviewed from one client are visible to the other when the project scope matches.

Interactive runs inherit your current environment. Scheduled macOS runs read additional values from $SLEEP_HOME/env, which defaults to ~/.sleep/env.

mkdir -p ~/.sleep touch ~/.sleep/env chmod 600 ~/.sleep/env

The file accepts KEY=VALUE lines. Common settings are:

ANTHROPIC_API_KEY=... ANTHROPIC_BASE_URL=... ANTHROPIC_MODEL=... SLEEP_MODEL=...

An explicit --model wins over SLEEP_MODEL, which wins over ANTHROPIC_MODEL. Existing process environment variables win over values in the file.

Before enabling the schedule, test the same path manually:

./sleep.py nightly --dry-run ./sleep.py sleep --force --budget 0.10

Review and safety model

Sleep separates memory into three tiers:

All runtime data lives under $SLEEP_HOME, which defaults to ~/.sleep:

buffer/ temporary T0 records candidates/ provisional T1 records reports/ replay reports logs/ hook and nightly logs .quarantine/ rejected unsafe input state.json sleep and replay timestamps env optional scheduled-run environment

Useful logs:

~/.sleep/logs/hook-fires.log ~/.sleep/logs/hook.log ~/.sleep/logs/nightly.log

Use another home for testing or for a separate memory pool:

SLEEP_HOME=/tmp/my-sleep ./sleep.py status -v

Troubleshooting

Nothing was captured

./sleep.py status -v ./sleep.py doctor

Check ~/.sleep/logs/hook-fires.log. If it is empty, the integration did not fire. If it contains events but the buffer is empty, the events were ignored or quarantined.

The default gate requires 3 records and a 6-hour interval. Inspect the decision with:

./sleep.py sleep --dry-run

Use --force only when you intentionally want a model call.

The scheduled pass cannot reach the model

Confirm that ~/.sleep/env exists, has mode 0600, and contains the same provider settings used by your interactive shell. Then run ./sleep.py sleep --force before relying on launchd.

Run ./sleep.py show <id> and check its cwd. Mixed-project batches are kept in T0 and return an error instead of producing candidates.