pi-sleep-agent 0.5.0 → 0.7.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.
package/README.md CHANGED
@@ -32,6 +32,8 @@ Sleep adds a reviewable memory cycle to Pi, OmO, and Claude Code. It records use
32
32
  - **Measured replay.** Run the same task with memory off and on before deciding whether a memory helps.
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
+ - **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).
35
37
  - **Safety gates.** Secrets are redacted, hostile text is quarantined, and machine-generated prompts cannot claim user provenance.
36
38
 
37
39
  ## Install
@@ -196,11 +198,12 @@ session activity -> T0 buffer -> gated sleep -> T1 provisional memory
196
198
 
197
199
  Dream is Sleep's unattended reflection phase. It does not update model weights and it never writes permanent memory on its own.
198
200
 
199
- A dream pass performs three steps:
201
+ A dream pass performs four steps:
200
202
 
201
203
  1. **Mine.** Find instructions you repeated across separate sessions in the same project. This step is deterministic and makes no model call.
202
204
  2. **Consolidate.** When the sleep gate passes, ask the configured model to turn recent T0 observations into provisional T1 candidates.
203
- 3. **Replay.** When replay is due, run selected tasks with provisional memory off and on, then write a comparison report.
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.
206
+ 4. **Replay.** When replay is due, run selected tasks with provisional memory off and on, then write a comparison report.
204
207
 
205
208
  Every result stays reviewable. Candidates remain in T1 until you explicitly run `promote`.
206
209
 
@@ -208,6 +211,7 @@ Preview the complete dream pass without model calls or writes:
208
211
 
209
212
  ```bash
210
213
  ./sleep.py nightly --dry-run
214
+ ./sleep.py nightly --dry-run --stale https://old.internal/app # also scan approved memory for a changed value
211
215
  ```
212
216
 
213
217
  Run it now:
@@ -237,11 +241,13 @@ Run the two dream components separately when you want more control:
237
241
  | `./sleep.py sleep --force` | Run consolidation now |
238
242
  | `./sleep.py show <id>` | Inspect a candidate and its rendered context |
239
243
  | `./sleep.py promote <id>` | Move an approved candidate to permanent memory |
244
+ | `./sleep.py demote <id> --note "..."` | Un-approve a promoted memory: mark the approved record as retracted (kept on record, not deleted) and reopen the candidate as refused |
240
245
  | `./sleep.py refuse <id> --note "..."` | Record that a candidate is incorrect |
241
246
  | `./sleep.py replay --run --limit 3` | Compare selected tasks with memory off and on |
242
247
  | `./sleep.py mine --dry-run` | Find preferences repeated across sessions |
243
248
  | `./sleep.py nightly --dry-run` | Preview the unattended nightly workflow |
244
249
  | `./sleep.py doctor` | Find duplicate or overlapping memory records |
250
+ | `./sleep.py doctor --stale <value>` | Show which approved records still hold a stale value (e.g. a changed URL) |
245
251
  | `./sleep.py inject --project "$PWD"` | Print provisional context for the current project |
246
252
 
247
253
  Run `./sleep.py <command> --help` for command-specific options.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-sleep-agent",
3
- "version": "0.5.0",
3
+ "version": "0.7.0",
4
4
  "description": "A reviewable sleep and dream cycle for Pi agent memory.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/sleepkit/cli.py CHANGED
@@ -61,14 +61,56 @@ def cmd_status(a) -> int:
61
61
  q = [f for f in os.listdir(paths.quarantine_dir()) if f.endswith(".json")]
62
62
  mdir = paths.memory_dir(a.cwd or None)
63
63
  try:
64
- permanent = [f for f in os.listdir(mdir) if f.endswith(".md")]
64
+ permanent = [f for f in os.listdir(mdir)
65
+ if f.endswith(".md") and f != "MEMORY.md"]
65
66
  except OSError:
66
67
  permanent = []
67
68
  _p("sleep memory: T0=disposable captures, T1=provisional awaiting review, T2=permanent (promote-only)")
68
69
  _p("T0 buffer %d records / %d files / %d bytes (captured while you worked)" % (bc["records"], bc["files"], bc["bytes"]))
69
70
  _p("T1 candidates %d provisional, %d refused, %d total (distilled, shown as unverified context)" % (len(prov), len(ref), len(cands)))
70
71
  _p(" quarantine %d parked (needs human eyes) (held out until you review)" % len(q))
71
- _p("T2 canonical %s (%d permanent records; only you can promote)" % (mdir, len(permanent)))
72
+ retracted = []
73
+ act_perm = []
74
+ for f in permanent:
75
+ st_ = "?"
76
+ try:
77
+ with open(os.path.join(mdir, f), encoding="utf-8") as fh:
78
+ st_ = store.parse(fh.read())[0].get("status", "?")
79
+ except (OSError, ValueError):
80
+ st_ = "?"
81
+ if st_ == "retracted":
82
+ retracted.append(f)
83
+ else:
84
+ act_perm.append(f)
85
+ _p("T2 canonical %s (%d permanent records; only you can promote)" % (mdir, len(act_perm)))
86
+ if act_perm:
87
+ _p("")
88
+ _p("permanent (last 5, promoted with review date + source):")
89
+ for f in act_perm[-5:]:
90
+ try:
91
+ with open(os.path.join(mdir, f), encoding="utf-8") as fh:
92
+ m, b = store.parse(fh.read())
93
+ except (OSError, ValueError):
94
+ m, b = {}, ""
95
+ when = m.get("promoted_at", "?")[:10]
96
+ src = m.get("source", "?")
97
+ _p(" %-10s %-10s %-8s %s" % (f[:-3][:10], when, src,
98
+ b.replace("\n", " ")[:88]))
99
+ if retracted:
100
+ _p("")
101
+ _p("retracted (last 5, demoted; kept on record, not active memory):")
102
+ for f in retracted[-5:]:
103
+ try:
104
+ with open(os.path.join(mdir, f), encoding="utf-8") as fh:
105
+ m, b = store.parse(fh.read())
106
+ except (OSError, ValueError):
107
+ m, b = {}, ""
108
+ when = m.get("retracted_at", "?")[:10]
109
+ line = " %-10s %-10s %s" % (f[:-3][:10], when,
110
+ b.replace("\n", " ")[:88])
111
+ if m.get("note"):
112
+ line += " [demoted: %s]" % str(m["note"]).replace("\n", " ")[:120]
113
+ _p(line)
72
114
  if prov:
73
115
  _p("")
74
116
  _p("provisional (context only, never directives):")
@@ -118,6 +160,13 @@ def cmd_promote(a) -> int:
118
160
  return 0 if ok else 3
119
161
 
120
162
 
163
+ def cmd_demote(a) -> int:
164
+ ok, out = store.demote(a.id, memory_dir=a.memory_dir, dry_run=a.dry_run,
165
+ note=a.note)
166
+ _p(("DEMOTED " if ok else "REFUSED ") + out)
167
+ return 0 if ok else 3
168
+
169
+
121
170
  def cmd_refuse(a) -> int:
122
171
  """The other half of the review loop: 'this observation is wrong', recorded
123
172
  rather than silently deleted, so the pool shows what was judged and rejected."""
@@ -140,7 +189,7 @@ def cmd_prune(a) -> int:
140
189
 
141
190
 
142
191
  def cmd_doctor(a) -> int:
143
- issues = store.doctor()
192
+ issues = store.doctor(needle=a.stale)
144
193
  if a.json:
145
194
  _p(json.dumps(issues, indent=2, sort_keys=True, default=str))
146
195
  elif not issues:
@@ -206,6 +255,10 @@ def cmd_nightly(a) -> int:
206
255
  rep: dict = {"ts": paths.now()} # heterogeneous on purpose: three reports, one JSON
207
256
  rep["mine"] = ({"skipped": "--no-mine"} if a.no_mine
208
257
  else mine.mine(min_sessions=a.mine_min_sessions, dry_run=a.dry_run))
258
+ # The hygiene report lands in the night regardless of the gates: it is
259
+ # read-only, so the worst an unattended pass can do is surface a stale
260
+ # value (e.g. a changed deployment URL) for a person to act on later.
261
+ rep["doctor"] = {"issues": store.doctor(needle=a.stale)}
209
262
  rep["sleep"] = consolidate.run_sleep(session=a.session, model=a.model,
210
263
  budget_usd=a.budget,
211
264
  min_records=a.min_records,
@@ -322,6 +375,13 @@ def main(argv=None) -> int:
322
375
  pr.add_argument("--dry-run", action="store_true")
323
376
  pr.set_defaults(fn=cmd_promote)
324
377
 
378
+ dm = sub.add_parser("demote", help="un-approve a promoted memory (T2 -> refused, marked not deleted)")
379
+ dm.add_argument("id")
380
+ dm.add_argument("--memory-dir")
381
+ dm.add_argument("--note", default="")
382
+ dm.add_argument("--dry-run", action="store_true")
383
+ dm.set_defaults(fn=cmd_demote)
384
+
325
385
  rf = sub.add_parser("refuse", help="mark a candidate wrong, with a note")
326
386
  rf.add_argument("candidate_id")
327
387
  rf.add_argument("--note", default="")
@@ -339,6 +399,9 @@ def main(argv=None) -> int:
339
399
 
340
400
  dc = sub.add_parser("doctor", help="read-only hygiene report")
341
401
  dc.add_argument("--json", action="store_true")
402
+ dc.add_argument("--stale", default=None,
403
+ help="value (e.g. a URL) to scan approved T2 memory for; "
404
+ "reports which permanent records still hold it")
342
405
  dc.set_defaults(fn=cmd_doctor)
343
406
 
344
407
  rp = sub.add_parser("replay", help="layer 3: A/B measure provisional memory, report-only")
@@ -352,6 +415,8 @@ def main(argv=None) -> int:
352
415
 
353
416
  nt = sub.add_parser("nightly",
354
417
  help="unattended pass: gated consolidation + replay when due")
418
+ nt.add_argument("--stale", default=None,
419
+ help="value (e.g. a URL) to scan approved T2 memory for each night")
355
420
  nt.add_argument("--session")
356
421
  nt.add_argument("--model", default=None)
357
422
  nt.add_argument("--budget", type=float, default=1.00)
package/sleepkit/store.py CHANGED
@@ -308,7 +308,14 @@ def set_status(cid: str, status: str, extra: dict | None = None) -> bool:
308
308
  meta["reviewed"] = paths.now()
309
309
  for k, v in (extra or {}).items():
310
310
  meta[k] = v
311
- with open(os.path.join(paths.candidates_dir(), cid + ".md"), "w", encoding="utf-8") as fh:
311
+ # Write back where the record actually lives: promoted candidates are in the
312
+ # archive, pending ones in candidates. Writing always to candidates used to
313
+ # leave a promoted record's status change stranded in a stale archive copy.
314
+ loc = paths.candidates_dir()
315
+ if meta.get("promoted_to") or not os.path.isfile(os.path.join(loc, cid + ".md")):
316
+ if os.path.isfile(os.path.join(paths.archive_dir("candidates"), cid + ".md")):
317
+ loc = paths.archive_dir("candidates")
318
+ with open(os.path.join(loc, cid + ".md"), "w", encoding="utf-8") as fh:
312
319
  fh.write(emit(meta, body))
313
320
  return True
314
321
 
@@ -337,9 +344,11 @@ def promote(cid: str, memory_dir: str | None = None, dry_run: bool = False) -> t
337
344
  # Expansion-only: if the name is taken, open a new file rather than merging.
338
345
  if os.path.exists(dest):
339
346
  dest = os.path.join(mdir, "%s-%s.md" % (slugify(body.split(".")[0][:60]), cid[-4:]))
340
- line = "- **%s**: [detail](%s). %s" % (
347
+ when = paths.now()
348
+ src = meta.get("source", "?")
349
+ line = "- **%s**: [detail](%s). %s _(promoted %s, source=%s)_" % (
341
350
  os.path.basename(dest)[:-3], os.path.basename(dest),
342
- body.replace("\n", " ")[:220])
351
+ body.replace("\n", " ")[:160], when[:10], src)
343
352
  if dry_run:
344
353
  return True, "would write %s (+ index line)" % dest
345
354
  os.makedirs(mdir, exist_ok=True)
@@ -350,7 +359,7 @@ def promote(cid: str, memory_dir: str | None = None, dry_run: bool = False) -> t
350
359
  # reader inside the memory store never sees a record claiming to be provisional.
351
360
  out_meta = {k: v for k, v in meta.items() if not k.startswith("_")}
352
361
  out_meta["status"] = "promoted"
353
- out_meta["promoted_at"] = paths.now()
362
+ out_meta["promoted_at"] = when
354
363
  with open(dest, "w", encoding="utf-8") as fh:
355
364
  fh.write(emit(out_meta, body))
356
365
  ok, why = append_index_line(mdir, line)
@@ -399,6 +408,83 @@ def append_index_line(memory_dir: str, line: str) -> tuple[bool, str]:
399
408
  return True, "appended"
400
409
 
401
410
 
411
+ def remove_index_line(memory_dir: str, line: str, slug: str) -> bool:
412
+ """Drop one managed index line by slug. Never touches content outside the block."""
413
+ idx = os.path.join(memory_dir, "MEMORY.md")
414
+ if not os.path.isfile(idx):
415
+ return False
416
+ with open(idx, encoding="utf-8") as fh:
417
+ existing = fh.read()
418
+ block_re = re.compile(re.escape(IDX_BEGIN) + r".*?" + re.escape(IDX_END), re.S)
419
+ m = block_re.search(existing)
420
+ if not m:
421
+ return False
422
+ block = m.group(0)
423
+ # Match any line whose "**<slug>**" heading equals ours, regardless of suffix.
424
+ target = "**%s**" % slug
425
+ kept, found = [], False
426
+ for ln in block.split("\n"):
427
+ if re.match(r"\s*- \*\*[^*]+\*\*:", ln) and target in ln:
428
+ found = True
429
+ continue
430
+ kept.append(ln)
431
+ if not found:
432
+ return False
433
+ new_block = "\n".join(kept)
434
+ updated = existing[:m.start()] + new_block + existing[m.end():]
435
+ with open(idx, "w", encoding="utf-8") as fh:
436
+ fh.write(updated)
437
+ return True
438
+
439
+
440
+ def demote(cid: str, memory_dir: str | None = None, dry_run: bool = False,
441
+ note: str = "") -> tuple[bool, str]:
442
+ """T2 -> refused. Explicit human act: an approved memory turned out wrong.
443
+
444
+ Promotion was "create a new file, never edit one"; reversal keeps that spirit.
445
+ The canonical T2 copy is *marked* retracted, not deleted, so the audit trail of
446
+ what was once approved survives; the index line is dropped so the retired value
447
+ no longer reads as active memory; and the archived candidate is re-opened as a
448
+ refused record the reviewer can see in `status`. Nothing on this path edits or
449
+ deletes a past verdict.
450
+ """
451
+ got = get_candidate(cid)
452
+ if not got:
453
+ return False, "no such candidate: " + cid
454
+ meta, body = got
455
+ if meta.get("status") != "promoted":
456
+ return False, "not promoted (nothing to demote): " + cid
457
+ dest = meta.get("promoted_to") or ""
458
+ mdir = memory_dir or paths.memory_dir()
459
+ slug = os.path.basename(dest)[:-3] if dest else ""
460
+ if dry_run:
461
+ return True, "would retract %s (drop index line, mark candidate refused)" % (slug or cid)
462
+ stamp = paths.now()
463
+ # 1) mark the canonical T2 copy retracted
464
+ t2_ok = True
465
+ if dest and os.path.isfile(dest):
466
+ try:
467
+ with open(dest, encoding="utf-8") as fh:
468
+ m2, b2 = parse(fh.read())
469
+ m2["status"] = "retracted"
470
+ m2["retracted_at"] = stamp
471
+ if note:
472
+ m2["note"] = note
473
+ with open(dest, "w", encoding="utf-8") as fh:
474
+ fh.write(emit(m2, b2))
475
+ except (OSError, ValueError):
476
+ t2_ok = False
477
+ # 2) drop the index line so the retired value no longer reads as active
478
+ if slug and mdir:
479
+ remove_index_line(mdir, "", slug)
480
+ # 3) re-open the archived candidate as refused with a note the reviewer can see
481
+ if note:
482
+ set_status(cid, "refused", {"notes": note, "reviewed": stamp})
483
+ else:
484
+ set_status(cid, "refused", {"reviewed": stamp})
485
+ return True, ("retracted %s" % (slug or cid)
486
+ + (" (T2 default not found)" if not t2_ok else ""))
487
+
402
488
  def supersede(old_id: str, new_id: str) -> bool:
403
489
  return (set_status(old_id, "superseded", {"superseded_by": new_id})
404
490
  and set_status(new_id, "provisional", {"supersedes": old_id}))
@@ -425,7 +511,8 @@ def prune_buffer(older_than_hours: float = 0.0, session: str | None = None) -> d
425
511
  return {"moved": moved, "remaining": buffer_counts()}
426
512
 
427
513
 
428
- def doctor(memory_dir: str | None = None, targets: list[str] | None = None) -> list[dict]:
514
+ def doctor(memory_dir: str | None = None, targets: list[str] | None = None,
515
+ needle: str | None = None) -> list[dict]:
429
516
  """Read-only hygiene report.
430
517
 
431
518
  Two checks, both about content rather than formatting:
@@ -455,6 +542,17 @@ def doctor(memory_dir: str | None = None, targets: list[str] | None = None) -> l
455
542
  if n > 1:
456
543
  out.append({"issue": "duplicate-heading-in-file", "heading": h,
457
544
  "count": n, "file": p})
545
+ if needle:
546
+ nlow = needle.strip().lower()
547
+ if nlow:
548
+ for p, text in bodies.items():
549
+ if os.path.basename(p) == "MEMORY.md":
550
+ # The index only points at detail files; flagging it re-reports
551
+ # every hit once for the detail file it names, so skip it.
552
+ continue
553
+ if nlow in text.lower():
554
+ out.append({"issue": "stale-value-in-memory", "file": p,
555
+ "value": needle})
458
556
  pool = [(c["id"], c.get("_body", "")) for c in list_candidates(with_body=True)]
459
557
  for i in range(len(pool)):
460
558
  for j in range(i + 1, len(pool)):