hippo-memory 3.5.1 → 3.7.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 (74) hide show
  1. package/README.md +37 -25
  2. package/dist/api/context/context-pools.js +2 -2
  3. package/dist/api/context/context.d.ts +1 -1
  4. package/dist/api/context/context.js +13 -9
  5. package/dist/api/ledger-db.d.ts +4 -2
  6. package/dist/api/ledger-db.js +11 -1
  7. package/dist/api/pilot-arm.js +4 -1
  8. package/dist/api/recall/finish.js +3 -2
  9. package/dist/api/recall/recall.js +3 -1
  10. package/dist/api/recall/request.d.ts +1 -1
  11. package/dist/api/recall/request.js +3 -1
  12. package/dist/api/tokens.d.ts +1 -1
  13. package/dist/api/tokens.js +3 -0
  14. package/dist/api/types.d.ts +2 -0
  15. package/dist/api/types.js +4 -0
  16. package/dist/base/config/config-keys.js +2 -1
  17. package/dist/base/config/config.d.ts +5 -1
  18. package/dist/base/config/config.js +1 -0
  19. package/dist/base/errors/read-only.d.ts +3 -0
  20. package/dist/base/errors/read-only.js +4 -0
  21. package/dist/base/memory/entry.d.ts +10 -2
  22. package/dist/base/memory/entry.js +12 -4
  23. package/dist/base/scope/read-admission.js +2 -2
  24. package/dist/base/util/env.d.ts +1 -0
  25. package/dist/base/util/env.js +3 -0
  26. package/dist/base/util/version.d.ts +1 -1
  27. package/dist/base/util/version.js +1 -1
  28. package/dist/cli.js +14 -1
  29. package/dist/db/connect.d.ts +4 -0
  30. package/dist/db/connect.js +79 -1
  31. package/dist/db/grant.js +1 -1
  32. package/dist/db/migrate.d.ts +3 -0
  33. package/dist/db/migrate.js +1 -1
  34. package/dist/db/store-runtime.d.ts +7 -0
  35. package/dist/db/store-runtime.js +4 -0
  36. package/dist/domain/consolidate/conflicts.js +3 -1
  37. package/dist/domain/context/select-policy.d.ts +1 -1
  38. package/dist/domain/context/select-policy.js +3 -3
  39. package/dist/domain/sharing/share.js +3 -1
  40. package/dist/store/sqlite/capture/captures.js +19 -6
  41. package/dist/store/sqlite/index.d.ts +1 -1
  42. package/dist/store/sqlite/learning/prediction-baserate.js +4 -2
  43. package/dist/store/sqlite/recall/candidates.js +3 -2
  44. package/dist/store/sqlite/recall/search-rows.js +5 -2
  45. package/dist/store/sqlite/runtime/handles.js +3 -0
  46. package/dist/surface/capture/capture-error.d.ts +4 -1
  47. package/dist/surface/capture/capture-error.js +2 -1
  48. package/dist/surface/capture/command.d.ts +8 -3
  49. package/dist/surface/capture/command.js +61 -11
  50. package/dist/surface/capture/extract.d.ts +2 -0
  51. package/dist/surface/capture/extract.js +7 -0
  52. package/dist/surface/capture/failure-caller.js +1 -0
  53. package/dist/surface/capture/user-messages.d.ts +9 -0
  54. package/dist/surface/capture/user-messages.js +42 -0
  55. package/dist/surface/cli/api-context.js +1 -0
  56. package/dist/surface/cli/cli-runtime.js +2 -1
  57. package/dist/surface/cli/hooks/capture-error.js +7 -1
  58. package/dist/surface/cli/hooks/codex-session-end-worker.js +1 -0
  59. package/dist/surface/cli/hooks/session-end-worker.js +14 -2
  60. package/dist/surface/cli/serve.js +4 -1
  61. package/dist/surface/cli/verb-row.d.ts +2 -0
  62. package/dist/surface/cli/verbs/health.js +3 -0
  63. package/dist/surface/cli/verbs/memory.js +5 -0
  64. package/dist/surface/cli/verbs/objects.js +2 -0
  65. package/dist/surface/cli/verbs/sessions.js +11 -0
  66. package/dist/surface/mcp/request.js +6 -2
  67. package/dist/surface/mcp/tools.d.ts +2 -0
  68. package/dist/surface/mcp/tools.js +8 -0
  69. package/dist/surface/open-store.d.ts +2 -2
  70. package/dist/surface/open-store.js +2 -2
  71. package/extensions/openclaw-plugin/openclaw.plugin.json +1 -1
  72. package/extensions/openclaw-plugin/package.json +1 -1
  73. package/openclaw.plugin.json +1 -1
  74. package/package.json +1 -1
@@ -1,6 +1,6 @@
1
1
  import * as fs from 'node:fs';
2
2
  import * as path from 'node:path';
3
- import { createMemory, Layer, USER_RULE_TAG } from '../../base/memory/entry.js';
3
+ import { createMemory, isUserMessage, Layer, USER_MESSAGE_TAG, USER_RULE_TAG, } from '../../base/memory/entry.js';
4
4
  import { duplicateKey, storedTextKeys } from '../../base/util/same-text.js';
5
5
  import { ruleReplaces } from '../../base/memory/rule-replaces.js';
6
6
  import { isCertainReason, storedDefect } from '../../base/memory/memory-quality.js';
@@ -15,6 +15,7 @@ import { followUpRules, usageLine, withFollowUpRules } from './follow-up.js';
15
15
  import { collectSessionTurns, sessionTail, resolveLastSessionTranscript, } from './transcript.js';
16
16
  import { PRIVATE_DIR } from '../../host/private-dir.js';
17
17
  import { evalClock } from '../../infra/eval-switches.js';
18
+ import { userMessageItems, userMessageRef } from './user-messages.js';
18
19
  export async function runCapture(target, options) {
19
20
  // Tee to a log file for the SessionEnd hook; APPEND, because `hippo sleep` runs first in that
20
21
  // sequence and already wrote its header and body.
@@ -69,7 +70,7 @@ async function runCaptureCore(target, options) {
69
70
  const read = readCaptureTexts(options);
70
71
  if (read === null)
71
72
  return;
72
- const { texts, userTexts, firstFollowUp, followUps } = read;
73
+ const { texts, userTexts, firstFollowUp, followUps, turns } = read;
73
74
  if (texts.every((text) => text.trim().length === 0)) {
74
75
  console.log('No text to capture from.');
75
76
  return;
@@ -81,7 +82,13 @@ async function runCaptureCore(target, options) {
81
82
  const dedup = await captureDedup(target.store.folderFiles, options);
82
83
  const rules = await modelRules(target, dedup, followUps);
83
84
  const patterned = extractFromTexts(scrubbed, userTexts, firstFollowUp);
84
- const extracted = scrubbedItems(withFollowUpRules(patterned, rules, scrub), scrub);
85
+ // A message dedupes only against messages, so a rule it states is kept as a rule too.
86
+ const keepsMessages = options.saveMessages === true && target.config.capture.userMessages;
87
+ const messages = keepsMessages ? userMessageItems(turns, scrub) : [];
88
+ const extracted = [
89
+ ...scrubbedItems(withFollowUpRules(patterned, rules, scrub), scrub),
90
+ ...messages,
91
+ ];
85
92
  if (extracted.length === 0) {
86
93
  console.log('No actionable items found in the input.');
87
94
  return;
@@ -109,6 +116,7 @@ async function captureFromCli({ store, config, embed }, options, dedup, extracte
109
116
  const writeOpts = {
110
117
  tenantId: options.global ? undefined : options.tenantId,
111
118
  originProject: options.originProject,
119
+ sessionId: options.sessionId ?? transcriptSession(options.transcriptPath),
112
120
  lean: false,
113
121
  dedup,
114
122
  now: evalClock()(),
@@ -118,23 +126,38 @@ async function captureFromCli({ store, config, embed }, options, dedup, extracte
118
126
  }
119
127
  return previewCapture({ store, config }, writeOpts, extracted, keys, ruleKeys);
120
128
  }
129
+ /** A Claude Code or Codex transcript is named for its session. */
130
+ function transcriptSession(transcriptPath) {
131
+ return transcriptPath ? path.basename(transcriptPath, '.jsonl') : undefined;
132
+ }
121
133
  /** The items with `scrub` applied to each text, as a path stores them; scrubbing can make two
122
134
  * items one, and the first stays unless a later one is the person's rule. */
123
135
  export function scrubbedItems(items, scrub) {
124
136
  return oncePerText(items.map((item) => ({ ...item, content: scrub(item.content) })));
125
137
  }
138
+ /** A message is the transcript and an item is what capture made of it, so each dedupes in its own
139
+ * lane: the same text can be both, and a held message never stops a rule. */
140
+ function laneKey(item) {
141
+ const key = duplicateKey(item.content);
142
+ return isUserMessage(item) ? `${USER_MESSAGE_TAG}\n${key}` : key;
143
+ }
126
144
  /** Held keys, each twin's clean text too when a held row has its old text and repair keeps that
127
- * row: a pinned row, or one whose text is no certain defect. */
128
- export function heldKeysOf(rows, twins) {
145
+ * row: a pinned row, or one whose text is no certain defect. A held message adds its lane key. */
146
+ export function heldKeysOf(all, twins) {
147
+ const rows = all.filter((row) => !isUserMessage(row));
129
148
  const keys = storedTextKeys(rows);
130
149
  for (const key of twinKeys(rows, twins))
131
150
  keys.add(key);
151
+ for (const row of all)
152
+ if (isUserMessage(row))
153
+ keys.add(laneKey(row));
132
154
  return keys;
133
155
  }
134
156
  /** The held keys that also stop a stated rule written for `ruleProject` (its names): every copy
135
157
  * but one the store's write replaces, which holds the rule's exact text, so a bold twin still
136
158
  * stops it. */
137
- export function ruleHeldKeysOf(rows, twins, ruleProject) {
159
+ export function ruleHeldKeysOf(all, twins, ruleProject) {
160
+ const rows = all.filter((row) => !isUserMessage(row));
138
161
  const keys = storedTextKeys(rows.filter((row) => !ruleReplaces(row, ruleProject)));
139
162
  for (const key of twinKeys(rows, twins))
140
163
  keys.add(key);
@@ -189,7 +212,7 @@ function readCaptureTexts(options) {
189
212
  switch (options.source) {
190
213
  case 'stdin': {
191
214
  try {
192
- return { texts: [fs.readFileSync(0, 'utf8')], userTexts: 0, followUps: [] };
215
+ return { texts: [fs.readFileSync(0, 'utf8')], userTexts: 0, followUps: [], turns: [] };
193
216
  }
194
217
  catch (err) {
195
218
  log.warn(`reading stdin failed: ${errorMessage(err)}`, errorFields(err));
@@ -209,7 +232,12 @@ function readCaptureTexts(options) {
209
232
  process.exitCode = 1;
210
233
  return null;
211
234
  }
212
- return { texts: [fs.readFileSync(options.filePath, 'utf8')], userTexts: 0, followUps: [] };
235
+ return {
236
+ texts: [fs.readFileSync(options.filePath, 'utf8')],
237
+ userTexts: 0,
238
+ followUps: [],
239
+ turns: [],
240
+ };
213
241
  }
214
242
  case 'last-session':
215
243
  return readSessionTexts(options);
@@ -240,6 +268,7 @@ function readSessionTexts(options) {
240
268
  userTexts: users.length,
241
269
  firstFollowUp: opener,
242
270
  followUps: userTurns.slice(opener),
271
+ turns,
243
272
  };
244
273
  }
245
274
  /** One entry per new text: building can throw, so a held text or a repeat within the batch is
@@ -248,7 +277,7 @@ function planCapture(extracted, isHeld, build) {
248
277
  const plan = { entries: [], keys: [], slots: [] };
249
278
  const firstSlot = new Map();
250
279
  for (const item of extracted) {
251
- const key = duplicateKey(item.content);
280
+ const key = laneKey(item);
252
281
  let slot = isHeld(item, key) ? -1 : firstSlot.get(key);
253
282
  if (slot === undefined) {
254
283
  slot = plan.entries.push(build(item)) - 1;
@@ -290,14 +319,14 @@ export async function captureExtractedItems({ store, config, embed }, options, e
290
319
  async function previewCapture({ store: { rejections }, config }, options, extracted, keys, ruleKeys) {
291
320
  const tally = { captured: 0, skipped: 0, rejected: 0 };
292
321
  const held = heldCheck(keys, ruleKeys);
293
- const fresh = extracted.filter((item) => !held(item, duplicateKey(item.content)));
322
+ const fresh = extracted.filter((item) => !held(item, laneKey(item)));
294
323
  const refused = await rejections.refusedAmong(fresh.map((item) => {
295
324
  const entry = captureEntry(item, options, config.defaultHalfLifeDays);
296
325
  return { tenantId: entry.tenantId, entryId: entry.id, content: entry.content };
297
326
  }));
298
327
  let next = 0;
299
328
  for (const item of extracted) {
300
- if (held(item, duplicateKey(item.content))) {
329
+ if (held(item, laneKey(item))) {
301
330
  tally.skipped++;
302
331
  console.log(` [skip] (${item.category}) ${item.content.slice(0, 80)}`);
303
332
  }
@@ -313,6 +342,8 @@ async function previewCapture({ store: { rejections }, config }, options, extrac
313
342
  return tally;
314
343
  }
315
344
  function captureEntry(item, options, baseHalfLifeDays) {
345
+ if (isUserMessage(item))
346
+ return userMessageEntry(item, options, baseHalfLifeDays);
316
347
  // kind stays 'distilled': these are curated items, not raw transcript (see MEMORY_ENVELOPE.md).
317
348
  // The write tenant must match the dedup read's, or scoped dedup passes and the row lands in
318
349
  // 'default'. A rule the person stated is pinned, so it injects even when a later prompt shares
@@ -333,4 +364,23 @@ function captureEntry(item, options, baseHalfLifeDays) {
333
364
  return created;
334
365
  return { ...created, originProject: projectId(options.originProject) };
335
366
  }
367
+ /** A message the person typed is raw transcript, so it is stored as written (MEMORY_ENVELOPE.md)
368
+ * with its owner and source. */
369
+ function userMessageEntry(item, options, baseHalfLifeDays) {
370
+ const created = createMemory(item.content, {
371
+ kind: 'raw',
372
+ layer: Layer.Episodic,
373
+ tags: [USER_MESSAGE_TAG],
374
+ source: USER_MESSAGE_TAG,
375
+ confidence: 'observed',
376
+ owner: `user:${options.actor ?? 'local'}`,
377
+ artifactRef: userMessageRef(options.sessionId, item.content),
378
+ tenantId: options.tenantId,
379
+ sourceSessionId: options.sessionId,
380
+ baseHalfLifeDays,
381
+ }, options.now);
382
+ if (options.originProject === undefined)
383
+ return created;
384
+ return { ...created, originProject: projectId(options.originProject) };
385
+ }
336
386
  //# sourceMappingURL=command.js.map
@@ -18,6 +18,8 @@ export type NoiseCheck = (line: string, sentenceOpen: boolean) => boolean;
18
18
  export declare function proseOnly(text: string, isNoise?: NoiseCheck): string;
19
19
  /** The text above has not ended its sentence; "e.g." at its end has not. */
20
20
  export declare function leftOpen(previous: string, next: string): boolean;
21
+ /** `text` without its paired bold markers, which can split an address or key past the scrubber. */
22
+ export declare function withoutBold(text: string): string;
21
23
  /** A sentence as capture stores it: its lead label and closing marks trimmed. */
22
24
  export declare function statedText(sentence: string): string;
23
25
  /** The sentences a pattern reads in `text`: wrapped lines joined, bold cut, and none that starts
@@ -146,6 +146,13 @@ function pairedBold(line) {
146
146
  /** The segmenter splits after "**Label.**" and leaves the closing `**` on the next rule, so each
147
147
  * real pair goes; a glob, `2**10` or `**kwargs` has no partner and stays as written. */
148
148
  const boldPairs = (line) => pairedBold(line).sort((a, b) => a - b);
149
+ /** `text` without its paired bold markers, which can split an address or key past the scrubber. */
150
+ export function withoutBold(text) {
151
+ return text
152
+ .split('\n')
153
+ .map((line) => cutOut(line, boldPairs(line)))
154
+ .join('\n');
155
+ }
149
156
  /** `line` without the two characters at each of the sorted `cuts`, built in one pass. */
150
157
  function cutOut(line, cuts) {
151
158
  let out = '';
@@ -63,6 +63,7 @@ export async function captureFailureForCaller(given, req) {
63
63
  let logged = 'store-failed';
64
64
  try {
65
65
  const caller = { actor: key.owner, originProject: req.project.name, origins: key.project };
66
+ // No embed: a server process keeps the model off its request path, as lean capture does.
66
67
  const outcome = failure.skip === null ? await storeLesson(ctx, failure.text, caller) : failure.skip;
67
68
  logged = outcome;
68
69
  return { outcome };
@@ -0,0 +1,9 @@
1
+ import { type ExtractedItem } from './extract.js';
2
+ import type { SessionTurn } from './transcript.js';
3
+ /** One item per user turn with enough prose, scrubbed and cut, in the order typed; scrubbed after
4
+ * the bold markers go, as capture's own items are. */
5
+ export declare function userMessageItems(turns: readonly SessionTurn[], scrub: (text: string) => string): ExtractedItem[];
6
+ /** Where a saved message came from: its session and a hash of its text, since a transcript line
7
+ * has no stable id across a turn close and the full close. */
8
+ export declare function userMessageRef(sessionId: string | undefined, text: string): string;
9
+ //# sourceMappingURL=user-messages.d.ts.map
@@ -0,0 +1,42 @@
1
+ // The messages a person typed in a session, as capture items: each one whole, so a fact told in
2
+ // chat can be recalled later even when it states no rule.
3
+ import { createHash } from 'node:crypto';
4
+ import { USER_MESSAGE_TAG } from '../../base/memory/entry.js';
5
+ import { ID_SUFFIX_CHARS } from '../../base/util/token-text.js';
6
+ import { truncateCodePointSafe } from '../../base/util/code-point-cut.js';
7
+ import { proseOnly, withoutBold } from './extract.js';
8
+ const MAX_USER_MESSAGE_CHARS = 2000;
9
+ /** A reply such as "ok thanks" holds nothing to recall. */
10
+ const MIN_USER_MESSAGE_WORDS = 3;
11
+ const CUT_MARK = '…';
12
+ /** One item per user turn with enough prose, scrubbed and cut, in the order typed; scrubbed after
13
+ * the bold markers go, as capture's own items are. */
14
+ export function userMessageItems(turns, scrub) {
15
+ return turns
16
+ .filter((turn) => turn.role === 'user')
17
+ .map((turn) => scrub(withoutBold(turn.text)).trim())
18
+ .filter(isWorthKeeping)
19
+ .map((text) => ({ content: cut(text), category: USER_MESSAGE_TAG, tags: [USER_MESSAGE_TAG] }));
20
+ }
21
+ function isWorthKeeping(text) {
22
+ return proseOnly(text).split(/\s+/).filter(Boolean).length >= MIN_USER_MESSAGE_WORDS;
23
+ }
24
+ /** A long message is mostly a paste, so it keeps only the person's own words, then is cut. */
25
+ function cut(text) {
26
+ if (text.length <= MAX_USER_MESSAGE_CHARS)
27
+ return text;
28
+ const prose = proseOnly(text)
29
+ .replace(/\n{3,}/g, '\n\n')
30
+ .trim();
31
+ if (prose.length <= MAX_USER_MESSAGE_CHARS)
32
+ return prose;
33
+ const room = MAX_USER_MESSAGE_CHARS - CUT_MARK.length;
34
+ return truncateCodePointSafe(prose, room).trimEnd() + CUT_MARK;
35
+ }
36
+ /** Where a saved message came from: its session and a hash of its text, since a transcript line
37
+ * has no stable id across a turn close and the full close. */
38
+ export function userMessageRef(sessionId, text) {
39
+ const hash = createHash('sha256').update(text).digest('hex').slice(0, ID_SUFFIX_CHARS);
40
+ return `session:${sessionId ?? 'unknown'}/${hash}`;
41
+ }
42
+ //# sourceMappingURL=user-messages.js.map
@@ -157,6 +157,7 @@ export function cliSecondStore(root) {
157
157
  export function cliLedgerReach(hippoRoot) {
158
158
  return ledgerReachOf({
159
159
  reach: cliReach(hippoRoot, cliStore(hippoRoot), cliInfra().embedderFor),
160
+ config: cliConfig(hippoRoot),
160
161
  });
161
162
  }
162
163
  /** `root`'s auto-sleep on a session of its own: the sleep outlives the frame whose write started
@@ -1,6 +1,7 @@
1
1
  // The CLI command's store runtime, apart from api-context.ts so cli.ts can end a command without
2
2
  // loading the verbs' store wiring.
3
3
  import { withStoreRuntime } from '../open-store.js';
4
+ import { envReadOnly } from '../../base/util/env.js';
4
5
  // One command per process, so its runtime is root state as its session is; between commands a store
5
6
  // pools nothing.
6
7
  let commandRuntime;
@@ -22,6 +23,6 @@ export async function runCliCommand(fn) {
22
23
  finally {
23
24
  commandRuntime = undefined;
24
25
  }
25
- });
26
+ }, { readOnly: envReadOnly() });
26
27
  }
27
28
  //# sourceMappingURL=cli-runtime.js.map
@@ -4,6 +4,8 @@ import { parseJson } from '../../../base/util/json.js';
4
4
  import { isInitialized } from '../../../host/project-identity.js';
5
5
  import { flushDeliveryRecorder, startToolFailureRecorder } from '../../../api/ledger-db.js';
6
6
  import { captureToolFailure } from '../../capture/capture-error.js';
7
+ import { detachedEmbedder } from '../../../api/embeddings.js';
8
+ import { withDetached } from '../../../api/detached.js';
7
9
  import { readHookStdin } from '../stdin.js';
8
10
  import { cliApiContext, cliHookRequest } from '../api-context.js';
9
11
  import { hookRuntime, hookStoreRoot, hostSessionId, payloadCwdRoot } from '../hook-runtime.js';
@@ -24,8 +26,12 @@ export async function handleCaptureError({ hippoRoot, tenantId, flags, }) {
24
26
  runtime: hookRuntime(flags),
25
27
  envSessionId: hostSessionId(),
26
28
  });
29
+ const folder = { store: ctx.store, config: ctx.config, embedderFor: ctx.infra.embedderFor };
27
30
  try {
28
- return await captureToolFailure(ctx, failure, (id) => rec?.logged(id));
31
+ return await withDetached(ctx, (detached) => {
32
+ const embed = detachedEmbedder(folder, ctx.infra, detached);
33
+ return captureToolFailure({ ...ctx, embed }, failure, (id) => rec?.logged(id));
34
+ });
29
35
  }
30
36
  finally {
31
37
  await flushDeliveryRecorder(rec);
@@ -83,6 +83,7 @@ async function captureCodexRollout({ hippoRoot, tenantId, store, logFile }, tran
83
83
  tenantId,
84
84
  originProject: store === hippoRoot ? undefined : resolveProjectIdentity(process.cwd()),
85
85
  sessionTurns: scan?.turns,
86
+ saveMessages: store === hippoRoot,
86
87
  };
87
88
  try {
88
89
  await runCapture(captureTarget(store, 'full'), captureOpts);
@@ -43,7 +43,17 @@ function runSessionEndWork({ hippoRoot, tenantId, flags, mode, held, }) {
43
43
  const root = into === ctx ? hippoRoot : ctx.reach?.global?.root;
44
44
  if (root === undefined)
45
45
  return false;
46
- const ended = { tenantId, flags, transcriptPath, turns, originProject, fromStart, mode };
46
+ const saveMessages = into === ctx;
47
+ const ended = {
48
+ tenantId,
49
+ flags,
50
+ transcriptPath,
51
+ turns,
52
+ originProject,
53
+ fromStart,
54
+ mode,
55
+ saveMessages,
56
+ };
47
57
  return captureEndedSession(root, ended);
48
58
  },
49
59
  digest: (scan, key, log) => recordSessionDigest(hippoRoot, ctx.store, scan, { key, tenantId, log, config: ctx.config }),
@@ -64,7 +74,7 @@ async function sleepFolderStore(hippoRoot, tenantId, flags, closeLogFile) {
64
74
  }
65
75
  }
66
76
  /** True when capture ran to the end, so a turn close may move its cursor past these turns. */
67
- async function captureEndedSession(store, { tenantId, flags, transcriptPath, turns, originProject, fromStart, mode }) {
77
+ async function captureEndedSession(store, { tenantId, flags, transcriptPath, turns, originProject, fromStart, mode, saveMessages, }) {
68
78
  const logFile = stringFlag(flags, 'log-file') ?? null;
69
79
  try {
70
80
  await runCapture(captureTarget(store, mode), {
@@ -76,6 +86,8 @@ async function captureEndedSession(store, { tenantId, flags, transcriptPath, tur
76
86
  tenantId,
77
87
  originProject,
78
88
  sessionTurns: turns,
89
+ sessionId: stringFlag(flags, 'session-id'),
90
+ saveMessages,
79
91
  fromStart,
80
92
  });
81
93
  return true;
@@ -2,7 +2,7 @@
2
2
  import { randomBytes } from 'node:crypto';
3
3
  import { installCrashHandlers } from '../../base/util/crash-handlers.js';
4
4
  import { printDashboardBanner, reportListenFailure } from './dashboard-banner.js';
5
- import { envBodyTimeoutMs, envPort, envTlsCert, envTlsKey } from '../../base/util/env.js';
5
+ import { envBodyTimeoutMs, envPort, envReadOnly, envTlsCert, envTlsKey, } from '../../base/util/env.js';
6
6
  import * as fs from 'node:fs';
7
7
  import * as path from 'node:path';
8
8
  import { boolFlag, numberFlag, stringFlag, stringFlagOrExit, } from './flag-values.js';
@@ -81,6 +81,9 @@ function keyRuleLine(hippoRoot) {
81
81
  `${localKeyPath(hippoRoot)} (readable by this user only); mint others with \`hippo auth create\``);
82
82
  }
83
83
  export async function handleServe({ hippoRoot, flags }) {
84
+ // The server's own runtime and worker threads write, so the switch stops it rather than leak.
85
+ if (envReadOnly())
86
+ fail('hippo serve does not run under HIPPO_READ_ONLY=1; read with hippo mcp');
84
87
  requireInit(hippoRoot);
85
88
  const portRaw = stringFlag(flags, 'port') ?? envPort() ?? DEFAULT_SERVER_PORT;
86
89
  const port = Number(portRaw);
@@ -35,6 +35,8 @@ export interface VerbRow {
35
35
  readonly destructive?: true;
36
36
  /** Unset: --dry-run is honoured exactly when the verb declares it; `false` refuses it even so. */
37
37
  readonly dryRun?: false | DryRunForm;
38
+ /** Under HIPPO_READ_ONLY=1, 'refuse' exits 1 and 'skip' exits 0 before the verb opens anything. */
39
+ readonly readOnly?: 'refuse' | 'skip';
38
40
  }
39
41
  export interface VerbSpec extends VerbRow {
40
42
  readonly run: (ctx: CommandContext) => Promise<void>;
@@ -133,6 +133,7 @@ export const HEALTH_VERBS = {
133
133
  ],
134
134
  }),
135
135
  outcome: verb(() => import('../curate.js'), 'handleOutcome', {
136
+ readOnly: 'refuse',
136
137
  repairsCodexWrapper: true,
137
138
  scoped: true,
138
139
  flags: { switches: ['bad', 'good'], values: ['id'] },
@@ -155,6 +156,7 @@ export const HEALTH_VERBS = {
155
156
  ],
156
157
  }),
157
158
  resolve: verb(() => import('../conflicts.js'), 'handleResolve', {
159
+ readOnly: 'refuse',
158
160
  needs: ['conflicts'],
159
161
  destructive: true,
160
162
  flags: { switches: ['forget', 'reject-loser'], values: ['keep', 'reason'] },
@@ -246,6 +248,7 @@ export const HEALTH_VERBS = {
246
248
  ],
247
249
  }),
248
250
  'capture-error': verb(() => import('../hooks/capture-error.js'), 'handleCaptureError', {
251
+ readOnly: 'skip',
249
252
  needs: ['failureLog', 'lessonWrites'],
250
253
  flags: { values: ['format', 'runtime'] },
251
254
  usage: [
@@ -33,6 +33,7 @@ export const MEMORY_VERBS = {
33
33
  ],
34
34
  }),
35
35
  remember: verb(() => import('../remember.js'), 'handleRemember', {
36
+ readOnly: 'refuse',
36
37
  repairsCodexWrapper: true,
37
38
  flags: {
38
39
  switches: ['error', 'extract', 'force', 'global', 'inferred', 'observed', 'pin', 'verified'],
@@ -52,6 +53,7 @@ export const MEMORY_VERBS = {
52
53
  ],
53
54
  }),
54
55
  supersede: verb(() => import('../remember.js'), 'handleSupersede', {
56
+ readOnly: 'refuse',
55
57
  destructive: true,
56
58
  flags: { switches: ['pin'], values: ['layer'], lists: ['tag'] },
57
59
  usage: [
@@ -211,6 +213,7 @@ export const MEMORY_VERBS = {
211
213
  ],
212
214
  }),
213
215
  refine: verb(() => import('../maintenance.js'), 'handleRefine', {
216
+ readOnly: 'refuse',
214
217
  flags: { switches: ['all', 'dry-run', 'json'], values: ['model'], numbers: ['limit'] },
215
218
  usage: [
216
219
  `
@@ -275,6 +278,7 @@ export const MEMORY_VERBS = {
275
278
  ],
276
279
  }),
277
280
  sleep: verb(() => import('../sleep.js'), 'handleSleep', {
281
+ readOnly: 'skip',
278
282
  needs: ['graphReads', 'vectors'],
279
283
  repairsCodexWrapper: true,
280
284
  destructive: true,
@@ -293,6 +297,7 @@ export const MEMORY_VERBS = {
293
297
  ],
294
298
  }),
295
299
  'daily-runner': verb(() => import('../daily-runner.js'), 'handleDailyRunner', {
300
+ readOnly: 'skip',
296
301
  needs: ['reports'],
297
302
  flags: {},
298
303
  usage: [
@@ -31,6 +31,7 @@ export const OBJECT_VERBS = {
31
31
  ],
32
32
  }),
33
33
  decide: verb(() => import('../decisions.js'), 'handleDecide', {
34
+ readOnly: 'refuse',
34
35
  needs: ['objects'],
35
36
  flags: { values: ['context', 'status', 'supersedes'], numbers: ['limit'] },
36
37
  usage: [
@@ -170,6 +171,7 @@ export const OBJECT_VERBS = {
170
171
  ],
171
172
  }),
172
173
  invalidate: verb(() => import('../curate.js'), 'handleInvalidate', {
174
+ readOnly: 'refuse',
173
175
  destructive: true,
174
176
  flags: { switches: ['churn', 'dry-run'], values: ['id', 'reason'] },
175
177
  usage: [
@@ -155,6 +155,7 @@ export const SESSION_VERBS = {
155
155
  ],
156
156
  }),
157
157
  forget: verb(() => import('../curate.js'), 'handleForget', {
158
+ readOnly: 'refuse',
158
159
  destructive: true,
159
160
  scoped: true,
160
161
  flags: { switches: ['archive', 'dry-run'], values: ['reason'] },
@@ -192,6 +193,7 @@ export const SESSION_VERBS = {
192
193
  ],
193
194
  }),
194
195
  learn: verb(() => import('../learn.js'), 'handleLearn', {
196
+ readOnly: 'refuse',
195
197
  needs: ['lessonWrites', 'vectors', 'vectorWrites'],
196
198
  scoped: true,
197
199
  flags: { switches: ['git'], values: ['repos'], numbers: ['days'] },
@@ -204,6 +206,7 @@ export const SESSION_VERBS = {
204
206
  ],
205
207
  }),
206
208
  promote: verb(() => import('../transfer.js'), 'handlePromote', {
209
+ readOnly: 'refuse',
207
210
  scoped: true,
208
211
  flags: {},
209
212
  usage: [
@@ -212,6 +215,7 @@ export const SESSION_VERBS = {
212
215
  ],
213
216
  }),
214
217
  share: verb(() => import('../transfer.js'), 'handleShare', {
218
+ readOnly: 'refuse',
215
219
  needs: ['vectors', 'vectorWrites'],
216
220
  dryRun: {
217
221
  form: '--auto',
@@ -243,6 +247,7 @@ export const SESSION_VERBS = {
243
247
  ],
244
248
  }),
245
249
  import: verb(() => import('../memory-import.js'), 'handleImport', {
250
+ readOnly: 'refuse',
246
251
  flags: {
247
252
  switches: ['agents', 'dry-run', 'global'],
248
253
  values: ['chatgpt', 'claude', 'cursor', 'file', 'markdown', 'name', 'scope', 'vault'],
@@ -278,6 +283,7 @@ export const SESSION_VERBS = {
278
283
  ],
279
284
  }),
280
285
  capture: verb(() => import('../hooks/capture.js'), 'handleCapture', {
286
+ readOnly: 'skip',
281
287
  repairsCodexWrapper: true,
282
288
  flags: {
283
289
  switches: ['dry-run', 'global', 'last-session', 'stdin'],
@@ -332,6 +338,7 @@ export const SESSION_VERBS = {
332
338
  ],
333
339
  }),
334
340
  'session-end': verb(() => import('../hooks/session-end.js'), 'handleSessionEnd', {
341
+ readOnly: 'skip',
335
342
  // Its sleep step reads --dry-run, but the capture after it writes for real.
336
343
  dryRun: false,
337
344
  flags: {
@@ -355,6 +362,7 @@ export const SESSION_VERBS = {
355
362
  ],
356
363
  }),
357
364
  '__session-end-worker': verb(() => import('../hooks/session-end-worker.js'), 'handleSessionEndWorker', {
365
+ readOnly: 'skip',
358
366
  needs: ['sessions', 'reports'],
359
367
  dryRun: false,
360
368
  flags: {
@@ -363,6 +371,7 @@ export const SESSION_VERBS = {
363
371
  },
364
372
  }),
365
373
  'pre-compact': verb(() => import('../hooks/pre-compact.js'), 'handlePreCompact', {
374
+ readOnly: 'skip',
366
375
  flags: { values: ['format', 'log-file', 'runtime'] },
367
376
  usage: [
368
377
  `
@@ -382,6 +391,7 @@ export const SESSION_VERBS = {
382
391
  ],
383
392
  }),
384
393
  'post-compact': verb(() => import('../hooks/post-compact.js'), 'handlePostCompact', {
394
+ readOnly: 'skip',
385
395
  flags: { values: ['log-file'] },
386
396
  usage: [
387
397
  `
@@ -398,6 +408,7 @@ export const SESSION_VERBS = {
398
408
  ],
399
409
  }),
400
410
  '__codex-session-end-worker': verb(() => import('../hooks/codex-session-end-worker.js'), 'handleCodexSessionEndWorker', {
411
+ readOnly: 'skip',
401
412
  flags: { values: ['codex-home', 'history-path', 'log-file', 'start-offset', 'started-at'] },
402
413
  }),
403
414
  hook: verb(() => import('../hook.js'), 'handleHook', {
@@ -9,7 +9,9 @@ import { RecallRequestError } from '../../api/recall/request.js';
9
9
  import { globalTargetOf } from '../../api/infra.js';
10
10
  import { recordTokens } from '../../api/tokens.js';
11
11
  import { mcpApiContext, } from './protocol.js';
12
- import { TOOLS, TOOLS_BY_NAME, ARGS_CHECKED_BY_API } from './tools.js';
12
+ import { TOOLS, TOOLS_BY_NAME, ARGS_CHECKED_BY_API, WRITE_TOOLS } from './tools.js';
13
+ import { READ_ONLY_REFUSAL } from '../../base/errors/read-only.js';
14
+ import { readOnlyOf } from '../../api/types.js';
13
15
  import { runRecallTool, runAssembleTool, runDrillTool, runContextTool } from './recall-tools.js';
14
16
  import { runRememberTool, runOutcomeTool, runLearnTool } from './memory-tools.js';
15
17
  import { runPredictBaserateTool, runStatusTool, runConflictsTool, runResolveTool, runShareTool, runPeersTool, } from './admin-tools.js';
@@ -130,7 +132,9 @@ async function callTool(id, params, ctx) {
130
132
  const run = toolRun(toolName, ctx);
131
133
  if (run === undefined)
132
134
  return errorReply(id, INTERNAL_ERROR, STORE_NOT_PORTED_MESSAGE);
133
- const refusal = sharedStoreRefusal(toolName, ctx);
135
+ const refusal = WRITE_TOOLS.has(toolName) && readOnlyOf(ctx)
136
+ ? READ_ONLY_REFUSAL
137
+ : sharedStoreRefusal(toolName, ctx);
134
138
  if (refusal !== undefined) {
135
139
  return resultReply(id, { content: [{ type: 'text', text: refusal }], isError: true });
136
140
  }
@@ -6,6 +6,8 @@ interface McpToolDefinition {
6
6
  }
7
7
  export declare const TOOLS: readonly McpToolDefinition[];
8
8
  export declare const TOOLS_BY_NAME: Map<string, McpToolDefinition>;
9
+ /** The tools that save, which answer the read-only refusal under HIPPO_READ_ONLY=1. */
10
+ export declare const WRITE_TOOLS: ReadonlySet<string>;
9
11
  export declare const ARGS_CHECKED_BY_API: Map<string, ReadonlySet<string>>;
10
12
  export {};
11
13
  //# sourceMappingURL=tools.d.ts.map
@@ -298,6 +298,14 @@ export const TOOLS = [
298
298
  },
299
299
  ];
300
300
  export const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
301
+ /** The tools that save, which answer the read-only refusal under HIPPO_READ_ONLY=1. */
302
+ export const WRITE_TOOLS = new Set([
303
+ 'hippo_remember',
304
+ 'hippo_outcome',
305
+ 'hippo_learn',
306
+ 'hippo_resolve',
307
+ 'hippo_share',
308
+ ]);
301
309
  // api.retrieve rejects these itself, so MCP and HTTP callers get the same typed error code for the
302
310
  // same bad value.
303
311
  export const ARGS_CHECKED_BY_API = new Map([
@@ -1,6 +1,6 @@
1
1
  import type { StoreRules } from '../base/ports/infra.js';
2
2
  import type { HippoStore, StoreGroups } from '../base/ports/store-index.js';
3
- import { StoreRuntime, type ServerRuntimeOptions, type SqliteServerRuntime } from '../store/sqlite/index.js';
3
+ import { StoreRuntime, type ServerRuntimeOptions, type SqliteServerRuntime, type StoreRuntimeOptions } from '../store/sqlite/index.js';
4
4
  export { askingNearestFirst, inSqliteSession as inStoreSession, runSqliteBatch as runStoreBatch, runSqliteHookRequest as runStoreHookRequest, runSqliteRequest as runStoreRequest, saveVectorGraphFile, sqliteDashboardReads as defaultDashboardReads, sqliteDiagnosticsStore as defaultDiagnostics, sqliteImportFiles as defaultImportFiles, sqliteImportStores as defaultImportStores, sqliteReach as defaultReach, sqliteStore as defaultStore, tenantOfApiKey, withSharedStoreHandles, type RequestStores as StoreSession, type ResolveOptions, type ServerRuntimeOptions, type SqliteServerRuntime as ServerRuntime, type SqliteStoreOptions as StoreOptions, type StoreRuntime, } from '../store/sqlite/index.js';
5
5
  export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, OTHER_STORE_MARKER, rankVectorRows, type VectorMatch, type VectorRow, } from '../store/sqlite/index.js';
6
6
  /** The default store as ./store-kit publishes it, with only the rules an add-on picks: a runtime
@@ -8,7 +8,7 @@ export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, OTHER_STORE_MARKE
8
8
  export declare const publishedDefaultStore: (hippoRoot: string, rules?: StoreRules) => HippoStore & StoreGroups;
9
9
  /** Runs `fn` on a store runtime of its own, disposed with the work `fn` detached on it once `fn`
10
10
  * settles, or closed by its exit hook if the process exits first. */
11
- export declare function withStoreRuntime<T>(fn: (runtime: StoreRuntime) => Promise<T>): Promise<T>;
11
+ export declare function withStoreRuntime<T>(fn: (runtime: StoreRuntime) => Promise<T>, opts?: StoreRuntimeOptions): Promise<T>;
12
12
  /** hippo.db as a server serves it, with an exit hook that closes what the server opened if
13
13
  * close() never runs. */
14
14
  export declare function defaultServerRuntime(hippoRoot: string, opts?: ServerRuntimeOptions): SqliteServerRuntime;
@@ -7,8 +7,8 @@ export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, OTHER_STORE_MARKE
7
7
  export const publishedDefaultStore = sqliteStoreWith;
8
8
  /** Runs `fn` on a store runtime of its own, disposed with the work `fn` detached on it once `fn`
9
9
  * settles, or closed by its exit hook if the process exits first. */
10
- export async function withStoreRuntime(fn) {
11
- const runtime = new StoreRuntime();
10
+ export async function withStoreRuntime(fn, opts = {}) {
11
+ const runtime = new StoreRuntime(opts);
12
12
  const onExit = () => runtime.closeNow();
13
13
  process.once('exit', onExit);
14
14
  try {
@@ -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.5.1",
5
+ "version": "3.7.0",
6
6
 
7
7
  "configSchema": {
8
8
  "type": "object",