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
@@ -5,6 +5,10 @@ import { logPhaseFailures } from '../../domain/consolidate/run.js';
5
5
  import { runConsolidation } from '../../domain/consolidate/sleep.js';
6
6
  import { strengthOf } from '../types.js';
7
7
  import { withDetached } from '../detached.js';
8
+ import { oneSleepPerStore, refusedAutoSleep, sleepWasRefused, } from './one-sleep.js';
9
+ // Long enough that a host skips the minutes another process spends on its sleep, short enough that
10
+ // the next due write after it ends is not left waiting.
11
+ const REFUSED_BACKOFF_MS = 60_000;
8
12
  /** Counts only when enabled: the count reads the store. */
9
13
  export async function autoSleepDue(newSince, tenantId, config, now) {
10
14
  const { enabled, threshold } = config;
@@ -21,7 +25,7 @@ export async function autoSleepAfterWrite(ctx) {
21
25
  const { tenantId, config } = ctx;
22
26
  if (host === undefined || !config.autoSleep.enabled || tenantId !== host.hostTenantId)
23
27
  return;
24
- if (host.latch.held)
28
+ if (host.latch.held || ctx.infra.clock().getTime() < (host.latch.notBefore ?? 0))
25
29
  return;
26
30
  // Held from the count on, so two writes landing together never both start a sleep.
27
31
  host.latch.held = true;
@@ -42,6 +46,11 @@ export async function autoSleepAfterWrite(ctx) {
42
46
  // it. A failure is logged here once, with the tenant.
43
47
  const sleep = host
44
48
  .run()
49
+ .then((outcome) => {
50
+ if (sleepWasRefused(outcome)) {
51
+ host.latch.notBefore = ctx.infra.clock().getTime() + REFUSED_BACKOFF_MS;
52
+ }
53
+ })
45
54
  .catch((err) => {
46
55
  log.error(`auto-sleep consolidate failed (tenant ${tenantId}): ${errorMessage(err)}`, errorFields(err));
47
56
  })
@@ -54,13 +63,17 @@ export async function autoSleepAfterWrite(ctx) {
54
63
  * that ran it. */
55
64
  export async function autoSleepConsolidate(ctx) {
56
65
  const { store, config, tenantId, infra } = ctx;
57
- const result = await runConsolidation(store, {
66
+ const result = await oneSleepPerStore(store, false, () => runConsolidation(store, {
58
67
  config,
59
68
  tenantId,
60
69
  llm: infra.llm,
61
70
  now: infra.clock(),
62
71
  strength: strengthOf(ctx),
63
- });
72
+ }), refusedAutoSleep);
73
+ if (sleepWasRefused(result)) {
74
+ log.info(`auto-sleep: skipped, a sleep is already running (since ${result.alreadyRunning.since})`);
75
+ return result;
76
+ }
64
77
  logPhaseFailures(result);
65
78
  return result;
66
79
  }
@@ -0,0 +1,23 @@
1
+ import type { Consolidation } from '../../base/ports/store/consolidation.js';
2
+ import type { ConsolidationResult } from '../../domain/consolidate/run.js';
3
+ import type { SleepResult } from './sleep.js';
4
+ /** What an auto-sleep answers when another sleep held the store; non-null, as the sleep child's
5
+ * reply check rejects a null result. */
6
+ export interface AutoSleepRefused {
7
+ readonly alreadyRunning: {
8
+ readonly since: string;
9
+ };
10
+ }
11
+ /** A sleep that did nothing: its 0 counts mean "nothing was done", not "the store is empty". */
12
+ export declare function refusedSleep(since: string): SleepResult;
13
+ export declare function refusedAutoSleep(since: string): AutoSleepRefused;
14
+ /** What a sleep entry point answers: its result, an auto-sleep's consolidation, a refusal, or nothing. */
15
+ export type SleepAnswer = SleepResult | ConsolidationResult | AutoSleepRefused | void;
16
+ /** True for an answer a held claim produced: the one test every reader of a sleep's answer uses. */
17
+ export declare function sleepWasRefused(result: SleepAnswer): result is AutoSleepRefused;
18
+ /** Runs `run` holding the store's claim; a held claim gives `refused(since)` and runs nothing. A dry
19
+ * run consolidates nothing, so it takes no claim, and a store without claim methods runs unguarded. */
20
+ export declare function oneSleepPerStore<R, F>({ consolidation }: {
21
+ readonly consolidation: Consolidation;
22
+ }, dryRun: boolean, run: () => Promise<R>, refused: (since: string) => F): Promise<R | F>;
23
+ //# sourceMappingURL=one-sleep.d.ts.map
@@ -0,0 +1,53 @@
1
+ import { errorFields, errorMessage, log } from '../../base/util/log.js';
2
+ /** A sleep that did nothing: its 0 counts mean "nothing was done", not "the store is empty". */
3
+ export function refusedSleep(since) {
4
+ return {
5
+ active: 0,
6
+ removed: 0,
7
+ mergedEpisodic: 0,
8
+ newSemantic: 0,
9
+ dryRun: false,
10
+ alreadyRunning: { since },
11
+ };
12
+ }
13
+ export function refusedAutoSleep(since) {
14
+ return { alreadyRunning: { since } };
15
+ }
16
+ /** True for an answer a held claim produced: the one test every reader of a sleep's answer uses. */
17
+ export function sleepWasRefused(result) {
18
+ return (typeof result === 'object' &&
19
+ result !== null &&
20
+ 'alreadyRunning' in result &&
21
+ result.alreadyRunning !== undefined);
22
+ }
23
+ /** Runs `run` holding the store's claim; a held claim gives `refused(since)` and runs nothing. A dry
24
+ * run consolidates nothing, so it takes no claim, and a store without claim methods runs unguarded. */
25
+ export async function oneSleepPerStore({ consolidation }, dryRun, run, refused) {
26
+ if (dryRun || consolidation.claimSleep === undefined)
27
+ return run();
28
+ const claim = await consolidation.claimSleep();
29
+ if (claim.kind === 'held')
30
+ return refused(claim.since);
31
+ try {
32
+ return await run();
33
+ }
34
+ finally {
35
+ await giveBack(consolidation);
36
+ }
37
+ }
38
+ // A failed release must not replace the sleep's own result or error; one retry, since a claim kept by a
39
+ // long-running host would refuse every later sleep until it restarts.
40
+ async function giveBack(consolidation) {
41
+ if (consolidation.releaseSleep === undefined)
42
+ return;
43
+ for (let attempt = 1; attempt <= 2; attempt++) {
44
+ try {
45
+ await consolidation.releaseSleep();
46
+ return;
47
+ }
48
+ catch (err) {
49
+ log.warn(`the sleep claim was not given back (attempt ${attempt} of 2): ${errorMessage(err)}`, errorFields(err));
50
+ }
51
+ }
52
+ }
53
+ //# sourceMappingURL=one-sleep.js.map
@@ -50,6 +50,11 @@ export interface SleepResult {
50
50
  };
51
51
  /** What the sleep did, in order. */
52
52
  events?: SleepEvent[];
53
+ /** Set when another sleep held the store's claim since that ISO time, so this one did nothing and
54
+ * its 0 counts mean "nothing was done", not "the store is empty". */
55
+ alreadyRunning?: {
56
+ since: string;
57
+ };
53
58
  }
54
59
  /** Sleeps the WHOLE store, every tenant, so /v1/sleep stays loopback-only; never auto-deletes
55
60
  * pinned, raw, kept or object-backing rows. */
@@ -1,8 +1,9 @@
1
1
  // The sleep cycle: decay, consolidation, dedupe, graph extraction and the other maintenance passes.
2
2
  import { runSleep } from './sleep-run.js';
3
+ import { oneSleepPerStore, refusedSleep } from './one-sleep.js';
3
4
  /** Sleeps the WHOLE store, every tenant, so /v1/sleep stays loopback-only; never auto-deletes
4
5
  * pinned, raw, kept or object-backing rows. */
5
6
  export async function sleepWholeStore(ctx, opts = {}) {
6
- return runSleep(ctx, opts);
7
+ return oneSleepPerStore(ctx.store, opts.dryRun === true, () => runSleep(ctx, opts), refusedSleep);
7
8
  }
8
9
  //# sourceMappingURL=sleep.js.map
@@ -1,6 +1,6 @@
1
1
  import type { TokenSummary, TokenSurface } from '../base/ports/store/ledger.js';
2
2
  import type { FailureSummary } from '../base/ports/store/rejections.js';
3
- import type { Context, ContextWith } from './types.js';
3
+ import { type Context, type ContextWith } from './types.js';
4
4
  /** Records memory text handed to an agent in the token ledger. Best-effort: never throws, since
5
5
  * a ledger failure must not fail the recall or context call. */
6
6
  export declare function recordTokens(ctx: Context, surface: TokenSurface, use: {
@@ -1,10 +1,13 @@
1
1
  // Token-use and failure reports.
2
2
  import { rethrowIfStoreBlocked } from '../base/util/store-blocked.js';
3
3
  import { errorMessage, log, errorFields } from '../base/util/log.js';
4
+ import { readOnlyOf } from './types.js';
4
5
  import { DAY_MS } from '../base/util/time.js';
5
6
  /** Records memory text handed to an agent in the token ledger. Best-effort: never throws, since
6
7
  * a ledger failure must not fail the recall or context call. */
7
8
  export async function recordTokens(ctx, surface, use) {
9
+ if (readOnlyOf(ctx))
10
+ return;
8
11
  try {
9
12
  await ctx.store.recordTokens({
10
13
  tenantId: ctx.tenantId,
@@ -94,6 +94,8 @@ export type EntryInfraPorts = Omit<InfraPorts, 'failureNotices'> & {
94
94
  /** A root's reach with the global store's config loaded beside it; `configAt` is the root's own
95
95
  * loader, and a promote embeds its copy with `embedderFor`. */
96
96
  export declare function contextReach(reach: StoreReach, configAt: (root: string) => HippoConfig, embedderFor: EmbedderFor, ledger?: LedgerHome): ContextReach;
97
+ /** Whether the root runs under HIPPO_READ_ONLY=1, where a read skips the writes it would make. */
98
+ export declare function readOnlyOf(ctx: Pick<Context, 'config'>): boolean;
97
99
  /** Whether the store serves many people: the root's reach says, else the store's config for an
98
100
  * integrator's store. */
99
101
  export declare function sharedStoreOf(ctx: Pick<Context, 'reach' | 'config'>): boolean;
package/dist/api/types.js CHANGED
@@ -30,6 +30,10 @@ export function contextReach(reach, configAt, embedderFor, ledger) {
30
30
  }
31
31
  return withConfig;
32
32
  }
33
+ /** Whether the root runs under HIPPO_READ_ONLY=1, where a read skips the writes it would make. */
34
+ export function readOnlyOf(ctx) {
35
+ return ctx.config.runtime?.readOnly === true;
36
+ }
33
37
  /** Whether the store serves many people: the root's reach says, else the store's config for an
34
38
  * integrator's store. */
35
39
  export function sharedStoreOf(ctx) {
@@ -50,6 +50,7 @@ function pinnedInjectFields(read) {
50
50
  promptRecallMinShared: read('promptRecallMinShared', count(P.promptRecallMinShared)),
51
51
  promptRecallMaxItems: read('promptRecallMaxItems', count(P.promptRecallMaxItems)),
52
52
  promptRecallCandidates: read('promptRecallCandidates', count(P.promptRecallCandidates)),
53
+ excludeTags: read('excludeTags', textList([])),
53
54
  };
54
55
  }
55
56
  // Every top-level key loadConfig reads. A bad value warns once, in one wording, and reads as the
@@ -78,6 +78,8 @@ export interface HippoConfig {
78
78
  promptRecallMaxItems: number;
79
79
  /** FTS candidate pool size per store before gating. Default 100. */
80
80
  promptRecallCandidates: number;
81
+ /** Tags the hook block leaves out: a row carrying any is no pin, recent or recall candidate. Default []. */
82
+ excludeTags?: string[];
81
83
  };
82
84
  /** Memory scope isolation (default true): ambient context (`hippo context`, the hook,
83
85
  * /v1/context, MCP hippo_context) excludes OTHER projects' memories; explicit recall is
@@ -181,6 +183,8 @@ export interface RuntimeSettings {
181
183
  /** HIPPO_LOSS_AVERSION_RATIO, which scales an error memory's strength; strength scoring
182
184
  * applies its floor. */
183
185
  readonly lossAversionRatio?: number;
186
+ /** HIPPO_READ_ONLY=1: the store refuses every write, so a read skips its own bookkeeping. */
187
+ readonly readOnly?: boolean;
184
188
  /** Where the CLEF rerankers send a request; without it they keep the native order. */
185
189
  readonly clef?: ClefSettings;
186
190
  }
@@ -60,6 +60,7 @@ export const DEFAULT_CONFIG = {
60
60
  promptRecallMinShared: 2,
61
61
  promptRecallMaxItems: 5,
62
62
  promptRecallCandidates: 100,
63
+ excludeTags: [],
63
64
  },
64
65
  contextProjectIsolation: true,
65
66
  extraction: {
@@ -8,7 +8,7 @@ export interface TransformersPackage {
8
8
  }
9
9
  /** The installed package to import, or null when neither is installed. */
10
10
  export declare function resolveTransformersPackage(): TransformersPackage | null;
11
- /** Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed. */
11
+ /** Whether @xenova/transformers or @huggingface/transformers is installed, resolved afresh on every call. */
12
12
  export declare function isEmbeddingAvailable(): boolean;
13
13
  export declare function resolveEmbeddingModel(embeddings: EmbeddingsConfig, explicitModel?: string): string;
14
14
  //# sourceMappingURL=local.d.ts.map
@@ -33,10 +33,9 @@ function entryUrl(name) {
33
33
  const viaRequire = ignoringCodes(NOT_INSTALLED, () => _require.resolve(name));
34
34
  return viaRequire === undefined ? null : pathToFileURL(viaRequire).href;
35
35
  }
36
- let installed;
37
- /** Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed. */
36
+ /** Whether @xenova/transformers or @huggingface/transformers is installed, resolved afresh on every call. */
38
37
  export function isEmbeddingAvailable() {
39
- return (installed ??= resolveTransformersPackage() !== null);
38
+ return resolveTransformersPackage() !== null;
40
39
  }
41
40
  export function resolveEmbeddingModel(embeddings, explicitModel) {
42
41
  const direct = explicitModel?.trim();
@@ -0,0 +1,3 @@
1
+ /** The refusal a write verb prints and a write MCP tool returns, word for word. */
2
+ export declare const READ_ONLY_REFUSAL = "read-only: not saved (HIPPO_READ_ONLY=1)";
3
+ //# sourceMappingURL=read-only.d.ts.map
@@ -0,0 +1,4 @@
1
+ // What every surface answers a write with under HIPPO_READ_ONLY=1, so a caller matches one text.
2
+ /** The refusal a write verb prints and a write MCP tool returns, word for word. */
3
+ export const READ_ONLY_REFUSAL = 'read-only: not saved (HIPPO_READ_ONLY=1)';
4
+ //# sourceMappingURL=read-only.js.map
@@ -109,6 +109,8 @@ export interface SpooledSummary {
109
109
  payload: Omit<CompactionStart, 'originProject'>;
110
110
  text: CompactionText;
111
111
  at: Date;
112
+ /** Stable per spool file, so a second import of it finds the record its first one made. */
113
+ importKey?: string;
112
114
  }
113
115
  /** How long a call waits on a locked store; unset is the store's default wait. */
114
116
  interface StoreWait {
@@ -102,7 +102,20 @@ export interface Consolidation {
102
102
  /** Marks the tenant's pending graph work up to `maxId` processed; returns how many rows it
103
103
  * marked. */
104
104
  markGraphDrained(tenantId: string, maxId: number): Promise<number>;
105
+ /** Takes the right to run a sleep on this store; `held` says another sleep has it and since
106
+ * when. One holder at a time across processes, and a holder that dies frees it. Optional: a
107
+ * store without it runs its sleeps unguarded. */
108
+ claimSleep?(): Promise<SleepClaim>;
109
+ /** Gives back a claim this store took; a claim not taken, or already given back, is a no-op. */
110
+ releaseSleep?(): Promise<void>;
105
111
  }
112
+ /** The answer to `claimSleep`: `since` is the ISO time the holder took it. */
113
+ export type SleepClaim = {
114
+ readonly kind: 'taken';
115
+ } | {
116
+ readonly kind: 'held';
117
+ readonly since: string;
118
+ };
106
119
  /** What each Consolidation method does to the store; every adapter honours it. */
107
120
  export declare const CONSOLIDATION_EFFECTS: {
108
121
  readonly begin: "write";
@@ -123,6 +136,8 @@ export declare const CONSOLIDATION_EFFECTS: {
123
136
  readonly duplicateCandidates: "read";
124
137
  readonly dirtyGraphTenants: "read";
125
138
  readonly markGraphDrained: "write";
139
+ readonly claimSleep: "write";
140
+ readonly releaseSleep: "write";
126
141
  };
127
142
  export interface SleepBegin {
128
143
  readonly dryRun: boolean;
@@ -18,5 +18,7 @@ export const CONSOLIDATION_EFFECTS = {
18
18
  duplicateCandidates: 'read',
19
19
  dirtyGraphTenants: 'read',
20
20
  markGraphDrained: 'write',
21
+ claimSleep: 'write',
22
+ releaseSleep: 'write',
21
23
  };
22
24
  //# sourceMappingURL=consolidation.js.map
@@ -51,6 +51,8 @@ export interface AmbientRecallRequest {
51
51
  terms: string[];
52
52
  limit: number;
53
53
  ownScope?: string;
54
+ /** Rows with any of these tags stay out of the full-text window, before its limit. */
55
+ excludeTags?: readonly string[];
54
56
  }
55
57
  /** The rows a non-pinned context read may admit; each predicate is one contextGet's admission
56
58
  * applies again in JS. */
@@ -29,6 +29,9 @@ export interface ObjectSave<K extends SavableKind = SavableKind> {
29
29
  readonly supersedesId?: number;
30
30
  /** Stored on a successor of a versioned kind only; a first version and a decision keep none. */
31
31
  readonly changeSummary?: string;
32
+ /** A decision only: a memory of the tenant the save also weakens, beside the one the replaced
33
+ * row mirrors; the save is refused when the tenant holds none. */
34
+ readonly weakensMemoryId?: string;
32
35
  readonly actor: string;
33
36
  /** The new row's createdAt and the replaced row's supersededAt: core's clock, as `toISOString`
34
37
  * gives it, since the list orders createdAt as text. */
@@ -50,6 +53,12 @@ export type IncidentOpenRefusal = {
50
53
  } | {
51
54
  readonly refused: 'vanished';
52
55
  };
56
+ /** Why a save wrote nothing: any `ObjectRefusal`, or `memoryId`, the memory the save named to
57
+ * weaken, is no memory of the tenant. */
58
+ export type SaveRefusal = ObjectRefusal | {
59
+ readonly refused: 'memory_missing';
60
+ readonly memoryId: string;
61
+ };
53
62
  export interface IncidentResolve {
54
63
  /** The row's resolutionText; core has checked it is not blank. */
55
64
  readonly text: string;
@@ -109,9 +118,11 @@ export interface Objects {
109
118
  closeObject(tenantId: string, kind: 'prediction', id: number, close: PredictionClose): Promise<Prediction>;
110
119
  /** In one transaction, in order: writes `mirror` as `EntryWrites.writeEntry` does; inserts the
111
120
  * row active (version 1, or the replaced row's plus one); with `supersedesId`, supersedes that
112
- * row; appends the supersede and create rows. A refusal (`missing`, `status`, `raced`,
113
- * `vanished`) writes nothing. */
114
- saveObject<K extends SavableKind>(tenantId: string, kind: K, save: ObjectSave<K>): Promise<ObjectByKind[K] | ObjectRefusal>;
121
+ * row; appends the supersede and create rows and the mirror's remember row. A decision then
122
+ * weakens the memory the replaced row mirrors, if it still has one, and the one
123
+ * `weakensMemoryId` names, each marked stale as `markStale` does and followed by its remember
124
+ * row. A refusal (`missing`, `status`, `raced`, `vanished`, `memory_missing`) writes nothing. */
125
+ saveObject<K extends SavableKind>(tenantId: string, kind: K, save: ObjectSave<K>): Promise<ObjectByKind[K] | SaveRefusal>;
115
126
  /** In one transaction, in order: writes `mirror` as `EntryWrites.writeEntry` does; checks each
116
127
  * linked id is a memory of the tenant; inserts the row open under the next id; appends the
117
128
  * incident_open row, then the mirror's remember row. A refusal leaves no mirror, row or audit
@@ -157,7 +168,7 @@ export interface ObjectCalls {
157
168
  listObjects(...args: ObjectListArgs): Promise<AnyObject[]>;
158
169
  objectById(tenantId: string, kind: ObjectKind | 'prediction', id: number): Promise<AnyObject | null>;
159
170
  closeObject(...args: ObjectCloseArgs): Promise<AnyObject | ObjectRefusal>;
160
- saveObject(...args: ObjectSaveArgs): Promise<AnyObject | ObjectRefusal | IncidentOpenRefusal>;
171
+ saveObject(...args: ObjectSaveArgs): Promise<AnyObject | SaveRefusal | IncidentOpenRefusal>;
161
172
  briefReceipts: Objects['briefReceipts'];
162
173
  predictionBaserate: Objects['predictionBaserate'];
163
174
  }
@@ -231,6 +231,8 @@ export declare const STORE_EFFECTS: {
231
231
  readonly duplicateCandidates: "read";
232
232
  readonly dirtyGraphTenants: "read";
233
233
  readonly markGraphDrained: "write";
234
+ readonly claimSleep: "write";
235
+ readonly releaseSleep: "write";
234
236
  };
235
237
  readonly learning: {
236
238
  readonly entriesMentioning: "read";
@@ -200,7 +200,7 @@ export type { VectorReads, StoredPart, StoredParts, VectorRowWrite, VectorWrite,
200
200
  export type { KeyRevoke, KeyMint, SelfKeyMint, KeyListQuery, KeyWrites } from './store/keys.js';
201
201
  export type { AmbientAdmission, AmbientCandidateRequest, AmbientCandidates, AmbientRefusal, ContextReads, SessionRawQuery, SessionRawCount, DescendantAdmission, DescendantOrigin, DescendantPage, DescendantWalk, SummaryDescendants, DagReads, } from './store/context-reads.js';
202
202
  export type { EntryWrite, EntryTarget, OutcomeWrite, SupersedeWrite, EntryRemoval, RawArchive, EntryWrites, LessonWrites, } from './store/entry-writes.js';
203
- export type { PredictionSave, PredictionClose, PredictionFilter, PredictionListQuery, ObjectListQuery, ObjectClose, ObjectSave, IncidentOpen, IncidentOpenRefusal, IncidentResolve, PoliciesInForceQuery, SkillsByNameQuery, Objects, } from './store/objects.js';
203
+ export type { PredictionSave, PredictionClose, PredictionFilter, PredictionListQuery, ObjectListQuery, ObjectClose, ObjectSave, IncidentOpen, IncidentOpenRefusal, IncidentResolve, SaveRefusal, PoliciesInForceQuery, SkillsByNameQuery, Objects, } from './store/objects.js';
204
204
  export type { AuditLog, AuditMaintenance } from './store/audit.js';
205
205
  export type { Readiness } from './store/diagnostics.js';
206
206
  export type { QuarantineListQuery, QuarantinedMemory, QuarantineRefusal, QuarantineApproval, QuarantineRejection, Quarantine, } from './store/quarantine.js';
@@ -17,6 +17,8 @@ export interface AmbientAdmission {
17
17
  /** The session of a shown or omitted transcript handoff: it stands for the closing message its
18
18
  * digest rows hold, so that session's digest stays out. */
19
19
  readonly handoffSessionId?: string;
20
+ /** Rows carrying any of these tags stay out; the prompt hook sets it from `pinnedInject.excludeTags`. */
21
+ readonly excludeTags?: readonly string[];
20
22
  }
21
23
  /**
22
24
  * Why an ambient load leaves a row out: `admission` refused it, or it passed but is neither pinned
@@ -33,9 +33,12 @@ export function ambientEnvelopeAdmits(e, a) {
33
33
  return true;
34
34
  return classifyOriginProject(e.originProject, a.currentProject) !== 'cross-project';
35
35
  }
36
- // Superseded rows go first because the envelope regex-scans content for secrets.
36
+ // The cheap checks go before the envelope, which regex-scans content for secrets.
37
37
  export function ambientAdmits(e, a) {
38
- return !isSuperseded(e) && !isOwnCompactionItem(e, a.ownSessionId) && ambientEnvelopeAdmits(e, a);
38
+ return (!isSuperseded(e) &&
39
+ !isOwnCompactionItem(e, a.ownSessionId) &&
40
+ !hasExcludedTag(e, a.excludeTags) &&
41
+ ambientEnvelopeAdmits(e, a));
39
42
  }
40
43
  /** Why an ambient load leaves `e` out, or null when it keeps it. */
41
44
  export function ambientRefusal(e, a) {
@@ -50,4 +53,7 @@ export function descendantAdmits(row, a) {
50
53
  function isOwnCompactionItem(e, ownSessionId) {
51
54
  return (!!ownSessionId && e.sourceSessionId === ownSessionId && e.tags.includes(COMPACTION_MEMORY_TAG));
52
55
  }
56
+ function hasExcludedTag(e, excludeTags) {
57
+ return excludeTags !== undefined && excludeTags.some((tag) => e.tags.includes(tag));
58
+ }
53
59
  //# sourceMappingURL=read-admission.js.map
@@ -47,6 +47,7 @@ export declare const envSkipAutoIntegrations: () => boolean;
47
47
  export declare const envSkipSchedule: () => boolean;
48
48
  export declare const envMcpStdio: () => boolean;
49
49
  export declare const envRequireServer: () => boolean;
50
+ export declare const envReadOnly: () => boolean;
50
51
  export declare const envStdinWaitMs: () => number | undefined;
51
52
  export declare function envLogLevel(): string;
52
53
  /** `HIPPO_LOG_FORMAT=json` writes each log line as one JSON object; anything else keeps the text
@@ -20,6 +20,7 @@ const FLAGS = {
20
20
  HIPPO_REQUIRE_SERVER: false,
21
21
  HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL: false,
22
22
  HIPPO_ALLOW_CLEARTEXT: false,
23
+ HIPPO_READ_ONLY: true,
23
24
  SLACK_ALLOW_UNKNOWN_TEAM_FALLBACK: false,
24
25
  GITHUB_ALLOW_UNKNOWN_INSTALLATION_FALLBACK: false,
25
26
  };
@@ -152,6 +153,7 @@ export function envRuntimeSettings() {
152
153
  dagRebuildCap: envDagRebuildCap(),
153
154
  activeScope: envActiveScope() ?? undefined,
154
155
  lossAversionRatio: envLossAversionRatio(),
156
+ readOnly: envReadOnly(),
155
157
  clef: envClefSettings(),
156
158
  };
157
159
  }
@@ -200,6 +202,7 @@ export const envSkipAutoIntegrations = bool('HIPPO_SKIP_AUTO_INTEGRATIONS');
200
202
  export const envSkipSchedule = bool('HIPPO_SKIP_SCHEDULE');
201
203
  export const envMcpStdio = bool('HIPPO_MCP_STDIO');
202
204
  export const envRequireServer = bool('HIPPO_REQUIRE_SERVER');
205
+ export const envReadOnly = bool('HIPPO_READ_ONLY');
203
206
  const envRequireSessionScopedFreshTail = bool('HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL');
204
207
  export const envStdinWaitMs = posInt('HIPPO_STDIN_WAIT_MS');
205
208
  export function envLogLevel() {
@@ -2,7 +2,7 @@
2
2
  * Single source of truth for the package version, written by scripts/sync-version.mjs; never
3
3
  * edit by hand. Read by the db rollback guard, /health, MCP. A constant, not a runtime
4
4
  * package.json read: the published bundle may lack package.json on a path ESM can resolve. */
5
- export declare const PACKAGE_VERSION = "3.4.0";
5
+ export declare const PACKAGE_VERSION = "3.6.0";
6
6
  /** The floor a store takes on its first expiring key: the first release with schema v53, set by
7
7
  * hand in that release; scripts/checks/check-expiring-keys-floor.mjs gates it. */
8
8
  export declare const EXPIRING_KEYS_MIN_BINARY = "1.64.0";
@@ -2,7 +2,7 @@
2
2
  * Single source of truth for the package version, written by scripts/sync-version.mjs; never
3
3
  * edit by hand. Read by the db rollback guard, /health, MCP. A constant, not a runtime
4
4
  * package.json read: the published bundle may lack package.json on a path ESM can resolve. */
5
- export const PACKAGE_VERSION = '3.4.0';
5
+ export const PACKAGE_VERSION = '3.6.0';
6
6
  /** The floor a store takes on its first expiring key: the first release with schema v53, set by
7
7
  * hand in that release; scripts/checks/check-expiring-keys-floor.mjs gates it. */
8
8
  export const EXPIRING_KEYS_MIN_BINARY = '1.64.0';
package/dist/cli.js CHANGED
@@ -1,7 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  // Hippo CLI entry point: parses argv and dispatches each verb through the table in
3
3
  // surface/cli/verbs.ts. `hippo help` prints the verb list from that table, so no list is kept here.
4
- import { envSkipAutoIntegrations, envTenant, validateFlags } from './base/util/env.js';
4
+ import { envReadOnly, envSkipAutoIntegrations, envTenant, validateFlags } from './base/util/env.js';
5
+ import { READ_ONLY_REFUSAL } from './base/errors/read-only.js';
5
6
  import * as fs from 'node:fs';
6
7
  import { fileURLToPath } from 'node:url';
7
8
  import { repairCodexWrapperIfInstalled } from './surface/hooks-install/codex-wrapper.js';
@@ -214,6 +215,14 @@ function checkUnknownFlags(command, flags, spec) {
214
215
  printError(`hippo: ignoring unknown flag ${flagNames(ignored)}. A later release will reject it.`);
215
216
  }
216
217
  }
218
+ // Before the verb reads stdin or opens a store, so a hook leaves no row, mirror file or worker.
219
+ function stopReadOnly(command, mode) {
220
+ if (mode === 'skip') {
221
+ log.warn(`hippo ${command}: skipped under HIPPO_READ_ONLY=1`);
222
+ return;
223
+ }
224
+ fail(READ_ONLY_REFUSAL);
225
+ }
217
226
  async function main(command, args, flags, hippoRoot) {
218
227
  if (command === '--version' || command === '-v' || boolFlag(flags, 'version'))
219
228
  printVersion();
@@ -245,6 +254,10 @@ async function main(command, args, flags, hippoRoot) {
245
254
  throw new CliExit(1);
246
255
  }
247
256
  assertVerbPorted(spec, CLI_STORE);
257
+ if (spec.readOnly !== undefined && envReadOnly()) {
258
+ stopReadOnly(command, spec.readOnly);
259
+ return;
260
+ }
248
261
  const run = () => spec.run({ hippoRoot, tenantId: envTenant(), args, flags });
249
262
  await (spec.scoped ? (await import('./surface/cli/api-context.js')).cliRequest(run) : run());
250
263
  }
@@ -11,6 +11,10 @@ export interface StoreAt {
11
11
  /** Runs `step` on the store unless it already ran to the end under the store's runtime; a throw
12
12
  * leaves it due, and with no runtime it always runs. */
13
13
  export declare function oncePerStore({ hippoRoot, runtime }: StoreAt, name: string, step: () => void): void;
14
+ /** Whether `db` was opened under a read-only runtime, so it refuses every write. */
15
+ export declare function isReadOnlyHandle(db: DatabaseSyncLike): boolean;
16
+ /** Runs `fn` with the gate open on `db`: a temp table lives in no store file. */
17
+ export declare function withTempTables<T>(db: DatabaseSyncLike, fn: () => T): T;
14
18
  /** Makes the next connection under `runtime` prove this store's schema again; `hippo init` calls
15
19
  * it because it is the explicit ask to set a store up. */
16
20
  export declare function reproveStoreSchema({ hippoRoot, runtime }: StoreAt): void;