sealkeep 0.11.2 → 0.11.4

package/ARCHITECTURE.md

@@ -88,6 +88,26 @@ Automatic context has a deliberately split latency contract:
   later safe boundary. Provider latency therefore changes freshness, never the
   latency of the current prompt or tool result.
 
+What that prepared context is then *used* for changed deliberately. Anything a
+hook adds to a conversation is re-read by the model on every later step of the
+session, so an unrequested block is not paid for once — it is rent for the rest
+of the session. Measured on one real session: 129 automatic injections, about
+465 tokens each, roughly 60,000 tokens of permanent weight nobody asked for.
+
+So recall is pull, not push. `formatNotice` emits one line at the start of a
+session saying preserved history exists and how to search it, and nothing
+afterwards; the agent reaches for the index over MCP when a question actually
+needs it. Teammate events still pass through, because a teammate line is a
+person addressing the session rather than recall addressing itself. The old
+behaviour remains available behind `recallPushEnabled` — `SEALKEEP_RECALL_PUSH=1`
+or a `runtime/recall-push` marker in the data directory — which is also what the
+tests that assert recall *content* switch on.
+
+`sealkeep meter` is the other half of the same idea. It reads local session
+files only, with no key and no network, and reports what each live session costs
+per step, what share of that is re-read history, and what the same work would
+cost from a fresh session carrying a small context pack.
+
 Autopilot has a similarly explicit deletion boundary. A fresh installation
 preserves, indexes, and uploads, while `local-settings.json` records
 `reclaimEnabled: false`; neither the generated service unit nor the running

package/CHANGELOG.md

@@ -3,6 +3,152 @@
 Notable changes, by published version. Sealkeep is pre-1.0: minor versions
 may change behavior, and say so here when they do.
 
+## 0.11.4 — 2026-09-23 — history stays findable
+
+- **An archive can no longer be dropped from search because one sidecar could
+  not be read.** The build treats an id missing from the archive ledger as
+  deleted and retires it, which in segments mode is permanent: the id vanishes
+  from every later lookup and no build indexes it again. But the ledger scan
+  skips any sidecar it cannot parse — a partial write being replaced, one
+  transient read error — and that scan is cached per directory, so the damage
+  only surfaces when something else changes the directory: a seal arriving
+  while a build runs, which is what a busy machine does all day. On one real
+  vault ten archives had been retired with nothing superseding them, and two
+  sessions were genuinely unfindable — words in one returned no hits from it
+  while matching hundreds of other sessions. Absence now counts as deletion
+  only when the scan read every sidecar.
+
+  A vault that already lost archives this way recovers with `sealkeep index
+  drop` followed by `sealkeep index build`, which clears every retirement and
+  indexes the archives again. Repairing it automatically was tried and dropped:
+  a retirement also travels between your machines, so a build that lifted one
+  could undo a removal another machine meant, and the suite caught that.
+
+- **The team check no longer runs on every seal.** 0.11.3 gave the lane its own
+  backing-off cadence, but a tick still asked it for a pass, and a tick is
+  scheduled whenever the queue has work — so cloud traffic still followed local
+  sealing. Measured on a busy machine: passes 4-6 seconds apart while a backlog
+  drained, against the 6-to-120-second schedule the lane had chosen. Nothing is
+  lost by waiting for that schedule; a pass this machine's own sealing triggers
+  cannot learn anything sooner than one the clock triggers.
+
+## 0.11.3 — 2026-09-23 — the context tax, and a vault that catches up
+
+- **The team check stops asking the cloud every three seconds.** The daemon
+  asked the same four questions twenty times a minute whether or not anything
+  had happened, and fetched the team space list three times per pass. Measured
+  against a stub plane, an idle daemon made 56 requests in 30 seconds, 55 of
+  them from this one loop: about 4.8 million a month per always-on machine,
+  with every machine drawing on one shared Cloud allowance. The list is now
+  fetched once, and a pass that finds nothing doubles the wait up to two
+  minutes; a pass that changes something brings the next one straight back.
+  Idle, that is 4 requests every 2 minutes, around 86,000 a month. Pushing
+  changes over realtime instead is the next step.
+
+- **Automatic uploads finish on a large vault.** Choosing where an archive
+  belongs walks every link of its chain and may ask the account whether a copy
+  already matches. That is real work that moves no bytes, and the upload
+  pass's two-minute idle deadline only counted bytes, so on a vault of 5,062
+  archives the first byte came at 168 seconds and every pass was stopped
+  before it began: no automatic upload ran for days while every surface
+  reported the service healthy. Preparation now counts as progress; a stalled
+  transfer still trips the deadline, because it reports no bytes either.
+
+- **The start of a long session becomes searchable.** The index build skipped
+  every earlier snapshot of a growing session, assuming the newest one would be
+  walked and cover them. A snapshot indexed as it was sealed is never walked,
+  and covers only the bytes it added, so everything sealed before it was never
+  indexed at all. On one real vault that was 400 snapshots across 76 sessions:
+  words found only in their early part came back in 0 of 20 searches, words
+  from the covered tail in 10. The build now schedules the newest snapshot that
+  still needs indexing, and walking its chain covers the rest.
+
+- **`sealkeep index build` says what it did.** It printed the index's running
+  total as if it were the result — "Indexed 4509 archives" after a run that
+  indexed one, while the 410 that doctor had sent the user to fix stayed as
+  they were. It now reports what this run covered, says "Already up to date"
+  when there was nothing, and names what is still missing. It no longer claims
+  the index is never uploaded: it is synced to your account, as ciphertext.
+
+- **The daemon's "is the index finished" check can pass.** It counted
+  superseded snapshots, which are never indexed on their own by design, so on
+  any vault that had ever superseded one it retried `index_incomplete` forever,
+  and disk reclaim waits for that check. It now uses the same definition as
+  `sealkeep index status` and doctor.
+
+- **Settings for what reaches your agent, and what this machine will spend.**
+  The local Settings page gains four controls, all with the numbers behind
+  them stated plainly rather than hidden: hand preserved history to an agent
+  when a session starts (on, with what it costs spelled out), let agents search
+  this vault themselves (on, the local MCP server), a background CPU ceiling,
+  and a background memory ceiling. Both ceilings only ever make Sealkeep
+  gentler than the automatic value, never greedier, and each has a floor below
+  which work would stall rather than pace. Turning recall off still leaves
+  preserved history written as notes the agent reads for itself.
+
+- **The agent-facing hook gets four seconds instead of two.** It unlocks the
+  keystore and decrypts a prepared file, measured at about 1.25 s on a modest
+  server; a live run went over two seconds and the agent discarded the output
+  with "hook timed out after 2s", so recall silently did nothing and nobody was
+  told. Four still fails open long before a person notices.
+
+- **`sealkeep doctor` reports whether preserved history can reach the agent.**
+  A new `agent-memory-notes` check says whether Claude keeps a memory directory
+  for this project and how many preserved sessions have been written there.
+
+- **Recall is written where the agent believes it.** Tested end to end on a
+  server, on two models: history pushed into the prompt by a hook was delivered
+  perfectly and then refused, in the agent's own words as "unverified/possibly
+  injected". Wording was not the cause — the same text pasted into a plain
+  session was believed. What an agent trusts is its own memory directory. So a
+  session start now writes preserved sessions there as ordinary notes, with
+  plain provenance (when the work happened, in this project) and no language
+  that reads as an injection; a note signed "recalled by Sealkeep" was read and
+  then discounted for exactly that reason. Notes are namespaced, additive, and
+  never touch a person's own notes or index lines. After the change the same
+  agent answered from memory, called Sealkeep itself for the detail, and got it
+  right.
+
+- **Recall never quotes a conversation back to itself.** A long session is
+  sealed while it is still running, so the newest preserved session was the one
+  you were in: an agent was shown its own earlier "I don't know" above a genuine
+  finding, judged the evidence contradictory, and used neither. Automatic recall
+  now excludes the current transcript and anything sealed since this
+  conversation began. `SEALKEEP_RECALL_DAYS` bounds how far back it looks, off
+  by default because a decision from a month ago is worth being reminded of.
+
+- **`sealkeep fork`** is the way out of an expensive session. Resuming a long
+  conversation sends its whole transcript with every request; one real evening,
+  two questions on a resumed session cost 41 million tokens, of which about
+  220,000 were the work. `fork` prices carrying on against starting fresh,
+  distils the session into a small pack — where the work got to, what was being
+  asked for, which files were open — and prints the command to start a new
+  session with it. Crucially it verifies first that the session is sealed and
+  indexed, and refuses to suggest walking away when it is not: the promise that
+  the history is one search away only holds if the history can actually be
+  searched.
+
+- **Recall never tells a session the same thing twice.** Preserved context was
+  re-sent after every prompt and every Bash, Edit and Write, and 80% of it had
+  already been given to that same conversation: the identical preamble 140
+  times, the same list of preserved sessions over and over. Because everything
+  already in a conversation is re-read on every later request, that repetition
+  cost 81.6 million tokens on one measured session. Recall still runs at every
+  boundary and still searches against the current prompt; it now remembers what
+  this conversation has been told and sends only what is new, says the framing
+  once, and treats a passage as already-seen whichever section it arrives in.
+  The record is per conversation, so a new session is still told where the work
+  is up to. `SEALKEEP_RECALL_PUSH=0` restricts recall to session start only.
+
+- **`sealkeep meter`** reports what your live agent sessions cost per step, how
+  much of that is re-read history, and what the same work would cost from a
+  fresh session carrying a small context pack. It reads local session files
+  only: no recovery phrase, no key, no network, nothing uploaded to produce a
+  number. Three signals, each of which was true of a session that ended a
+  weekly allowance: BLOATED when history is over 90% of input and over 50k a
+  step, STALE past seven days or 200 MB, and POLLING when an agent sleeps and
+  re-checks five or more times inside one turn.
+
 ## 0.11.2 — 2026-09-18 — a release tells you when a newer one exists
 
 - Sealkeep says, once a day at most, when a newer release is on npm and what

package/README.md

@@ -50,6 +50,115 @@ source, your prompts, and whatever you pasted at 2am.
 So the two obvious options are both bad: let them fill the disk, or `rm -rf` the reasoning
 behind six months of work. Sealkeep is the third option.
 
+## What it saves you
+
+An AI coding session charges you for its own history on every single step, and nothing
+tells you until the limit is gone. A session that has been alive for three months carries
+roughly 185,000 tokens of accumulated conversation, and every request re-sends all of it.
+Ask a one-line question and you pay 185,000 tokens to ask it. Let an agent run a loop of
+shell commands and you pay it once per command, whatever the command does.
+
+The worst version of this is resuming an old session. Pick up a months-old conversation to
+ask two questions and the whole transcript goes with every request: one real evening, two
+questions on a resumed session cost 41 million tokens, of which about 220,000 were the work.
+The weekly allowance was gone by 2am, and nothing had warned anybody.
+
+**Leave the session instead of resuming it.** `sealkeep fork` prices the choice, checks the
+history really is recoverable, and writes a small pack — where the work got to, what was
+being asked for, which files were open — to start fresh with. Everything else stays in the
+vault, and the pack tells your agent how to ask for it.
+
+```sh
+sealkeep fork            # the most expensive session you have open
+sealkeep fork --write    # write the pack and print the command to start fresh
+```
+
+```
+The most expensive session you have open is the claude one in bot.
+
+  carrying on there      615k tokens per step, 97% of it re-read history
+  starting fresh          22k tokens per step, carrying a 392-token pack instead
+  you would save         593k tokens on every step from here on
+
+The full session is sealed (afaa0cb4…) and searchable, so nothing is lost by leaving it.
+```
+
+That last line is the part that matters. If the session is not sealed and indexed yet,
+Sealkeep says so and refuses to pretend walking away is safe, because the promise only
+holds if your agent can genuinely get the detail back when it needs one.
+
+**It can also just tell you the number.** `sealkeep meter` answers the question nothing else
+can: what is each live session costing per step, how much of that is re-read history, and
+what the same work would cost starting fresh.
+
+```sh
+sealkeep meter                 # the last 24 hours
+sealkeep meter --hours 6 --json
+```
+
+It reads local session files only. No recovery phrase, no key, no network, nothing uploaded
+to produce a number. One real morning on one machine:
+
+```
+tool   where                  steps  per step  history  total in  signals
+claude bot                      457      597k      97%    272.8M  BLOATED
+claude sometest                 368      474k      96%    174.3M  BLOATED STALE
+codex  spala                    581      162k      99%     94.2M  BLOATED STALE POLLING
+
+Total sent: 807.8M. The same work from fresh sessions carrying a 3k-token pack: about 36.5M.
+That is roughly 771.4M spent re-reading, 95% of everything you sent.
+```
+
+Three signals, each of which was true of a session that ended a weekly allowance:
+**BLOATED** when history is over 90% of input and over 50k a step, **STALE** past seven days
+or 200 MB, and **POLLING** when an agent sleeps and re-checks five or more times inside one
+turn, paying the whole context on every tick.
+
+**Recall never tells your session the same thing twice.** It used to re-send the same
+preamble and the same list of preserved sessions after every prompt and every Bash, Edit
+and Write. Measured on one real session:
+
+| Injections over one session | 140 |
+| :-- | --: |
+| Payload they carried | ~65,000 tokens |
+| Of that, lines the session had already been given | **80%** |
+| What the repetition cost to re-send | **81.6 million tokens** |
+
+A block added early is re-sent on every one of the thousands of requests after it, so
+repeating yourself is the most expensive thing a memory tool can do.
+
+So recall still runs at every boundary, exactly as before, and still searches against what
+you just typed. It simply keeps track of what this conversation has already been told and
+sends only the part that is new. The framing is said once. A passage that arrived as a
+preserved session is not sent again as a search excerpt, because it is the same sentence
+wearing a different prefix. Nothing is lost: a genuinely new excerpt, or a teammate's new
+line, still arrives the moment it exists.
+
+The book-keeping is per conversation, not permanent. A new session is a new reader and is
+told where the work is up to, even though an earlier session on the same machine was told
+the same thing.
+
+Set `SEALKEEP_RECALL_PUSH=0` if you want memories only at session start and silence after.
+
+**Your history stays searchable without living in the prompt.** The whole archive is one
+`sealkeep search` or one MCP call away, so nothing has to be carried forward just in case.
+
+**Your disk comes back.** Verified, searchable, idle sessions are reclaimed, and the
+reasoning behind them survives in a form you can still read years later.
+
+## What you can turn off
+
+Everything automatic has a switch, on the local Settings page, with its cost stated rather
+than hidden.
+
+| Setting | Default | What it means |
+| --- | --- | --- |
+| Hand preserved history to an agent at session start | on | Your agent opens a project and knows where you left off. Each thing is sent once and never repeated; on a measured session that was under one percent of what the session sent. Off still writes the notes. |
+| Let agents search this vault themselves | on | The local tool server, so an agent can look things up on demand. Nothing is exposed to the network. |
+| Background CPU ceiling | automatic | Targets 30% of one core. A number here only ever makes Sealkeep gentler. |
+| Background memory ceiling | automatic | The ceiling a worker may reach before it stops and retries smaller. |
+| Background network limit | automatic | One 8 Mbps ceiling shared across Sealkeep's jobs. |
+
 ## How it works
 
 The order is the safety property. Nothing is reclaimed before it is verified, and nothing is
@@ -160,6 +269,8 @@ it stores archives as single objects, and says so.
 | `sealkeep autopilot status` · `off` | Check on it, or stop it |
 | `sealkeep quickstart` | Same setup, no background service |
 | `sealkeep status` · `doctor` | What is archived; whether this machine is healthy |
+| `sealkeep meter` | What your live sessions cost per step, and how much of it is re-read history |
+| `sealkeep fork` | Leave an expensive session without losing what it knows |
 | `sealkeep queue run` | Encrypt everything waiting |
 | `sealkeep daemon` | Watch, seal, index, and upload continuously; reclaim only when enabled |
 | `sealkeep search <query>` | Metadata search; `--content` searches inside sessions |
@@ -181,9 +292,12 @@ Codex, so the agent itself can search your sealed history, check vault
 status, and restore a session it needs — six tools, all local, nothing new
 exposed to the network.
 
-Ordinary work does not depend on the agent remembering to call that tool.
-The installed lifecycle hooks identify the current Git project and inject a
-small, labelled context automatically:
+The installed lifecycle hooks identify the current Git project and prepare that
+history locally, so the search is instant when the agent asks for it. What they
+no longer do is push it into the conversation: at the start of a session you get
+one line saying preserved history exists, and after that, silence until something
+is actually requested. Two things still arrive on their own, because both are a
+person talking rather than recall talking to itself:
 
 - **One developer, several machines.** A finished Mac session is sealed and
   its encrypted index syncs in the background. When the same developer opens