pi-sleep-agent 0.8.7 → 0.8.9

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
@@ -275,7 +275,7 @@ A dream pass performs four steps:
275
275
 
276
276
  1. **Mine.** Find instructions you repeated across separate sessions in the same project. This step is deterministic and makes no model call.
277
277
  2. **Consolidate.** When the sleep gate passes, ask the configured model to turn recent T0 observations into provisional T1 candidates.
278
- 3. **Hygiene.** Run the read-only `doctor` scan and fold any findings (duplicate headings, near-duplicate or contradicting candidates, records parked in quarantine awaiting review, or stale values when you pass `--stale <value>`) into the night's report.
278
+ 3. **Hygiene.** Run the read-only `doctor` scan and fold any findings (duplicate headings, near-duplicate or contradicting candidates, broken supersede links, records parked in quarantine awaiting review, or stale values when you pass `--stale <value>`) into the night's report.
279
279
  4. **Replay.** When replay is due, run selected tasks with provisional memory off and on, then write a comparison report.
280
280
 
281
281
  Every result stays reviewable. Candidates remain in T1 until you explicitly run `promote`.
@@ -319,9 +319,10 @@ Run the two dream components separately when you want more control:
319
319
  | `./sleep.py replay --run --limit 3` | Compare selected tasks with memory off and on |
320
320
  | `./sleep.py mine --dry-run` | Find preferences repeated across sessions |
321
321
  | `./sleep.py nightly --dry-run` | Preview the unattended nightly workflow |
322
- | `./sleep.py doctor` | Find duplicate or overlapping memory records, flag contradicting candidates (same subject, one side carries a correction marker) and print the `supersede <older> <newer>` command to run, flag provisional candidates not rediscovered for 4+ weeks, and report records parked in quarantine awaiting a human (report only: it never supersedes, drops, merges or un-parks anything itself) |
322
+ | `./sleep.py doctor` | Find duplicate or overlapping memory records, flag contradicting candidates (same subject, one side carries a correction marker) and print the `supersede <older> <newer>` command to run, flag provisional candidates not rediscovered for 4+ weeks, flag supersede pointers that name a record no longer in the store, and report records parked in quarantine awaiting a human (report only: it never supersedes, drops, merges or un-parks anything itself) |
323
323
  | `./sleep.py doctor --stale <value>` | Show which approved records still hold a stale value (e.g. a changed URL) |
324
324
  | `./sleep.py doctor --contradictions` | Ask a model to adjudicate shortlisted pairs of provisional records for conflicts (`--budget`, default $0.25); report-only, and each finding carries the `supersede <older> <newer>` command to run |
325
+ | `./sleep.py doctor --contradictions --tier t2` | Adjudicate pairs of **approved** permanent memory instead of candidates (`--tier both` does both); a T2 finding is labelled `contradicting-memory` and carries the `demote <older>` command, because approved memory is un-approved, never superseded |
325
326
 
326
327
  The headless model call picks its transport by what exists on the machine, in this order:
327
328
  the host agent's own `omo -p` (used when an `omo` binary is on PATH), then `claude
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-sleep-agent",
3
- "version": "0.8.7",
3
+ "version": "0.8.9",
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
@@ -151,6 +151,15 @@ def cmd_show(a) -> int:
151
151
  return 2
152
152
  meta, body = got
153
153
  _p(store.emit(meta, body))
154
+ # Show the supersede chain: with only the two pointer fields visible, answering
155
+ # "which record is current, and what did it replace?" means reading other files.
156
+ chain = store.supersession_chain(a.id)
157
+ if len(chain["order"]) > 1 or chain["broken"]:
158
+ _p("# supersede chain (oldest -> newest):")
159
+ _p(" " + " -> ".join(chain["order"]))
160
+ _p(" current: %s" % chain["current"])
161
+ for gone in chain["broken"]:
162
+ _p(" BROKEN: %s is referenced but not in the store" % gone)
154
163
  _p("# rendered for context:\n" + safety.render_for_context(
155
164
  {"text": body, "source": meta.get("source"), "trust": meta.get("trust")}))
156
165
  return 0
@@ -198,7 +207,14 @@ def _doctor_shortlist() -> list:
198
207
  return out
199
208
 
200
209
 
201
- def _llm_contradictions(pairs: list, budget: float, model: str | None) -> list:
210
+ def _tier_of(cid: str, memory_ids: set) -> str:
211
+ """Which tier a record belongs to, so a pair's own membership decides its wording."""
212
+ return "t2" if cid in memory_ids else "t1"
213
+
214
+
215
+ def _llm_contradictions(pairs: list, budget: float, model: str | None,
216
+ tier: str = "t1", records: dict | None = None,
217
+ memory_ids: set | None = None) -> list:
202
218
  """Ask the model to adjudicate shortlisted pairs. Report-only: returns findings,
203
219
  changes nothing. A failed or unparseable call yields [] so doctor still reports the
204
220
  rest of its scan instead of dying on a model problem."""
@@ -208,8 +224,15 @@ def _llm_contradictions(pairs: list, budget: float, model: str | None) -> list:
208
224
  # under meta["_body"] (that key only exists on the list_candidates path). Reading the
209
225
  # wrong one sent the model three pairs of empty bodies, and it answered, correctly,
210
226
  # that there was nothing to compare - a silently useless call, not a crash.
211
- seen = {}
227
+ # `records` carries (meta, body) for the ids the caller already parsed. A permanent
228
+ # T2 record is not in the candidate store, so `store.get_candidate` returns nothing
229
+ # for it and this function used to hand the model three pairs of EMPTY bodies - the
230
+ # model then answered, correctly, that no claim was present, and the whole T2 pass
231
+ # reported a clean store without reading a single memory.
232
+ seen = dict(records or {})
212
233
  for cid in {c for pair in pairs for c in pair}:
234
+ if cid in seen:
235
+ continue
213
236
  got = store.get_candidate(cid)
214
237
  seen[cid] = (got[0], got[1]) if got else ({}, "")
215
238
  lines = []
@@ -219,8 +242,16 @@ def _llm_contradictions(pairs: list, budget: float, model: str | None) -> list:
219
242
  meta, body = seen.get(cid, ({}, ""))
220
243
  lines.append(" id=%s ts=%s body=%s" % (cid, meta.get("ts", "?"),
221
244
  (body or "").replace("\n", " ").strip()))
222
- user = ("Unreviewed provisional memory records, grouped into candidate pairs.\n"
223
- "Adjudicate each pair per your instructions.\n\n" + "\n".join(lines))
245
+ if tier in ("t2", "both"):
246
+ user = ("Memory records, grouped into candidate pairs. Some are unreviewed "
247
+ "provisional candidates; some are permanent memories a human already "
248
+ "approved.\nAdjudicate each pair per your instructions: two approved "
249
+ "memories that now assert opposite things mean the older one needs a "
250
+ "human verdict, not that the memory store is broken.\n\n"
251
+ + "\n".join(lines))
252
+ else:
253
+ user = ("Unreviewed provisional memory records, grouped into candidate pairs.\n"
254
+ "Adjudicate each pair per your instructions.\n\n" + "\n".join(lines))
224
255
  pf = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "prompts",
225
256
  "contradiction-check.md")
226
257
  # The subprocess seam: tests replace llm.run with a fake so the adjudication path is
@@ -255,6 +286,7 @@ def _llm_contradictions(pairs: list, budget: float, model: str | None) -> list:
255
286
  if not isinstance(doc, dict):
256
287
  return []
257
288
  found = []
289
+ mem = memory_ids or set()
258
290
  for item in doc.get("pairs") or []:
259
291
  if not isinstance(item, dict) or not item.get("contradiction"):
260
292
  continue
@@ -262,18 +294,63 @@ def _llm_contradictions(pairs: list, budget: float, model: str | None) -> list:
262
294
  older, newer = pairs[int(item["pair"]) - 1]
263
295
  except (KeyError, IndexError, ValueError, TypeError):
264
296
  continue
265
- found.append({"issue": "contradicting-candidates",
266
- "pair": [older, newer], "older": older, "newer": newer,
267
- "source": "model", "reason": str(item.get("reason", ""))[:200],
268
- "suggest": "sleep.py supersede %s %s" % (older, newer)})
297
+ # The label follows the pair, not the --tier flag: in `both` mode a T1 finding
298
+ # must not be reported as memory, nor a memory finding as a candidate.
299
+ tier_of_pair = "t2" if (older in mem and newer in mem) else "t1"
300
+ # T2 has no supersede verb: the only honest action on approved memory is a
301
+ # human demote (un-approve) of the record that lost, so the suggestion differs.
302
+ if tier_of_pair == "t2":
303
+ found.append({"issue": "contradicting-memory",
304
+ "pair": [older, newer], "older": older, "newer": newer,
305
+ "source": "model", "reason": str(item.get("reason", ""))[:200],
306
+ "suggest": "sleep.py demote %s" % older})
307
+ else:
308
+ found.append({"issue": "contradicting-candidates",
309
+ "pair": [older, newer], "older": older, "newer": newer,
310
+ "source": "model", "reason": str(item.get("reason", ""))[:200],
311
+ "suggest": "sleep.py supersede %s %s" % (older, newer)})
269
312
  return found
270
313
 
271
314
 
315
+ def _doctor_memory_shortlist(memory_dir: str | None = None) -> list:
316
+ """(id, body, ts) for every active permanent T2 record, the input to candidate_pairs."""
317
+ return store.permanent_records(memory_dir)
318
+
319
+
320
+ def _memory_records(memory_dir: str | None = None) -> dict:
321
+ """id -> (meta, body) for active permanent records, the lookup the adjudicator needs."""
322
+ out = {}
323
+ for cid, body, ts in store.permanent_records(memory_dir):
324
+ out[cid] = ({"id": cid, "ts": ts}, body)
325
+ return out
326
+
327
+
272
328
  def cmd_doctor(a) -> int:
273
329
  issues = store.doctor(needle=a.stale)
274
330
  if getattr(a, "contradictions", False):
275
- pairs = store.candidate_pairs(_doctor_shortlist())
276
- issues += _llm_contradictions(pairs, getattr(a, "budget", 0.25), getattr(a, "model", None))
331
+ tier = getattr(a, "tier", "t1") or "t1"
332
+ mdir = getattr(a, "cwd", None) or None
333
+ records: dict = {}
334
+ memory_ids: set = set()
335
+ if tier == "t2":
336
+ recs = _doctor_memory_shortlist(mdir)
337
+ records = _memory_records(mdir)
338
+ memory_ids = set(records)
339
+ elif tier == "both":
340
+ mem_recs = _doctor_memory_shortlist(mdir)
341
+ records = _memory_records(mdir)
342
+ memory_ids = set(records)
343
+ recs = _doctor_shortlist() + mem_recs
344
+ else:
345
+ recs = _doctor_shortlist()
346
+ # Keep only same-tier pairs: a T1-vs-T2 pair has no single honest action (there is
347
+ # no verb that both supersedes a candidate and un-approves a memory), so asking the
348
+ # model about it would produce a suggestion no command can carry out.
349
+ pairpairs = [p for p in store.candidate_pairs(recs)
350
+ if (_tier_of(p[0], memory_ids) == _tier_of(p[1], memory_ids))]
351
+ issues += _llm_contradictions(pairpairs, getattr(a, "budget", 0.25),
352
+ getattr(a, "model", None), tier=tier,
353
+ records=records, memory_ids=memory_ids)
277
354
  if a.json:
278
355
  _p(json.dumps(issues, indent=2, sort_keys=True, default=str))
279
356
  elif not issues:
@@ -531,6 +608,10 @@ def main(argv=None) -> int:
531
608
  "conflicts (costs budget; report-only, supersedes nothing)")
532
609
  dc.add_argument("--budget", type=float, default=0.25,
533
610
  help="max USD for --contradictions (default 0.25)")
611
+ dc.add_argument("--tier", choices=["t1", "t2", "both"], default="t1",
612
+ help="which tier --contradictions adjudicates: unreviewed "
613
+ "candidates (t1, default), approved permanent memory (t2), "
614
+ "or both")
534
615
  dc.set_defaults(fn=cmd_doctor)
535
616
 
536
617
  rp = sub.add_parser("replay", help="layer 3: A/B measure provisional memory, report-only")
package/sleepkit/store.py CHANGED
@@ -638,6 +638,112 @@ def demote(cid: str, memory_dir: str | None = None, dry_run: bool = False,
638
638
  return True, ("retracted %s" % (slug or cid)
639
639
  + (" (T2 default not found)" if not t2_ok else ""))
640
640
 
641
+ def _first_ref(value) -> str:
642
+ """One id out of a supersede field, which parse() returns as a LIST.
643
+
644
+ store.parse() turns tags/evidence/supersedes/superseded_by into lists, so treating
645
+ the value as a string produced repr text like "['c1']" and every chain walk missed.
646
+ Accepts either shape and takes the first entry.
647
+ """
648
+ if isinstance(value, (list, tuple)):
649
+ return str(value[0]).strip() if value else ""
650
+ return str(value or "").split("|")[0].strip()
651
+
652
+
653
+ def permanent_records(memory_dir: str | None = None) -> list:
654
+ """(id, body, ts) for every ACTIVE permanent (T2) record, the T2 analogue of the
655
+ provisional shortlist input.
656
+
657
+ Retracted files are excluded: a memory a person already un-approved is a decision,
658
+ not an inconsistency to re-report. `id` prefers the frontmatter id and falls back to
659
+ the filename slug, so a hand-written file (no id in frontmatter) is still nameable
660
+ in a finding and actionable with `demote <slug>`.
661
+ """
662
+ mdir = memory_dir or paths.memory_dir()
663
+ out = []
664
+ if not os.path.isdir(mdir):
665
+ return out
666
+ for name in sorted(os.listdir(mdir)):
667
+ if not name.endswith(".md") or name == "MEMORY.md":
668
+ continue
669
+ path = os.path.join(mdir, name)
670
+ try:
671
+ with open(path, encoding="utf-8") as fh:
672
+ meta, body = parse(fh.read())
673
+ except (OSError, ValueError):
674
+ continue
675
+ if meta.get("status") == "retracted":
676
+ continue
677
+ ref = str(meta.get("id") or name[:-3]).strip()
678
+ out.append((ref, body or "", str(meta.get("ts") or meta.get("promoted_at") or "")))
679
+ return out
680
+
681
+
682
+ def _archived_candidates() -> list:
683
+ """Parsed frontmatter of archived candidates (promoted/superseded records live there)."""
684
+ out = []
685
+ d = paths.archive_dir("candidates")
686
+ if not os.path.isdir(d):
687
+ return out
688
+ for name in sorted(os.listdir(d)):
689
+ if not name.endswith(".md"):
690
+ continue
691
+ try:
692
+ with open(os.path.join(d, name), encoding="utf-8") as fh:
693
+ meta, _body = parse(fh.read())
694
+ except (OSError, ValueError):
695
+ continue
696
+ out.append(meta)
697
+ return out
698
+
699
+
700
+ def supersession_chain(cid: str, max_hops: int = 20) -> dict:
701
+ """Walk a record's supersede links in both directions.
702
+
703
+ A supersede writes one pointer on each side, so the *chain* is only visible by
704
+ following them: after three changes, "which record is current?" costs reading files.
705
+ Returns {"order": [oldest..newest], "current": id, "broken": [ids]} - `broken` names
706
+ ids that are referenced but missing from the store, which is how a hand-edited or
707
+ partially archived chain shows up instead of silently reading as a two-record story.
708
+ """
709
+ seen_up, chain = set(), []
710
+ node = cid
711
+ while node and node not in seen_up and len(chain) < max_hops:
712
+ seen_up.add(node)
713
+ chain.append(node)
714
+ got = get_candidate(node)
715
+ if not got:
716
+ break
717
+ node = _first_ref(got[0].get("supersedes"))
718
+ order = list(reversed(chain)) # oldest -> newest
719
+ missing = []
720
+ if order and not get_candidate(order[0]):
721
+ missing.append(order[0])
722
+ # Walk forward from the OLDEST end, not from the requested id: asking about the
723
+ # replaced record must still report what replaced it.
724
+ # Forward walk: follow superseded_by from whatever end we know, always extending the
725
+ # NEWEST side. It is not gated on the seed id (the oldest member has no supersedes and
726
+ # would otherwise stop the walk before it ever looked forward).
727
+ node = order[-1] if order else cid
728
+ seen_down = set(order)
729
+ while node and len(order) < max_hops:
730
+ got = get_candidate(node)
731
+ if not got:
732
+ break
733
+ nxt = _first_ref(got[0].get("superseded_by"))
734
+ if not nxt or nxt in seen_down:
735
+ break
736
+ seen_down.add(nxt)
737
+ if get_candidate(nxt):
738
+ order.append(nxt)
739
+ node = nxt
740
+ else:
741
+ missing.append(nxt)
742
+ break
743
+ current = order[-1] if order else cid
744
+ return {"order": order, "current": current, "broken": missing}
745
+
746
+
641
747
  def supersede(old_id: str, new_id: str) -> bool:
642
748
  """Mark old_id invalid as of now and new_id valid as of now.
643
749
 
@@ -808,6 +914,19 @@ def doctor(memory_dir: str | None = None, targets: list[str] | None = None,
808
914
  # Report the count and the newest ids; nothing is dropped or changed here.
809
915
  # Path assembled without paths.home(): home() creates the whole tier skeleton as a
810
916
  # side effect, and a read-only report that lays down directories is not read-only.
917
+ # A supersede writes a pointer on each side, so a link can dangle: the file was
918
+ # pruned, the archive lost it, or a hand edit dropped it. A dangling link reads as
919
+ # "this record replaced something" while the something is unrecoverable - worth one
920
+ # line, since it is invisible in every other view.
921
+ for c in list_candidates(with_body=False) + _archived_candidates():
922
+ cid = c.get("id")
923
+ if not cid:
924
+ continue
925
+ for field in ("supersedes", "superseded_by"):
926
+ target = _first_ref(c.get(field))
927
+ if target and not get_candidate(target):
928
+ out.append({"issue": "broken-supersede-link", "id": cid,
929
+ "field": field, "missing": target})
811
930
  qdir = os.path.join(paths.SLEEP_HOME, ".quarantine")
812
931
  if os.path.isdir(qdir):
813
932
  parked = sorted(f for f in os.listdir(qdir) if f.endswith(".json"))