pi-sleep-agent 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Binary file
package/README.md CHANGED
@@ -1,3 +1,363 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # Sleep
4
+
5
+ **Give your coding agents useful memory without giving memory control.**
6
+
7
+ Capture while agents work. Consolidate when they stop. Promote only what you approve.
8
+
9
+ [![Tests](https://img.shields.io/badge/tests-127%20passing-c4f042?labelColor=111827&style=flat-square)](#install)
10
+ [![Python](https://img.shields.io/badge/python-3.10%2B-369eff?labelColor=111827&style=flat-square)](https://www.python.org/)
11
+ [![Runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-0-ffcb47?labelColor=111827&style=flat-square)](#install)
12
+ [![Agents](https://img.shields.io/badge/agents-Pi%20%7C%20Claude-a78bfa?labelColor=111827&style=flat-square)](#supported-agents)
13
+
14
+ </div>
15
+
16
+ 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.
17
+
18
+ <p align="center">
19
+ <img src=".github/assets/sleep-replay.png" alt="Sleep CLI showing provisional memory improving a replay result" width="920" />
20
+ </p>
21
+
22
+ ## What you get
23
+
24
+ - **Automatic capture.** Hooks and the Pi extension collect useful observations while you work.
25
+ - **Budgeted consolidation.** Sleep runs only after the record and time gates pass.
26
+ - **Review before permanence.** New memories stay provisional until you promote or refuse them.
27
+ - **Nightly dream cycle.** Mine repeated preferences, consolidate recent observations, and measure memory effects while you are away.
28
+ - **Measured replay.** Run the same task with memory off and on before deciding whether a memory helps.
29
+ - **Repeated preference detection.** `mine` finds instructions you gave in multiple sessions without a model call.
30
+ - **Project isolation.** A project's provisional memory is injected only into that project.
31
+ - **Safety gates.** Secrets are redacted, hostile text is quarantined, and machine-generated prompts cannot claim user provenance.
32
+
33
+ ## Install
34
+
35
+ Requirements:
36
+
37
+ - Python 3.10 or newer
38
+ - Claude Code CLI for model-backed consolidation and replay
39
+ - Pi, OmO, Claude Code, or any combination of them
40
+
41
+ ```bash
42
+ ./install.sh --dry-run # show every change without writing
43
+ ./install.sh # install the shared skill and Claude Code hooks
44
+ ./install.sh --extension # also install the Pi/OmO extension
45
+ ./install.sh --launchd # also schedule the nightly pass on macOS
46
+ ```
47
+
48
+ The installer runs the test suite first, creates backups before configuration changes, and is safe to run again.
49
+
50
+ ### Pi / OmO extension
51
+
52
+ Pi and OmO require Sleep's user-installed extension for automatic integration:
53
+
54
+ ```bash
55
+ ./install.sh --extension
56
+ ```
57
+
58
+ The installer links this repository's `extension/` directory to:
59
+
60
+ ```text
61
+ ~/.omo/agent/extensions/sleep
62
+ ```
63
+
64
+ The extension loads on the next Pi or OmO session and performs three jobs:
65
+
66
+ - captures user messages and relevant tool activity into T0,
67
+ - injects matching T1 provisional memory into the agent context,
68
+ - wakes the sleep policy after the agent settles.
69
+
70
+ Verify that it loaded:
71
+
72
+ ```bash
73
+ omo -p 'hi' >/dev/null 2>&1
74
+ tail -4 ~/.sleep/logs/extension.log
75
+ ```
76
+
77
+ The log should contain `session_start`, `publish`, and `agent_settled` entries.
78
+
79
+ 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.
80
+
81
+ ### Install from npm (Pi / OmO)
82
+
83
+ Sleep also ships as the npm package `pi-sleep-agent`, so Pi and OmO can use
84
+
85
+ the extension without cloning the repository. Install it through the `pi install`
86
+
87
+ package flow:
88
+
89
+ ```bash
90
+ pi install npm:pi-sleep-agent
91
+ # or, for a specific published version
92
+ pi install npm:pi-sleep-agent@0.1.0
93
+ ```
94
+
95
+ The package contains the extension (`pi.extensions`), the Sleep skill
96
+
97
+ (`pi.skills`), and the Python runtime behind it, so the CLI works from the
98
+
99
+ installed package too. Pi manages the package under its own directory; do not
100
+
101
+ guess that path. The extension resolves its own runtime from the package and
102
+
103
+ records it in the log, so the verification below proves it loaded the installed
104
+
105
+ copy rather than a checkout:
106
+
107
+ ```bash
108
+ omo -p 'hi' >/dev/null 2>&1
109
+ tail -4 ~/.sleep/logs/extension.log # session_start, publish, agent_settled
110
+ ```
111
+
112
+ Those three log lines are the proof that the packaged extension loaded and its
113
+
114
+ Python runtime ran. If they do not appear, reload the extension (`pi install` it
115
+
116
+ again, or restart the session); do not dig under the package directory and guess
117
+
118
+ a path.
119
+
120
+ Verify the tarball contract locally without publishing:
121
+
122
+ ```bash
123
+ npm run pack:check # what npm pack would ship, as JSON
124
+ npm run smoke:package # install the tarball into an isolated Pi home and prove it loads
125
+ ```
126
+
127
+ To remove Sleep and restore the backed-up configuration:
128
+
129
+ ```bash
130
+ ./uninstall.sh
131
+ ```
132
+
133
+ ## Quick start
134
+
135
+ Check the installation:
136
+
137
+ ```bash
138
+ ./sleep.py status -v
139
+ ./sleep.py doctor
140
+ ./sleep.py sleep --dry-run
141
+ ```
142
+
143
+ Capture a useful observation manually when needed:
144
+
145
+ ```bash
146
+ ./sleep.py capture --text "The staging gateway requires X-Route: blue." --kind fact --source user
147
+ ```
148
+
149
+ Run a consolidation pass:
150
+
151
+ ```bash
152
+ ./sleep.py sleep --dry-run
153
+ ./sleep.py sleep --force
154
+ ```
155
+
156
+ Review the resulting candidate before making it permanent:
157
+
158
+ ```bash
159
+ ./sleep.py status -v
160
+ ./sleep.py show <candidate-id>
161
+ ./sleep.py promote <candidate-id> --dry-run
162
+ ./sleep.py promote <candidate-id>
163
+ ```
164
+
165
+ Reject an incorrect candidate without deleting its audit trail:
166
+
167
+ ```bash
168
+ ./sleep.py refuse <candidate-id> --note "Incorrect for the current deployment."
169
+ ```
170
+
171
+ ## Day-to-day workflow
172
+
173
+ After installation, normal sessions need no extra commands:
174
+
175
+ 1. The integration captures observations into the temporary T0 buffer.
176
+ 2. The sleep gate waits for at least 3 records and 6 hours since the previous pass.
177
+ 3. A model condenses the buffer into provisional T1 candidates.
178
+ 4. Provisional candidates can appear as clearly marked background context in matching projects.
179
+ 5. You inspect candidates and choose whether to promote them into permanent T2 memory.
180
+
181
+ ```text
182
+ session activity -> T0 buffer -> gated sleep -> T1 provisional memory
183
+ |
184
+ review or replay
185
+ |
186
+ explicit promote
187
+ |
188
+ T2 permanent memory
189
+ ```
190
+
191
+ ## Dream cycle
192
+
193
+ Dream is Sleep's unattended reflection phase. It does not update model weights and it never writes permanent memory on its own.
194
+
195
+ A dream pass performs three steps:
196
+
197
+ 1. **Mine.** Find instructions you repeated across separate sessions in the same project. This step is deterministic and makes no model call.
198
+ 2. **Consolidate.** When the sleep gate passes, ask the configured model to turn recent T0 observations into provisional T1 candidates.
199
+ 3. **Replay.** When replay is due, run selected tasks with provisional memory off and on, then write a comparison report.
200
+
201
+ Every result stays reviewable. Candidates remain in T1 until you explicitly run `promote`.
202
+
203
+ Preview the complete dream pass without model calls or writes:
204
+
205
+ ```bash
206
+ ./sleep.py nightly --dry-run
207
+ ```
208
+
209
+ Run it now:
210
+
211
+ ```bash
212
+ ./sleep.py nightly --force
213
+ ```
214
+
215
+ Run the two dream components separately when you want more control:
216
+
217
+ ```bash
218
+ ./sleep.py mine --dry-run
219
+ ./sleep.py mine
220
+
221
+ ./sleep.py replay --limit 3 # show the replay plan
222
+ ./sleep.py replay --run --limit 3 --budget 0.10
223
+ ```
224
+
225
+ `--budget` is the maximum cost per task across both replay arms. Dream reports are written under `$SLEEP_HOME/reports/` and never trigger promotion automatically.
226
+
227
+ ## Useful commands
228
+
229
+ | Command | Purpose |
230
+ |---|---|
231
+ | `./sleep.py status -v` | Show buffer, candidate, quarantine, and permanent-memory status |
232
+ | `./sleep.py sleep --dry-run` | Check whether the sleep gate would run |
233
+ | `./sleep.py sleep --force` | Run consolidation now |
234
+ | `./sleep.py show <id>` | Inspect a candidate and its rendered context |
235
+ | `./sleep.py promote <id>` | Move an approved candidate to permanent memory |
236
+ | `./sleep.py refuse <id> --note "..."` | Record that a candidate is incorrect |
237
+ | `./sleep.py replay --run --limit 3` | Compare selected tasks with memory off and on |
238
+ | `./sleep.py mine --dry-run` | Find preferences repeated across sessions |
239
+ | `./sleep.py nightly --dry-run` | Preview the unattended nightly workflow |
240
+ | `./sleep.py doctor` | Find duplicate or overlapping memory records |
241
+ | `./sleep.py inject --project "$PWD"` | Print provisional context for the current project |
242
+
243
+ Run `./sleep.py <command> --help` for command-specific options.
244
+
245
+ ## Supported agents
246
+
247
+ | Agent | Integration |
248
+ |---|---|
249
+ | Claude Code | `UserPromptSubmit`, `PostToolUse`, `Stop`, and `PreCompact` hooks |
250
+ | Pi / OmO | Required user-installed extension: `./install.sh --extension` |
251
+
252
+ Both integrations share `$SLEEP_HOME`, so candidates reviewed from one client are visible to the other when the project scope matches.
253
+
254
+ ## Configure unattended model calls
255
+
256
+ Interactive runs inherit your current environment. Scheduled macOS runs read additional values from `$SLEEP_HOME/env`, which defaults to `~/.sleep/env`.
257
+
258
+ ```bash
259
+ mkdir -p ~/.sleep
260
+ touch ~/.sleep/env
261
+ chmod 600 ~/.sleep/env
262
+ ```
263
+
264
+ The file accepts `KEY=VALUE` lines. Common settings are:
265
+
266
+ ```text
267
+ ANTHROPIC_API_KEY=...
268
+ ANTHROPIC_BASE_URL=...
269
+ ANTHROPIC_MODEL=...
270
+ SLEEP_MODEL=...
271
+ ```
272
+
273
+ An explicit `--model` wins over `SLEEP_MODEL`, which wins over `ANTHROPIC_MODEL`. Existing process environment variables win over values in the file.
274
+
275
+ Before enabling the schedule, test the same path manually:
276
+
277
+ ```bash
278
+ ./sleep.py nightly --dry-run
279
+ ./sleep.py sleep --force --budget 0.10
280
+ ```
281
+
282
+ ## Review and safety model
283
+
284
+ Sleep separates memory into three tiers:
285
+
286
+ | Tier | Meaning | Who writes it |
287
+ |---|---|---|
288
+ | T0 | Temporary session observations | Hooks, extension, or `capture` |
289
+ | T1 | Provisional memory shown as unverified background | Consolidation and `mine` |
290
+ | T2 | Permanent memory | Only an explicit `promote` command |
291
+
292
+ Additional safeguards:
293
+
294
+ - Model output is always stamped as agent-generated and cannot mark itself user-confirmed.
295
+ - Provisional memory is rendered as background, not as an instruction.
296
+ - Secret-like values are replaced with redaction markers.
297
+ - Prompt-injection and exfiltration shapes are moved to quarantine.
298
+ - Mixed-project buffers fail closed instead of assigning facts to the wrong project.
299
+ - Replay reports results but never promotes memory automatically.
300
+ - Every model call has an explicit budget limit.
301
+
302
+ ## Data and logs
303
+
304
+ All runtime data lives under `$SLEEP_HOME`, which defaults to `~/.sleep`:
305
+
306
+ ```text
307
+ buffer/ temporary T0 records
308
+ candidates/ provisional T1 records
309
+ reports/ replay reports
310
+ logs/ hook and nightly logs
311
+ .quarantine/ rejected unsafe input
312
+ state.json sleep and replay timestamps
313
+ env optional scheduled-run environment
314
+ ```
315
+
316
+ Useful logs:
317
+
318
+ ```bash
319
+ ~/.sleep/logs/hook-fires.log
320
+ ~/.sleep/logs/hook.log
321
+ ~/.sleep/logs/nightly.log
322
+ ```
323
+
324
+ Use another home for testing or for a separate memory pool:
325
+
326
+ ```bash
327
+ SLEEP_HOME=/tmp/my-sleep ./sleep.py status -v
328
+ ```
329
+
330
+ ## Troubleshooting
331
+
332
+ **Nothing was captured**
333
+
334
+ ```bash
335
+ ./sleep.py status -v
336
+ ./sleep.py doctor
337
+ ```
338
+
339
+ 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.
340
+
341
+ **Sleep keeps skipping**
342
+
343
+ The default gate requires 3 records and a 6-hour interval. Inspect the decision with:
344
+
345
+ ```bash
346
+ ./sleep.py sleep --dry-run
347
+ ```
348
+
349
+ Use `--force` only when you intentionally want a model call.
350
+
351
+ **The scheduled pass cannot reach the model**
352
+
353
+ 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.
354
+
355
+ **A candidate appears in the wrong context**
356
+
357
+ Run `./sleep.py show <id>` and check its `cwd`. Mixed-project batches are kept in T0 and return an error instead of producing candidates.
358
+
359
+ ## More documentation
360
+
361
+ - [Measured evidence and validation history](docs/EVIDENCE.md)
362
+ - [Sleep Framework analysis](sleep-framework.md)
363
+ - [Shared `/sleep` skill](skill/sleep/SKILL.md)