pi-sleep-agent 0.8.21 → 0.8.23
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 +34 -4
- package/docs/EVIDENCE.md +130 -8
- package/package.json +1 -1
- package/sleepkit/cli.py +30 -1
- package/sleepkit/consolidate.py +5 -0
- package/sleepkit/paths.py +65 -14
- package/sleepkit/store.py +126 -6
package/README.md
CHANGED
|
@@ -62,7 +62,10 @@ Sleep adds a reviewable memory cycle to nine selectable coding-agent targets. It
|
|
|
62
62
|
- **Kind-aware promotion.** `promote` refuses to make an agent's reading of a *preference*
|
|
63
63
|
permanent: a statement about what you want needs your own words, while a fact, procedure or
|
|
64
64
|
warning is confirmed by the human running `promote` (you read it and chose it). The refusal
|
|
65
|
-
message names which rule stopped it
|
|
65
|
+
message names which rule stopped it and how to answer it: `sleep promote <id>
|
|
66
|
+
--confirmed-by-user` is you saying "yes, I want that", so the record is written with
|
|
67
|
+
`source: user` and the date you confirmed it, and the T1 trace keeps the same receipt. The
|
|
68
|
+
flag answers only the provenance question; the speculative-source check still runs first.
|
|
66
69
|
- **Repeated preference detection.** `mine` finds instructions you gave in multiple sessions without a model call.
|
|
67
70
|
- **Project isolation.** A project's provisional memory is injected only into that project.
|
|
68
71
|
- **Reviewable permanence.** Each approved memory in your index carries its review date and source, so you can tell when a saved instruction was pinned.
|
|
@@ -83,6 +86,7 @@ Sleep adds a reviewable memory cycle to nine selectable coding-agent targets. It
|
|
|
83
86
|
hint a model proposed, so a wrong tag costs a missing filter hit, never a wrong fact.
|
|
84
87
|
- **Served-record accounting.** Every injection stamps the records it actually printed (`injected`, `injected_at` on the record itself), so `doctor` can name a provisional that **no session has ever asked for** in 8+ weeks (`unused-candidate-never-served`). That is a different fact from "nobody re-learned it", and only the record can tell the two apart; report only, nothing is dropped.
|
|
85
88
|
- **Indexed by default.** A long observation is injected as its opening claim plus a pointer (`[+714 chars: sleep.py show <id>]`) instead of its whole narrative; `inject --full` prints the complete bodies. The block states its warning once in the frame and each line carries only its own `source`/`trust`; measured on a live pool: 5581 -> 3377 characters with the index, then 3359 -> **2896** once the per-line frame stopped repeating (~28% of the block had been identical prose).
|
|
89
|
+
- **A queue that is not moving.** Three report lines answer three different questions about a provisional record that has gone quiet: `stale-candidate-unrediscovered` (nobody re-learned it), `unused-candidate-never-served` (nobody ever saw it), and `served-ignored` (sessions carried it and nothing happened - two or more injections with no rediscovery, past half its kind's window). The third one is the stuck-queue shape, and the answer to it is a decision rather than a wait: promote it, refuse it, or say `sleep keep <id>` and name the window you are parking it for. A kept record keeps its status and its body; only the three queue lines stand down, and they come back when the window ends. All three remain report-only.
|
|
86
90
|
- **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).
|
|
87
91
|
- **Safety gates.** Secrets are redacted, hostile text is quarantined, and machine-generated prompts cannot claim user provenance.
|
|
88
92
|
|
|
@@ -363,14 +367,16 @@ Run the two dream components separately when you want more control:
|
|
|
363
367
|
| `./sleep.py sleep --force` | Run consolidation now |
|
|
364
368
|
| `./sleep.py show <id>` | Inspect a candidate and its rendered context |
|
|
365
369
|
| `./sleep.py promote <id>` | Move an approved candidate to permanent memory |
|
|
370
|
+
| `./sleep.py promote <id> --confirmed-by-user` | Promote a *preference* an agent read out of your behaviour, after you have read it and said it is right: the record is written with `source: user` and the date you confirmed it |
|
|
366
371
|
| `./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. Also accepts a permanent record's filename slug or the `id:` it carries, so a memory whose candidate record is gone is still reversible |
|
|
367
372
|
| `./sleep.py refuse <id> --note "..."` | Record that a candidate is incorrect |
|
|
373
|
+
| `./sleep.py keep <id> [--weeks N]` | Park a candidate for N weeks (default 8) without deciding: the record stays provisional and the queue checks (`stale-candidate-unrediscovered`, `unused-candidate-never-served`, `served-ignored`) stop naming it until the window ends. Nothing is dropped and no status changes, because "I have seen this and I am not deciding yet" is a real answer |
|
|
368
374
|
| `./sleep.py replay --run --limit 3` | Compare selected tasks with memory off and on |
|
|
369
375
|
| `./sleep.py status -v` | ... and the last measured memory quality (`3 helps / 1 hurts / 4 ties from 8 samples`, or "no replay measurement has run yet") |
|
|
370
376
|
| `./sleep.py mine --dry-run` | Find preferences repeated across sessions |
|
|
371
377
|
| `./sleep.py nightly --dry-run` | Preview the unattended nightly workflow |
|
|
372
378
|
| `./sleep.py sleep --min-urgency <points>` | Score the hygiene findings and let them waive `--min-interval` (default 2: a growing backlog or a stale candidate clears it, a dangling link does not). `--min-urgency 0` or `--no-doctor-gate` keeps the flat policy, and the record floor (`--min-records`) is never waived |
|
|
373
|
-
| `./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 unrediscovered past their kind's threshold (4 weeks for a fact, 13 for a preference, 8 for a procedure, 52 for a warning; kind and threshold appear in the finding), flag records no session was ever served past their kind's unused threshold (8 / 26 / 12 / 52), flag supersede pointers that name a record no longer in the store, report a T0 buffer larger
|
|
379
|
+
| `./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 unrediscovered past their kind's threshold (4 weeks for a fact, 13 for a preference, 8 for a procedure, 52 for a warning; kind and threshold appear in the finding), flag records no session was ever served past their kind's unused threshold (8 / 26 / 12 / 52), flag records that sessions did carry and then never acted on (`served-ignored`: two or more injections, no rediscovery, and half the kind's stale window gone by - the shape a stuck queue leaves behind), flag supersede pointers that name a record no longer in the store, report a T0 buffer larger
|
|
374
380
|
than the 120-record consolidation window (with the count left outside it), and report records
|
|
375
381
|
parked in quarantine awaiting a human (report only: it never supersedes, drops, merges or un-parks anything itself) |
|
|
376
382
|
| `./sleep.py doctor --stale <value>` | Show which approved records still hold a stale value (e.g. a changed URL) |
|
|
@@ -462,11 +468,12 @@ All runtime data lives under `$SLEEP_HOME`, which defaults to `~/.sleep`:
|
|
|
462
468
|
```text
|
|
463
469
|
buffer/ temporary T0 records
|
|
464
470
|
candidates/ provisional T1 records
|
|
471
|
+
memory/ permanent T2 memory: one file per record plus its MEMORY.md index
|
|
465
472
|
reports/ replay reports
|
|
466
473
|
logs/ hook and nightly logs
|
|
467
474
|
.quarantine/ rejected unsafe input
|
|
468
475
|
state.json sleep and replay timestamps, and the last measured memory-quality summary
|
|
469
|
-
env optional scheduled-run environment
|
|
476
|
+
env optional scheduled-run environment (also where SLEEP_MEMORY_DIR is read from)
|
|
470
477
|
```
|
|
471
478
|
|
|
472
479
|
Useful logs:
|
|
@@ -483,6 +490,29 @@ Use another home for testing or for a separate memory pool:
|
|
|
483
490
|
SLEEP_HOME=/tmp/my-sleep ./sleep.py status -v
|
|
484
491
|
```
|
|
485
492
|
|
|
493
|
+
### Where permanent memory is written
|
|
494
|
+
|
|
495
|
+
T2 lives in one fixed place: `$SLEEP_HOME/memory` (`~/.sleep/memory` by default).
|
|
496
|
+
It is sleep's own store and not a host's project memory, so it does not move with the
|
|
497
|
+
directory a hook happened to run in and it cannot collide with the agent host's own
|
|
498
|
+
memory files. `status` prints the path it resolved, on the `T2 canonical` line.
|
|
499
|
+
|
|
500
|
+
`SLEEP_MEMORY_DIR` overrides it. Set it in `~/.sleep/env` for a scheduled run that
|
|
501
|
+
has no shell of its own:
|
|
502
|
+
|
|
503
|
+
```text
|
|
504
|
+
SLEEP_MEMORY_DIR=/path/to/another/store
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
The two keys sleep reads from that file are `SLEEP_MEMORY_DIR` and `SLEEP_MODEL`;
|
|
508
|
+
a value exported in the environment always wins over the file. Every `promote` and
|
|
509
|
+
`demote` names the store it wrote, so a pass that landed somewhere unexpected says so
|
|
510
|
+
rather than looking successful.
|
|
511
|
+
|
|
512
|
+
An install that predates this keeps reading the project memory directory its records
|
|
513
|
+
actually sit in, because a store has an external reader worth more than a tidy path.
|
|
514
|
+
Run `./sleep.py status` to see which one is in force before moving records by hand.
|
|
515
|
+
|
|
486
516
|
## Troubleshooting
|
|
487
517
|
|
|
488
518
|
**Nothing was captured**
|
|
@@ -506,7 +536,7 @@ Use `--force` only when you intentionally want a model call.
|
|
|
506
536
|
|
|
507
537
|
**The scheduled pass cannot reach the model**
|
|
508
538
|
|
|
509
|
-
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).
|
|
539
|
+
Confirm that `~/.sleep/env` exists, has mode `0600`, and contains the same provider settings used by your interactive shell. A `SLEEP_MEMORY_DIR` line in that same file is honoured by scheduled runs; see [Where permanent memory is written](#where-permanent-memory-is-written). Then run `./sleep.py sleep --force` before relying on the scheduled pass (launchd / cron / Task Scheduler).
|
|
510
540
|
|
|
511
541
|
**A candidate appears in the wrong context**
|
|
512
542
|
|
package/docs/EVIDENCE.md
CHANGED
|
@@ -7,14 +7,12 @@ ever exercised.
|
|
|
7
7
|
|
|
8
8
|
## Ran
|
|
9
9
|
|
|
10
|
-
**Unit tests.** `
|
|
11
|
-
`tests/test_core.py` (hook parsing, the proposal parser, the gate arithmetic,
|
|
12
|
-
|
|
13
|
-
`tests/test_cli.py`, where every call is a real
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
asserts a promoted file carries the memory text and not only frontmatter, one asserts the index is copied
|
|
17
|
-
before it is rewritten. Both were checked load-bearing: with the fix removed, each one fails.
|
|
10
|
+
**Unit tests.** `npm run validate` -> `Ran 261 tests ... OK` (plus `ruff` clean and the package
|
|
11
|
+
smoke): 87 in-process tests in `tests/test_core.py` (hook parsing, the proposal parser, the gate arithmetic,
|
|
12
|
+
the provenance ceiling, redaction, the kind-lifetime floor, and the answer scorer's verdict branches) plus 174
|
|
13
|
+
in `tests/test_cli.py`, where every call is a real subprocess of `sleep.py`, `tools/wire.py`, `install.sh` or
|
|
14
|
+
`uninstall.sh` against a throwaway `$SLEEP_HOME`. No test reaches the network or a model. The counts in this
|
|
15
|
+
paragraph are the ones the run above printed; when they disagree with the suite, the suite is right.
|
|
18
16
|
|
|
19
17
|
**One real sleep cycle, end to end** (`~/.sleep/reports/2026-10-31-163914-replay.md`; the report filename
|
|
20
18
|
format is `<utc>-replay.md`, the `A` in a filename like `...-16A-replay.md` in an older note was my mistake):
|
|
@@ -395,6 +393,24 @@ records and hit sentences that merely mention a constant. End-anchoring it - a p
|
|
|
395
393
|
back - dropped the count to 17 and, on a hand-built set, kept 6/6 probe phrasings flagged and 4/4 human phrasings
|
|
396
394
|
clean, including `never return MEMORY.md as a raw string, parse it first`.
|
|
397
395
|
|
|
396
|
+
|
|
397
|
+
**T2 happened to be the wrong directory, and one env line was a no-op** (2026-11-06). Two defects with the
|
|
398
|
+
same shape: a stored path that nothing checked and a documented key that nothing read. Measured on this laptop:
|
|
399
|
+
|
|
400
|
+
| claim | measurement |
|
|
401
|
+
|---|---|
|
|
402
|
+
| the project key sleep built was never the one Claude Code builds | sleep's rule kept `.` and `-` (`Users-yunus.aydin-Research-sleep`, no such directory) while the host's own key folded the dot (`-Users-yunus-aydin-Research-sleep`), so resolution fell through to a hard-coded fallback on every call |
|
|
403
|
+
| where T2 actually was | `~/.claude-work/projects/-Users-yunus-aydin/memory`, 107 records, shared with the host's own project memory |
|
|
404
|
+
| a `SLEEP_MEMORY_DIR` line in `~/.sleep/env` | read by nothing that decided a path: `llm.auth_env()` only ever passed the file to `subprocess.run(env=...)`, so `paths.memory_dir()` used its fallback instead |
|
|
405
|
+
| the fixed location after the change | `./sleep.py status` prints `T2 canonical /Users/yunus.aydin/.sleep/memory (11 permanent records)` |
|
|
406
|
+
| the env line after the change | in a throwaway `SLEEP_HOME`, a `promote` with `SLEEP_MEMORY_DIR` only in the env file wrote `<from-file>/the-staging-gateway-needs-a-ten-minute-timeout.md` and created nothing under the fallback |
|
|
407
|
+
| precedence | the same `promote` with the value exported in the environment used the exported store and never created the file's |
|
|
408
|
+
|
|
409
|
+
Eleven records that `confirmed_by` or `promoted_at` shows were written by this tool were copied to the new
|
|
410
|
+
store; the old directory was left intact and no file was deleted. `promote` and `demote` already printed the
|
|
411
|
+
path they wrote, which is what makes a pass that lands somewhere unexpected detectable rather than silent.
|
|
412
|
+
|
|
413
|
+
|
|
398
414
|
## Did not run
|
|
399
415
|
|
|
400
416
|
- **Compaction triggered by size.** Three measurements, and none of them is a proof of the reprint path:
|
|
@@ -698,3 +714,109 @@ Pinned by `tests/test_cli.py::InstallUninstall`
|
|
|
698
714
|
`test_mac_scheduler_reports_a_bootstrap_that_registers_nothing`). The fakes hold jobs in
|
|
699
715
|
a state file, so the read-back is a real second call and not a restatement of the first,
|
|
700
716
|
and the second test fails if "loaded" is ever printed on the strength of an exit code.
|
|
717
|
+
|
|
718
|
+
|
|
719
|
+
## 2026-11-06: the queue knew it was stuck and could not say so
|
|
720
|
+
|
|
721
|
+
`~/.sleep` on this machine held 11 provisional candidates, every one of them
|
|
722
|
+
`injected: 2`, none of them with a `rediscovered` count, and not one promoted or
|
|
723
|
+
refused. `doctor --json` returned a single line (`quarantine-awaiting-review (1)`).
|
|
724
|
+
The band those 11 were sitting in had no name in the report at all.
|
|
725
|
+
|
|
726
|
+
The reason is structural. The stale check keys on `last = rediscovered_at or ts`
|
|
727
|
+
(`store.py:1221`), and the unused check requires `served == 0` where
|
|
728
|
+
`served = injected + rediscovered` (`store.py:1237`). A record that entered two
|
|
729
|
+
sessions' contexts and changed nothing is invisible to both: too young for one,
|
|
730
|
+
too served for the other.
|
|
731
|
+
|
|
732
|
+
The new line, `served-ignored`, is the missing third question: has anything happened
|
|
733
|
+
since this entered a context at all. `MIN_SERVED_IGNORED = 2` (one injection can be a
|
|
734
|
+
session that ended before it read anything, which is not evidence about the record),
|
|
735
|
+
`rediscovered == 0`, and half the record's own stale window gone by.
|
|
736
|
+
|
|
737
|
+
Measured in a throwaway `SLEEP_HOME` (the live store was not touched):
|
|
738
|
+
|
|
739
|
+
| state | doctor |
|
|
740
|
+
|---|---|
|
|
741
|
+
| 11 candidates, never injected, fresh | `[]` |
|
|
742
|
+
| 11 candidates, `injected=2`, 25 days old | `[]` (a preference's half-window is 45.5 days) |
|
|
743
|
+
| 11 candidates, `injected=2`, 60 days old | `served-ignored x11` |
|
|
744
|
+
|
|
745
|
+
One row of the third case:
|
|
746
|
+
|
|
747
|
+
{"age_days": 59, "id": "c17939463163db0", "injected": 2,
|
|
748
|
+
"issue": "served-ignored", "kind": "preference", "rediscovered": 0,
|
|
749
|
+
"threshold_weeks": 6.5}
|
|
750
|
+
|
|
751
|
+
and its score, through the gate that shipped in 0.8.20:
|
|
752
|
+
|
|
753
|
+
urgency(doctor()) -> (22, 'served-ignored (+22; served-ignored x11)')
|
|
754
|
+
|
|
755
|
+
The floor still holds: with an empty buffer the same run returns
|
|
756
|
+
`reason: buffer has 0 record(s), needs 3` while carrying `urgency: 22`.
|
|
757
|
+
|
|
758
|
+
`sleep keep <id> [--weeks N]` is the answer half. It writes `kept`/`kept_until` into
|
|
759
|
+
the record's own frontmatter and the three queue checks stand down for the window;
|
|
760
|
+
nothing is dropped and the status stays `provisional`, because "I have seen this and
|
|
761
|
+
I am not deciding yet" was previously inexpressible except by promoting the record
|
|
762
|
+
(a lie about its status) or editing the file by hand.
|
|
763
|
+
|
|
764
|
+
$ ./sleep.py keep c17939463163db0 --weeks 8
|
|
765
|
+
KEPT kept c17939463163db0 until 2027-01-01 (56 day(s))
|
|
766
|
+
# doctor: served-ignored x11 -> x10
|
|
767
|
+
# window expired by hand -> x11 again, is_kept(meta) False
|
|
768
|
+
|
|
769
|
+
Pinned by `tests/test_core.py::T` (`test_a_served_candidate_nobody_acted_on_is_named`,
|
|
770
|
+
`test_one_injection_is_not_yet_evidence_about_the_record`,
|
|
771
|
+
`test_a_rediscovered_record_is_not_served_ignored`,
|
|
772
|
+
`test_keep_parks_a_record_and_the_window_expires`,
|
|
773
|
+
`test_keep_refuses_a_record_that_is_not_provisional`) and
|
|
774
|
+
`tests/test_cli.py::Gates` (`test_keep_parks_a_candidate_and_the_doctor_stops_naming_it`,
|
|
775
|
+
`test_keep_refuses_a_candidate_that_is_not_provisional`).
|
|
776
|
+
|
|
777
|
+
## 2026-11-06: a refusal that had no way to be answered
|
|
778
|
+
|
|
779
|
+
`promote` refuses a preference whose `source` is not `user`, on the reasoning that a
|
|
780
|
+
statement about what the person wants needs the person's own words. That rule is right
|
|
781
|
+
and it had no door: the person reading the record and saying "yes, that is what I want"
|
|
782
|
+
could not act on it, so a correct instruction an agent had read out of their behaviour
|
|
783
|
+
stayed provisional forever, or got promoted after somebody edited the file by hand.
|
|
784
|
+
|
|
785
|
+
Two records on this machine sat in exactly that state (`c179355873180e3`, an agent's
|
|
786
|
+
reading that "pushla" means work is not done until it is pushed; `c17936420749fd5`, that
|
|
787
|
+
model references need their provider prefix). The person read both and confirmed both.
|
|
788
|
+
|
|
789
|
+
### What was added
|
|
790
|
+
|
|
791
|
+
`sleep promote <id> --confirmed-by-user` -> `store.promote(..., confirmed=True)`.
|
|
792
|
+
|
|
793
|
+
The flag is the first of the two questions answered in the room. The kind check asks *did
|
|
794
|
+
the person say this*; the trust check asks *was it verified*. Confirmation answers the
|
|
795
|
+
first and deliberately not the second, so the speculative-source refusal still runs on the
|
|
796
|
+
same call. When it passes:
|
|
797
|
+
|
|
798
|
+
- the record is written with `source: user` (which is the fact the refusal was about), plus
|
|
799
|
+
`confirmed_by: user` and `confirmed_at`, so a memory that says "the user wants X" can
|
|
800
|
+
show who said so and when;
|
|
801
|
+
- the T1 trace in `archive/candidates/` carries the same three fields, because the record
|
|
802
|
+
that says the user confirmed it must not leave behind a trace saying an agent read it;
|
|
803
|
+
- the refusal message now names the flag, so the rule is answerable from the output rather
|
|
804
|
+
than from reading `store.py`.
|
|
805
|
+
|
|
806
|
+
### Measured (temporary `SLEEP_HOME`, agent-sourced preference, trust=observed)
|
|
807
|
+
|
|
808
|
+
| call | result |
|
|
809
|
+
|---|---|
|
|
810
|
+
| `promote cid` | refused, message names `--confirmed-by-user` |
|
|
811
|
+
| `promote cid --confirmed-by-user` | promoted, T2 frontmatter `source: user`, `confirmed_by: user`, `confirmed_at` set |
|
|
812
|
+
| T1 archive after that call | `source: user`, `confirmed_by: user`, `confirmed_at` set |
|
|
813
|
+
| `promote cid --confirmed-by-user`, trust=speculative | still refused, "refusing to persist speculative memory" |
|
|
814
|
+
|
|
815
|
+
Tests: `test_an_agent_sourced_preference_needs_the_users_own_confirmation` and
|
|
816
|
+
`test_confirmation_does_not_launder_a_speculative_record` in `tests/test_cli.py`.
|
|
817
|
+
|
|
818
|
+
### What this does not do
|
|
819
|
+
|
|
820
|
+
The flag does not make an agent's reading true. It records that a person read one and
|
|
821
|
+
agreed, which is the only thing that can make it permanent, and the receipt is on the
|
|
822
|
+
record. A later reader who doubts the memory can see that a human confirmed it and when.
|
package/package.json
CHANGED
package/sleepkit/cli.py
CHANGED
|
@@ -182,7 +182,10 @@ def cmd_show(a) -> int:
|
|
|
182
182
|
|
|
183
183
|
|
|
184
184
|
def cmd_promote(a) -> int:
|
|
185
|
-
|
|
185
|
+
"""`--confirmed-by-user` is the person's own answer to "did you say this?", which is
|
|
186
|
+
the one thing an agent-sourced preference cannot answer for itself."""
|
|
187
|
+
ok, out = store.promote(a.id, memory_dir=a.memory_dir, dry_run=a.dry_run,
|
|
188
|
+
confirmed=getattr(a, "confirmed", False))
|
|
186
189
|
_p(("PROMOTED " if ok else "REFUSED ") + out)
|
|
187
190
|
return 0 if ok else 3
|
|
188
191
|
|
|
@@ -203,6 +206,16 @@ def cmd_refuse(a) -> int:
|
|
|
203
206
|
return 0 if ok else 3
|
|
204
207
|
|
|
205
208
|
|
|
209
|
+
def cmd_keep(a) -> int:
|
|
210
|
+
"""Park a candidate deliberately. The record stays provisional; the queue checks
|
|
211
|
+
stop naming it until the window ends. Nothing is dropped and no status changes,
|
|
212
|
+
because "I have seen this and I am not deciding yet" is a real answer and there
|
|
213
|
+
was no way to say it."""
|
|
214
|
+
ok, out = store.keep_candidate(a.candidate_id, weeks=a.weeks)
|
|
215
|
+
_p(("KEPT " if ok else "REFUSED ") + out)
|
|
216
|
+
return 0 if ok else 3
|
|
217
|
+
|
|
218
|
+
|
|
206
219
|
def cmd_supersede(a) -> int:
|
|
207
220
|
ok = store.supersede(a.old_id, a.new_id)
|
|
208
221
|
_p("superseded" if ok else "REFUSED (bad id)")
|
|
@@ -702,6 +715,9 @@ def main(argv=None) -> int:
|
|
|
702
715
|
pr.add_argument("id")
|
|
703
716
|
pr.add_argument("--memory-dir")
|
|
704
717
|
pr.add_argument("--dry-run", action="store_true")
|
|
718
|
+
pr.add_argument("--confirmed-by-user", dest="confirmed", action="store_true",
|
|
719
|
+
help="the user read this record and confirmed it; answers the "
|
|
720
|
+
"user-provenance refusal for an agent-sourced preference")
|
|
705
721
|
pr.set_defaults(fn=cmd_promote)
|
|
706
722
|
|
|
707
723
|
dm = sub.add_parser("demote", help="un-approve a promoted memory (T2 -> refused, marked not deleted)")
|
|
@@ -716,6 +732,11 @@ def main(argv=None) -> int:
|
|
|
716
732
|
rf.add_argument("--note", default="")
|
|
717
733
|
rf.set_defaults(fn=cmd_refuse)
|
|
718
734
|
|
|
735
|
+
kp = sub.add_parser("keep", help="park a candidate for N weeks without deciding")
|
|
736
|
+
kp.add_argument("candidate_id")
|
|
737
|
+
kp.add_argument("--weeks", type=float, default=8.0)
|
|
738
|
+
kp.set_defaults(fn=cmd_keep)
|
|
739
|
+
|
|
719
740
|
su = sub.add_parser("supersede", help="mark old candidate superseded by new")
|
|
720
741
|
su.add_argument("old_id")
|
|
721
742
|
su.add_argument("new_id")
|
|
@@ -807,6 +828,14 @@ def main(argv=None) -> int:
|
|
|
807
828
|
ij.set_defaults(fn=cmd_inject)
|
|
808
829
|
|
|
809
830
|
a = ap.parse_args(argv)
|
|
831
|
+
# The env file carries what an unattended run needs and the shell did not export.
|
|
832
|
+
# Only the two keys memory_dir() itself reads are adopted here: a headless pass has
|
|
833
|
+
# no interactive shell to set them, and reading that file for the model transport
|
|
834
|
+
# alone (llm.auth_env) left SLEEP_MEMORY_DIR a silent no-op. The real environment
|
|
835
|
+
# still wins, so a one-off shell or a test is never overridden by a stale value.
|
|
836
|
+
for k, v in llm.env_overrides(paths.env_file()).items():
|
|
837
|
+
if k in ("SLEEP_MEMORY_DIR", "SLEEP_MODEL"):
|
|
838
|
+
os.environ.setdefault(k, v)
|
|
810
839
|
if hasattr(a, "model"):
|
|
811
840
|
a.model = llm.resolve_model(getattr(a, "model", None))
|
|
812
841
|
paths.home()
|
package/sleepkit/consolidate.py
CHANGED
|
@@ -468,6 +468,10 @@ def hours_since(ts):
|
|
|
468
468
|
# near-duplicate-candidates 1
|
|
469
469
|
# candidate-duplicates-memory 1
|
|
470
470
|
# stale-value-in-memory 1
|
|
471
|
+
# served-ignored 2 this is the stuck-queue shape: the record
|
|
472
|
+
# already entered sessions and changed nothing,
|
|
473
|
+
# and it is the one state where a pass can make
|
|
474
|
+
# progress (a promote, a drop, or a keep)
|
|
471
475
|
#
|
|
472
476
|
# Everything else (duplicate-heading-in-file and any future issue) weighs 0 on
|
|
473
477
|
# purpose: a new finding must be given a weight deliberately, and an unknown one must
|
|
@@ -476,6 +480,7 @@ URGENCY_WEIGHTS = {
|
|
|
476
480
|
"buffer-exceeds-consolidation-window": (3, "the backlog grows until a pass runs"),
|
|
477
481
|
"stale-candidate-unrediscovered": (2, "unconfirmed memory is still served as context"),
|
|
478
482
|
"unused-candidate-never-served": (2, "a record no session was ever served"),
|
|
483
|
+
"served-ignored": (2, "a record sessions carried and never acted on"),
|
|
479
484
|
"broken-supersede-link": (1, "a link dangles but does not grow"),
|
|
480
485
|
"quarantine-awaiting-review": (1, "needs a person, not a pass"),
|
|
481
486
|
"contradicting-candidates": (1, "the pass can surface it, only a person can settle it"),
|
package/sleepkit/paths.py
CHANGED
|
@@ -60,25 +60,76 @@ def env_file() -> str:
|
|
|
60
60
|
|
|
61
61
|
|
|
62
62
|
# --- memory repo resolution ------------------------------------------------
|
|
63
|
-
#
|
|
64
|
-
#
|
|
65
|
-
#
|
|
63
|
+
# T2 is sleep's own store, not a host's project memory. The host's own store is
|
|
64
|
+
# written under its own rule, and the writer here could not know a store's rule
|
|
65
|
+
# ahead of a switch on an unset var in an env file, so the directory it picked was
|
|
66
|
+
# always the fallback; it also gave one path a store that named another. T2 therefore
|
|
67
|
+
# has one home of its own. It used to be the project memory directory of whichever
|
|
68
|
+
# agent cwd was current, and that directory is NOT written to any more: promote
|
|
69
|
+
# creates its target if it is missing, so the location must not depend on which
|
|
70
|
+
# project a hook happened to run in.
|
|
66
71
|
|
|
67
|
-
|
|
72
|
+
SLEEP_MEMORY_ENV = "SLEEP_MEMORY_DIR"
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def memory_dir_home() -> str:
|
|
76
|
+
return os.path.join(home(), "memory")
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def memory_dir_env() -> str | None:
|
|
80
|
+
"""The one override that is honoured, read from the process environment (and
|
|
81
|
+
adopted from the env file by the CLI before any command runs)."""
|
|
82
|
+
value = (os.environ.get(SLEEP_MEMORY_ENV) or "").strip()
|
|
83
|
+
return os.path.expanduser(value) if value else None
|
|
68
84
|
|
|
69
85
|
|
|
70
86
|
def memory_dir(cwd: str | None = None) -> str:
|
|
71
|
-
|
|
87
|
+
"""Where T2 lives: the override, else sleep's own home, else what already exists.
|
|
88
|
+
|
|
89
|
+
``cwd`` is kept in the signature because callers still pass it, and it stays
|
|
90
|
+
meaningful only for the last branch: an install that has been running since
|
|
91
|
+
before this change keeps reading the project memory directory its records
|
|
92
|
+
actually sit in, instead of one that reads empty and looks like data loss. A
|
|
93
|
+
directory that has never been written to therefore resolves to sleep's own home
|
|
94
|
+
and not to a path built from the caller's cwd. Callers that must inspect a
|
|
95
|
+
*specific* store keep passing it explicitly (store.* all take memory_dir=...).
|
|
96
|
+
"""
|
|
97
|
+
env = memory_dir_env()
|
|
72
98
|
if env:
|
|
73
|
-
return
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
99
|
+
return env
|
|
100
|
+
ours = memory_dir_home()
|
|
101
|
+
if os.path.isdir(ours) and any(fn.endswith(".md") for fn in os.listdir(ours)):
|
|
102
|
+
return ours
|
|
103
|
+
legacy = _legacy_project_memory_dir(cwd)
|
|
104
|
+
if legacy:
|
|
105
|
+
return legacy
|
|
106
|
+
return ours
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def _legacy_project_memory_dir(cwd: str | None) -> str | None:
|
|
110
|
+
"""The pre-0.8.23 location, only when it actually holds records.
|
|
111
|
+
|
|
112
|
+
Reads the old project key so records promoted before the move are still found;
|
|
113
|
+
returns None (so the caller keeps sleep's own home) when nothing with a body is
|
|
114
|
+
there.
|
|
115
|
+
"""
|
|
116
|
+
base = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.expanduser("~/.claude-work")
|
|
117
|
+
cands = []
|
|
118
|
+
if cwd:
|
|
119
|
+
cands.append(os.path.join(base, "projects", _project_key(cwd), "memory"))
|
|
120
|
+
cands.append(os.path.join(base, "projects", _project_key(os.getcwd()), "memory"))
|
|
121
|
+
for cand in cands:
|
|
122
|
+
try:
|
|
123
|
+
names = os.listdir(cand)
|
|
124
|
+
except OSError:
|
|
125
|
+
continue
|
|
126
|
+
if any(fn.endswith(".md") and fn != "MEMORY.md" for fn in names):
|
|
127
|
+
return cand
|
|
128
|
+
return None
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def _project_key(cwd: str) -> str:
|
|
132
|
+
return re.sub(r"[^A-Za-z0-9._-]", "-", os.path.abspath(cwd)).strip("-")
|
|
82
133
|
|
|
83
134
|
|
|
84
135
|
def new_id(prefix: str = "s") -> str:
|
package/sleepkit/store.py
CHANGED
|
@@ -17,7 +17,7 @@ import os
|
|
|
17
17
|
import re
|
|
18
18
|
import shutil
|
|
19
19
|
import time
|
|
20
|
-
from datetime import datetime
|
|
20
|
+
from datetime import datetime, timedelta
|
|
21
21
|
|
|
22
22
|
from . import paths, safety
|
|
23
23
|
|
|
@@ -33,6 +33,12 @@ STALE_CANDIDATE_WEEKS = 4.0
|
|
|
33
33
|
# with things that were never useful. Report only, like every other doctor line.
|
|
34
34
|
UNUSED_CANDIDATE_WEEKS = 8.0
|
|
35
35
|
|
|
36
|
+
# How many injections are enough to call a record served-and-ignored. Two, not one:
|
|
37
|
+
# a single injection can be a session that ended before it read anything, which is
|
|
38
|
+
# not evidence about the record. Two independent sessions carrying it and changing
|
|
39
|
+
# nothing is.
|
|
40
|
+
MIN_SERVED_IGNORED = 2
|
|
41
|
+
|
|
36
42
|
# What the two constants above are a default FOR. A record's kind is not decoration:
|
|
37
43
|
# a warning that nobody re-learned in a month is not the same debt as a preference
|
|
38
44
|
# nobody re-learned in a month, and the flat constants made the four kinds behave
|
|
@@ -58,6 +64,27 @@ KIND_LIFETIME_WEEKS = {
|
|
|
58
64
|
}
|
|
59
65
|
|
|
60
66
|
|
|
67
|
+
def is_kept(meta: dict) -> bool:
|
|
68
|
+
"""True while a person's `keep` on this record still holds.
|
|
69
|
+
|
|
70
|
+
`sleep keep` exists because "leave this here" was not expressible: the only way to
|
|
71
|
+
stop the queue checks naming a record was to promote it (a lie about its status) or
|
|
72
|
+
to edit the file by hand. A kept record is skipped by those checks until its
|
|
73
|
+
`kept_until` passes; nothing is dropped, and the record stays provisional.
|
|
74
|
+
"""
|
|
75
|
+
until = str(meta.get("kept_until", "") or "").strip()
|
|
76
|
+
if not until:
|
|
77
|
+
return False
|
|
78
|
+
if not str(meta.get("kept", "") or "").strip():
|
|
79
|
+
return False
|
|
80
|
+
try:
|
|
81
|
+
end = datetime.strptime(until, "%Y-%m-%d")
|
|
82
|
+
except ValueError:
|
|
83
|
+
return False
|
|
84
|
+
now = datetime.strptime(paths.now()[:10], "%Y-%m-%d")
|
|
85
|
+
return now < end
|
|
86
|
+
|
|
87
|
+
|
|
61
88
|
def lifetime_for(kind: str, default_weeks: float = 0.0) -> tuple[float, float, str]:
|
|
62
89
|
"""(stale_weeks, unused_weeks, kind) for one record's kind.
|
|
63
90
|
|
|
@@ -343,6 +370,48 @@ def _record_rediscovery(cid: str, session: str) -> str | None:
|
|
|
343
370
|
cid, n, cid)
|
|
344
371
|
|
|
345
372
|
|
|
373
|
+
def keep_candidate(cid: str, weeks: float = 8.0) -> tuple[bool, str]:
|
|
374
|
+
"""Mark a provisional record as deliberately parked for `weeks`.
|
|
375
|
+
|
|
376
|
+
Writes `kept`/`kept_until` into the record's own frontmatter, which is where the
|
|
377
|
+
doctor reads them: the decision lives next to the fact it is about, and it survives
|
|
378
|
+
a restart in a way a flag file would not. Nothing else about the record changes -
|
|
379
|
+
same body, same status, same queue - so the checks simply stop naming it until the
|
|
380
|
+
window ends, after which it is judged again as if nothing had happened.
|
|
381
|
+
"""
|
|
382
|
+
got = get_candidate(cid)
|
|
383
|
+
if not got:
|
|
384
|
+
return False, "no such candidate: %s" % cid
|
|
385
|
+
meta, body = got
|
|
386
|
+
if meta.get("status") != "provisional":
|
|
387
|
+
return False, "%s is %s, not provisional" % (cid, meta.get("status"))
|
|
388
|
+
try:
|
|
389
|
+
days = max(1, int(round(float(weeks) * 7)))
|
|
390
|
+
except (TypeError, ValueError):
|
|
391
|
+
return False, "weeks must be a number"
|
|
392
|
+
now = paths.now()[:10]
|
|
393
|
+
until = _date_plus_days(now, days)
|
|
394
|
+
meta["kept"] = now
|
|
395
|
+
meta["kept_until"] = until
|
|
396
|
+
loc = paths.candidates_dir()
|
|
397
|
+
if not os.path.isfile(os.path.join(loc, cid + ".md")):
|
|
398
|
+
p = os.path.join(paths.archive_dir("candidates"), cid + ".md")
|
|
399
|
+
if os.path.isfile(p):
|
|
400
|
+
loc = paths.archive_dir("candidates")
|
|
401
|
+
try:
|
|
402
|
+
with open(os.path.join(loc, cid + ".md"), "w", encoding="utf-8") as fh:
|
|
403
|
+
fh.write(emit(meta, body))
|
|
404
|
+
except OSError as exc:
|
|
405
|
+
return False, "could not write %s: %s" % (cid, exc)
|
|
406
|
+
return True, "kept %s until %s (%d day(s))" % (cid, until, days)
|
|
407
|
+
|
|
408
|
+
|
|
409
|
+
def _date_plus_days(day: str, days: int) -> str:
|
|
410
|
+
"""`day` (YYYY-MM-DD) plus `days`, as a plain calendar date."""
|
|
411
|
+
base = datetime.strptime(day, "%Y-%m-%d")
|
|
412
|
+
return (base + timedelta(days=days)).strftime("%Y-%m-%d")
|
|
413
|
+
|
|
414
|
+
|
|
346
415
|
def record_injection(ids: list[str]) -> int:
|
|
347
416
|
"""Stamp `injected`/`injected_at` on the records a session's context just carried.
|
|
348
417
|
|
|
@@ -518,8 +587,17 @@ def slugify(text: str, maxlen: int = 48) -> str:
|
|
|
518
587
|
KIND_PROMOTE_NEEDS_USER = ("preference",)
|
|
519
588
|
|
|
520
589
|
|
|
521
|
-
def promote(cid: str, memory_dir: str | None = None, dry_run: bool = False
|
|
522
|
-
|
|
590
|
+
def promote(cid: str, memory_dir: str | None = None, dry_run: bool = False,
|
|
591
|
+
confirmed: bool = False) -> tuple[bool, str]:
|
|
592
|
+
"""T1 -> T2. Explicit human act. Creates a NEW file, never edits one.
|
|
593
|
+
|
|
594
|
+
A preference captured from an agent is an agent's READING of what the user wants,
|
|
595
|
+
and the rule above refuses it. The kind check asks whether the person said it;
|
|
596
|
+
the trust check asks whether it was verified. `confirmed=True` is the first
|
|
597
|
+
question answered in the room: the person read this body and said yes, so the
|
|
598
|
+
source becomes `user` and the record carries when that happened, because a
|
|
599
|
+
memory that says "the user wants X" must be able to show who said so. It does
|
|
600
|
+
not answer the second question, which is why the trust check still runs."""
|
|
523
601
|
got = get_candidate(cid)
|
|
524
602
|
if not got:
|
|
525
603
|
return False, "no such candidate: " + cid
|
|
@@ -531,10 +609,18 @@ def promote(cid: str, memory_dir: str | None = None, dry_run: bool = False) -> t
|
|
|
531
609
|
return False, ("refusing to persist speculative memory from source=%s; "
|
|
532
610
|
"re-record with the user's own words or run a replay first" % src)
|
|
533
611
|
kind = str(meta.get("kind", "") or "")
|
|
534
|
-
if kind in KIND_PROMOTE_NEEDS_USER and src != "user":
|
|
612
|
+
if kind in KIND_PROMOTE_NEEDS_USER and src != "user" and not confirmed:
|
|
535
613
|
return False, ("refusing to persist a %s from source=%s: a statement about what "
|
|
536
614
|
"the user wants needs the user's own words, not an agent's reading "
|
|
537
|
-
"of them
|
|
615
|
+
"of them. If the user read this record and confirmed it, re-run with "
|
|
616
|
+
"--confirmed-by-user" % (kind, src))
|
|
617
|
+
if confirmed:
|
|
618
|
+
# Only what the refusal was about: the provenance of a claim about the person.
|
|
619
|
+
# trust is untouched, so a speculative record is still refused one line above.
|
|
620
|
+
src = "user"
|
|
621
|
+
meta["source"] = "user"
|
|
622
|
+
meta["confirmed_by"] = "user"
|
|
623
|
+
meta["confirmed_at"] = paths.now()
|
|
538
624
|
mdir = memory_dir or paths.memory_dir()
|
|
539
625
|
name = "%s.md" % slugify(body.split(".")[0][:60] or cid)
|
|
540
626
|
dest = os.path.join(mdir, name)
|
|
@@ -563,7 +649,14 @@ def promote(cid: str, memory_dir: str | None = None, dry_run: bool = False) -> t
|
|
|
563
649
|
with open(dest, "w", encoding="utf-8") as fh:
|
|
564
650
|
fh.write(emit(out_meta, body))
|
|
565
651
|
ok, why = append_index_line(mdir, line)
|
|
566
|
-
|
|
652
|
+
# `confirmed` rewrote meta in memory; the T1 copy has to record that too, or the
|
|
653
|
+
# record that says "the user confirmed this" leaves behind a trace saying an agent
|
|
654
|
+
# read it. set_status merges the extras over the stored frontmatter for this.
|
|
655
|
+
extra = {"promoted_to": dest, "promoted_at": paths.now()}
|
|
656
|
+
if confirmed:
|
|
657
|
+
extra.update({"source": "user", "confirmed_by": "user",
|
|
658
|
+
"confirmed_at": meta.get("confirmed_at")})
|
|
659
|
+
set_status(cid, "promoted", extra)
|
|
567
660
|
shutil.move(os.path.join(paths.candidates_dir(), cid + ".md"),
|
|
568
661
|
os.path.join(paths.archive_dir("candidates"), cid + ".md"))
|
|
569
662
|
return True, "wrote %s; index %s" % (dest, why)
|
|
@@ -1211,6 +1304,11 @@ def doctor(memory_dir: str | None = None, targets: list[str] | None = None,
|
|
|
1211
1304
|
for c in list_candidates():
|
|
1212
1305
|
if c.get("status") != "provisional":
|
|
1213
1306
|
continue
|
|
1307
|
+
if is_kept(c):
|
|
1308
|
+
# The person looked at this record and said "leave it alone". A deliberate
|
|
1309
|
+
# wait is not a smell, so the three queue checks below all stand down for
|
|
1310
|
+
# the window that keep set, and none of them pretends the record changed.
|
|
1311
|
+
continue
|
|
1214
1312
|
# Last activity = the most recent rediscovery if there was one, else the
|
|
1215
1313
|
# record's own creation ts. A provisional that is neither being promoted
|
|
1216
1314
|
# nor re-learned for weeks is noise the queue keeps injecting into every
|
|
@@ -1225,6 +1323,26 @@ def doctor(memory_dir: str | None = None, targets: list[str] | None = None,
|
|
|
1225
1323
|
"kind": kind, "threshold_weeks": stale_weeks,
|
|
1226
1324
|
"age_days": int(age_h // 24),
|
|
1227
1325
|
"last_seen": str(last)[:10], "rediscovered": int(c.get("rediscovered", 0) or 0)})
|
|
1326
|
+
# The third emptiness, and the one the first two cannot see. `unused` below
|
|
1327
|
+
# needs served == 0, so a record that entered a session's context twice and
|
|
1328
|
+
# was never promoted, never re-learned and never asked for is invisible to
|
|
1329
|
+
# both: it is neither unused nor quiet-as-a-whole, it is being served into
|
|
1330
|
+
# every session and doing nothing. That is the shape a stuck queue has, and
|
|
1331
|
+
# before this check the only way to see it was to read `status` by eye.
|
|
1332
|
+
#
|
|
1333
|
+
# The bar is deliberately low: MIN_SERVED_IGNORED injections is enough, and the
|
|
1334
|
+
# age threshold is half the record's own stale window, because the question is
|
|
1335
|
+
# not "has this gone bad" but "has anything happened since it entered the
|
|
1336
|
+
# context at all". It stays report only, like every other line here: the
|
|
1337
|
+
# answer is a promote, a drop, or `sleep keep`, and all three are a person's.
|
|
1338
|
+
served = int(c.get("injected", 0) or 0)
|
|
1339
|
+
redis = int(c.get("rediscovered", 0) or 0)
|
|
1340
|
+
if served >= MIN_SERVED_IGNORED and redis == 0 and age_h is not None:
|
|
1341
|
+
if age_h >= stale_weeks * 7 * 24 / 2:
|
|
1342
|
+
out.append({"issue": "served-ignored", "id": c["id"], "kind": kind,
|
|
1343
|
+
"injected": served, "rediscovered": redis,
|
|
1344
|
+
"age_days": int(age_h // 24),
|
|
1345
|
+
"threshold_weeks": round(stale_weeks / 2, 1)})
|
|
1228
1346
|
# The sibling of the check above, measuring a different emptiness. That one says
|
|
1229
1347
|
# "nobody re-learned this"; this one says "nobody ever asked for this": no inject
|
|
1230
1348
|
# ever carried it and no consolidation ever saw it come up again. A record can be
|
|
@@ -1234,6 +1352,8 @@ def doctor(memory_dir: str | None = None, targets: list[str] | None = None,
|
|
|
1234
1352
|
for c in list_candidates():
|
|
1235
1353
|
if c.get("status") != "provisional":
|
|
1236
1354
|
continue
|
|
1355
|
+
if is_kept(c):
|
|
1356
|
+
continue
|
|
1237
1357
|
served = int(c.get("injected", 0) or 0) + int(c.get("rediscovered", 0) or 0)
|
|
1238
1358
|
if served:
|
|
1239
1359
|
continue
|