hippo-memory 3.4.0 → 3.6.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.
Files changed (135) hide show
  1. package/README.md +29 -26
  2. package/dist/api/callers.d.ts +4 -1
  3. package/dist/api/context/context-plan.js +3 -0
  4. package/dist/api/context/context-pools.js +2 -0
  5. package/dist/api/context/context.d.ts +1 -1
  6. package/dist/api/context/context.js +13 -9
  7. package/dist/api/ledger-db.d.ts +4 -2
  8. package/dist/api/ledger-db.js +11 -1
  9. package/dist/api/objects/object-kinds.d.ts +1 -4
  10. package/dist/api/objects/object-kinds.js +1 -5
  11. package/dist/api/pilot-arm.js +4 -1
  12. package/dist/api/recall/finish.js +3 -2
  13. package/dist/api/recall/recall.js +3 -1
  14. package/dist/api/recall/request.d.ts +1 -1
  15. package/dist/api/recall/request.js +3 -1
  16. package/dist/api/session-end.d.ts +3 -2
  17. package/dist/api/session-end.js +8 -4
  18. package/dist/api/sharing.d.ts +4 -3
  19. package/dist/api/sharing.js +2 -2
  20. package/dist/api/sleep/auto-sleep.d.ts +3 -2
  21. package/dist/api/sleep/auto-sleep.js +16 -3
  22. package/dist/api/sleep/one-sleep.d.ts +23 -0
  23. package/dist/api/sleep/one-sleep.js +53 -0
  24. package/dist/api/sleep/sleep.d.ts +5 -0
  25. package/dist/api/sleep/sleep.js +2 -1
  26. package/dist/api/tokens.d.ts +1 -1
  27. package/dist/api/tokens.js +3 -0
  28. package/dist/api/types.d.ts +2 -0
  29. package/dist/api/types.js +4 -0
  30. package/dist/base/config/config-keys.js +1 -0
  31. package/dist/base/config/config.d.ts +4 -0
  32. package/dist/base/config/config.js +1 -0
  33. package/dist/base/embeddings/local.d.ts +1 -1
  34. package/dist/base/embeddings/local.js +2 -3
  35. package/dist/base/errors/read-only.d.ts +3 -0
  36. package/dist/base/errors/read-only.js +4 -0
  37. package/dist/base/ports/store/capture.d.ts +2 -0
  38. package/dist/base/ports/store/consolidation.d.ts +15 -0
  39. package/dist/base/ports/store/consolidation.js +2 -0
  40. package/dist/base/ports/store/context-reads.d.ts +2 -0
  41. package/dist/base/ports/store/objects.d.ts +15 -4
  42. package/dist/base/ports/store/store-effects.d.ts +2 -0
  43. package/dist/base/ports/store.d.ts +1 -1
  44. package/dist/base/scope/read-admission.d.ts +2 -0
  45. package/dist/base/scope/read-admission.js +8 -2
  46. package/dist/base/util/env.d.ts +1 -0
  47. package/dist/base/util/env.js +3 -0
  48. package/dist/base/util/version.d.ts +1 -1
  49. package/dist/base/util/version.js +1 -1
  50. package/dist/cli.js +14 -1
  51. package/dist/db/connect.d.ts +4 -0
  52. package/dist/db/connect.js +79 -1
  53. package/dist/db/grant.js +1 -1
  54. package/dist/db/migrate.d.ts +3 -0
  55. package/dist/db/migrate.js +1 -1
  56. package/dist/db/migrations/index.d.ts +1 -1
  57. package/dist/db/migrations/index.js +3 -1
  58. package/dist/db/migrations/v63.d.ts +3 -0
  59. package/dist/db/migrations/v63.js +9 -0
  60. package/dist/db/store-runtime.d.ts +7 -0
  61. package/dist/db/store-runtime.js +4 -0
  62. package/dist/domain/consolidate/merge.js +6 -6
  63. package/dist/domain/consolidate/tombstones.d.ts +3 -4
  64. package/dist/domain/consolidate/tombstones.js +3 -3
  65. package/dist/domain/objects/decisions.d.ts +4 -7
  66. package/dist/domain/objects/decisions.js +1 -9
  67. package/dist/domain/objects/descriptor.d.ts +2 -0
  68. package/dist/domain/objects/lifecycle.js +8 -2
  69. package/dist/domain/sharing/share.d.ts +16 -4
  70. package/dist/domain/sharing/share.js +33 -17
  71. package/dist/entry/store-kit.js +2 -1
  72. package/dist/infra/local-embedder.js +14 -2
  73. package/dist/infra/spool-claims.d.ts +2 -2
  74. package/dist/infra/spool-claims.js +4 -3
  75. package/dist/infra/spool-import.js +1 -1
  76. package/dist/infra/spool-record.d.ts +3 -1
  77. package/dist/store/sqlite/capture/compaction-hooks.js +14 -6
  78. package/dist/store/sqlite/capture/spool-request-id.d.ts +3 -0
  79. package/dist/store/sqlite/capture/spool-request-id.js +12 -0
  80. package/dist/store/sqlite/consolidation/consolidation.js +2 -0
  81. package/dist/store/sqlite/consolidation/sleep-lock.d.ts +4 -0
  82. package/dist/store/sqlite/consolidation/sleep-lock.js +69 -0
  83. package/dist/store/sqlite/entries/entry-filter.js +1 -2
  84. package/dist/store/sqlite/entries/entry-row.js +5 -1
  85. package/dist/store/sqlite/entries/entry-writes.js +3 -10
  86. package/dist/store/sqlite/entries/raw-archive.d.ts +2 -1
  87. package/dist/store/sqlite/entries/raw-archive.js +12 -3
  88. package/dist/store/sqlite/index.d.ts +1 -1
  89. package/dist/store/sqlite/learning/prediction-baserate.js +4 -2
  90. package/dist/store/sqlite/recall/candidates.js +2 -7
  91. package/dist/store/sqlite/recall/search-rows.d.ts +3 -0
  92. package/dist/store/sqlite/recall/search-rows.js +27 -8
  93. package/dist/store/sqlite/records/object-rows.d.ts +2 -0
  94. package/dist/store/sqlite/records/object-rows.js +5 -1
  95. package/dist/store/sqlite/records/object-writes.d.ts +3 -0
  96. package/dist/store/sqlite/records/object-writes.js +43 -1
  97. package/dist/store/sqlite/review/conflicts.js +3 -4
  98. package/dist/store/sqlite/runtime/handles.js +3 -0
  99. package/dist/store/sqlite/runtime/rule-sql.d.ts +1 -0
  100. package/dist/store/sqlite/runtime/rule-sql.js +2 -0
  101. package/dist/surface/capture/session-worker.d.ts +3 -2
  102. package/dist/surface/capture/session-worker.js +36 -10
  103. package/dist/surface/cli/api-context.js +3 -1
  104. package/dist/surface/cli/cli-runtime.js +2 -1
  105. package/dist/surface/cli/client.d.ts +6 -5
  106. package/dist/surface/cli/client.js +50 -19
  107. package/dist/surface/cli/decisions.js +16 -17
  108. package/dist/surface/cli/hooks/session-end-worker.js +3 -2
  109. package/dist/surface/cli/install-steps.js +99 -13
  110. package/dist/surface/cli/memory-writes.js +3 -2
  111. package/dist/surface/cli/serve.js +4 -1
  112. package/dist/surface/cli/sleep-render.js +7 -0
  113. package/dist/surface/cli/sleep.d.ts +3 -2
  114. package/dist/surface/cli/sleep.js +10 -4
  115. package/dist/surface/cli/transfer.js +6 -3
  116. package/dist/surface/cli/verb-row.d.ts +2 -0
  117. package/dist/surface/cli/verbs/health.js +3 -0
  118. package/dist/surface/cli/verbs/memory.js +5 -0
  119. package/dist/surface/cli/verbs/objects.js +2 -0
  120. package/dist/surface/cli/verbs/sessions.js +11 -0
  121. package/dist/surface/hooks-install/codex-wrapper.js +52 -11
  122. package/dist/surface/hooks-install/rules/hook-blocks.js +9 -2
  123. package/dist/surface/mcp/admin-tools.js +5 -2
  124. package/dist/surface/mcp/request.js +6 -2
  125. package/dist/surface/mcp/tools.d.ts +2 -0
  126. package/dist/surface/mcp/tools.js +8 -0
  127. package/dist/surface/open-store.d.ts +2 -2
  128. package/dist/surface/open-store.js +2 -2
  129. package/dist/surface/server/routes/decisions.js +2 -2
  130. package/dist/surface/server/sleep-child.js +5 -4
  131. package/dist/surface/server/sleep-offload.js +36 -25
  132. package/extensions/openclaw-plugin/openclaw.plugin.json +1 -1
  133. package/extensions/openclaw-plugin/package.json +1 -1
  134. package/openclaw.plugin.json +1 -1
  135. package/package.json +1 -1
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # 🦛 Hippo
2
2
 
3
- **Stop re-teaching your agent.**
3
+ **Your corrections, remembered by Claude Code, Codex and Cursor.**
4
4
 
5
- Make your agent's memory work like a brain. Hippo is long-term memory for coding agents. It's a critical layer for your AI harness that connects across your different tools (Cursor, Claude Code, Codex). It keeps your proprietary data completely local, and it actually learns over time. By strengthening memories each time they are recalled, Hippo preserves what works, lets mistakes decay, and continuously compounds your agents' intelligence.
5
+ Hippo is open-source memory that runs on your machine and gives the rules it captured back to the agent when a new session starts. In our Claude Code test on 29 repositories, adding it to built-in memory cut repeat mistakes from 21 in 100 to 11, at the same cost.
6
6
 
7
7
  [![npm](https://img.shields.io/npm/v/hippo-memory)](https://npmjs.com/package/hippo-memory)
8
8
  [![npm downloads](https://img.shields.io/npm/dm/hippo-memory)](https://npmjs.com/package/hippo-memory)
@@ -24,7 +24,7 @@ npm install -g hippo-memory && hippo init
24
24
 
25
25
  Setting up every git repo under a folder in one go is a second step. The [Quick start](#quick-start) says what it changes, then gives the command.
26
26
 
27
- Package installation alone does not enable automatic preservation on every agent. Complete the documented setup and required host trust; capture and compaction coverage depend on the integration.
27
+ Installing the package alone captures nothing, and what runs after init depends on the agent.
28
28
 
29
29
  Having an AI agent install it? Point it at [llms-install.md](llms-install.md): it installs, wires hippo into the agents it finds, and verifies with `hippo doctor`.
30
30
 
@@ -56,7 +56,7 @@ Every measurement we have ever published is indexed in [`docs/evals/`](docs/eval
56
56
  pre-registrations kept next to their results, including the runs that failed and the one
57
57
  claim we retracted.
58
58
 
59
- - **Z0 round 2, 16 repositories, Claude Code with hippo against its built-in memory: no extra cost (ratio 0.999 [0.962, 1.037]) and about 12% less spent on teach and correction turns. A drop in repeat mistakes is not shown (-8.9 points [-18.5, +0.7], under the pre-registered 15-point minimum).** ([result](docs/evals/2026-11-01-z0-round2-result.md))
59
+ - **Correct your agent once, and with hippo it repeats that mistake about half as often. Z0 round 3, real Claude Code sessions on 29 repositories, hippo against built-in memory alone: 11 repeats in 100 against 21, 2 to 4 tasks after the correction, at no extra cost (ratio 1.006 [0.964, 1.049]).** With no memory the agent repeats it 83 times in 100. Over every first chance to repeat, the pre-registered read is 14.9 points fewer [5.5, 24.3], adjusted p 0.006, against a full-win line of 15. The gain is the same with lesson capture switched off, so round 4 tests how much of it the stored lessons carry. ([result](docs/evals/2026-11-08-z0-round3-result.md); [round 2](docs/evals/2026-11-01-z0-round2-result.md), on 16 repositories, was inconclusive at -8.9 points)
60
60
  - **Sequential Learning Benchmark.** [benchmarks/sequential-learning/](benchmarks/sequential-learning/). 50 tasks, 10 buried traps. Measures whether agents learn from past mistakes, not just retrieve text. v0.11.0 informal magnitude RETRACTED v1.7.9; mechanism remains shipped. See [CHANGELOG.md](./CHANGELOG.md) v1.7.9 entry.
61
61
  - **LongMemEval oracle split, all 500 questions in one pooled store, BM25 only, no embeddings, v0.11: R@5 = 74.0%** ([benchmarks/README.md](benchmarks/README.md), scripts in [benchmarks/longmemeval/](benchmarks/longmemeval/)). A different setup from the per-haystack results under [Benchmarks](#benchmarks), so the two are not a before and after.
62
62
  - **On a private 300-query developer store, R@1 0.41 to 0.62 with `hippo recall "<query>" --reranker jev`**, the free local cross-encoder against Jev ([full eval](docs/evals/2026-09-19-jev-reranker.md)). The opt-in [TypeSafe Jev](https://typesafe.ai) reranker, off by default, about 0.0004 USD a recall. 2000-draw paired bootstrap; the margin held in 20 of 20 seeds and a permutation null reached it in 0 of 200 runs. Ranking only: three graded tests on one 150-question LongMemEval set did **not** show a better answer rate than the free local cross-encoder, and that negative result is in the same doc. What it buys today is a shorter context: on that set, 2 memories ranked by Jev answered as well as 5 ranked by the cross-encoder.
@@ -88,7 +88,7 @@ npm install -g hippo-memory
88
88
  hippo init
89
89
  ```
90
90
 
91
- **Optional: many repos at once.** Read what it changes first. `hippo init --scan <folder>` looks for git repos in the folder and up to three levels below it, skipping dot-folders and `node_modules`. Each repo gets a `.hippo/` store, seeded with lessons from the last 365 days of its commits and with its [agent memories](#agent-memories), and is added to the daily run's list. For the agents it finds, it installs the same user-level hooks as `hippo init`: 7 Claude Code hook entries in `~/.claude/settings.json` and the OpenCode plugin. It also sets up the daily 6:15am run, a crontab line on Linux and macOS or a scheduled task on Windows. It adds no block to any repo's `CLAUDE.md` or `AGENTS.md`. `--no-hooks`, `--no-schedule` and `--no-learn` leave out the hooks, the daily run and the history import.
91
+ **Optional: many repos at once.** Read what it changes first. `hippo init --scan <folder>` looks for git repos in the folder and up to three levels below it, skipping dot-folders and `node_modules`. Each repo gets a `.hippo/` store, seeded with lessons from the last 365 days of its commits and with its [agent memories](#agent-memories), and is added to the daily run's list. For the agents it finds, it installs the same user-level hooks as `hippo init`: 8 Claude Code hook entries in `~/.claude/settings.json` and the OpenCode plugin. It also sets up the daily 6:15am run, a crontab line on Linux and macOS or a scheduled task on Windows. It adds no block to any repo's `CLAUDE.md` or `AGENTS.md`. `--no-hooks`, `--no-schedule` and `--no-learn` leave out the hooks, the daily run and the history import.
92
92
 
93
93
  ```bash
94
94
  hippo init --scan ~
@@ -119,7 +119,7 @@ Run `hippo init` inside one project. This is everything it writes, in the projec
119
119
 
120
120
  - **The project's store.** A `.hippo/` folder: SQLite plus markdown mirrors. On the first run in a git repo it learns lessons from the last 30 days of commits.
121
121
  - **Instruction files.** A block between `<!-- hippo:start -->` and `<!-- hippo:end -->` in the project's `CLAUDE.md` or `AGENTS.md`, only if that file already exists. Codex, Cursor, OpenClaw, OpenCode and Pi read `AGENTS.md`.
122
- - **Claude Code,** when the project has `CLAUDE.md` or `.claude/settings.json`: 7 hook entries in `~/.claude/settings.json`, one each on SessionEnd, UserPromptSubmit, PreCompact, PostCompact and PostToolUseFailure and two on SessionStart. [Framework Integrations](#framework-integrations) says what each one runs.
122
+ - **Claude Code,** when the project has `CLAUDE.md` or `.claude/settings.json`: 8 hook entries in `~/.claude/settings.json`, one each on SessionEnd, UserPromptSubmit, PreCompact, PostCompact and PostToolUseFailure and three on SessionStart. [Framework Integrations](#framework-integrations) says what each one runs.
123
123
  - **OpenCode,** when the project has `.opencode/` or `opencode.json`: a plugin at `~/.config/opencode/plugins/hippo.ts`.
124
124
  - **Codex,** when the project has `AGENTS.md` or `.codex` and Codex is installed (`$CODEX_HOME`, else `~/.codex`, exists): 2 hook entries in Codex's `hooks.json`, one on UserPromptSubmit that sends your pinned memories plus up to 5 that match the prompt with every prompt and one on SessionStart after a compaction. **Codex runs them only after you trust them once in `/hooks`.** Init also prints `hippo hook install codex`, the opt-in that wraps the Codex launcher to capture sessions; `hippo hook uninstall codex` removes hippo's hooks and the wrapper.
125
125
  - **A daily run at 6:15am,** one per machine: a crontab line on Linux and macOS, a scheduled task named `hippo-daily-runner` on Windows. It runs `hippo learn --git --days 1` and then `hippo sleep` in every project listed in `~/.hippo/workspaces.json`, and init adds this project to that list.
@@ -773,7 +773,7 @@ The command runs with no shell, so each argument reaches the program as written.
773
773
  | `hippo decide "<decision>" --context "<why>"` | Include reasoning |
774
774
  | `hippo decide "<decision>" --supersedes <id>` | Supersede a previous decision |
775
775
  | `hippo hook list` | Show available framework hooks |
776
- | `hippo hook install <target>` | Install hook (claude-code also adds its 7 settings.json hook entries: session start and end, each prompt, compaction, failed tool calls) |
776
+ | `hippo hook install <target>` | Install hook (claude-code also adds its 8 settings.json hook entries: session start and end, each prompt, compaction, failed tool calls) |
777
777
  | `hippo hook uninstall <target>` | Remove hook |
778
778
  | `hippo handoff create --summary "..."` | Create a session handoff |
779
779
  | `hippo handoff latest` | Show the most recent handoff |
@@ -803,6 +803,8 @@ The command runs with no shell, so each argument reaches the program as written.
803
803
 
804
804
  On `heartbeat`, `block`, `review` and `complete`, a given `--run` is checked against the card's live run and the command is refused, unchanged, if the two do not match.
805
805
 
806
+ `HIPPO_READ_ONLY=1` uses a store without changing it, for example in the test phase of a benchmark. `hippo recall`, `hippo context`, the prompt hook and the MCP read tools give the same answers and write nothing: no recall counts, token-ledger rows, audit rows or mirror files, and a store with a WAL keeps its WAL. `remember`, `supersede`, `refine`, `outcome`, `resolve`, `decide`, `invalidate`, `forget`, `learn`, `promote`, `share` and `import`, and the MCP tools `hippo_remember`, `hippo_outcome`, `hippo_learn`, `hippo_resolve` and `hippo_share`, answer `read-only: not saved (HIPPO_READ_ONLY=1)` and save nothing (the CLI exits 1). `capture`, `capture-error`, `sleep`, `pre-compact`, `post-compact` and `session-end` log one line and do nothing, `hippo serve` does not start, and any other command that writes to the store fails with the store's own read-only error.
807
+
806
808
  ---
807
809
 
808
810
  ## Framework Integrations
@@ -813,7 +815,7 @@ On `heartbeat`, `block`, `review` and `complete`, a given `--run` is checked aga
813
815
 
814
816
  | Framework | Detected by | Patches |
815
817
  |-----------|------------|---------|
816
- | Claude Code | `CLAUDE.md` or `.claude/settings.json` | `CLAUDE.md` + 7 hook entries in `~/.claude/settings.json` (listed below) |
818
+ | Claude Code | `CLAUDE.md` or `.claude/settings.json` | `CLAUDE.md` + 8 hook entries in `~/.claude/settings.json` (listed below) |
817
819
  | Codex | `AGENTS.md` or `.codex` | `AGENTS.md` + `UserPromptSubmit`/`SessionStart(compact)` hooks in Codex's `hooks.json` when Codex is installed (trust them once in `/hooks`); session capture is opt-in with `hippo hook install codex`, which wraps the Codex launcher |
818
820
  | Cursor | `AGENTS.md` | `AGENTS.md`, which Cursor reads from the project root |
819
821
  | OpenClaw | `.openclaw` or `AGENTS.md` | `AGENTS.md`; the native plugin is a separate install: `openclaw plugins install hippo-memory` |
@@ -829,7 +831,7 @@ Setup guides on the website: [Claude Code](https://hippo-memory.com/claude-code/
829
831
  If you prefer explicit control:
830
832
 
831
833
  ```bash
832
- hippo hook install claude-code # patches CLAUDE.md + adds the 7 settings.json hook entries listed below
834
+ hippo hook install claude-code # patches CLAUDE.md + adds the 8 settings.json hook entries listed below
833
835
  hippo hook install codex # patches AGENTS.md + adds hooks to Codex's hooks.json + wraps the detected Codex launcher
834
836
  hippo hook install cursor # patches AGENTS.md
835
837
  hippo hook install openclaw # patches AGENTS.md
@@ -844,10 +846,11 @@ This adds a `<!-- hippo:start -->` ... `<!-- hippo:end -->` block that tells the
844
846
 
845
847
  The block asks for nothing a hook already does, because each extra tool call re-reads the whole context. Re-running `hippo init` swaps a block an older hippo wrote for the current one, as long as nobody edited it. It leaves an edited block alone and says so, and never touches text outside the markers.
846
848
 
847
- For Claude Code, it also adds 7 hook entries to `~/.claude/settings.json`:
849
+ For Claude Code, it also adds 8 hook entries to `~/.claude/settings.json`:
848
850
  - a `SessionEnd` hook that runs `hippo sleep` and then `hippo capture` when the session exits. Capture matches the last 20 user and 10 assistant messages of the transcript against word patterns for decisions, rules, errors and preferences. It uses no model unless you turn on `capture.followUpRules` (see Conversation Capture) and does not read earlier turns, so a correction older than that window needs a `hippo remember` by hand.
849
851
  - a `SessionStart` hook that prints the previous session's consolidation log on stderr, where `claude --debug` shows it. When the last sleep failed or a compaction summary was set aside, it shows you one line that points to `hippo doctor`.
850
- - a `UserPromptSubmit` hook that runs `hippo context --pinned-only --include-recent 5 --format additional-context` every turn. It re-injects pinned memories (`hippo remember <text> --pin`) plus up to 5 memories that share words with your prompt. When nothing matches, it adds only the pinned ones. Since 1.55.0 this replaces the 5 newest memories, which cut the median block from 847 to 533 tokens in our eval. `{"pinnedInject":{"promptRecall":false}}` brings back the 5 newest, so fresh same-session lessons appear on the next prompt whatever you ask. The block is rendered without live strength percentages, so it stays byte-identical while its memories do not change, and it is sent only when it changed since the session's last prompt: an unchanged block is skipped, resent every 10 skips (`pinnedInject.refreshTurns`, `0` never resends) and resent after compaction. The prompt-matched memories go in a separate block that is never skipped, so they are sent on every prompt they match. `{"pinnedInject":{"skipUnchanged":false}}` sends the pinned block every turn as before. Opt out entirely with `{"pinnedInject":{"enabled":false}}` in `.hippo/config.json`.
852
+ - a second `SessionStart` hook that runs `hippo session-rules`, which prints the rules you taught under `## Rules from the user` and nothing else. It has no matcher, so a resumed or cleared session and a compaction get the rules again.
853
+ - a `UserPromptSubmit` hook that runs `hippo context --pinned-only --include-recent 5 --format additional-context` every turn. It re-injects pinned memories (`hippo remember <text> --pin`) plus up to 5 memories that share words with your prompt. When nothing matches, it adds only the pinned ones. Since 1.55.0 this replaces the 5 newest memories, which cut the median block from 847 to 533 tokens in our eval. `{"pinnedInject":{"promptRecall":false}}` brings back the 5 newest, so fresh same-session lessons appear on the next prompt whatever you ask. The block is rendered without live strength percentages, so it stays byte-identical while its memories do not change, and it is sent only when it changed since the session's last prompt: an unchanged block is skipped, resent every 10 skips (`pinnedInject.refreshTurns`, `0` never resends) and resent after compaction. The prompt-matched memories go in a separate block that is never skipped, so they are sent on every prompt they match. `{"pinnedInject":{"skipUnchanged":false}}` sends the pinned block every turn as before. `{"pinnedInject":{"excludeTags":["session-digest"]}}` leaves out every memory that carries a listed tag, whether it is pinned, recent or matched to the prompt; the list is empty by default. Opt out entirely with `{"pinnedInject":{"enabled":false}}` in `.hippo/config.json`.
851
854
  - a `PreCompact` hook that runs `hippo pre-compact` before the transcript gets summarized. It records the compaction in the store, saves a working-state snapshot (task/summary/next step) so mid-session compaction can't drop it, and asks the summariser to end its summary with a "Memories for hippo" list: the lessons, decisions and corrections from the session that should outlive it. The `SessionEnd` hook still owns extracting durable memories from the transcript.
852
855
  - a second `SessionStart` hook (matcher `compact`) that runs `hippo compact-resume`, printing that snapshot back into context right after compaction, if it is under 15 minutes old.
853
856
  - a `PostCompact` hook that runs `hippo post-compact`. It keeps the summary in the store with secrets scrubbed, and saves each item of that list as a memory that sleep never deletes: at most 10 per compaction, skipping an item an earlier compaction already saved and any item that looks like a secret. An item over 500 characters stays in the compaction's record only. It then prints one line, such as "Hippo saved 3 memories from this compaction and restored your task snapshot." If the store is busy, the summary waits in the store's `compactions-spool/` folder and `hippo sleep` finishes the save; `hippo doctor` names any compaction left unfinished for over 10 minutes. It also counts spool files that are waiting, stale (left by a replay that stopped) or set aside as `.bad`. The session that compacted does not have those memories injected back into its own prompts, since it just read them in the summary; `hippo recall` still finds them. The hook prints nothing when there is no store to save to.
@@ -934,7 +937,7 @@ Plugin docs: [extensions/openclaw-plugin/](extensions/openclaw-plugin/). Integra
934
937
 
935
938
  ### Claude Code Plugin
936
939
 
937
- Plugin with session, prompt and compaction hooks plus error auto-capture. See [extensions/claude-code-plugin/](extensions/claude-code-plugin/).
940
+ Plugin with session, prompt and compaction hooks, error auto-capture, and the `hippo-memory` MCP server (`hippo mcp`). See [extensions/claude-code-plugin/](extensions/claude-code-plugin/).
938
941
 
939
942
  Full integration details: [integrations/](integrations/)
940
943
 
@@ -1107,59 +1110,59 @@ node run.mjs --adapter all
1107
1110
 
1108
1111
  ### How do I give Claude Code memory between sessions?
1109
1112
 
1110
- Run `npm install -g hippo-memory`, then `hippo init` in the project. If the project has a `CLAUDE.md`, init adds a short block saying the prompt hook injects pinned rules and matching memories, and asking Claude to run `hippo context --auto` at the start of a task only if no hippo memory block has appeared. It also adds hooks to Claude Code's settings that keep your pinned memories in context, save a task snapshot before compaction, and run `hippo sleep` when the session ends. `hippo init --scan ~` gives every git repo under your home folder a store and installs the same hooks, but adds no block to any `CLAUDE.md`. The [Claude Code plugin](https://github.com/kitfunso/hippo-memory/tree/master/extensions/claude-code-plugin) is the alternative to these hooks; use one, not both.
1113
+ Run `npm install -g hippo-memory`, then `hippo init` in the project. Init adds a short block to an existing `CLAUDE.md` and installs hooks that keep pinned memories in context, save your task before compaction, store failed tool calls and run `hippo sleep` when the session ends.
1111
1114
 
1112
1115
  ### How do I give Cursor memory between sessions?
1113
1116
 
1114
- `hippo init` adds its instructions to `AGENTS.md` if the project has one, and Cursor reads that file from the project root. The [MCP server](#mcp-server) gives Cursor's agent tools to recall and store memories once you add `hippo mcp` to `.cursor/mcp.json`. Older hippo versions wrote the block to `.cursorrules`; `hippo hook uninstall cursor` removes it from there, and from `AGENTS.md` only when the block there is Cursor's own and unedited (`hippo hook install cursor` puts it back). A block written for Codex or another agent stays, since Cursor reads it too, and so does an edited block, since hippo cannot tell whose it is. `hippo import --cursor .cursor/rules` turns your existing rules into memories; it reads an older single `.cursorrules` file too.
1117
+ `hippo init` adds its instructions to `AGENTS.md` if the project has one, which Cursor reads. Add `hippo mcp` to `.cursor/mcp.json` and Cursor's agent gets tools to recall and store memories. `hippo import --cursor .cursor/rules` turns your existing rules into memories.
1115
1118
 
1116
1119
  ### How do I give Codex memory across sessions?
1117
1120
 
1118
- `hippo init` adds its instructions to your `AGENTS.md`, which Codex reads before it starts work. Capturing Codex sessions is opt-in: `hippo hook install codex` wraps the Codex launcher, and `hippo hook uninstall codex` removes the wrapper.
1121
+ `hippo init` adds its instructions to your `AGENTS.md`, which Codex reads before it starts work. Capturing Codex sessions is opt-in, with `hippo hook install codex`.
1119
1122
 
1120
1123
  ### Which agents does hippo work with?
1121
1124
 
1122
- `hippo init` detects Claude Code, Codex, Cursor, OpenClaw, OpenCode and Pi, and wires itself into each one's instruction file, hooks or plugin. It only patches instruction files that already exist. Any MCP client can use the [MCP server](#mcp-server), and other tools can call the CLI or the HTTP API that `hippo serve` starts.
1125
+ `hippo init` detects Claude Code, Codex, Cursor, OpenClaw, OpenCode and Pi, and wires itself into each one's instruction file, hooks or plugin. What runs automatically differs by agent. Any MCP client can use the [MCP server](#mcp-server), and anything else can call the CLI.
1123
1126
 
1124
1127
  ### Can I use hippo as an MCP memory server?
1125
1128
 
1126
- Yes. `hippo mcp` runs the server over stdio, and `npx -y hippo-memory mcp` runs it without a global install. Add it to the MCP config of Claude Desktop, Cursor, Windsurf (now Devin Desktop), Cline or any other client (example [above](#mcp-server)); in Claude Code, run `claude mcp add hippo-memory -- hippo mcp`. The agent gets tools such as `hippo_recall`, `hippo_remember` and `hippo_outcome`.
1129
+ Yes. `hippo mcp` runs the server over stdio. Add it to the MCP config of Cursor, Claude Desktop, Windsurf (now Devin Desktop), Cline or any other client, or in Claude Code run `claude mcp add hippo-memory -- hippo mcp`.
1127
1130
 
1128
1131
  ### How is hippo different from mem0?
1129
1132
 
1130
- mem0 uses a language model to extract memories, OpenAI by default in its open-source library, and memories stored through its hosted MCP server live in your Mem0 account ([mem0 docs](https://docs.mem0.ai/platform/mem0-mcp), checked 2026-09-28). Hippo stores memories in SQLite on your machine, needs no account and no model, and `hippo init` wires it into the coding agents it finds. mem0's platform and hippo both mark an older fact superseded when a newer one replaces it. Hippo also lets you mark a recalled memory wrong with `hippo outcome --bad`, and it drops out of the top results.
1133
+ mem0 uses a language model to extract memories, and its hosted MCP server keeps them in your Mem0 account ([mem0 docs](https://docs.mem0.ai/platform/mem0-mcp), checked 2026-09-28). Hippo stores memories in SQLite on your machine and needs no account and no model. On LoCoMo, a public test of questions about long conversations, Mem0 scored 94.9 and hippo 89.4 when we ran both.
1131
1134
 
1132
1135
  ### Is this just RAG?
1133
1136
 
1134
- No. RAG searches a fixed corpus. Hippo's store changes as your agent works: a memory marked wrong drops out of the top results, a newer fact supersedes the old one, and memories that keep getting recalled last longer while unused ones fade on a half-life. Recall itself is search: BM25, plus embeddings if you install them.
1137
+ Partly. Recall is search, BM25 plus embeddings if you install them. The difference is that the store changes as your agent works. A memory you mark wrong drops down the results, a newer fact replaces an old one, and unused memories fade.
1135
1138
 
1136
1139
  ### Does it need embeddings?
1137
1140
 
1138
- No. Recall runs on BM25 out of the box, with no model and no network call, and a default install has no embedder. Embeddings are an optional install for hybrid search. On LongMemEval-S, where each question gets its own haystack, the benchmark scripts (not `hippo recall`) fuse BM25 with the free local MiniLM embedder and reach 98.0% recall@5, counting a hit when any answer session is in the top five. On LongMemEval's oracle split with one pooled store, BM25 alone scored 74.0% recall@5 in v0.11. The two runs use different setups, so they are not a before and after.
1141
+ No. Recall runs on BM25 out of the box, with no model and no network call. With the optional free local embedder on, hippo scored higher than without it on two of five public answer tests, by 3.4 and 11.9 points, with no clear difference on the other three.
1139
1142
 
1140
1143
  ### Do I still need CLAUDE.md?
1141
1144
 
1142
- Yes, for short standing rules such as build commands, code style and things never to do. Claude Code loads `CLAUDE.md` and its auto memory into every session, and its [memory docs](https://code.claude.com/docs/en/memory) say that when two rules contradict each other, Claude may pick one arbitrarily. Hippo holds the lessons that pile up, recalls the ones that match the task, and retires the ones marked wrong or replaced. `hippo init` adds its block to `CLAUDE.md`, and `hippo import --claude CLAUDE.md` turns existing notes into memories.
1145
+ Yes, for short standing rules such as build commands and code style. Claude Code's [memory docs](https://code.claude.com/docs/en/memory) say that when two rules contradict each other, Claude may pick one arbitrarily. Hippo holds the lessons that pile up and recalls the ones that match the task.
1143
1146
 
1144
1147
  ### What happens when a memory turns out to be wrong?
1145
1148
 
1146
- Mark it, and it drops out of the top results. `hippo outcome --bad` weakens the memories from the last recall, `hippo supersede <id> "<new fact>"` replaces one with a newer version, and `hippo reject <id> --reason "<why>"` stops that value from returning at all. On the synthetic E1 test, where every mark is correct, plain BM25 plus the outcome mark cut how often a marked-bad memory stayed in the top five from 71.9% to 0.0%. Real marks are noisier, because `--bad` marks the whole recall batch.
1149
+ `hippo outcome --bad` weakens the memories from the last recall, and `hippo supersede <id> "<new fact>"` replaces one. On a synthetic test where every mark was correct, a bad mark cut how often a wrong memory stayed in the top five from 71.9% to 0.0%. Real marks are noisier.
1147
1150
 
1148
1151
  ### Where does hippo keep my data?
1149
1152
 
1150
- On your machine, in SQLite: `.hippo/hippo.db` in each project, plus a global store in `~/.hippo/` for lessons shared across projects, with markdown mirrors you can read and commit. Recall makes no network call by default. Text goes to an outside provider only through features that use one: an API embedder, the Jev or LLM reranker, `hippo refine`, and the fact extraction `hippo sleep` runs through Anthropic's API whenever `ANTHROPIC_API_KEY` is set in its environment. To turn that last one off, set `{"extraction":{"enabled":false}}` in `.hippo/config.json`.
1153
+ On your machine, in SQLite, as `.hippo/hippo.db` in each project and a global store in `~/.hippo/`, with markdown mirrors you can read and commit. Recall makes no network call by default. Text leaves your machine only through an API embedder, a reranker, model-read rule capture (`capture.followUpRules`), `hippo refine`, or `hippo sleep` when `ANTHROPIC_API_KEY` is set. `{"extraction":{"enabled":false}}` in `.hippo/config.json` turns that last one off.
1151
1154
 
1152
1155
  ### What does hippo cost?
1153
1156
 
1154
- Nothing. Hippo is MIT-licensed and needs no account or API key. Optional features that call an outside provider bill through it: the Jev reranker costs about 0.0004 USD a recall, and API embedders and sleep's fact extraction bill your own keys. Memory text handed to your agent uses context tokens, and `hippo tokens` shows how many.
1157
+ Nothing. Hippo is MIT-licensed and needs no account or API key. Optional features that call an outside provider bill through it. The Jev reranker costs about 0.0004 USD a recall, and API embedders and sleep's fact extraction use your own keys.
1155
1158
 
1156
1159
  ### Is it production-ready?
1157
1160
 
1158
- Judge it by what is tested. 3,500+ tests run against a real database, with no module mocks and no mocked store, and a negative test checks that one tenant cannot read another's memories. It is MIT-licensed and has zero runtime dependencies. What has not been shown yet is whether agents do better work with it: the published numbers measure retrieval.
1161
+ Judge it by what is tested. 3,500+ tests run against a real database, with no module mocks and no mocked store. It has zero runtime dependencies. The next question covers what it does to an agent's work.
1159
1162
 
1160
1163
  ### Has hippo been shown to make agents better at their work?
1161
1164
 
1162
- Not yet. The published numbers measure retrieval: whether the right memory comes back, and whether a memory marked wrong stays out of the results. A paired test that runs real agent sessions with and without hippo is under way. Every measurement, including failed runs and one retracted claim, is indexed in [docs/evals](https://github.com/kitfunso/hippo-memory/blob/master/docs/evals/README.md).
1165
+ On repeat mistakes, yes, in [one test of our own](https://github.com/kitfunso/hippo-memory/blob/master/docs/evals/2026-11-08-z0-round3-result.md). We corrected Claude Code once on 29 repositories and counted repeats 2 to 4 tasks later, finding 11 in 100 with hippo added, against 21 with built-in memory alone, at the same cost. We can't yet say why, because the gain was the same with lesson capture switched off. Failed runs are in [docs/evals](https://github.com/kitfunso/hippo-memory/blob/master/docs/evals/README.md) too.
1163
1166
 
1164
1167
  ---
1165
1168
 
@@ -11,9 +11,12 @@ export interface AutoSleepHost {
11
11
  /** The rows `tenantId` wrote since the store's last sleep, counted on the store of the call
12
12
  * that wrote, so a write's count opens no second connection. */
13
13
  readonly newSince: (tenantId: string, now: Date) => Promise<number>;
14
- /** Held while a sleep is counted or run, so two writes landing together start one. */
14
+ /** `held` is set while a sleep is counted or run, so two writes landing together start one.
15
+ * `notBefore` is the epoch ms before which no write retries, set after a sleep another process
16
+ * made this host skip. */
15
17
  readonly latch: {
16
18
  held: boolean;
19
+ notBefore?: number;
17
20
  };
18
21
  }
19
22
  export type AutoSleepStart = Omit<AutoSleepHost, 'latch'>;
@@ -129,6 +129,8 @@ export function planContext(ctx, opts, local) {
129
129
  /** The prompt-recall candidate request the ambient loads carry, when the prompt has any terms. */
130
130
  export function promptRecallRequest(opts, plan) {
131
131
  const { pinnedInject } = plan.config;
132
+ // Optional: a config built in code before this key existed has none, and reads as no list.
133
+ const excludeTags = pinnedInject.excludeTags ?? [];
132
134
  const promptRecallTerms = plan.promptRecallPending && pinnedInject.enabled ? promptSearchTerms(opts.prompt ?? '') : [];
133
135
  return promptRecallTerms.length > 0
134
136
  ? {
@@ -138,6 +140,7 @@ export function promptRecallRequest(opts, plan) {
138
140
  min: 1,
139
141
  })),
140
142
  ownScope: plan.ownScope,
143
+ ...(excludeTags.length > 0 && { excludeTags }),
141
144
  }
142
145
  : undefined;
143
146
  }
@@ -68,6 +68,8 @@ export function ambientAdmission(opts, plan, digestHandoff) {
68
68
  // Inside admit, not after the load, so the loader's window widens past a session's own items.
69
69
  ownSessionId: opts.currentSessionId || undefined,
70
70
  handoffSessionId: digestHandoff?.evidence?.derivedFrom === 'transcript' ? digestHandoff.sessionId : undefined,
71
+ // Only the hook block's pinned-only reads drop tags; a search or plain context read keeps them.
72
+ excludeTags: plan.pinnedOnly ? plan.config.pinnedInject.excludeTags : undefined,
71
73
  };
72
74
  const admit = (e) => ambientAdmits(e, rule);
73
75
  // The two-store search has always ranked a session's own compaction items; only the local search
@@ -1,5 +1,5 @@
1
1
  import type { ContextOptions, ContextResult } from './context-types.js';
2
- import type { Context } from '../types.js';
2
+ import { type Context } from '../types.js';
3
3
  /** Tokens a context block may use when the caller sets no budget; the hook command and the CLI
4
4
  * default match it. */
5
5
  export declare const DEFAULT_CONTEXT_BUDGET = 1500;
@@ -9,6 +9,7 @@ import { selectPinned, selectStrongest } from './context-select.js';
9
9
  import { selectBySearch } from './context-search.js';
10
10
  import { strengthenOf } from '../recall/finish.js';
11
11
  import { keepShownIds } from '../recall/last-recalled.js';
12
+ import { readOnlyOf } from '../types.js';
12
13
  import { NO_QUERY, sourceOf, globalSource, planContext, promptRecallRequest, openBlockBudget, } from './context-plan.js';
13
14
  import { ambientAdmission, loadPools, userRuleReserve } from './context-pools.js';
14
15
  import { loadTaskSections, pointerModes } from './context-task-state.js';
@@ -51,7 +52,7 @@ export async function assembleContext(ctx, opts) {
51
52
  if (items.length === 0 && noSections) {
52
53
  // A query that found nothing is the coverage-gap signal, so it still gets a trace; pinned-only
53
54
  // stays read-only.
54
- if (!plan.pinnedOnly)
55
+ if (!plan.pinnedOnly && !readOnlyOf(ctx))
55
56
  await traceEmptyContext(ctx, opts, plan);
56
57
  return { entries: [], tokens: 0 };
57
58
  }
@@ -156,14 +157,17 @@ async function recordRetrieval(ctx, { opts, plan, selected, activeSnapshot }) {
156
157
  })),
157
158
  };
158
159
  const writes = { goalLog: [], audit: [], trace, strengthen: strengthenOf(ctx, retrievedIds) };
159
- // The last recall feeds only outcomeForLastRecall, so a store that keeps none still finishes the
160
- // recall without one.
161
- const store = ctx.store;
162
- const traceId = store.lastRecall
163
- ? await store.lastRecall.finishRecall(writes, plan.hasGlobal ? plan.globalRoot : undefined)
164
- : await store.finishRecall(writes).then(() => null);
165
- plan.obs?.traced(traceId);
166
- await store.bumpRecallStats(selected.length);
160
+ // A read-only store keeps its rows; the reply still shows them as this retrieval left them.
161
+ if (!readOnlyOf(ctx)) {
162
+ // The last recall feeds only outcomeForLastRecall, so a store that keeps none still finishes the
163
+ // recall without one.
164
+ const store = ctx.store;
165
+ const traceId = store.lastRecall
166
+ ? await store.lastRecall.finishRecall(writes, plan.hasGlobal ? plan.globalRoot : undefined)
167
+ : await store.finishRecall(writes).then(() => null);
168
+ plan.obs?.traced(traceId);
169
+ await store.bumpRecallStats(selected.length);
170
+ }
167
171
  // Replace selectedItems entries with markRetrieved-updated copies so the returned ContextResult
168
172
  // reflects post-recall state.
169
173
  const items = selected.map((s) => ({
@@ -1,7 +1,7 @@
1
1
  import type { LedgerTurn } from '../base/ports/store.js';
2
2
  import type { TokenSurface, TokenUse } from '../base/ports/store/ledger.js';
3
3
  import type { LastSent } from '../base/session/skip-unchanged.js';
4
- import type { Context, GlobalInReach, LedgerHome } from './types.js';
4
+ import { type Context, type GlobalInReach, type LedgerHome } from './types.js';
5
5
  import { type DeliveryFault, type DeliveryRecorder } from './delivery/delivery-recorder.js';
6
6
  import type { DeliveryEventInput, DeliveryEventType } from '../base/session/delivery.js';
7
7
  import type { HookRuntime } from '../base/session/capture-contract.js';
@@ -10,10 +10,12 @@ import type { HookRuntime } from '../base/session/capture-contract.js';
10
10
  export interface LedgerReach {
11
11
  readonly local?: LedgerHome;
12
12
  readonly global?: GlobalInReach;
13
+ /** Under HIPPO_READ_ONLY=1 the rows are still read, so a skip decision holds, and never booked. */
14
+ readonly readOnly?: true;
13
15
  }
14
16
  /** Only a store that keeps a ledger has one, and a local one needs a reach that says the caller
15
17
  * has a store. */
16
- export declare function ledgerReachOf(ctx: Pick<Context, 'reach'>, shared?: boolean): LedgerReach;
18
+ export declare function ledgerReachOf(ctx: Pick<Context, 'reach' | 'config'>, shared?: boolean): LedgerReach;
17
19
  /** The call's own store, else the global store (the prompt hook fires where none is); null with
18
20
  * neither. */
19
21
  export declare function ledgerHome(reach: LedgerReach): LedgerHome | null;
@@ -1,3 +1,4 @@
1
+ import { readOnlyOf } from './types.js';
1
2
  import { createDeliveryRecorder, } from './delivery/delivery-recorder.js';
2
3
  import { errorMessage, log, errorFields } from '../base/util/log.js';
3
4
  function homeOf(global) {
@@ -11,7 +12,8 @@ function homeOf(global) {
11
12
  * has a store. */
12
13
  export function ledgerReachOf(ctx, shared) {
13
14
  const local = ctx.reach?.hasLocal === true ? ctx.reach.ledger : undefined;
14
- return shared === true ? { local } : { local, global: ctx.reach?.global };
15
+ const reach = shared === true ? { local } : { local, global: ctx.reach?.global };
16
+ return readOnlyOf(ctx) ? { ...reach, readOnly: true } : reach;
15
17
  }
16
18
  /** The call's own store, else the global store (the prompt hook fires where none is); null with
17
19
  * neither. */
@@ -23,16 +25,22 @@ export function ledgerHome(reach) {
23
25
  }
24
26
  /** Books one row in ledgerHome's store, best-effort. */
25
27
  export async function bookTokenUse(use, reach) {
28
+ if (reach.readOnly === true)
29
+ return;
26
30
  await ledgerHome(reach)?.ledger.recordTurn({ uses: [use] });
27
31
  }
28
32
  /** Books a turn's rows and then its delivery event on one connection of ledgerHome's store,
29
33
  * best-effort. */
30
34
  export async function bookLedgerTurn(turn, reach) {
35
+ if (reach.readOnly === true)
36
+ return;
31
37
  await ledgerHome(reach)?.ledger.recordTurn(turn);
32
38
  }
33
39
  /** bookLedgerTurn where each row is its own attempt: a row that fails is noted and the rest
34
40
  * still land. */
35
41
  export async function bookLedgerTurnPerRow(turn, reach) {
42
+ if (reach.readOnly === true)
43
+ return;
36
44
  await ledgerHome(reach)?.ledger.recordTurn({ ...turn, perRow: true });
37
45
  }
38
46
  /** What the session last sent on `surface` in ledgerHome's store; null with no ledger, no row or
@@ -43,6 +51,8 @@ export async function ledgerLastSent(tenantId, sessionId, surface, reach) {
43
51
  /** A delivery recorder for a hook on `ctx`'s store when the ledger store enables one, else null;
44
52
  * never throws. */
45
53
  export async function startDeliveryRecorder(ctx, start) {
54
+ if (readOnlyOf(ctx))
55
+ return null;
46
56
  try {
47
57
  // The same store the token ledger writes to, so its config governs both.
48
58
  const reach = ledgerReachOf(ctx);
@@ -1,8 +1,7 @@
1
- import type { MemoryEntry } from '../../base/memory/entry.js';
2
1
  import type { Incident, Policy, ProjectBrief } from '../../base/records/object-types.js';
3
2
  import { type SaveIncidentOptions } from '../../domain/objects/incidents.js';
4
3
  import { type BriefDigest } from '../../domain/objects/project-briefs.js';
5
- import type { Context, ContextWith } from '../types.js';
4
+ import type { ContextWith } from '../types.js';
6
5
  import { type WriteOrigin } from './objects.js';
7
6
  export type { BriefDigest } from '../../domain/objects/project-briefs.js';
8
7
  export type { SaveIncidentOptions } from '../../domain/objects/incidents.js';
@@ -39,6 +38,4 @@ export declare function briefRefresh(ctx: ContextWith<'objects'>, repo: string):
39
38
  /** The active decision whose mirror is `memoryId`, or null: what the CLI's `--supersedes
40
39
  * <memory-id>` names. */
41
40
  export declare function decisionIdByMemory(ctx: ContextWith<'objects'>, memoryId: string): Promise<number | null>;
42
- /** Weakens the memory a new decision replaces, once that decision has saved. */
43
- export declare function decisionMemoryWeaken(ctx: Context, entry: MemoryEntry): Promise<void>;
44
41
  //# sourceMappingURL=object-kinds.d.ts.map
@@ -1,6 +1,6 @@
1
1
  import { MAX_CUSTOMER_LEN, MAX_NOTE_LEN } from '../../domain/objects/customer-notes.js';
2
2
  import { MAX_SHORT_FIELD_LEN } from '../../base/util/limits.js';
3
- import { resolveActiveDecisionIdByMemory, weakenSupersededMemory, } from '../../domain/objects/decisions.js';
3
+ import { resolveActiveDecisionIdByMemory } from '../../domain/objects/decisions.js';
4
4
  import { openIncident, resolveOpenIncident, } from '../../domain/objects/incidents.js';
5
5
  import { policiesAsOf } from '../../domain/objects/policies.js';
6
6
  import { MAX_PROCESS_STEP_LEN, MAX_PROCESS_STEPS } from '../../domain/objects/processes.js';
@@ -70,8 +70,4 @@ export function briefRefresh(ctx, repo) {
70
70
  export function decisionIdByMemory(ctx, memoryId) {
71
71
  return resolveActiveDecisionIdByMemory(ctx.store.objects, ctx.tenantId, memoryId);
72
72
  }
73
- /** Weakens the memory a new decision replaces, once that decision has saved. */
74
- export function decisionMemoryWeaken(ctx, entry) {
75
- return weakenSupersededMemory(ctx.store.entryWrites, entry, ctx.actor.subject);
76
- }
77
73
  //# sourceMappingURL=object-kinds.js.map
@@ -13,6 +13,9 @@ export async function sessionPilotArm(tenantId, sessionId, write, opts) {
13
13
  if (rate <= 0)
14
14
  return null;
15
15
  const { ownTenantOnly } = opts;
16
- return home.ledger.pilotArm(tenantId, sessionId, rate, { write, ownTenantOnly });
16
+ return home.ledger.pilotArm(tenantId, sessionId, rate, {
17
+ write: write && opts.reach.readOnly !== true,
18
+ ownTenantOnly,
19
+ });
17
20
  }
18
21
  //# sourceMappingURL=pilot-arm.js.map
@@ -2,7 +2,7 @@
2
2
  // counter, token ledger row and the client's shown list).
3
3
  import { auditQueryFields } from '../../base/records/audit-report.js';
4
4
  import { recordTokens } from '../tokens.js';
5
- import { strengthOf } from '../types.js';
5
+ import { readOnlyOf, strengthOf } from '../types.js';
6
6
  import { keepShownIds } from './last-recalled.js';
7
7
  import { biasHintEnabled, } from './anchoring.js';
8
8
  import { sessionRing, peekSessionRing, noteRecall } from './session-rings.js';
@@ -116,7 +116,8 @@ export async function recordShownRecall(ctx, store, how, shown) {
116
116
  }
117
117
  const items = how.counts === 'none' ? 0 : shown.ids.length;
118
118
  // A recall with no audit row counts nothing, as it strengthens and traces nothing.
119
- if (shown.written && (how.counts === 'every' || items > 0))
119
+ const counted = shown.written && !readOnlyOf(ctx) && (how.counts === 'every' || items > 0);
120
+ if (counted)
120
121
  await store.bumpRecallStats(items);
121
122
  // The ledger books text that was sent, so its row does not wait on the audit write.
122
123
  await recordTokens(ctx, how.ledger, {
@@ -3,7 +3,7 @@
3
3
  // request.ts.
4
4
  import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../../base/rank/search-types.js';
5
5
  import { assertScopeRequestAllowed, personalScopeOf } from '../../base/scope/recall-scope.js';
6
- import { ownerOrSubject, RecallContractError, sharedStoreOf } from '../types.js';
6
+ import { ownerOrSubject, readOnlyOf, RecallContractError, sharedStoreOf, } from '../types.js';
7
7
  import { callerOf, recallAuditMetadata, recallAuditRow, recallLead, recordShownRecall, shownRecallRows, strengthenOf, } from './finish.js';
8
8
  import { composeRecall, planRecall, recallOrigin, } from './compose.js';
9
9
  import { rankCtxOf, rankRecall, } from './pipeline.js';
@@ -125,6 +125,8 @@ function rankRequestOf(ctx, opts, windowSize, personalScope) {
125
125
  /** The one recall write: the caller's leading audit rows go first, and the ids shown are the
126
126
  * ones strengthened. */
127
127
  async function finishRecall(ctx, opts, writes, shownIds) {
128
+ if (readOnlyOf(ctx))
129
+ return;
128
130
  await ctx.store.finishRecall({
129
131
  ...writes,
130
132
  audit: [...(opts.trace?.leadingAudit ?? []), ...writes.audit],
@@ -1,7 +1,7 @@
1
1
  import { BadRequestError } from '../../base/errors/api-errors.js';
2
2
  import { type JsonValue } from '../../base/util/json.js';
3
3
  import type { ContextOptions } from '../context/context-types.js';
4
- import type { Context } from '../types.js';
4
+ import { type Context } from '../types.js';
5
5
  import type { CliCoreRanker, RecallBoostOptions, RecallFilterOptions, CliCoreQuery, RecallOptions, RecallResult, RecallWindowOptions } from './types.js';
6
6
  /** A recall or context input the caller must fix; MCP answers it with an isError result, HTTP
7
7
  * with a 400. */
@@ -7,6 +7,7 @@ import { reportAuditWriteFailure } from '../../base/records/audit-report.js';
7
7
  import { isJsonString } from '../../base/util/json.js';
8
8
  import { MAX_ID_LEN } from '../../base/util/limits.js';
9
9
  import { estimateTokens } from '../../base/util/token-text.js';
10
+ import { readOnlyOf } from '../types.js';
10
11
  import { rankCtxOf, rankRecall } from './pipeline.js';
11
12
  import { BUDGET_RANKED } from './profiles.js';
12
13
  import { callerOf, heldIds, RECALL_RECORDING, recallAuditMetadata, recallAuditRow, recordShownRecall, shownRecallRows, strengthenOf, } from './finish.js';
@@ -210,7 +211,8 @@ async function recordShown(ctx, { store, opts, core, done }) {
210
211
  strengthen: strengthenOf(ctx, ids),
211
212
  trace: traceOf(ctx, opts, core, shown.results),
212
213
  };
213
- const audited = await finishOrReport(() => finishShown(store, core.lastRecall, writes, ids.length > 0));
214
+ const audited = !readOnlyOf(ctx) &&
215
+ (await finishOrReport(() => finishShown(store, core.lastRecall, writes, ids.length > 0)));
214
216
  if (audited && second !== undefined)
215
217
  await finishSecond(ctx, second, recallRow, heldElsewhere);
216
218
  // The caller prints whether or not the record was written, so the ring and the ledger still take
@@ -51,8 +51,9 @@ export interface SessionEndWork<Turn, Scan extends {
51
51
  }) => void;
52
52
  /** Where the re-read count's lines wait for sleep. */
53
53
  held: HeldLog;
54
- /** Sleeps the folder's own store; reports its own failure. */
55
- sleep: () => Promise<void>;
54
+ /** Sleeps the folder's own store; reports its own failure. True when another sleep held the
55
+ * store's claim, so this one consolidated nothing. */
56
+ sleep: () => Promise<boolean | void>;
56
57
  /** Imports the session's agent notes into the global store, for a folder that does not sleep
57
58
  * here. */
58
59
  importAgentNotes: () => Promise<void>;
@@ -173,8 +173,10 @@ async function sleepStep(ctx, w) {
173
173
  await w.importAgentNotes();
174
174
  return;
175
175
  }
176
- if (w.mode !== 'turn' || !w.sessionId)
177
- return w.sleep();
176
+ if (w.mode !== 'turn' || !w.sessionId) {
177
+ await w.sleep();
178
+ return;
179
+ }
178
180
  // Each line starts the log afresh, as a sleep does.
179
181
  const prefix = `turn close, session ${w.sessionId}`;
180
182
  try {
@@ -184,8 +186,10 @@ async function sleepStep(ctx, w) {
184
186
  w.log(`${prefix}: skip sleep, ${why}`, { startFresh: true });
185
187
  return;
186
188
  }
187
- await w.sleep();
188
- w.log(`${prefix}: ran sleep at ${count} new memories (threshold ${threshold})`);
189
+ const refused = await w.sleep();
190
+ w.log(refused
191
+ ? `${prefix}: skip sleep, a sleep is already running`
192
+ : `${prefix}: ran sleep at ${count} new memories (threshold ${threshold})`);
189
193
  }
190
194
  catch (err) {
191
195
  w.log(`${prefix}: sleep check failed: ${errorMessage(err)}`, {
@@ -1,4 +1,5 @@
1
1
  import type { MemoryEntry } from '../base/memory/entry.js';
2
+ import { type ShareOutcome } from '../domain/sharing/share.js';
2
3
  import { type Context, type ContextWith } from './types.js';
3
4
  export { AUTO_SHARE_MIN_SCORE, transferScore } from '../domain/sharing/share.js';
4
5
  /** One project's rows in the global store. */
@@ -7,11 +8,11 @@ export interface SharePeer {
7
8
  readonly count: number;
8
9
  readonly latest: string;
9
10
  }
10
- /** Copies one of the caller's memories to the global store; null when its transfer score is too
11
- * low and `force` is off. */
11
+ /** Copies one of the caller's memories to the global store unless its transfer score is too low
12
+ * and `force` is off, or the caller's global rows already hold its text. */
12
13
  export declare function shareToGlobal(ctx: ContextWith<'folderFiles'>, id: string, opts: {
13
14
  readonly force: boolean;
14
- }): Promise<MemoryEntry | null>;
15
+ }): Promise<ShareOutcome>;
15
16
  /** The caller's memories whose transfer score reaches `minScore`, copied to the global store
16
17
  * unless `dryRun`. */
17
18
  export declare function autoShareToGlobal(ctx: ContextWith<'sharing' | 'folderFiles'>, opts: {
@@ -17,8 +17,8 @@ function requireGlobalTarget(ctx, action) {
17
17
  }
18
18
  return target;
19
19
  }
20
- /** Copies one of the caller's memories to the global store; null when its transfer score is too
21
- * low and `force` is off. */
20
+ /** Copies one of the caller's memories to the global store unless its transfer score is too low
21
+ * and `force` is off, or the caller's global rows already hold its text. */
22
22
  export async function shareToGlobal(ctx, id, opts) {
23
23
  const target = requireGlobalTarget(ctx, 'share');
24
24
  const options = { force: opts.force, tenantId: ctx.tenantId, embed: ctx.infra };
@@ -1,12 +1,13 @@
1
1
  import type { HippoConfig } from '../../base/config/config.js';
2
2
  import { type ConsolidationResult } from '../../domain/consolidate/run.js';
3
3
  import { type Context, type ContextWith } from '../types.js';
4
+ import { type AutoSleepRefused } from './one-sleep.js';
4
5
  /**
5
6
  * Runs one auto-sleep consolidation of the folder its host was built for: the HTTP server passes
6
7
  * one that runs it off its event loop, in a child process; stdio passes one that runs it in its
7
8
  * own.
8
9
  */
9
- export type AutoSleepRunner = () => Promise<void>;
10
+ export type AutoSleepRunner = () => Promise<void | AutoSleepRefused>;
10
11
  export interface AutoSleepDue {
11
12
  enabled: boolean;
12
13
  count: number;
@@ -23,5 +24,5 @@ export declare function autoSleepDue(newSince: (tenantId: string, now: Date) =>
23
24
  export declare function autoSleepAfterWrite(ctx: Pick<Context, 'tenantId' | 'config' | 'callers' | 'infra' | 'detached'>): Promise<void>;
24
25
  /** What one auto-sleep runs: the consolidation alone, its skipped passes logged by the process
25
26
  * that ran it. */
26
- export declare function autoSleepConsolidate(ctx: Pick<ContextWith<'consolidation' | 'learning' | 'lessonWrites' | 'auditMaintenance' | 'vectors'>, 'store' | 'config' | 'tenantId' | 'infra'>): Promise<ConsolidationResult>;
27
+ export declare function autoSleepConsolidate(ctx: Pick<ContextWith<'consolidation' | 'learning' | 'lessonWrites' | 'auditMaintenance' | 'vectors'>, 'store' | 'config' | 'tenantId' | 'infra'>): Promise<ConsolidationResult | AutoSleepRefused>;
27
28
  //# sourceMappingURL=auto-sleep.d.ts.map