Sleep-cycle memory for agents: capture while awake, distill while asleep

Sleep, a new memory system for coding agents, adds a reviewable memory cycle to Pi, OmO and Claude Code that captures observations during a session, consolidates them into provisional memory afterward, and requires explicit human approval before any memory becomes permanent. The tool ships as the npm package pi-sleep-agent (version 0.1.0) and requires Python 3.10 or newer plus the Claude Code CLI for model-backed consolidation and replay; its installer runs the test suite first and creates backups before configuration changes. Sleep redacts secrets, quarantines hostile text, and blocks machine-generated prompts from claiming user provenance, with a nightly pass that mines repeated preferences without a model call and measures memory effects by replaying the same task with memory off and on.

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. Requirements: - Python 3.10 or newer - Claude Code CLI for model-backed consolidation and replay - Pi, OmO, Claude Code, or any combination of them ./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: - captures user messages and relevant tool activity into T0, - injects matching T1 provisional memory into the agent context, - wakes the sleep policy after the agent settles. Verify that it loaded: 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 package flow: 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 copy rather than a checkout: 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 a path. 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 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." After installation, normal sessions need no extra commands: 1. The integration captures observations into the temporary T0 buffer. 2. The sleep gate waits for at least 3 records and 6 hours since the previous pass. 3. A model condenses the buffer into provisional T1 candidates. 4. Provisional candidates can appear as clearly marked background context in matching projects. 5. You inspect candidates and choose whether to promote them into permanent T2 memory. php session activity - T0 buffer - gated sleep - T1 provisional memory | review or replay | explicit promote | T2 permanent memory Dream is Sleep's unattended reflection phase. It does not update model weights and it never writes permanent memory on its own. A dream pass performs three steps: 1. Mine. Find instructions you repeated across separate sessions in the same project. This step is deterministic and makes no model call. 2. Consolidate. When the sleep gate passes, ask the configured model to turn recent T0 observations into provisional T1 candidates. 3. Replay. When replay is due, run selected tasks with provisional memory off and on, then write a comparison report. 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 Sleep separates memory into three tiers: | Tier | Meaning | Who writes it | |---|---|---| | T0 | Temporary session observations | Hooks, extension, or capture | | T1 | Provisional memory shown as unverified background | Consolidation and mine | | T2 | Permanent memory | Only an explicit promote command | Additional safeguards: - Model output is always stamped as agent-generated and cannot mark itself user-confirmed. - Provisional memory is rendered as background, not as an instruction. - Secret-like values are replaced with redaction markers. - Prompt-injection and exfiltration shapes are moved to quarantine. - Mixed-project buffers fail closed instead of assigning facts to the wrong project. - Replay reports results but never promotes memory automatically. - Every model call has an explicit budget limit. 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 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. Sleep keeps skipping 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. A candidate appears in the wrong context Run ./sleep.py show <id and check its cwd . Mixed-project batches are kept in T0 and return an error instead of producing candidates.