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
@@ -53,6 +53,10 @@ export function updateMemoryRows(db, entries) {
53
53
  `UPDATE memories SET ${set}, updated_at = datetime('now') FROM v WHERE memories.id = v.id`).run(...chunk.flatMap(memoryRowValues));
54
54
  }
55
55
  }
56
+ // Storage spells "no successor" one way: a blank link is stored as none. Whitespace stays a link.
57
+ function storedLink(link) {
58
+ return link === '' ? null : (link ?? null);
59
+ }
56
60
  /** Bind values for WRITTEN_COLUMNS, in its order. */
57
61
  function memoryRowValues(entry) {
58
62
  // Markdown rebuilds, imports and add-ons pass stamps as written; only toISOString text sorts by
@@ -82,7 +86,7 @@ function memoryRowValues(entry) {
82
86
  entry.traceOutcome ?? null,
83
87
  entry.sourceSessionId ?? null,
84
88
  entry.validFrom ?? created,
85
- entry.supersededBy ?? null,
89
+ storedLink(entry.supersededBy),
86
90
  entry.extractedFrom ?? null,
87
91
  entry.dagLevel ?? 0,
88
92
  entry.dagParentId ?? null,
@@ -2,7 +2,7 @@
2
2
  // and the shared entry write path.
3
3
  import { markRetrieved } from '../../../base/memory/entry.js';
4
4
  import { entryAfterOutcome } from '../../../base/memory/keep-rules.js';
5
- import { closeHippoDb, withWriteScope, isSqliteBusy, } from '../../../db/index.js';
5
+ import { closeHippoDb, withWriteScope, } from '../../../db/index.js';
6
6
  import { rethrowIfStoreBlocked } from '../../../base/util/store-blocked.js';
7
7
  import { RejectedValueError, ConflictError, CrossTenantIdError, memoryNotFoundText, NotFoundError, } from '../../../base/errors/api-errors.js';
8
8
  import { markSummaryDirtyInTx, markSummariesDirtyInTx } from './summary-dirty.js';
@@ -16,7 +16,7 @@ import { mirrorBestEffort, writeMarkdownMirror, purgeMirrorBestEffort, removeEnt
16
16
  import { deferDueMirrors, markMirrorsDue } from '../folder-files/due-mirrors.js';
17
17
  import { bindHandleClock } from '../runtime/handle-clock.js';
18
18
  import { CLI_ACTOR } from '../../../base/scope/actor.js';
19
- import { archiveRawMemory } from './raw-archive.js';
19
+ import { archiveRawMemory, markMirrorCleaned } from './raw-archive.js';
20
20
  import { assertWriteRight, readerReaches, targetReader } from '../../../base/scope/recall-scope.js';
21
21
  import { recordTraceOutcome } from '../recall/recall-trace.js';
22
22
  import { deleteEntryCore } from './delete-and-batch.js';
@@ -512,13 +512,6 @@ function cleanArchivedMirrors(db, files, id) {
512
512
  `${errorMessage(mirrorErr)}`, errorFields(mirrorErr));
513
513
  return;
514
514
  }
515
- try {
516
- cachedStatement(db, `UPDATE raw_archive SET mirror_cleaned_at = ? WHERE memory_id = ?`).run(files.clock().toISOString(), id);
517
- }
518
- catch (err) {
519
- if (!isSqliteBusy(err))
520
- throw err;
521
- log.warnThenDebug('archive-mirror-stamp-busy', `archived ${id}; the store was busy, so the mirror reaper will re-check it on the next open`, errorFields(err));
522
- }
515
+ markMirrorCleaned(db, id, files.clock().toISOString());
523
516
  }
524
517
  //# sourceMappingURL=entry-writes.js.map
@@ -7,7 +7,8 @@ export interface ArchiveOptions {
7
7
  * audit row included. */
8
8
  afterArchive?: (db: DatabaseSyncLike, archivedMemoryId: string) => void;
9
9
  }
10
- /** Stamps the archived copy of `memoryId` as having its markdown mirror cleaned at `at`. */
10
+ /** Stamps the archived copy of `memoryId` as having its markdown mirror cleaned at `at`; a busy store
11
+ * leaves it unstamped for the reaper, since the change it follows has already committed. */
11
12
  export declare function markMirrorCleaned(db: DatabaseSyncLike, memoryId: string, at: string): void;
12
13
  /** archiveRawMemory for every row in `ids` in one write scope, in the same few statements for
13
14
  * one row or many; throws, archiving none, if any is missing or not raw. Returns the
@@ -1,16 +1,25 @@
1
1
  import { DEFAULT_TENANT_ID } from '../../../base/util/tenant.js';
2
2
  import { memoryNotFoundText, NotFoundError } from '../../../base/errors/api-errors.js';
3
3
  import { rawRemovalRefusal } from '../../../base/errors/raw-append-only.js';
4
- import { isFtsAvailable, withWriteScope } from '../../../db/index.js';
4
+ import { isFtsAvailable, isSqliteBusy, withWriteScope } from '../../../db/index.js';
5
5
  import { appendAuditEvents } from '../audit/audit.js';
6
6
  import { reportAuditWriteFailure } from '../../../base/records/audit-report.js';
7
7
  import { markSummaryDirtyInTx } from './summary-dirty.js';
8
8
  import { CLI_ACTOR } from '../../../base/scope/actor.js';
9
9
  import { cachedStatement } from '../../../db/statement-cache.js';
10
10
  import { handleStamp } from '../runtime/handle-clock.js';
11
- /** Stamps the archived copy of `memoryId` as having its markdown mirror cleaned at `at`. */
11
+ import { errorFields, log } from '../../../base/util/log.js';
12
+ /** Stamps the archived copy of `memoryId` as having its markdown mirror cleaned at `at`; a busy store
13
+ * leaves it unstamped for the reaper, since the change it follows has already committed. */
12
14
  export function markMirrorCleaned(db, memoryId, at) {
13
- cachedStatement(db, `UPDATE raw_archive SET mirror_cleaned_at = ? WHERE memory_id = ?`).run(at, memoryId);
15
+ try {
16
+ cachedStatement(db, `UPDATE raw_archive SET mirror_cleaned_at = ? WHERE memory_id = ?`).run(at, memoryId);
17
+ }
18
+ catch (err) {
19
+ if (!isSqliteBusy(err))
20
+ throw err;
21
+ log.warnThenDebug('archive-mirror-stamp-busy', `removed raw ${memoryId}; the store was busy, so the mirror reaper will re-check it on the next open`, errorFields(err));
22
+ }
14
23
  }
15
24
  // Every id list binds as one JSON array, so each statement's text is the same for one row or many.
16
25
  const IDS = 'SELECT value FROM json_each(?)';
@@ -7,7 +7,7 @@ import { sortableStamp } from '../../../base/memory/created-stamp.js';
7
7
  import { cachedStatement } from '../../../db/statement-cache.js';
8
8
  import { notSupersededIn } from '../../../db/sql-predicates.js';
9
9
  import { MEMORY_SELECT_COLUMNS, rowToEntry, parseJsonArray, } from '../runtime/rows.js';
10
- import { pickRarestFtsQuery, listRecallEntries } from './search-rows.js';
10
+ import { pickRarestFtsQuery, listRecallEntriesWithout } from './search-rows.js';
11
11
  import { oldestFirst } from '../../rules/order.js';
12
12
  import { tenantAnd } from '../runtime/tenant.js';
13
13
  import { rowsHoldingTexts } from '../sharing/copy-rows.js';
@@ -187,12 +187,7 @@ export function listAmbientCandidates(db, tenantId, { recentNeeded, judge, recal
187
187
  function promptRecallEntries(db, tenantId, recall) {
188
188
  const ftsQuery = pickRarestFtsQuery(db, recall.terms);
189
189
  return ftsQuery
190
- ? listRecallEntries(db, ftsQuery, {
191
- limit: recall.limit,
192
- tenantId,
193
- includeSuperseded: false,
194
- ownScope: recall.ownScope,
195
- })
190
+ ? listRecallEntriesWithout(db, ftsQuery, { limit: recall.limit, tenantId, includeSuperseded: false, ownScope: recall.ownScope }, recall.excludeTags ?? [])
196
191
  : [];
197
192
  }
198
193
  // calculateStrength's decay exponent with its reward factor under `model`: the strongest rows,
@@ -11,6 +11,9 @@ export declare function listSearchEntries(db: DatabaseSyncLike, query: string, l
11
11
  * '%:private:%'` runs before the LIMIT so private rows cannot starve admitted ones;
12
12
  * `passesScopeFilterForRecall` is the exact post-filter. */
13
13
  export declare function listRecallEntries(db: DatabaseSyncLike, query: string, options: RecallSearchEntriesOptions): MemoryEntry[];
14
+ /** `listRecallEntries` with rows tagged `excludeTags` cut before the limit, which the recall port
15
+ * has no option for. */
16
+ export declare function listRecallEntriesWithout(db: DatabaseSyncLike, query: string, options: RecallSearchEntriesOptions, excludeTags: readonly string[]): MemoryEntry[];
14
17
  /** The rows nearest `queryVector` that pass `spec`, nearest first; `index` proposes them when it
15
18
  * can. */
16
19
  export declare function listVectorCandidateEntries(db: DatabaseSyncLike, queryVector: readonly number[], spec: VectorCandidateSpec, index?: VectorIndex): Promise<MemoryEntry[]>;
@@ -1,7 +1,7 @@
1
1
  import { isFtsAvailable } from '../../../db/index.js';
2
2
  import { cjkIndexTerms, partitionCjkTerms, tokenize } from '../../../base/util/tokenize.js';
3
3
  import { recallScopeFilter } from '../../../base/scope/recall-scope.js';
4
- import { originInSql, scopeAdmitSql } from '../runtime/rule-sql.js';
4
+ import { originInSql, scopeAdmitSql, tagsOf } from '../runtime/rule-sql.js';
5
5
  import { ftsTermParts, RAREST_TERM_COUNT, rarestFtsQuery, spreadCjkTerms, } from '../../../base/rank/prompt-recall.js';
6
6
  import { errorMessage, log, errorFields } from '../../../base/util/log.js';
7
7
  import { topVectorMatches } from '../../../db/vector-match.js';
@@ -47,10 +47,20 @@ function withProject(scope, col, origin) {
47
47
  params: [...scope.params, ...originProjects],
48
48
  };
49
49
  }
50
+ // In SQL, not after the window cut, so excluded rows cannot fill the LIMIT that kept rows need.
51
+ function withoutTags(scope, col, excludeTags) {
52
+ if (excludeTags.length === 0)
53
+ return scope;
54
+ return {
55
+ sql: `${scope.sql} AND NOT EXISTS (SELECT 1 FROM json_each(${tagsOf(`${col}tags_json`)}) ` +
56
+ `WHERE value IN (${placeholders(excludeTags.length)}))`,
57
+ params: [...scope.params, ...excludeTags],
58
+ };
59
+ }
50
60
  const FTS_QUERY_SYNTAX_RE = /fts5: syntax error|unterminated string/i;
51
61
  function listSearchRows(db, { query, limit, tenantId, options = {} }) {
52
- const { scopeFilter, includeSuperseded = true, originProjects } = options;
53
- const p = searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjects);
62
+ const { scopeFilter, includeSuperseded = true, originProjects, excludeTags = [] } = options;
63
+ const p = searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjects, excludeTags);
54
64
  const terms = Array.from(new Set(tokenize(query)));
55
65
  if (terms.length === 0) {
56
66
  // LIMIT here too, so every candidate path honours the caller's cap.
@@ -90,7 +100,7 @@ function interleaveRows(a, b, limit) {
90
100
  }
91
101
  return [...out.values()];
92
102
  }
93
- function searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjects) {
103
+ function searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjects, excludeTags) {
94
104
  // One tenant reads through the composite idx_memories_tenant_created.
95
105
  const one = tenantId !== ALL_TENANTS;
96
106
  const tenantPredicate = tenantAnd(tenantId, 'm.tenant_id = ?').sql;
@@ -102,8 +112,8 @@ function searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjec
102
112
  // Tenant-only path: for every tenant `tenantOnlyPredicate` is '', so the archived clause switches
103
113
  // between ' AND' and ' WHERE' by caller context.
104
114
  const archivedClauseTenantOnly = one ? ` AND kind != 'archived'` : ` WHERE kind != 'archived'`;
105
- const aliasScope = withProject(recallScopeClause('m.', scopeFilter), 'm.', originProjects);
106
- const plainScope = withProject(recallScopeClause('', scopeFilter), '', originProjects);
115
+ const aliasScope = withoutTags(withProject(recallScopeClause('m.', scopeFilter), 'm.', originProjects), 'm.', excludeTags);
116
+ const plainScope = withoutTags(withProject(recallScopeClause('', scopeFilter), '', originProjects), '', excludeTags);
107
117
  const scopeParams = aliasScope.params;
108
118
  const currentAlias = includeSuperseded ? '' : ` AND ${notSupersededIn('m.')}`;
109
119
  const currentNoAlias = includeSuperseded ? '' : ` AND ${notSupersededIn()}`;
@@ -215,6 +225,11 @@ export function listSearchEntries(db, query, limit = DEFAULT_SEARCH_CANDIDATE_LI
215
225
  * '%:private:%'` runs before the LIMIT so private rows cannot starve admitted ones;
216
226
  * `passesScopeFilterForRecall` is the exact post-filter. */
217
227
  export function listRecallEntries(db, query, options) {
228
+ return listRecallEntriesWithout(db, query, options, []);
229
+ }
230
+ /** `listRecallEntries` with rows tagged `excludeTags` cut before the limit, which the recall port
231
+ * has no option for. */
232
+ export function listRecallEntriesWithout(db, query, options, excludeTags) {
218
233
  const { limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true, originProjects, ownScope, } = options;
219
234
  const scopeFilter = recallScopeFilter(requestedScope, explicitScopeMode, ownScope);
220
235
  return listSearchRows(db, {
@@ -225,6 +240,7 @@ export function listRecallEntries(db, query, options) {
225
240
  scopeFilter,
226
241
  includeSuperseded,
227
242
  originProjects,
243
+ excludeTags,
228
244
  },
229
245
  }).map(rowToEntry);
230
246
  }
@@ -130,6 +130,8 @@ interface SaveRule<K extends SavableKind> {
130
130
  readonly createKeys: (fields: ObjectFields[K], version: number) => JsonObject;
131
131
  /** Keys the supersede row stores after its own. */
132
132
  readonly supersedeKeys?: (fields: ObjectFields[K]) => JsonObject;
133
+ /** The save also weakens the replaced row's mirror and the memory it names. */
134
+ readonly weakensPredecessor?: true;
133
135
  }
134
136
  export declare const hasText: (text: string | null | undefined) => boolean;
135
137
  type SaveRules = {
@@ -201,7 +201,11 @@ const refreshKeys = (f) => f.receiptCount === undefined
201
201
  ? { refreshed: false }
202
202
  : { refreshed: true, receipt_count: f.receiptCount };
203
203
  export const SAVE_RULES = {
204
- decision: { versioned: false, createKeys: (f) => ({ has_context: hasText(f.context) }) },
204
+ decision: {
205
+ versioned: false,
206
+ createKeys: (f) => ({ has_context: hasText(f.context) }),
207
+ weakensPredecessor: true,
208
+ },
205
209
  process: {
206
210
  versioned: true,
207
211
  createKeys: (f, version) => ({
@@ -14,5 +14,8 @@ export declare function saveAny(on: OnHandle, files: StoreFiles, ...[tenantId, k
14
14
  } | {
15
15
  readonly refused: "unlinked";
16
16
  readonly memoryId: string;
17
+ } | {
18
+ readonly refused: "memory_missing";
19
+ readonly memoryId: string;
17
20
  } | import("../../../base/ports/store/objects.js").Prediction;
18
21
  //# sourceMappingURL=object-writes.d.ts.map
@@ -5,6 +5,8 @@ import { placeholders } from '../../../db/sql.js';
5
5
  import { chunked } from '../../../base/util/chunked.js';
6
6
  import { calculateStrength, LEGACY_TYPED_HALF_LIFE } from '../../../base/memory/strength.js';
7
7
  import { deriveHalfLife } from '../../../base/memory/entry.js';
8
+ import { markStale, SUPERSEDED_TAG } from '../../../base/memory/stale-mark.js';
9
+ import { readEntriesByIds } from '../entries/entry-reads.js';
8
10
  import { stampOriginProject, upsertEntryRow } from '../entries/entry-row.js';
9
11
  import { auditEntryWrite, writeEntryMirrors, auditingRefusal } from '../entries/entry-writes.js';
10
12
  import { markGraphDirty } from '../graph/graph-queue.js';
@@ -168,6 +170,7 @@ function onStoreHalfLife(db, mirror, rules) {
168
170
  function withMirror(on, write, writeRow) {
169
171
  return on((db, files) => auditingRefusal(db, write.actor, () => {
170
172
  let mirror = stampOriginProject(files, write.mirror);
173
+ let also = [];
171
174
  const written = withWriteScopeOr(db, 'write_entry', (rollback) => {
172
175
  mirror = onStoreHalfLife(db, mirror, files);
173
176
  upsertEntryRow(db, mirror);
@@ -175,6 +178,10 @@ function withMirror(on, write, writeRow) {
175
178
  if (refusalOf(row))
176
179
  return rollback(row);
177
180
  auditEntryWrite(db, mirror, write.actor);
181
+ const others = write.alsoWrite?.(db) ?? [];
182
+ if (refusalOf(others))
183
+ return rollback(others);
184
+ also = others;
178
185
  return row;
179
186
  });
180
187
  if (refusalOf(written))
@@ -183,18 +190,53 @@ function withMirror(on, write, writeRow) {
183
190
  if (write.graphTenant !== undefined)
184
191
  markGraphDirty(db, write.graphTenant, mirror.id);
185
192
  writeEntryMirrors(files.hippoRoot, mirror);
193
+ for (const entry of also)
194
+ writeEntryMirrors(files.hippoRoot, entry);
186
195
  return written;
187
196
  }), openStore);
188
197
  }
198
+ /** The memory the replaced row mirrors; none when the save replaces nothing or the mirror is gone. */
199
+ function replacedMirrorId(db, tenantId, kind, replaced) {
200
+ if (replaced === undefined)
201
+ return undefined;
202
+ // SAFETY: the SELECT names memory_id, a column every typed-object table has.
203
+ const row = cachedStatement(db, `SELECT memory_id FROM ${objectTable(kind)} WHERE id = ? AND tenant_id = ?`).get(replaced, tenantId);
204
+ return row?.memory_id ?? undefined;
205
+ }
206
+ /** Weakens the memory the replaced row mirrors, if it has one, and the one the save names, in the
207
+ * save's scope. A named memory the tenant does not hold refuses the save; a gone mirror is skipped. */
208
+ function weakenWithSave(db, tenantId, kind, save) {
209
+ const named = save.weakensMemoryId;
210
+ const derived = replacedMirrorId(db, tenantId, kind, save.supersedesId);
211
+ const ids = [...new Set([derived, named].filter((id) => id !== undefined))];
212
+ const held = readEntriesByIds(db, ids, tenantId);
213
+ if (named !== undefined && !held.has(named)) {
214
+ return { refused: 'memory_missing', memoryId: named };
215
+ }
216
+ const weakened = [];
217
+ for (const id of ids) {
218
+ const entry = held.get(id);
219
+ if (entry === undefined)
220
+ continue;
221
+ const marked = markStale(entry, SUPERSEDED_TAG);
222
+ upsertEntryRow(db, marked);
223
+ auditEntryWrite(db, marked, save.actor);
224
+ weakened.push(marked);
225
+ }
226
+ return weakened;
227
+ }
189
228
  function save(on, tenantId, kind, save) {
190
229
  const spec = rowSpec(kind);
191
230
  const write = {
192
231
  mirror: save.mirror,
193
232
  actor: save.actor,
194
233
  graphTenant: spec.graphType ? tenantId : undefined,
234
+ alsoWrite: SAVE_RULES[kind].weakensPredecessor
235
+ ? (db) => weakenWithSave(db, tenantId, kind, save)
236
+ : undefined,
195
237
  };
196
238
  const written = withMirror(on, write, (db, memoryId) => writeObjectRow(db, { tenantId, kind, memoryId, save }));
197
- return isObjectRefusal(written) ? written : spec.rowTo(written);
239
+ return refusalOf(written) ? written : spec.rowTo(written);
198
240
  }
199
241
  /** The linked ids are checked once the mirror is in and before the INSERT, so a refusal undoes
200
242
  * the mirror with it. */
@@ -3,7 +3,7 @@ import { ALL_TENANTS, DEFAULT_TENANT_ID } from '../../../base/util/tenant.js';
3
3
  import { withWriteScope } from '../../../db/index.js';
4
4
  import { insertRejectedValue } from './rejection.js';
5
5
  import { rejectionDigest, normalizeValueForRejection, } from '../../../base/records/rejection-digest.js';
6
- import { archiveRawMemory } from '../entries/raw-archive.js';
6
+ import { archiveRawMemory, markMirrorCleaned } from '../entries/raw-archive.js';
7
7
  import { MEMORY_CONFLICT_COLUMNS, parseJsonArray, rowToMemoryConflict, } from '../runtime/rows.js';
8
8
  import { audit } from '../audit/audit-event.js';
9
9
  import { syncChangedMirrors, purgeMirrorBestEffort } from '../folder-files/mirrors.js';
@@ -418,9 +418,8 @@ function purgeRemovedLoserMirrors(hippoRoot, db, loserId, removal) {
418
418
  // which the cleanupArchivedMirrors reaper never scans.
419
419
  const purge = { id: removedId, isRaw, logPrefix: 'resolveConflict' };
420
420
  const mirrorOk = purgeMirrorBestEffort(hippoRoot, purge);
421
- if (mirrorOk && isRaw) {
422
- cachedStatement(db, `UPDATE raw_archive SET mirror_cleaned_at = ? WHERE memory_id = ?`).run(handleStamp(db), removedId);
423
- }
421
+ if (mirrorOk && isRaw)
422
+ markMirrorCleaned(db, removedId, handleStamp(db));
424
423
  }
425
424
  }
426
425
  /** The conflict and loser ids every conflict_resolve audit row names. */
@@ -23,6 +23,7 @@ export declare function scopeAdmitSql(col: '' | 'm.', ownScope?: string | null):
23
23
  /** `origin_project IN (?, ...)` with one placeholder per name, the SQL twin of an origin filter;
24
24
  * an empty list matches nothing. */
25
25
  export declare function originInSql(names: readonly string[], column?: string): string;
26
+ export declare const tagsOf: (column: string) => string;
26
27
  /** SQL twin of ownScopeTouches, which is also canReadScope for an admin: every row but another
27
28
  * person's personal one. LIKE folds ASCII case as isPersonalScope's /i does. */
28
29
  export declare function touchableScopeSql(col: '' | 'm.', ownScope?: string | null): SqlFragment;
@@ -89,6 +89,8 @@ export function scopeAdmitSql(col, ownScope) {
89
89
  export function originInSql(names, column = 'origin_project') {
90
90
  return names.length === 0 ? '0' : `${column} IN (${placeholders(names.length)})`;
91
91
  }
92
+ // A tags column that is not a JSON array reads as no tags, as parseJsonArray reads it.
93
+ export const tagsOf = (column) => `CASE WHEN NOT json_valid(${column}) THEN '[]' WHEN json_type(${column}) = 'array' THEN ${column} ELSE '[]' END`;
92
94
  /** SQL twin of ownScopeTouches, which is also canReadScope for an admin: every row but another
93
95
  * person's personal one. LIKE folds ASCII case as isPersonalScope's /i does. */
94
96
  export function touchableScopeSql(col, ownScope) {
@@ -4,8 +4,9 @@ import type { SessionTurn } from './transcript.js';
4
4
  /** A turn close runs after each reply; a full close runs once, when the session ends. */
5
5
  export type WorkerMode = 'turn' | 'full';
6
6
  /** Runs `work` unless a live worker holds this session, which then runs the request after its
7
- * own so the last reply is never dropped. */
8
- export declare function runSessionWorker(sessionId: string | null, mode: WorkerMode, work: (mode: WorkerMode) => Promise<void>): Promise<void>;
7
+ * own so the last reply is never dropped. A detached worker's stderr goes nowhere, so `gaveUp`
8
+ * is where it leaves the line saying it stopped with the request still queued. */
9
+ export declare function runSessionWorker(sessionId: string | null, mode: WorkerMode, work: (mode: WorkerMode) => Promise<void>, gaveUp?: LineLog): Promise<void>;
9
10
  /** The cursor position after `turns`: how many there were and a hash of the last. */
10
11
  export declare function turnPosition(turns: readonly SessionTurn[]): string;
11
12
  /** The turns after `position`; all of them when it is null or its last turn is no longer in
@@ -63,13 +63,13 @@ function takeQueued(queued) {
63
63
  catch (err) {
64
64
  // ENOENT means nothing is queued; any other refusal leaves the request queued for the next
65
65
  // round, but is told.
66
- if (errorCode(err) !== 'ENOENT') {
67
- logger.warn(`session worker: cannot take the queued request ${queued}: ${errorMessage(err)}`, errorFields(err));
68
- }
69
- return null;
66
+ if (errorCode(err) === 'ENOENT')
67
+ return { kind: 'empty' };
68
+ logger.warn(`session worker: cannot take the queued request ${queued}: ${errorMessage(err)}`, errorFields(err));
69
+ return { kind: 'failed', err };
70
70
  }
71
71
  try {
72
- return fs.readFileSync(taken, 'utf8') === 'full' ? 'full' : 'turn';
72
+ return { kind: 'took', mode: fs.readFileSync(taken, 'utf8') === 'full' ? 'full' : 'turn' };
73
73
  }
74
74
  finally {
75
75
  fs.rmSync(taken, { force: true });
@@ -77,35 +77,61 @@ function takeQueued(queued) {
77
77
  }
78
78
  // Rounds in which takeQueued took nothing: such a request stays queued for the next worker instead of spinning here.
79
79
  const MAX_ROUNDS = 5;
80
+ function queuedKind(queued) {
81
+ try {
82
+ return fs.readFileSync(queued, 'utf8') === 'full' ? 'full' : 'turn';
83
+ }
84
+ catch (err) {
85
+ logger.debug(`session worker: cannot read ${queued}: ${errorMessage(err)}`, errorFields(err));
86
+ return 'unreadable';
87
+ }
88
+ }
89
+ function reportGaveUp(queued, lastFailed, gaveUp) {
90
+ const lastTake = lastFailed === null
91
+ ? 'none: the request was queued again each round'
92
+ : errorMessage(lastFailed.err);
93
+ const line = `session worker: gave up after ${MAX_ROUNDS} rounds with the ${queuedKind(queued)} request ` +
94
+ `still queued in ${queued}; ` +
95
+ `last take error: ${lastTake}`;
96
+ logger.warn(line, lastFailed === null ? undefined : errorFields(lastFailed.err));
97
+ gaveUp?.(line);
98
+ }
80
99
  /** Runs `work` unless a live worker holds this session, which then runs the request after its
81
- * own so the last reply is never dropped. */
82
- export async function runSessionWorker(sessionId, mode, work) {
100
+ * own so the last reply is never dropped. A detached worker's stderr goes nowhere, so `gaveUp`
101
+ * is where it leaves the line saying it stopped with the request still queued. */
102
+ export async function runSessionWorker(sessionId, mode, work, gaveUp) {
83
103
  const files = sessionStateFiles(sessionId);
84
104
  if (files === null)
85
105
  return work(mode);
86
106
  if (!queueRun(files, mode))
87
107
  return;
88
108
  let idleRounds = 0;
109
+ let lastFailed = null;
89
110
  for (let take = takeFileLock(files.lock); take.kind !== 'held'; take = takeFileLock(files.lock)) {
90
111
  if (take.kind === 'unusable') {
91
112
  warnUnusableLockOnce(files.lock, take.cause);
92
113
  return work(mode);
93
114
  }
94
115
  let ran = false;
116
+ let next = { kind: 'empty' };
95
117
  try {
96
- for (let next = takeQueued(files.queued); next !== null; next = takeQueued(files.queued)) {
118
+ for (next = takeQueued(files.queued); next.kind === 'took'; next = takeQueued(files.queued)) {
97
119
  ran = true;
98
- await work(next);
120
+ await work(next.mode);
99
121
  }
100
122
  }
101
123
  finally {
102
124
  take.lock.release();
103
125
  }
126
+ if (next.kind === 'failed')
127
+ lastFailed = next;
104
128
  // A taker that found the lock held left its request queued, so look again after every release.
105
129
  if (!fs.existsSync(files.queued))
106
130
  return;
107
- if (!ran && ++idleRounds >= MAX_ROUNDS)
131
+ if (!ran && ++idleRounds >= MAX_ROUNDS) {
132
+ reportGaveUp(files.queued, lastFailed, gaveUp);
108
133
  return;
134
+ }
109
135
  }
110
136
  }
111
137
  function turnKey(turn) {
@@ -4,6 +4,7 @@ import { contextReach, } from '../../api/types.js';
4
4
  import { ledgerReachOf } from '../../api/ledger-db.js';
5
5
  import { configReader } from '../../host/config-file.js';
6
6
  import { autoSleepConsolidate } from '../../api/sleep/auto-sleep.js';
7
+ import { sleepWasRefused } from '../../api/sleep/one-sleep.js';
7
8
  import { rerankerWithClef } from '../../api/recall/rows.js';
8
9
  import { hippoHomeDir } from '../../host/agent-homes.js';
9
10
  import { allMcpTools } from '../mcp/request.js';
@@ -166,7 +167,7 @@ function rootAutoSleep(root, hostTenantId) {
166
167
  config: cliConfig(root),
167
168
  tenantId: hostTenantId,
168
169
  infra: cliInfra(),
169
- }), 'cli', cliRuntime()).then(() => undefined);
170
+ }), 'cli', cliRuntime()).then((outcome) => (sleepWasRefused(outcome) ? outcome : undefined));
170
171
  }
171
172
  /** Stdio is the operator's own process: host admin, the folder's hippo.db, and an auto-sleep
172
173
  * that runs in process. One host per stdio loop, so its callers live as long as the loop, which
@@ -18,7 +18,7 @@ export declare class HttpResponseError extends Error {
18
18
  * pidfile's port. */
19
19
  export declare class MalformedReplyError extends Error {
20
20
  readonly route: string;
21
- constructor(route: string, detail: string);
21
+ constructor(route: string, detail: string, cause?: unknown);
22
22
  }
23
23
  /** The server gates every write, so a reply may be a skip; `force: true` stores it anyway. */
24
24
  export declare function postRemember(serverUrl: string, apiKey: string | undefined, opts: RememberOptions & {
@@ -51,10 +51,11 @@ export interface NearestIdsBody {
51
51
  /** The ids the server finds nearest `body.vector`, nearest first, in one try that gives up after
52
52
  * `timeoutMs`. */
53
53
  export declare function nearestIds(serverUrl: string, apiKey: string | undefined, body: NearestIdsBody, timeoutMs: number): Promise<string[]>;
54
- /**
55
- * 'never-sent': connection never opened, safe to replay locally. 'delivery-unknown': the request
56
- * was on the wire and may have committed, so never replay a write. 'none': not a transport
57
- * failure. */
54
+ /** 'never-sent': the connection never opened, so a write replays locally. 'none': the server answered
55
+ * with an error, or the request could not be built. 'delivery-unknown': the default for every error
56
+ * not listed, as the request may have committed, so a write is never replayed. */
58
57
  export type TransportFailure = 'none' | 'never-sent' | 'delivery-unknown';
59
58
  export declare function classifyTransportFailure(err: Error): TransportFailure;
59
+ /** What the user reads when a write may have landed and is not replayed. */
60
+ export declare function deliveryUnknownReason(err: Error, url: string): string;
60
61
  //# sourceMappingURL=client.d.ts.map
@@ -76,18 +76,31 @@ async function throwForStatus(res) {
76
76
  * pidfile's port. */
77
77
  export class MalformedReplyError extends Error {
78
78
  route;
79
- constructor(route, detail) {
80
- super(`the hippo server's reply to ${route} was not the expected JSON object (${detail})`);
79
+ constructor(route, detail, cause) {
80
+ super(`the hippo server's reply to ${route} was not the expected JSON object (${detail})`, cause === undefined ? undefined : { cause });
81
81
  this.route = route;
82
82
  this.name = 'MalformedReplyError';
83
83
  }
84
84
  }
85
+ /** A 2xx body under the cap: the plain Errors `readCappedJson` throws become a MalformedReplyError,
86
+ * and a transport error keeps its class. */
87
+ async function readReplyBody(res, route) {
88
+ try {
89
+ return await readCappedJson(res, MAX_REPLY_BYTES);
90
+ }
91
+ catch (err) {
92
+ if (err instanceof Error && err.constructor === Error) {
93
+ throw new MalformedReplyError(route, err.message, err);
94
+ }
95
+ throw err;
96
+ }
97
+ }
85
98
  /**
86
99
  * A 2xx reply's body, read under the cap; it must be a JSON object, and `guard` narrows it further
87
100
  * where the shape is known.
88
101
  */
89
102
  async function readReply(res, route, guard) {
90
- const body = await readCappedJson(res, MAX_REPLY_BYTES);
103
+ const body = await readReplyBody(res, route);
91
104
  if (!isJsonObject(body)) {
92
105
  throw new MalformedReplyError(route, body === null ? 'null' : Array.isArray(body) ? 'array' : 'a scalar');
93
106
  }
@@ -155,29 +168,47 @@ function transportCode(err) {
155
168
  const cause = err.cause;
156
169
  return isObjectLike(cause) && 'code' in cause ? String(cause.code) : '';
157
170
  }
171
+ const SOCKET_CODES = new Set([
172
+ 'ECONNRESET',
173
+ 'ECONNABORTED',
174
+ 'EPIPE',
175
+ 'UND_ERR_SOCKET',
176
+ ]);
177
+ /** A request that was on the wire when it failed: a dead socket, a fetch TypeError (no code means no
178
+ * known syscall) or a server gone quiet. */
179
+ function diedOnTheWire(err) {
180
+ return (SOCKET_CODES.has(transportCode(err)) || err instanceof TypeError || err.name === 'TimeoutError');
181
+ }
158
182
  export function classifyTransportFailure(err) {
159
- // The server answered, so the transport worked, whatever the message says.
160
- if (err instanceof HttpResponseError)
183
+ // The server answered, or encodeURIComponent threw before any request existed.
184
+ if (err instanceof HttpResponseError || err instanceof URIError)
161
185
  return 'none';
162
186
  const code = transportCode(err);
163
187
  // Connect-phase failures: no request bytes ever left the client, so a stale pidfile can be healed
164
188
  // and the call replayed on the direct path.
165
189
  if (code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'EAI_AGAIN')
166
190
  return 'never-sent';
167
- // The socket died mid-exchange.
168
- if (code === 'ECONNRESET' ||
169
- code === 'ECONNABORTED' ||
170
- code === 'EPIPE' ||
171
- code === 'UND_ERR_SOCKET') {
172
- return 'delivery-unknown';
191
+ // Any other error may have committed: only the two classes above are known not to have.
192
+ return 'delivery-unknown';
193
+ }
194
+ const WRITE_MAY_HAVE_LANDED = 'so the write may already have been applied. Not retrying locally.';
195
+ /** The syscall code or the class name of an error hippo does not know, never its message, which a
196
+ * foreign library may fill with the request's headers. */
197
+ function unrecognisedDetail(err) {
198
+ const code = transportCode(err);
199
+ const name = err.constructor.name;
200
+ const detail = /^[A-Z0-9_]+$/.test(code) ? code : name === 'Error' ? '' : name;
201
+ return detail === '' ? '' : ` (${detail})`;
202
+ }
203
+ /** What the user reads when a write may have landed and is not replayed. */
204
+ export function deliveryUnknownReason(err, url) {
205
+ if (err instanceof MalformedReplyError) {
206
+ return `${url} answered, but its reply could not be read, ${WRITE_MAY_HAVE_LANDED}`;
207
+ }
208
+ if (diedOnTheWire(err)) {
209
+ return `the connection to ${url} dropped or timed out mid-request, ${WRITE_MAY_HAVE_LANDED}`;
173
210
  }
174
- // Fetch rejects every network failure as a TypeError, with a cause only when the syscall is
175
- // known, so no code means the conservative answer.
176
- if (err instanceof TypeError)
177
- return 'delivery-unknown';
178
- // The request was sent and the server went quiet, so it may have committed.
179
- if (err.name === 'TimeoutError')
180
- return 'delivery-unknown';
181
- return 'none';
211
+ const unrecognised = `failed in a way hippo does not recognise${unrecognisedDetail(err)}`;
212
+ return `the request to ${url} ${unrecognised}, ${WRITE_MAY_HAVE_LANDED}`;
182
213
  }
183
214
  //# sourceMappingURL=client.js.map