hippo-memory 3.4.0 → 3.5.1

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 (95) hide show
  1. package/README.md +4 -4
  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/objects/object-kinds.d.ts +1 -4
  6. package/dist/api/objects/object-kinds.js +1 -5
  7. package/dist/api/session-end.d.ts +3 -2
  8. package/dist/api/session-end.js +8 -4
  9. package/dist/api/sharing.d.ts +4 -3
  10. package/dist/api/sharing.js +2 -2
  11. package/dist/api/sleep/auto-sleep.d.ts +3 -2
  12. package/dist/api/sleep/auto-sleep.js +16 -3
  13. package/dist/api/sleep/one-sleep.d.ts +23 -0
  14. package/dist/api/sleep/one-sleep.js +53 -0
  15. package/dist/api/sleep/sleep.d.ts +5 -0
  16. package/dist/api/sleep/sleep.js +2 -1
  17. package/dist/base/config/config-keys.js +1 -0
  18. package/dist/base/config/config.d.ts +2 -0
  19. package/dist/base/config/config.js +1 -0
  20. package/dist/base/embeddings/local.d.ts +1 -1
  21. package/dist/base/embeddings/local.js +2 -3
  22. package/dist/base/ports/store/capture.d.ts +2 -0
  23. package/dist/base/ports/store/consolidation.d.ts +15 -0
  24. package/dist/base/ports/store/consolidation.js +2 -0
  25. package/dist/base/ports/store/context-reads.d.ts +2 -0
  26. package/dist/base/ports/store/objects.d.ts +15 -4
  27. package/dist/base/ports/store/store-effects.d.ts +2 -0
  28. package/dist/base/ports/store.d.ts +1 -1
  29. package/dist/base/scope/read-admission.d.ts +2 -0
  30. package/dist/base/scope/read-admission.js +8 -2
  31. package/dist/base/util/version.d.ts +1 -1
  32. package/dist/base/util/version.js +1 -1
  33. package/dist/db/migrations/index.d.ts +1 -1
  34. package/dist/db/migrations/index.js +3 -1
  35. package/dist/db/migrations/v63.d.ts +3 -0
  36. package/dist/db/migrations/v63.js +9 -0
  37. package/dist/domain/consolidate/merge.js +6 -6
  38. package/dist/domain/consolidate/tombstones.d.ts +3 -4
  39. package/dist/domain/consolidate/tombstones.js +3 -3
  40. package/dist/domain/objects/decisions.d.ts +4 -7
  41. package/dist/domain/objects/decisions.js +1 -9
  42. package/dist/domain/objects/descriptor.d.ts +2 -0
  43. package/dist/domain/objects/lifecycle.js +8 -2
  44. package/dist/domain/sharing/share.d.ts +16 -4
  45. package/dist/domain/sharing/share.js +33 -17
  46. package/dist/entry/store-kit.js +2 -1
  47. package/dist/infra/local-embedder.js +14 -2
  48. package/dist/infra/spool-claims.d.ts +2 -2
  49. package/dist/infra/spool-claims.js +4 -3
  50. package/dist/infra/spool-import.js +1 -1
  51. package/dist/infra/spool-record.d.ts +3 -1
  52. package/dist/store/sqlite/capture/compaction-hooks.js +14 -6
  53. package/dist/store/sqlite/capture/spool-request-id.d.ts +3 -0
  54. package/dist/store/sqlite/capture/spool-request-id.js +12 -0
  55. package/dist/store/sqlite/consolidation/consolidation.js +2 -0
  56. package/dist/store/sqlite/consolidation/sleep-lock.d.ts +4 -0
  57. package/dist/store/sqlite/consolidation/sleep-lock.js +69 -0
  58. package/dist/store/sqlite/entries/entry-filter.js +1 -2
  59. package/dist/store/sqlite/entries/entry-row.js +5 -1
  60. package/dist/store/sqlite/entries/entry-writes.js +3 -10
  61. package/dist/store/sqlite/entries/raw-archive.d.ts +2 -1
  62. package/dist/store/sqlite/entries/raw-archive.js +12 -3
  63. package/dist/store/sqlite/recall/candidates.js +2 -7
  64. package/dist/store/sqlite/recall/search-rows.d.ts +3 -0
  65. package/dist/store/sqlite/recall/search-rows.js +22 -6
  66. package/dist/store/sqlite/records/object-rows.d.ts +2 -0
  67. package/dist/store/sqlite/records/object-rows.js +5 -1
  68. package/dist/store/sqlite/records/object-writes.d.ts +3 -0
  69. package/dist/store/sqlite/records/object-writes.js +43 -1
  70. package/dist/store/sqlite/review/conflicts.js +3 -4
  71. package/dist/store/sqlite/runtime/rule-sql.d.ts +1 -0
  72. package/dist/store/sqlite/runtime/rule-sql.js +2 -0
  73. package/dist/surface/capture/session-worker.d.ts +3 -2
  74. package/dist/surface/capture/session-worker.js +36 -10
  75. package/dist/surface/cli/api-context.js +2 -1
  76. package/dist/surface/cli/client.d.ts +6 -5
  77. package/dist/surface/cli/client.js +50 -19
  78. package/dist/surface/cli/decisions.js +16 -17
  79. package/dist/surface/cli/hooks/session-end-worker.js +3 -2
  80. package/dist/surface/cli/install-steps.js +99 -13
  81. package/dist/surface/cli/memory-writes.js +3 -2
  82. package/dist/surface/cli/sleep-render.js +7 -0
  83. package/dist/surface/cli/sleep.d.ts +3 -2
  84. package/dist/surface/cli/sleep.js +10 -4
  85. package/dist/surface/cli/transfer.js +6 -3
  86. package/dist/surface/hooks-install/codex-wrapper.js +52 -11
  87. package/dist/surface/hooks-install/rules/hook-blocks.js +9 -2
  88. package/dist/surface/mcp/admin-tools.js +5 -2
  89. package/dist/surface/server/routes/decisions.js +2 -2
  90. package/dist/surface/server/sleep-child.js +5 -4
  91. package/dist/surface/server/sleep-offload.js +36 -25
  92. package/extensions/openclaw-plugin/openclaw.plugin.json +1 -1
  93. package/extensions/openclaw-plugin/package.json +1 -1
  94. package/openclaw.plugin.json +1 -1
  95. package/package.json +1 -1
@@ -1,17 +1,17 @@
1
1
  // First-class object verbs for decisions: record one (optionally superseding an older one's
2
2
  // memory), list, get, close.
3
3
  import { memoryGet } from '../../api/memories/memories.js';
4
- import { decisionIdByMemory, decisionMemoryWeaken } from '../../api/objects/object-kinds.js';
4
+ import { decisionIdByMemory } from '../../api/objects/object-kinds.js';
5
5
  import { objectClose, objectCreate, objectGet, objectList, objectStates, } from '../../api/objects/objects.js';
6
6
  import { printError } from './output.js';
7
7
  import { flagValueless, nonEmptyStringFlag, stringFlag, } from './flag-values.js';
8
8
  import { requireInit } from './shared.js';
9
9
  import { cliApiContext } from './api-context.js';
10
10
  import { closeObjectVerb, foundOrExit, idArgOrExit, listObjectsVerb, printLifecycleTail, } from './object-verbs.js';
11
- import { errorMessage } from '../../base/util/log.js';
12
11
  import { fail } from './exit.js';
13
12
  import { shellFolder } from './versioned-verbs.js';
14
13
  const DECISION = { cmd: 'decide', noun: 'Decision', idLabel: 'decision' };
14
+ const NOT_RECORDED = 'The decision was NOT recorded. Nothing changed, so it is safe to run the command again.';
15
15
  function printDecisionRow(d) {
16
16
  const supPart = d.supersededBy !== null ? ` superseded_by=#${d.supersededBy}` : '';
17
17
  console.log(`#${d.id} [${d.status}]${supPart} memory=${d.memoryId ?? '-'}`);
@@ -63,22 +63,20 @@ async function decideCreate(ctx, decisionText, flags) {
63
63
  fail('--supersedes requires a memory id, e.g. hippo decide "<text>" --supersedes mem_abc123.');
64
64
  }
65
65
  const supersedesMemId = stringFlag(flags, 'supersedes') ?? null;
66
- // Commit the table create+supersede first (inside the save's SAVEPOINT) and weaken the old memory
67
- // last, best-effort, so a memory-write failure cannot leave the memory stale while the table
68
- // shows the supersession.
66
+ // The save weakens the old memory in the same write. A decision row backing the memory is
67
+ // weakened through its supersede link; a plain memory is named so the save weakens it too.
69
68
  let supersedesDecisionId;
70
- let oldEntry = null;
69
+ let weakensMemoryId;
71
70
  if (supersedesMemId) {
72
- oldEntry = await memoryGet(ctx, supersedesMemId);
73
- if (!oldEntry) {
71
+ if (!(await memoryGet(ctx, supersedesMemId))) {
74
72
  fail(`Memory ${supersedesMemId} not found.`);
75
73
  }
76
74
  supersedesDecisionId = (await decisionIdByMemory(ctx, supersedesMemId)) ?? undefined;
75
+ if (supersedesDecisionId === undefined)
76
+ weakensMemoryId = supersedesMemId;
77
77
  }
78
- const write = { decisionText, context, supersedesDecisionId };
79
- const created = await objectCreate(ctx, 'decision', write, shellFolder());
80
- if (oldEntry)
81
- await weakenOrWarn(ctx, oldEntry, supersedesMemId);
78
+ const write = { decisionText, context, supersedesDecisionId, weakensMemoryId };
79
+ const created = await recordDecision(ctx, write, Boolean(supersedesMemId));
82
80
  console.log(`Decision recorded: #${created.id}`);
83
81
  if (created.memoryId)
84
82
  console.log(` memory: ${created.memoryId}`);
@@ -91,14 +89,15 @@ function exitWithDecideUsage() {
91
89
  printError(' hippo decide get <id>');
92
90
  fail(' hippo decide close <id>');
93
91
  }
94
- async function weakenOrWarn(ctx, oldEntry, supersedesMemId) {
95
- // Best-effort and last: the decision already committed. Failing here would make a retry find no
96
- // active decision for the old memory and create a duplicate active successor, so warn instead.
92
+ async function recordDecision(ctx, write, supersedes) {
97
93
  try {
98
- await decisionMemoryWeaken(ctx, oldEntry);
94
+ return await objectCreate(ctx, 'decision', write, shellFolder());
99
95
  }
100
96
  catch (e) {
101
- printError(` warning: decision recorded and superseded, but failed to weaken the prior memory ${supersedesMemId}: ${errorMessage(e)}`);
97
+ // True only while the save is whole or nothing: a throw after its commit would break this claim.
98
+ if (supersedes)
99
+ printError(NOT_RECORDED);
100
+ throw e;
102
101
  }
103
102
  }
104
103
  function printSupersedes(supersedesMemId, supersedesDecisionId) {
@@ -11,7 +11,7 @@ import { workingFolder } from '../shared.js';
11
11
  import { boolFlag, stringFlag } from '../flag-values.js';
12
12
  import { appendSessionEndCloseLog, captureTarget, flushingOnExit, logSessionEndImport, reportSessionEndFailure, } from '../hook-runtime.js';
13
13
  export async function handleSessionEndWorker({ hippoRoot, tenantId, flags, }) {
14
- await runSessionWorker(stringFlag(flags, 'session-id') ?? null, boolFlag(flags, 'turn') ? 'turn' : 'full', (mode) => sessionEndWork(hippoRoot, tenantId, flags, mode));
14
+ await runSessionWorker(stringFlag(flags, 'session-id') ?? null, boolFlag(flags, 'turn') ? 'turn' : 'full', (mode) => sessionEndWork(hippoRoot, tenantId, flags, mode), (line, opts) => appendSessionEndCloseLog(stringFlag(flags, 'log-file') ?? null, line, opts));
15
15
  }
16
16
  async function sessionEndWork(hippoRoot, tenantId, flags, mode) {
17
17
  const logFile = stringFlag(flags, 'log-file') ?? null;
@@ -55,11 +55,12 @@ function runSessionEndWork({ hippoRoot, tenantId, flags, mode, held, }) {
55
55
  * regardless. */
56
56
  async function sleepFolderStore(hippoRoot, tenantId, flags, closeLogFile) {
57
57
  try {
58
- await (await import('../sleep.js')).sleepStore({ hippoRoot, tenantId, args: [], flags });
58
+ return await (await import('../sleep.js')).sleepStore({ hippoRoot, tenantId, args: [], flags });
59
59
  }
60
60
  catch (err) {
61
61
  // sleepStore writes its own failure line only once its log tee is open.
62
62
  reportSessionEndFailure(closeLogFile, 'session-end: sleep', err);
63
+ return false;
63
64
  }
64
65
  }
65
66
  /** True when capture ran to the end, so a turn close may move its cursor past these turns. */
@@ -93,9 +93,13 @@ function scheduleOnWindows(taskName, cmd, run) {
93
93
  }
94
94
  }
95
95
  catch (err) {
96
- // A non-zero exit means the task does not exist yet, so it is created below.
97
- if (schedulerTimedOut(err))
98
- warnSchedulerTimedOut('schtasks /query');
96
+ if (schedulerTimedOut(err)) {
97
+ // An unanswered query may hide an existing task, so nothing is created over it.
98
+ console.log(` schtasks /query did not answer within ${SCHEDULER_CALL_TIMEOUT_MS / 1000} s and was stopped, so Task ` +
99
+ `Scheduler was not changed; run hippo init again, or check for the task ${taskName}.`);
100
+ return;
101
+ }
102
+ // Any other non-zero exit means the task does not exist yet, so it is created below.
99
103
  }
100
104
  try {
101
105
  run('schtasks', buildSchtasksCreateArgs(taskName, cmd), SCHEDULER_CALL);
@@ -129,28 +133,110 @@ function readCrontab(run) {
129
133
  throw err;
130
134
  }
131
135
  }
136
+ const dailyCronLine = (cmd, marker) => `15 6 * * * ${cmd} ${marker}`;
137
+ // The five schedule fields or an @macro, with any leading blanks.
138
+ const CRON_SCHEDULE = /^\s*(?:@\S+|\S+(?:\s+\S+){4})(?=\s|$)/;
139
+ /** Best effort shell scan: false when `text` ends inside a quote, where a marker is another job's data. */
140
+ function outsideQuotes(text) {
141
+ let open = '';
142
+ for (let i = 0; i < text.length; i++) {
143
+ const c = text[i];
144
+ if (open === `'`)
145
+ open = c === `'` ? '' : open;
146
+ else if (c === '\\')
147
+ i++;
148
+ else if (open === '"')
149
+ open = c === '"' ? '' : open;
150
+ else if (c === `'` || c === '"')
151
+ open = c;
152
+ }
153
+ return open === '';
154
+ }
155
+ /** Where `marker` stands in `line` as a whole token outside quotes, or -1; `<marker>-old` is another name. */
156
+ function markerAt(line, marker) {
157
+ const blankOrEdge = (i) => i < 0 || i >= line.length || /\s/.test(line[i]);
158
+ const isOurs = (at) => blankOrEdge(at - 1) && blankOrEdge(at + marker.length) && outsideQuotes(line.slice(0, at));
159
+ for (let at = line.indexOf(marker); at >= 0; at = line.indexOf(marker, at + 1)) {
160
+ if (isOurs(at))
161
+ return at;
162
+ }
163
+ return -1;
164
+ }
165
+ /** `line` with its command replaced by `cmd`, schedule and marker kept; null when it has no schedule. */
166
+ function withCommand(line, at, cmd) {
167
+ const schedule = CRON_SCHEDULE.exec(line)?.[0];
168
+ if (schedule === undefined || at < schedule.length)
169
+ return null;
170
+ return line.slice(schedule.length, at).trim() === cmd
171
+ ? line
172
+ : `${schedule} ${cmd} ${line.slice(at)}`;
173
+ }
174
+ function appendEntry(existing, marker, cmd) {
175
+ // A user with no crontab yet gets the line alone, with no blank line above it.
176
+ const kept = existing.trimEnd();
177
+ return {
178
+ kind: 'write',
179
+ text: `${kept === '' ? '' : `${kept}\n`}${dailyCronLine(cmd, marker)}\n`,
180
+ said: [' Scheduled machine-level daily runner (6:15am) via crontab'],
181
+ };
182
+ }
183
+ /**
184
+ * What to do with the user's crontab so it holds exactly one active line for the daily runner.
185
+ * Every other line is kept as it was, line endings included.
186
+ */
187
+ function reconcileCrontab(existing, marker, cmd) {
188
+ const lines = existing.split('\n');
189
+ const isEntry = (line) => !/^\s*#/.test(line) && markerAt(line, marker) >= 0;
190
+ const [first, ...extra] = lines.flatMap((line, i) => (isEntry(line) ? [i] : []));
191
+ if (first === undefined)
192
+ return appendEntry(existing, marker, cmd);
193
+ const old = lines[first];
194
+ const fresh = withCommand(old, markerAt(old, marker), cmd);
195
+ if (fresh === null)
196
+ return { kind: 'unreadable', line: old.trim() };
197
+ if (fresh === old && extra.length === 0)
198
+ return { kind: 'keep' };
199
+ const said = [
200
+ ...(fresh === old
201
+ ? []
202
+ : [
203
+ ' Updated the daily runner entry in your crontab (the command changed).',
204
+ ` was: ${old.trimEnd()}`,
205
+ ` now: ${fresh.trimEnd()}`,
206
+ ]),
207
+ ...extra.flatMap((i) => [
208
+ ' Removed a duplicate daily runner entry from your crontab:',
209
+ ` ${lines[i].trimEnd()}`,
210
+ ]),
211
+ ];
212
+ const text = lines
213
+ .map((line, i) => (i === first ? fresh : line))
214
+ .filter((_, i) => !extra.includes(i))
215
+ .join('\n');
216
+ return { kind: 'write', text: text.endsWith('\n') ? text : `${text}\n`, said };
217
+ }
132
218
  function scheduleOnCrontab(taskName, cmd, run) {
133
219
  const marker = `# hippo:${taskName}`;
134
220
  try {
135
- const existing = readCrontab(run);
136
- if (existing.includes(marker)) {
221
+ const plan = reconcileCrontab(readCrontab(run), marker, cmd);
222
+ if (plan.kind === 'keep')
137
223
  return; // already scheduled
224
+ if (plan.kind === 'unreadable') {
225
+ log.warn(`install: the daily runner line in your crontab is not a cron schedule hippo can read, so it was left as it ` +
226
+ `is: ${plan.line}`);
227
+ return;
138
228
  }
139
- const cronLine = `15 6 * * * ${cmd} ${marker}`;
140
- // A user with no crontab yet gets the line alone, with no blank line above it.
141
- const kept = existing.trimEnd();
142
- const newCrontab = `${kept === '' ? '' : `${kept}\n`}${cronLine}\n`;
143
- run('crontab', ['-'], { ...SCHEDULER_CALL, input: newCrontab });
144
- console.log(` Scheduled machine-level daily runner (6:15am) via crontab`);
229
+ run('crontab', ['-'], { ...SCHEDULER_CALL, input: plan.text });
230
+ for (const line of plan.said)
231
+ console.log(line);
145
232
  }
146
233
  catch (err) {
147
234
  if (schedulerTimedOut(err))
148
235
  warnSchedulerTimedOut('crontab');
149
236
  log.warn(`install: crontab could not be read or written, so the daily runner is not scheduled: ${errorMessage(err)}`, errorFields(err));
150
237
  // No permission or no crontab program: print the line for the user to add by hand.
151
- const cronLine = `15 6 * * * ${cmd}`;
152
238
  console.log(` To schedule the machine-level daily runner, add to crontab (crontab -e):`);
153
- console.log(` ${cronLine}`);
239
+ console.log(` ${dailyCronLine(cmd, marker)}`);
154
240
  }
155
241
  }
156
242
  //# sourceMappingURL=install-steps.js.map
@@ -159,8 +159,9 @@ async function sendOrFallBack(hippoRoot, server, call) {
159
159
  if (failure === 'none')
160
160
  return call.refused(err);
161
161
  if (failure === 'delivery-unknown') {
162
- fail(`hippo: the connection to ${server.url} dropped or timed out mid-request, so the write may already have been ` +
163
- 'applied. Not retrying locally. Check with `hippo recall` before running this again.');
162
+ log.debug('a served write may have landed, so it is not replayed on the store', errorFields(err));
163
+ const reason = client.deliveryUnknownReason(err, server.url);
164
+ fail(`hippo: ${reason} Check with \`hippo recall\` before running this again.`);
164
165
  }
165
166
  failIfServerRequired('the server pidfile was stale (connection refused)');
166
167
  log.warn('stale server pidfile detected, falling back to direct mode', errorFields(err));
@@ -3,11 +3,18 @@
3
3
  import { renderAmbientSummary } from '../../base/memory/ambient.js';
4
4
  import { plural } from '../../base/util/format.js';
5
5
  import { sleepEventLines } from '../render/sleep-events.js';
6
+ import { sleepWasRefused } from '../../api/sleep/one-sleep.js';
6
7
  /**
7
8
  * The lines `hippo sleep` prints for an api.sleep result; pure, so the snapshot tests read them
8
9
  * without a console spy.
9
10
  */
10
11
  export function sleepResultLines(result) {
12
+ if (sleepWasRefused(result)) {
13
+ return [
14
+ `A sleep is already running on this store (since ${result.alreadyRunning.since}), ` +
15
+ 'so this one skipped consolidation.',
16
+ ];
17
+ }
11
18
  return [
12
19
  ...sleepCountLines(result),
13
20
  ...(result.dryRun ? ['\n(dry run - nothing written)'] : []),
@@ -1,6 +1,7 @@
1
1
  import { type CommandContext } from './flag-values.js';
2
2
  /** Runs `hippo sleep`; `--global` sleeps the global store instead of the folder's. */
3
3
  export declare function handleSleep({ hippoRoot, tenantId, args, flags, }: CommandContext): Promise<void>;
4
- /** Sleeps one store; with `--log-file` it also tees its output to that file. */
5
- export declare function sleepStore({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
4
+ /** Sleeps one store; with `--log-file` it also tees its output to that file. True when another
5
+ * sleep held the store's claim, so this one consolidated nothing. */
6
+ export declare function sleepStore({ hippoRoot, tenantId, flags }: CommandContext): Promise<boolean>;
6
7
  //# sourceMappingURL=sleep.d.ts.map
@@ -11,6 +11,7 @@ import * as api from '../../api/index.js';
11
11
  import { cliConfig, cliApiContext, cliStore, cliSyncOptions } from './api-context.js';
12
12
  import { saveVectorGraphFile } from '../open-store.js';
13
13
  import { sleepResultLines } from './sleep-render.js';
14
+ import { sleepWasRefused } from '../../api/sleep/one-sleep.js';
14
15
  import { errorFields, errorMessage, log } from '../../base/util/log.js';
15
16
  import { teeStdStreams } from '../../host/stream-tee.js';
16
17
  import { boolFlag, stringFlag } from './flag-values.js';
@@ -26,7 +27,8 @@ export async function handleSleep({ hippoRoot, tenantId, args, flags, }) {
26
27
  const root = boolFlag(flags, 'global') ? hippoHomeDir() : hippoRoot;
27
28
  await sleepStore({ hippoRoot: root, tenantId, args, flags });
28
29
  }
29
- /** Sleeps one store; with `--log-file` it also tees its output to that file. */
30
+ /** Sleeps one store; with `--log-file` it also tees its output to that file. True when another
31
+ * sleep held the store's claim, so this one consolidated nothing. */
30
32
  export async function sleepStore({ hippoRoot, tenantId, flags }) {
31
33
  // Tee stdout/stderr to a log file when --log-file is set; the SessionEnd hook uses it so the
32
34
  // SessionStart hook can re-display the output.
@@ -43,9 +45,10 @@ export async function sleepStore({ hippoRoot, tenantId, flags }) {
43
45
  }
44
46
  }
45
47
  try {
46
- await runSleepCommand(hippoRoot, tenantId, flags);
47
- if (logFile)
48
+ const refused = await runSleepCommand(hippoRoot, tenantId, flags);
49
+ if (logFile && !refused)
48
50
  console.log('[hippo] sleep complete');
51
+ return refused;
49
52
  }
50
53
  catch (err) {
51
54
  if (logFile)
@@ -115,6 +118,7 @@ async function learnBeforeSleep(hippoRoot, tenantId, flags) {
115
118
  printAgentImport(await importForStore(hippoRoot, cliSyncOptions(tenantId, currentMachine())), '');
116
119
  }
117
120
  }
121
+ /** True when another sleep held the store's claim, so this one consolidated nothing. */
118
122
  async function runSleepCommand(hippoRoot, tenantId, flags) {
119
123
  requireInit(hippoRoot);
120
124
  await learnBeforeSleep(hippoRoot, tenantId, flags);
@@ -137,11 +141,13 @@ async function runSleepCommand(hippoRoot, tenantId, flags) {
137
141
  noShare: boolFlag(flags, 'no-share'),
138
142
  });
139
143
  renderSleepResult(result);
144
+ const refused = sleepWasRefused(result);
140
145
  // A store with no `hippo serve` gets its saved vector graph from its sleeps.
141
- if (!result.dryRun) {
146
+ if (!result.dryRun && !refused) {
142
147
  await saveVectorGraphFile(hippoRoot, {
143
148
  maxVectors: ctx.config.vectorGraph.maxVectors,
144
149
  });
145
150
  }
151
+ return refused;
146
152
  }
147
153
  //# sourceMappingURL=sleep.js.map
@@ -50,9 +50,12 @@ export async function handleShare({ hippoRoot, tenantId, args, flags, }) {
50
50
  const force = boolFlag(flags, 'force');
51
51
  const ctx = cliApiContext(hippoRoot, tenantId);
52
52
  const result = await api.shareToGlobal(ctx, shareId, { force });
53
- if (result) {
54
- console.log(`Shared [${result.id}] to global store.`);
55
- console.log(` Source: ${result.source}`);
53
+ if (result.kind === 'shared') {
54
+ console.log(`Shared [${result.entry.id}] to global store.`);
55
+ console.log(` Source: ${result.entry.source}`);
56
+ }
57
+ else if (result.kind === 'already-shared') {
58
+ console.log(`Already shared: the global store holds this text as [${result.existingId}].`);
56
59
  }
57
60
  else {
58
61
  const entry = await memoryGet(ctx, shareId);
@@ -110,22 +110,40 @@ export function installedRealCodexPath() {
110
110
  }
111
111
  return metadata.realCodexPath;
112
112
  }
113
- export function detectRealCodexPath() {
114
- const metadata = readCodexWrapperMetadata();
115
- if (isCodexWrapperMetadataValid(metadata))
116
- return metadata.realCodexPath;
113
+ /** The launcher paths of each PATH folder, in PATH order, wrapper folder excluded, with their
114
+ * install plans. */
115
+ function pathLauncherFolders() {
117
116
  const { wrapperDir } = resolveCodexWrapperPaths();
118
- const entries = (envPath() ?? '')
117
+ const folders = (envPath() ?? '')
119
118
  .split(path.delimiter)
120
119
  .map((entry) => entry.trim())
121
120
  .filter(Boolean)
122
121
  .filter((entry) => !pathEquals(entry, wrapperDir));
123
- for (const entry of entries) {
124
- for (const name of CODEX_LAUNCHER_NAMES) {
125
- const candidate = path.join(entry, name);
126
- if (fs.existsSync(candidate))
127
- return candidate;
122
+ return folders.map((folder) => CODEX_LAUNCHER_NAMES.map((name) => {
123
+ const original = path.join(folder, name);
124
+ return { original, plan: resolveCodexInstallPlan(original) };
125
+ }));
126
+ }
127
+ /** Whether the plan's command path is empty or hippo's wrapper, so writing a wrapper there loses no
128
+ * launcher; a cmd shim for a vacated exe slot would otherwise overwrite a live codex.cmd. */
129
+ function commandPathIsFree(plan) {
130
+ return !fs.existsSync(plan.commandPath) || isHippoCodexWrapperFile(plan.commandPath);
131
+ }
132
+ export function detectRealCodexPath() {
133
+ const metadata = readCodexWrapperMetadata();
134
+ if (isCodexWrapperMetadataValid(metadata))
135
+ return metadata.realCodexPath;
136
+ // The first folder with a launcher wins, as the shell would resolve `codex`; within a folder a
137
+ // backup beside an empty slot means an install stopped after its rename, so the slot is the launcher.
138
+ for (const slots of pathLauncherFolders()) {
139
+ const vacated = slots.find(({ original, plan }) => fs.existsSync(plan.backupPath) && !fs.existsSync(original) && commandPathIsFree(plan));
140
+ if (vacated) {
141
+ log.info(`recovered an interrupted codex wrapper install from the backup ${vacated.plan.backupPath}`);
142
+ return vacated.original;
128
143
  }
144
+ const present = slots.find(({ original }) => fs.existsSync(original));
145
+ if (present)
146
+ return present.original;
129
147
  }
130
148
  return null;
131
149
  }
@@ -184,6 +202,9 @@ function makeWrapperDirs(paths) {
184
202
  }
185
203
  }
186
204
  function backUpRealLauncher(realCodexPath, backupPath) {
205
+ // The launcher is gone and its backup is not: an earlier install already made this rename.
206
+ if (!fs.existsSync(realCodexPath) && fs.existsSync(backupPath))
207
+ return;
187
208
  // A launcher that is not our wrapper is the current codex, so it replaces any older backup a
188
209
  // Codex update left.
189
210
  if (!isHippoCodexWrapperFile(realCodexPath)) {
@@ -216,10 +237,30 @@ function restoreCodexLauncher(metadata, metadataPath) {
216
237
  fs.renameSync(plan.backupPath, originalCodexPath);
217
238
  return true;
218
239
  }
240
+ /** With no metadata, a backup beside an empty or hippo-wrapped slot is an install that stopped
241
+ * part-way; a slot or command path holding a real launcher is never touched. */
242
+ function restoreLeftoverBackups() {
243
+ let changed = false;
244
+ for (const { original, plan } of pathLauncherFolders().flat()) {
245
+ if (!fs.existsSync(plan.backupPath))
246
+ continue;
247
+ if (fs.existsSync(original) && !isHippoCodexWrapperFile(original))
248
+ continue;
249
+ if (!commandPathIsFree(plan))
250
+ continue;
251
+ if (isHippoCodexWrapperFile(plan.commandPath))
252
+ fs.rmSync(plan.commandPath, { force: true });
253
+ fs.renameSync(plan.backupPath, original);
254
+ changed = true;
255
+ }
256
+ return changed;
257
+ }
219
258
  export function uninstallCodexWrapper() {
220
259
  const paths = resolveCodexWrapperPaths();
221
260
  const metadata = readCodexWrapperMetadata();
222
- let changed = metadata !== null && restoreCodexLauncher(metadata, paths.metadataPath);
261
+ let changed = metadata === null
262
+ ? restoreLeftoverBackups()
263
+ : restoreCodexLauncher(metadata, paths.metadataPath);
223
264
  cleanupLegacyCodexPathWrappers(paths);
224
265
  if (fs.existsSync(paths.metadataPath)) {
225
266
  fs.rmSync(paths.metadataPath, { force: true });
@@ -95,8 +95,8 @@ ends, so there is nothing to record or run by hand.
95
95
  content: agentsBlock('session', { footer: PI_FOOTER }),
96
96
  },
97
97
  };
98
- // sha256 of each trimmed block an earlier hippo wrote, so init refreshes only blocks nobody edited.
99
- // Add the old hash when a block changes.
98
+ // sha256 of every block text hippo has shipped, current ones included, so init refreshes only
99
+ // blocks nobody edited. scripts/checks/check-hook-block-hashes.mjs fails while a text is unlisted.
100
100
  const SHIPPED_HOOK_HASHES = new Map([
101
101
  ['c80e760208aed70f6094757736b9a2f496ba5c30d88bc2a7ae3e128b403dcc6b', 'claude-code'],
102
102
  ['75937be6b7fdc2b87bcb08b7fec56757808075db129d99eff3e9f769f80a7781', 'claude-code'],
@@ -121,6 +121,13 @@ const SHIPPED_HOOK_HASHES = new Map([
121
121
  ['8b8f5986d7f7ed15f06e68720d8913c3cab23d94366b411935ca2bbaa334553b', 'pi'],
122
122
  ['37767b355e18beac726b05b9e2b898dab8c6135fd7b98f3aa52edc734d5dd283', 'pi'],
123
123
  ['6e85a5cccb3cfeaa9a080713754936db730f96376f94cc9a9888a746149c7268', 'pi'],
124
+ ['9943e6f7e3e18cda82197f77f012841916223fd2e026c10196392f9090554dd8', 'claude-code'],
125
+ ['baa311df8f1cf35bc014f27e5e9cf8f9120bfa1594d5a48a4c31d6bf5922b5ae', 'codex'],
126
+ ['0fdf490b8120e538b0f2c2417b844d39da772415715d0572f31c5337162a4912', 'cursor'],
127
+ ['80d457096eabd14cc9a2178c06cb76b2440c02eec4eb117ef9fe57eaa03c3c20', 'openclaw'],
128
+ ['9af7ca33d8b9e96cec2dd519d5a52435ccd7bcb7590a9b1c4f8615da70ac48ce', 'opencode'],
129
+ ['ffb8b55d4ee75b876afabfa75df3836b6aa50cff117120562b71fa28888a5f7b', 'pi'],
130
+ ['349d81d433a8000a92fa99e97eebe88e31f752dec6456198c648bb0953129beb', 'openclaw'],
124
131
  ]);
125
132
  /**
126
133
  * The first hippo block in `text` and the agent whose current or shipped text it is; `owner` is
@@ -101,9 +101,12 @@ export async function runShareTool({ args, ctx, store }) {
101
101
  // The share reads the id in the caller's tenant only, so tenant A cannot copy tenant B's row to
102
102
  // the global store.
103
103
  const shared = await shareToGlobal({ ...apiCtx, store }, shareId, { force });
104
- if (!shared)
104
+ if (shared.kind === 'low-score')
105
105
  return 'Transfer score too low. Use force=true to override.';
106
- return `Shared [${shared.id}] to global store. Source: ${shared.source}`;
106
+ if (shared.kind === 'already-shared') {
107
+ return `Already shared: the global store holds this text as [${shared.existingId}].`;
108
+ }
109
+ return `Shared [${shared.entry.id}] to global store. Source: ${shared.entry.source}`;
107
110
  }
108
111
  export async function runPeersTool({ ctx }) {
109
112
  // Tenant-scope peer discovery to the caller, as hippo_share does.
@@ -6,8 +6,8 @@ import { isJsonNumber } from '../../../base/util/json.js';
6
6
  import { parseJsonBody, getString, requiredString, } from '../validation.js';
7
7
  import { MAX_SHORT_FIELD_LEN } from '../../../base/util/limits.js';
8
8
  const TEXT = { max: MAX_SHORT_FIELD_LEN };
9
- // The HTTP surface has no legacy --supersedes <memory-id> constraint, so it supersedes by table id
10
- // and never weakens a memory mirror.
9
+ // The HTTP surface supersedes by table id; the store weakens the replaced decision's memory in the
10
+ // same save.
11
11
  function supersededId(body) {
12
12
  const raw = body['supersedesDecisionId'];
13
13
  if (raw === undefined || raw === null)
@@ -4,6 +4,7 @@
4
4
  import { evalStoreRules } from '../../infra/eval-switches.js';
5
5
  import { sleepWholeStore } from '../../api/sleep/sleep.js';
6
6
  import { autoSleepConsolidate } from '../../api/sleep/auto-sleep.js';
7
+ import { sleepWasRefused } from '../../api/sleep/one-sleep.js';
7
8
  import { rootInfra } from '../../infra/ports.js';
8
9
  import { configReader } from '../../host/config-file.js';
9
10
  import { createHost } from '../../host/host.js';
@@ -31,9 +32,9 @@ function sleepJob({ hippoRoot, ...job }, session) {
31
32
  return sleepWholeStore({ tenantId: job.tenantId, actor: job.actor, store, reach, config, infra }, job.opts);
32
33
  }
33
34
  /** A sleep that changed the store saves its vector graph file, so a store whose server holds no
34
- * graph gets one. */
35
- async function saveGraphAfter(job) {
36
- if (job.kind !== 'sleep' || job.opts.dryRun)
35
+ * graph gets one; a refused sleep changed nothing. */
36
+ async function saveGraphAfter(job, result) {
37
+ if (job.kind !== 'sleep' || job.opts.dryRun || sleepWasRefused(result))
37
38
  return;
38
39
  const { maxVectors } = loadConfig(job.hippoRoot).vectorGraph;
39
40
  await saveVectorGraphFile(job.hippoRoot, { maxVectors, deadline: job.deadline - EXIT_MARGIN_MS });
@@ -70,7 +71,7 @@ process.once('message', (message) => {
70
71
  // After the reply, so the sleep's caller never waits on the build; the server's queue waits
71
72
  // for the exit.
72
73
  if (reply.ok)
73
- await saveGraphAfter(job);
74
+ await saveGraphAfter(job, reply.result);
74
75
  return code;
75
76
  })
76
77
  .catch((err) => {
@@ -23,11 +23,22 @@ export function isSleepReply(message) {
23
23
  'message' in message &&
24
24
  typeof message.message === 'string');
25
25
  }
26
- function failureOf(reply, code, signal) {
27
- if (!reply || reply.ok) {
28
- return new Error(`sleep process ended without an answer (code ${code}, signal ${signal})`);
26
+ // The failed-versus-deadline order lives in this precedence, not in the type.
27
+ function settle(end, event) {
28
+ if (end?.kind === 'answered')
29
+ return end;
30
+ switch (event.kind) {
31
+ case 'reply':
32
+ if (event.reply.ok)
33
+ return { kind: 'answered', result: event.reply.result };
34
+ return end ?? { kind: 'failed', reply: event.reply };
35
+ case 'malformed':
36
+ return end ?? { kind: 'malformed' };
37
+ case 'deadline':
38
+ return { kind: 'deadline' };
39
+ case 'close':
40
+ return end ?? { kind: 'closed' };
29
41
  }
30
- return replyError(reply);
31
42
  }
32
43
  function runInChild(job) {
33
44
  let ended = () => undefined;
@@ -45,22 +56,19 @@ function childAnswer(job, ended) {
45
56
  stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
46
57
  windowsHide: true,
47
58
  });
48
- let reply;
49
- let timedOut = false;
50
- let malformed = false;
59
+ let end;
51
60
  // SIGKILL because the child is inside synchronous hippo.db work and cannot run a handler; the
52
61
  // OS drops its write lock.
53
62
  const timer = setTimeout(() => {
54
- timedOut = true;
63
+ end = settle(end, { kind: 'deadline' });
55
64
  child.kill('SIGKILL');
56
65
  }, deadlineMs);
57
66
  child.once('message', (message) => {
58
- if (isSleepReply(message))
59
- reply = message;
60
- else
61
- malformed = true;
62
- if (reply?.ok)
63
- resolve(reply.result);
67
+ end = settle(end, isSleepReply(message)
68
+ ? { kind: 'reply', reply: message }
69
+ : { kind: 'malformed' });
70
+ if (end.kind === 'answered')
71
+ resolve(end.result);
64
72
  });
65
73
  child.once('error', (err) => {
66
74
  clearTimeout(timer);
@@ -72,22 +80,25 @@ function childAnswer(job, ended) {
72
80
  child.once('close', (code, signal) => {
73
81
  clearTimeout(timer);
74
82
  ended();
75
- if (reply?.ok)
76
- return;
77
- reject(unansweredFailure(reply, code, signal, { timedOut, malformed, deadlineMs }));
83
+ end = settle(end, { kind: 'close' });
84
+ if (end.kind !== 'answered')
85
+ reject(unansweredFailure(end, deadlineMs, code, signal));
78
86
  });
79
87
  child.send({ ...job, deadline: Date.now() + deadlineMs });
80
88
  });
81
89
  }
82
- /** Why a child that closed without a good reply failed, the deadline first. */
83
- function unansweredFailure(reply, code, signal, { timedOut, malformed, deadlineMs }) {
84
- if (timedOut) {
85
- return new HttpError(504, `sleep did not finish within ${deadlineMs} ms and was stopped; the next sleep carries on from there`);
90
+ /** Why a child that closed without a good reply failed. */
91
+ function unansweredFailure(end, deadlineMs, code, signal) {
92
+ switch (end.kind) {
93
+ case 'deadline':
94
+ return new HttpError(504, `sleep did not finish within ${deadlineMs} ms and was stopped; the next sleep carries on from there`);
95
+ case 'malformed':
96
+ return new Error(`sleep process sent a reply that is not a sleep result (code ${code}, signal ${signal})`);
97
+ case 'failed':
98
+ return replyError(end.reply);
99
+ case 'closed':
100
+ return new Error(`sleep process ended without an answer (code ${code}, signal ${signal})`);
86
101
  }
87
- if (malformed) {
88
- return new Error(`sleep process sent a reply that is not a sleep result (code ${code}, signal ${signal})`);
89
- }
90
- return failureOf(reply, code, signal);
91
102
  }
92
103
  // One running and one waiting: each further sleep would only hold a request open behind work the
93
104
  // waiting one already covers.
@@ -2,7 +2,7 @@
2
2
  "id": "hippo-memory",
3
3
  "name": "Hippo Memory",
4
4
  "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
5
- "version": "3.4.0",
5
+ "version": "3.5.1",
6
6
 
7
7
  "configSchema": {
8
8
  "type": "object",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hippo-memory",
3
- "version": "3.4.0",
3
+ "version": "3.5.1",
4
4
  "type": "module",
5
5
  "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
6
6
  "main": "index.ts",