pi-sleep-agent 0.8.0 → 0.8.2
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.
- package/README.md +97 -24
- package/package.json +1 -1
- package/sleepkit/safety.py +21 -0
- package/sleepkit/store.py +46 -0
package/README.md
CHANGED
|
@@ -6,14 +6,14 @@
|
|
|
6
6
|
|
|
7
7
|
Capture while agents work. Consolidate when they stop. Promote only what you approve.
|
|
8
8
|
|
|
9
|
-
[](#install)
|
|
10
10
|
[](https://www.python.org/)
|
|
11
11
|
[](#install)
|
|
12
|
-
[](#supported-agents)
|
|
13
13
|
|
|
14
14
|
</div>
|
|
15
15
|
|
|
16
|
-
Sleep adds a reviewable memory cycle to
|
|
16
|
+
Sleep adds a reviewable memory cycle to nine selectable coding-agent targets. 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
17
|
|
|
18
18
|
<p align="center">
|
|
19
19
|
<img src=".github/assets/sleep-replay.png" alt="Terminal showing the sleep cycle: agents capture observations, sleep consolidates them into provisional memory, and only your promote makes them permanent" width="920" />
|
|
@@ -33,7 +33,7 @@ Sleep adds a reviewable memory cycle to Pi, OmO, and Claude Code. It records use
|
|
|
33
33
|
- **Repeated preference detection.** `mine` finds instructions you gave in multiple sessions without a model call.
|
|
34
34
|
- **Project isolation.** A project's provisional memory is injected only into that project.
|
|
35
35
|
- **Reviewable permanence.** Each approved memory in your index carries its review date and source, so you can tell when a saved instruction was pinned.
|
|
36
|
-
- **Stale-value scan.** `doctor --stale <value>` finds which approved records still hold a value you know has changed (for example a deployment URL).
|
|
36
|
+
- **Stale-value scan.** `doctor --stale <value>` finds which approved records still hold a value you know has changed (for example a deployment URL). Unreviewed provisional candidates are also flagged: a fact the agent proposed once and never rediscovered for 4+ weeks keeps getting injected into every session's context, so `doctor` surfaces it as `stale-candidate-unrediscovered` (a report line it never acts on, nothing is dropped).
|
|
37
37
|
- **Safety gates.** Secrets are redacted, hostile text is quarantined, and machine-generated prompts cannot claim user provenance.
|
|
38
38
|
|
|
39
39
|
## Install
|
|
@@ -42,18 +42,83 @@ Requirements:
|
|
|
42
42
|
|
|
43
43
|
- Python 3.10 or newer
|
|
44
44
|
- Claude Code CLI for model-backed consolidation and replay
|
|
45
|
-
-
|
|
45
|
+
- One or more supported coding agents from the table below
|
|
46
46
|
|
|
47
47
|
```bash
|
|
48
48
|
./install.sh --dry-run # show every change without writing
|
|
49
|
-
./install.sh # install
|
|
50
|
-
|
|
51
|
-
./install.sh --
|
|
49
|
+
./install.sh # install skill + hooks; asks whether to add the
|
|
50
|
+
# nightly pass and the Pi/OmO extension (no flags needed)
|
|
51
|
+
./install.sh --extension # also install the Pi/OmO extension (no prompt)
|
|
52
|
+
./install.sh --nightly # also schedule the nightly pass (no prompt)
|
|
53
|
+
./install.sh --launchd # alias for --nightly (macOS convention)
|
|
52
54
|
```
|
|
53
55
|
|
|
54
|
-
|
|
56
|
+
On Windows the entry point `./install.sh` becomes `python tools\install.py` (or
|
|
57
|
+
`py tools\install.py`); the flags are identical:
|
|
55
58
|
|
|
56
|
-
|
|
59
|
+
```bat
|
|
60
|
+
py tools\install.py --dry-run
|
|
61
|
+
py tools\install.py --extension --nightly
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**Which agents get the capture hooks is your choice.** A plain `install.py` on a
|
|
65
|
+
real terminal asks which coding agents to wire (multi-select, default Claude Code).
|
|
66
|
+
Scripts and CI can pick explicitly without a prompt:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
python3 tools/install.py --agents claude # Claude Code only (default)
|
|
70
|
+
python3 tools/install.py --agents claude,gemini,cursor # several verified hook formats
|
|
71
|
+
python3 tools/install.py --agents pi,oh-my-pi # extension targets stay independent
|
|
72
|
+
SLEEP_PROJECT=/path/to/project python3 tools/install.py --agents opencode
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Accepted keys are `claude`, `gemini`, `pi`, `oh-my-pi`, `cursor`, `opencode`,
|
|
76
|
+
`windsurf`, `codex`, and `cline`. The interactive prompt shows the same list.
|
|
77
|
+
Selecting one key never installs another key. The older `--extension` flag selects
|
|
78
|
+
`pi` only.
|
|
79
|
+
|
|
80
|
+
| Key | Surface written | Capability | Confidence |
|
|
81
|
+
|---|---|---|---|
|
|
82
|
+
| `claude` | `$CLAUDE_HOME/settings.json` | Prompt capture, tool capture, stop and compact consolidation | Verified |
|
|
83
|
+
| `gemini` | `~/.gemini/settings.json` | `BeforePrompt`, `AfterTool`, `SessionEnd` | Measured hook grammar |
|
|
84
|
+
| `pi` | `~/.omo/agent/extensions/sleep` | Full TypeScript extension capture and context injection | Verified |
|
|
85
|
+
| `oh-my-pi` | `~/.omp/agent/extensions/sleep` | Pi-lineage extension path | Best effort |
|
|
86
|
+
| `cursor` | `~/.cursor/hooks.json` | Tool capture and session-end consolidation | Documented native hooks |
|
|
87
|
+
| `opencode` | `<project>/.opencode/` | Tool capture and idle consolidation through a project plugin | Verified plugin grammar |
|
|
88
|
+
| `windsurf` | `~/.codeium/windsurf/hooks.json` | Prompt and code-write capture | Measured hook grammar |
|
|
89
|
+
| `codex` | `~/.codex/config.toml` | Completion notification only; no per-turn prompt capture | Documented, limited |
|
|
90
|
+
| `cline` | VS Code user `settings.json` | `request_created` capture only | Best effort |
|
|
91
|
+
|
|
92
|
+
OpenCode is project-scoped. Set `SLEEP_PROJECT` when the project is not the
|
|
93
|
+
current directory. The installer renders the repository path into the copied
|
|
94
|
+
plugin and registers `./.opencode/plugins` in that project's
|
|
95
|
+
`.opencode/opencode.json`.
|
|
96
|
+
|
|
97
|
+
Codex has no per-turn hook. Its `[notify]` integration can wake consolidation
|
|
98
|
+
when a run completes, but it cannot capture the prompt stream. If `[notify]`
|
|
99
|
+
already owns a different command, Sleep leaves it unchanged. Cline and Oh My Pi
|
|
100
|
+
are marked best effort because their public integration contracts are less stable.
|
|
101
|
+
A missing event should be reported with the affected agent, config path, and the
|
|
102
|
+
last lines from `~/.sleep/logs/`.
|
|
103
|
+
|
|
104
|
+
Amp, Antigravity, GitHub Copilot, Aider, and OpenHands are not installer targets.
|
|
105
|
+
Their available surfaces are respectively absent/unstable lifecycle hooks or
|
|
106
|
+
transcript/event-stream polling, which this installer does not impersonate as a
|
|
107
|
+
working command-hook integration.
|
|
108
|
+
|
|
109
|
+
The installer runs the test suite first, creates backups before configuration
|
|
110
|
+
changes, and is safe to run again. `--dry-run` does not modify existing links or
|
|
111
|
+
config files. Uninstall removes only exact Sleep-owned commands, preserves foreign
|
|
112
|
+
entries, and backs up JSON/TOML files before changing them. It is one Python
|
|
113
|
+
script and works on macOS, Linux, and Windows; per-platform scheduling is chosen
|
|
114
|
+
automatically:
|
|
115
|
+
|
|
116
|
+
- **macOS** - a LaunchAgent (`~/Library/LaunchAgents/com.aydinnyunus.sleep-nightly.plist`).
|
|
117
|
+
- **Linux** - a cron job (`crontab -l`, kept inside owned `# BEGIN/END aydinnyunus-sleep-nightly` markers).
|
|
118
|
+
- **Windows** - a Task Scheduler task via `schtasks /create /tn aydinnyunus-sleep-nightly`.
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
### Pi / OmO and Oh My Pi extensions
|
|
57
122
|
|
|
58
123
|
Pi and OmO require Sleep's user-installed extension for automatic integration:
|
|
59
124
|
|
|
@@ -61,12 +126,17 @@ Pi and OmO require Sleep's user-installed extension for automatic integration:
|
|
|
61
126
|
./install.sh --extension
|
|
62
127
|
```
|
|
63
128
|
|
|
64
|
-
The installer links this repository's `extension/` directory to
|
|
129
|
+
The installer links this repository's `extension/` directory to the selected
|
|
130
|
+
extension target only:
|
|
65
131
|
|
|
66
132
|
```text
|
|
67
|
-
~/.omo/agent/extensions/sleep
|
|
133
|
+
pi -> ~/.omo/agent/extensions/sleep
|
|
134
|
+
oh-my-pi -> ~/.omp/agent/extensions/sleep
|
|
68
135
|
```
|
|
69
136
|
|
|
137
|
+
Use `--agents oh-my-pi` for Oh My Pi. `--extension` remains an alias for selecting
|
|
138
|
+
`pi`; it does not install Oh My Pi implicitly.
|
|
139
|
+
|
|
70
140
|
The extension loads on the next Pi or OmO session and performs three jobs:
|
|
71
141
|
|
|
72
142
|
- captures user messages and relevant tool activity into T0,
|
|
@@ -136,6 +206,8 @@ To remove Sleep and restore the backed-up configuration:
|
|
|
136
206
|
./uninstall.sh
|
|
137
207
|
```
|
|
138
208
|
|
|
209
|
+
On Windows, `python tools\uninstall.py` (or `py tools\uninstall.py`).
|
|
210
|
+
|
|
139
211
|
## Quick start
|
|
140
212
|
|
|
141
213
|
Check the installation:
|
|
@@ -202,7 +274,7 @@ A dream pass performs four steps:
|
|
|
202
274
|
|
|
203
275
|
1. **Mine.** Find instructions you repeated across separate sessions in the same project. This step is deterministic and makes no model call.
|
|
204
276
|
2. **Consolidate.** When the sleep gate passes, ask the configured model to turn recent T0 observations into provisional T1 candidates.
|
|
205
|
-
3. **Hygiene.** Run the read-only `doctor` scan and fold any findings (duplicate headings, near-duplicate candidates, or stale values when you pass `--stale <value>`) into the night's report.
|
|
277
|
+
3. **Hygiene.** Run the read-only `doctor` scan and fold any findings (duplicate headings, near-duplicate candidates, records parked in quarantine awaiting review, or stale values when you pass `--stale <value>`) into the night's report.
|
|
206
278
|
4. **Replay.** When replay is due, run selected tasks with provisional memory off and on, then write a comparison report.
|
|
207
279
|
|
|
208
280
|
Every result stays reviewable. Candidates remain in T1 until you explicitly run `promote`.
|
|
@@ -246,7 +318,7 @@ Run the two dream components separately when you want more control:
|
|
|
246
318
|
| `./sleep.py replay --run --limit 3` | Compare selected tasks with memory off and on |
|
|
247
319
|
| `./sleep.py mine --dry-run` | Find preferences repeated across sessions |
|
|
248
320
|
| `./sleep.py nightly --dry-run` | Preview the unattended nightly workflow |
|
|
249
|
-
| `./sleep.py doctor` | Find duplicate or overlapping memory records |
|
|
321
|
+
| `./sleep.py doctor` | Find duplicate or overlapping memory records, flag provisional candidates not rediscovered for 4+ weeks, and report records parked in quarantine awaiting a human (report only, never dropped or un-parked) |
|
|
250
322
|
| `./sleep.py doctor --stale <value>` | Show which approved records still hold a stale value (e.g. a changed URL) |
|
|
251
323
|
| `./sleep.py inject --project "$PWD"` | Print provisional context for the current project |
|
|
252
324
|
|
|
@@ -254,12 +326,12 @@ Run `./sleep.py <command> --help` for command-specific options.
|
|
|
254
326
|
|
|
255
327
|
## Supported agents
|
|
256
328
|
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
329
|
+
The installer support matrix and confidence levels live in [Install](#install).
|
|
330
|
+
All selected integrations share `$SLEEP_HOME`, so candidates reviewed from one
|
|
331
|
+
client are visible to another when the project scope matches. Capture depth is not
|
|
332
|
+
identical: Claude, Gemini, Pi/OmO, OpenCode, Cursor, and Windsurf expose multiple
|
|
333
|
+
lifecycle boundaries; Codex is completion-only; Cline is request-created-only;
|
|
334
|
+
Oh My Pi is a best-effort Pi-lineage extension path.
|
|
263
335
|
|
|
264
336
|
## Configure unattended model calls
|
|
265
337
|
|
|
@@ -305,7 +377,7 @@ Additional safeguards:
|
|
|
305
377
|
- Provisional memory is rendered as background, not as an instruction.
|
|
306
378
|
- Secret-like values are replaced with redaction markers.
|
|
307
379
|
- Prompt-injection and exfiltration shapes are moved to quarantine.
|
|
308
|
-
- Mixed-project buffers
|
|
380
|
+
- Mixed-project buffers are partitioned by project and consolidated separately; unaddressed records stay in T0.
|
|
309
381
|
- Replay reports results but never promotes memory automatically.
|
|
310
382
|
- Every model call has an explicit budget limit.
|
|
311
383
|
|
|
@@ -360,14 +432,15 @@ Use `--force` only when you intentionally want a model call.
|
|
|
360
432
|
|
|
361
433
|
**The scheduled pass cannot reach the model**
|
|
362
434
|
|
|
363
|
-
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.
|
|
435
|
+
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 the scheduled pass (launchd / cron / Task Scheduler).
|
|
364
436
|
|
|
365
437
|
**A candidate appears in the wrong context**
|
|
366
438
|
|
|
367
|
-
Run `./sleep.py show <id>` and check its `cwd`. Mixed-project batches are
|
|
439
|
+
Run `./sleep.py show <id>` and check its `cwd`. Mixed-project batches are partitioned by canonical `cwd`; each project is consolidated independently, while records without a project address stay in T0.
|
|
368
440
|
|
|
369
441
|
## More documentation
|
|
370
442
|
|
|
443
|
+
- [Sleep: the reviewable-memory extension for coding agents](https://aydinnyunus.github.io/2026/11/01/sleep-agent-memory-extension/) (blog)
|
|
371
444
|
- [Measured evidence and validation history](docs/EVIDENCE.md)
|
|
372
445
|
- [Sleep Framework analysis](sleep-framework.md)
|
|
373
|
-
- [Shared `/sleep` skill](skill/sleep/SKILL.md)
|
|
446
|
+
- [Shared `/sleep` skill](shared-skill/sleep/SKILL.md)
|
package/package.json
CHANGED
package/sleepkit/safety.py
CHANGED
|
@@ -141,6 +141,24 @@ _RELAY_WEAK = [
|
|
|
141
141
|
r"read-only code review\.|work in the git repo\b)"), "addressed to a role"),
|
|
142
142
|
]
|
|
143
143
|
|
|
144
|
+
# A skill's body reaches the hook as a typed prompt: the person invokes a slash command
|
|
145
|
+
# and the harness sends the skill text as the user turn, so it looks like authored speech
|
|
146
|
+
# while it is a program's instructions to a model. Measured 2026-11-01: the payload of
|
|
147
|
+
# ~/.claude-work/skills/ai-evaluator-pass/SKILL.md was captured twice as source=user and
|
|
148
|
+
# mined into a "preference" candidate; the shape gives it away. It is COMPOUND on purpose:
|
|
149
|
+
# a verdict token alone ("return PASS or FAIL") is something a person also types when they
|
|
150
|
+
# want a review, so it only counts together with a body-level constraint ("be concise",
|
|
151
|
+
# "do not edit files") that a slash-command payload carries and a person rarely does.
|
|
152
|
+
_RELAY_VERDICT = re.compile(
|
|
153
|
+
r"(?i)\b(?:return|respond with|answer|reply)\s+(?:pass|fail|ok|done)\b"
|
|
154
|
+
r"(?:\s*(?:or|/)\s*(?:pass|fail|ok|done)\b)?")
|
|
155
|
+
_RELAY_BODY_CONSTRAINT = re.compile(
|
|
156
|
+
r"(?i)\b(?:do not (?:edit|modify|write|create|touch)\s+(?:any\s+)?files?|be concise)\b")
|
|
157
|
+
_RELAY_COMPOUND = [
|
|
158
|
+
(lambda t: bool(_RELAY_VERDICT.search(t)) and bool(_RELAY_BODY_CONSTRAINT.search(t)),
|
|
159
|
+
"skill payload (verdict token + body constraint)"),
|
|
160
|
+
]
|
|
161
|
+
|
|
144
162
|
|
|
145
163
|
def machine_driven(environ: dict | None = None) -> str:
|
|
146
164
|
"""Name of an env marker proving this session was spawned by a host, else "".
|
|
@@ -163,6 +181,9 @@ def relay_reason(text: str, environ: dict | None = None) -> str | None:
|
|
|
163
181
|
for pat, why in _RELAY_STRONG:
|
|
164
182
|
if pat.search(t):
|
|
165
183
|
return why
|
|
184
|
+
for pred, why in _RELAY_COMPOUND:
|
|
185
|
+
if pred(t):
|
|
186
|
+
return why
|
|
166
187
|
if machine_driven(environ):
|
|
167
188
|
for pat, why in _RELAY_WEAK:
|
|
168
189
|
if pat.search(t):
|
package/sleepkit/store.py
CHANGED
|
@@ -16,11 +16,30 @@ import os
|
|
|
16
16
|
import re
|
|
17
17
|
import shutil
|
|
18
18
|
import time
|
|
19
|
+
from datetime import datetime
|
|
19
20
|
|
|
20
21
|
from . import paths, safety
|
|
21
22
|
|
|
22
23
|
KINDS = ("fact", "preference", "procedure", "warning")
|
|
23
24
|
|
|
25
|
+
# Doctor flags a provisional candidate as stale when its last activity (creation
|
|
26
|
+
# or the most recent rediscovery) is older than this.
|
|
27
|
+
STALE_CANDIDATE_WEEKS = 4.0
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _hours_since(ts: str) -> float | None:
|
|
31
|
+
"""Hours since an ISO timestamp written by paths.now(). Unparseable input
|
|
32
|
+
returns None, meaning 'no constraint' rather than 'flag everything'."""
|
|
33
|
+
if not ts:
|
|
34
|
+
return None
|
|
35
|
+
try:
|
|
36
|
+
dt = datetime.fromisoformat(ts)
|
|
37
|
+
except (ValueError, TypeError):
|
|
38
|
+
return None
|
|
39
|
+
if dt.tzinfo is None:
|
|
40
|
+
dt = dt.astimezone()
|
|
41
|
+
return (datetime.now(dt.tzinfo) - dt).total_seconds() / 3600.0
|
|
42
|
+
|
|
24
43
|
IDX_BEGIN = "<!-- sleep:begin (managed by sleepctl; lines here are appended, never rewritten) -->"
|
|
25
44
|
IDX_END = "<!-- sleep:end -->"
|
|
26
45
|
|
|
@@ -240,6 +259,7 @@ def _record_rediscovery(cid: str, session: str) -> str | None:
|
|
|
240
259
|
n = int(meta.get("rediscovered", 0) or 0) + 1
|
|
241
260
|
meta["rediscovered"] = str(n)
|
|
242
261
|
meta["rediscovered_in"] = "|".join(sessions)
|
|
262
|
+
meta["rediscovered_at"] = paths.now()
|
|
243
263
|
loc = paths.candidates_dir()
|
|
244
264
|
if not os.path.isfile(os.path.join(loc, cid + ".md")):
|
|
245
265
|
p = os.path.join(paths.archive_dir("candidates"), cid + ".md")
|
|
@@ -606,6 +626,19 @@ def doctor(memory_dir: str | None = None, targets: list[str] | None = None,
|
|
|
606
626
|
if sim >= 0.75:
|
|
607
627
|
out.append({"issue": "near-duplicate-candidates",
|
|
608
628
|
"pair": [pool[i][0], pool[j][0]], "similarity": round(sim, 2)})
|
|
629
|
+
cutoff_hours = STALE_CANDIDATE_WEEKS * 7 * 24
|
|
630
|
+
for c in list_candidates():
|
|
631
|
+
if c.get("status") != "provisional":
|
|
632
|
+
continue
|
|
633
|
+
# Last activity = the most recent rediscovery if there was one, else the
|
|
634
|
+
# record's own creation ts. A provisional that is neither being promoted
|
|
635
|
+
# nor re-learned for weeks is noise the queue keeps injecting into every
|
|
636
|
+
# session's context, so the doctor surfaces it (report only, nothing drops).
|
|
637
|
+
last = c.get("rediscovered_at") or c.get("ts")
|
|
638
|
+
age_h = _hours_since(str(last)) if last else None
|
|
639
|
+
if age_h is not None and age_h >= cutoff_hours:
|
|
640
|
+
out.append({"issue": "stale-candidate-unrediscovered", "id": c["id"],
|
|
641
|
+
"last_seen": str(last)[:10], "rediscovered": int(c.get("rediscovered", 0) or 0)})
|
|
609
642
|
for cid, body in pool:
|
|
610
643
|
for path, text in bodies.items():
|
|
611
644
|
# MEMORY.md is the index: it restates every entry by design, so scoring
|
|
@@ -618,4 +651,17 @@ def doctor(memory_dir: str | None = None, targets: list[str] | None = None,
|
|
|
618
651
|
if sim >= 0.7:
|
|
619
652
|
out.append({"issue": "candidate-duplicates-memory", "id": cid, "file": path,
|
|
620
653
|
"similarity": round(sim, 2)})
|
|
654
|
+
# Quarantine is a wait-for-a-human state, not a resting state: entries parked there
|
|
655
|
+
# are held out of every future consolidation until someone reads them. `doctor`
|
|
656
|
+
# reporting "clean" while the queue holds parked records is the failure a user hits
|
|
657
|
+
# by asking exactly the question doctor answers ("is anything waiting on me?").
|
|
658
|
+
# Report the count and the newest ids; nothing is dropped or changed here.
|
|
659
|
+
# Path assembled without paths.home(): home() creates the whole tier skeleton as a
|
|
660
|
+
# side effect, and a read-only report that lays down directories is not read-only.
|
|
661
|
+
qdir = os.path.join(paths.SLEEP_HOME, ".quarantine")
|
|
662
|
+
if os.path.isdir(qdir):
|
|
663
|
+
parked = sorted(f for f in os.listdir(qdir) if f.endswith(".json"))
|
|
664
|
+
if parked:
|
|
665
|
+
out.append({"issue": "quarantine-awaiting-review", "count": len(parked),
|
|
666
|
+
"newest": [f[:-5] for f in parked[-3:]]})
|
|
621
667
|
return out
|