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
@@ -4,7 +4,8 @@ import { COMPACTION_DB_WAIT_MS, REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS, } fr
4
4
  import { errorFields, errorMessage, log as hippoLog, reportCompactionFailure, } from '../../../base/util/log.js';
5
5
  import { isSqliteBusy } from '../../../db/index.js';
6
6
  import { closeStartedWithoutSummary, nextCompactionStart, openTranscriptRows, stalledSummarizedRows, } from './compaction-rows.js';
7
- import { compactionOrigin, markSnapshotSaved, markSummarized, recordSummary, saveItems, startCompaction, toRecord, } from './compactions-record.js';
7
+ import { compactionByRequest, compactionOrigin, markSnapshotSaved, markSummarized, recordSummary, saveItems, startCompaction, toRecord, } from './compactions-record.js';
8
+ import { spoolRequestId } from './spool-request-id.js';
8
9
  import { answered, bound } from '../runtime/bound.js';
9
10
  import { waitingOpener } from '../runtime/open.js';
10
11
  import { handleNow } from '../runtime/handle-clock.js';
@@ -126,11 +127,18 @@ function saveStalled(db, files, tenantId, opts) {
126
127
  return { saved, notes };
127
128
  }
128
129
  function recordSpooled(db, files, spooled) {
129
- const { id, sessionId, originProject, cwd, items } = recordSummary(db, files, spooled.tenantId, {
130
- meta: spooled.payload,
131
- text: spooled.text,
132
- at: spooled.at,
133
- });
130
+ const { tenantId, payload, importKey } = spooled;
131
+ const requestId = importKey === undefined ? undefined : spoolRequestId(importKey);
132
+ const earlier = requestId === undefined
133
+ ? null
134
+ : compactionByRequest(db, { tenantId, requestId, sessionId: payload.sessionId });
135
+ const { id, sessionId, originProject, cwd, items } = earlier ??
136
+ recordSummary(db, files, tenantId, {
137
+ meta: payload,
138
+ text: spooled.text,
139
+ at: spooled.at,
140
+ caller: { requestId },
141
+ });
134
142
  return { id, sessionId, originProject, cwd, items };
135
143
  }
136
144
  function saveRecordItems(db, files, tenantId, record, opts) {
@@ -0,0 +1,3 @@
1
+ /** `spool:` plus the key; a key too long for an id is hashed, so one key always gives one id. */
2
+ export declare function spoolRequestId(importKey: string): string;
3
+ //# sourceMappingURL=spool-request-id.d.ts.map
@@ -0,0 +1,12 @@
1
+ // The request id a spool file's compaction record carries, so a second import of the file finds it.
2
+ import { createHash } from 'node:crypto';
3
+ import { MAX_ID_LEN } from '../../../base/util/limits.js';
4
+ const PREFIX = 'spool:';
5
+ /** `spool:` plus the key; a key too long for an id is hashed, so one key always gives one id. */
6
+ export function spoolRequestId(importKey) {
7
+ const id = `${PREFIX}${importKey}`;
8
+ if (id.length <= MAX_ID_LEN)
9
+ return id;
10
+ return `${PREFIX}${createHash('sha256').update(importKey).digest('hex')}`;
11
+ }
12
+ //# sourceMappingURL=spool-request-id.js.map
@@ -24,6 +24,7 @@ import { auditRows, dirtySummaries, listL2SummariesPage, settleSummary, } from '
24
24
  import { META_KEY } from '../../../db/meta.js';
25
25
  import { noteRebuildFailures } from './rebuild-holds.js';
26
26
  import { emptyExtractions, noteEmptyExtractions } from './empty-extractions.js';
27
+ import { sleepClaim } from './sleep-lock.js';
27
28
  // A half-life move reads, writes, audits and records its base on one handle, so it commits whole or
28
29
  // not at all.
29
30
  function listHalfLifeRows(db, from, typedPending) {
@@ -140,6 +141,7 @@ export function sqliteConsolidation(handles) {
140
141
  ...bound(on, recordSleepBody(files), openStore),
141
142
  ...bound(on, bareBodies),
142
143
  commit: chunkedCommit(handles),
144
+ ...sleepClaim(files.hippoRoot),
143
145
  };
144
146
  }
145
147
  //# sourceMappingURL=consolidation.js.map
@@ -0,0 +1,4 @@
1
+ import type { Consolidation } from '../../../base/ports/store/consolidation.js';
2
+ /** The claim members of the folder's Consolidation group; the closure keeps the lock its sleep holds. */
3
+ export declare function sleepClaim(hippoRoot: string): Required<Pick<Consolidation, 'claimSleep' | 'releaseSleep'>>;
4
+ //# sourceMappingURL=sleep-lock.d.ts.map
@@ -0,0 +1,69 @@
1
+ // A sleep's claim on the store: a file lock beside hippo.db that every process on the folder honours,
2
+ // freed by the operating system when its holder dies, so no age or pid check can break a live sleep.
3
+ import * as fs from 'node:fs';
4
+ import * as path from 'node:path';
5
+ import { takeFileLock } from '../../../host/file-lock.js';
6
+ import { errorFields, errorMessage, log } from '../../../base/util/log.js';
7
+ import { answered } from '../runtime/bound.js';
8
+ const SLEEP_LOCK_FILE = 'sleep.lock.db';
9
+ // A folder that cannot keep a lock warns once for the process, not once per sleep.
10
+ const warnedRoots = new Set();
11
+ /** When the holder took the claim: the mtime it stamped on the lock file. */
12
+ function claimedSince(file) {
13
+ // A file gone under a live holder, or one that cannot be read, has no stamp left, so the time is now.
14
+ try {
15
+ return (fs.statSync(file, { throwIfNoEntry: false })?.mtime ?? new Date()).toISOString();
16
+ }
17
+ catch (err) {
18
+ log.warn(`the sleep claim on ${file} could not be read: ${errorMessage(err)}`, errorFields(err));
19
+ return new Date().toISOString();
20
+ }
21
+ }
22
+ // By path, never by descriptor: a descriptor closed here would drop this process's other locks.
23
+ function stamp(file) {
24
+ try {
25
+ const now = new Date();
26
+ fs.utimesSync(file, now, now);
27
+ }
28
+ catch (err) {
29
+ log.warn(`the sleep claim on ${file} was not stamped, so a refused sleep may name an older time: ` +
30
+ errorMessage(err), errorFields(err));
31
+ }
32
+ }
33
+ function warnUnusable(hippoRoot, cause) {
34
+ if (warnedRoots.has(hippoRoot))
35
+ return;
36
+ warnedRoots.add(hippoRoot);
37
+ log.warn(`the sleep claim could not be taken on ${hippoRoot}, so sleeps there run unguarded: ` +
38
+ errorMessage(cause), errorFields(cause));
39
+ }
40
+ /** The claim members of the folder's Consolidation group; the closure keeps the lock its sleep holds. */
41
+ export function sleepClaim(hippoRoot) {
42
+ // Joined at the claim, so a store built on a root that is no path still opens.
43
+ const lockFile = () => path.join(hippoRoot, SLEEP_LOCK_FILE);
44
+ let held = null;
45
+ return {
46
+ claimSleep: () => answered(() => {
47
+ const file = lockFile();
48
+ const take = takeFileLock(file);
49
+ if (take.kind === 'held')
50
+ return { kind: 'held', since: claimedSince(file) };
51
+ if (take.kind === 'unusable') {
52
+ warnUnusable(hippoRoot, take.cause);
53
+ return { kind: 'taken' };
54
+ }
55
+ held = take.lock;
56
+ stamp(file);
57
+ return { kind: 'taken' };
58
+ }),
59
+ releaseSleep: () => answered(() => {
60
+ try {
61
+ held?.release();
62
+ }
63
+ finally {
64
+ held = null;
65
+ }
66
+ }),
67
+ };
68
+ }
69
+ //# sourceMappingURL=sleep-lock.js.map
@@ -7,6 +7,7 @@ import { notSupersededAt } from '../../../db/sql-predicates.js';
7
7
  import { cachedStatement } from '../../../db/statement-cache.js';
8
8
  import { entriesPage, entryPageOrder, entryRange, } from '../runtime/keyset.js';
9
9
  import { MEMORY_SELECT_COLUMNS, rowToEntry } from '../runtime/rows.js';
10
+ import { tagsOf } from '../runtime/rule-sql.js';
10
11
  import { tenantAnd, TENANT_IS } from '../runtime/tenant.js';
11
12
  /** The least string above every string that starts with `prefix` in byte order, or null when
12
13
  * none is. */
@@ -36,8 +37,6 @@ function startsWith(column, prefix) {
36
37
  ? { sql: `${column} >= ?`, params: [prefix] }
37
38
  : { sql: `${column} >= ? AND ${column} < ?`, params: [prefix, upper] };
38
39
  }
39
- // A tags column that is not a JSON array reads as no tags, as parseJsonArray reads it.
40
- const tagsOf = (column) => `CASE WHEN NOT json_valid(${column}) THEN '[]' WHEN json_type(${column}) = 'array' THEN ${column} ELSE '[]' END`;
41
40
  const TERMS = {
42
41
  ids: (ids, column) => inList(column('id'), ids),
43
42
  origins: (origins, column) => inList(column('origin_project'), origins),
@@ -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(?)';
@@ -5,7 +5,7 @@ export { sqliteImportStores } from './maintenance/agent-import-stores.js';
5
5
  export { openSqliteSession, runSqliteBatch, runSqliteHookRequest, runSqliteRequest, type RequestPreset, } from './runtime/request-scope.js';
6
6
  export { sqliteServerRuntime, type ServerRuntimeOptions, type SqliteServerRuntime, } from './runtime/server-runtime.js';
7
7
  export type { SqliteStoreOptions } from './runtime/grant.js';
8
- export { StoreRuntime } from '../../db/store-runtime.js';
8
+ export { StoreRuntime, type StoreRuntimeOptions } from '../../db/store-runtime.js';
9
9
  export type { RequestStores } from '../../db/index.js';
10
10
  export { tenantOfApiKey, type ResolveOptions } from './runtime/tenant.js';
11
11
  export { askingNearestFirst } from './vectors/vector-reads.js';
@@ -5,6 +5,7 @@ import { assertTenantId } from '../../../base/scope/tenant-id.js';
5
5
  import { appendAuditEvents } from '../audit/audit.js';
6
6
  import { CLI_ACTOR } from '../../../base/scope/actor.js';
7
7
  import { cachedStatement } from '../../../db/statement-cache.js';
8
+ import { isReadOnlyHandle } from '../../../db/connect.js';
8
9
  import { plural } from '../../../base/util/format.js';
9
10
  function emptyBaserate(classTag) {
10
11
  const nulls = {
@@ -65,9 +66,10 @@ emitAudit = true) {
65
66
  `).all(tenantId, classTag);
66
67
  const baserate = predictionBaserateOf(classTag, rows.map((r) => ({ estimate: r.estimate_value, actual: r.actual_value })));
67
68
  // An empty class is audited too, since an agent probing one is a signal; the recall path passes
68
- // false and audits its own hint.
69
- if (emitAudit)
69
+ // false and audits its own hint, and a read-only store keeps no row of the read.
70
+ if (emitAudit && !isReadOnlyHandle(db)) {
70
71
  auditBaserateRead(db, { tenantId, actor, classTag, nClosed: baserate.nClosed });
72
+ }
71
73
  return baserate;
72
74
  }
73
75
  function auditBaserateRead(db, { tenantId, actor, classTag, nClosed }) {
@@ -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,13 +1,14 @@
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';
8
8
  import { MEMORY_SELECT_COLUMNS, MEMORY_SEARCH_COLUMNS, rowToEntry, } from '../runtime/rows.js';
9
9
  import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../../../base/rank/search-types.js';
10
10
  import { cachedStatement } from '../../../db/statement-cache.js';
11
+ import { withTempTables } from '../../../db/connect.js';
11
12
  import { escapeLike } from '../../../base/util/escape.js';
12
13
  import { ftsAnyPhrase } from './fts-phrase.js';
13
14
  import { placeholders } from '../../../db/sql.js';
@@ -47,10 +48,20 @@ function withProject(scope, col, origin) {
47
48
  params: [...scope.params, ...originProjects],
48
49
  };
49
50
  }
51
+ // In SQL, not after the window cut, so excluded rows cannot fill the LIMIT that kept rows need.
52
+ function withoutTags(scope, col, excludeTags) {
53
+ if (excludeTags.length === 0)
54
+ return scope;
55
+ return {
56
+ sql: `${scope.sql} AND NOT EXISTS (SELECT 1 FROM json_each(${tagsOf(`${col}tags_json`)}) ` +
57
+ `WHERE value IN (${placeholders(excludeTags.length)}))`,
58
+ params: [...scope.params, ...excludeTags],
59
+ };
60
+ }
50
61
  const FTS_QUERY_SYNTAX_RE = /fts5: syntax error|unterminated string/i;
51
62
  function listSearchRows(db, { query, limit, tenantId, options = {} }) {
52
- const { scopeFilter, includeSuperseded = true, originProjects } = options;
53
- const p = searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjects);
63
+ const { scopeFilter, includeSuperseded = true, originProjects, excludeTags = [] } = options;
64
+ const p = searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjects, excludeTags);
54
65
  const terms = Array.from(new Set(tokenize(query)));
55
66
  if (terms.length === 0) {
56
67
  // LIMIT here too, so every candidate path honours the caller's cap.
@@ -90,7 +101,7 @@ function interleaveRows(a, b, limit) {
90
101
  }
91
102
  return [...out.values()];
92
103
  }
93
- function searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjects) {
104
+ function searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjects, excludeTags) {
94
105
  // One tenant reads through the composite idx_memories_tenant_created.
95
106
  const one = tenantId !== ALL_TENANTS;
96
107
  const tenantPredicate = tenantAnd(tenantId, 'm.tenant_id = ?').sql;
@@ -102,8 +113,8 @@ function searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjec
102
113
  // Tenant-only path: for every tenant `tenantOnlyPredicate` is '', so the archived clause switches
103
114
  // between ' AND' and ' WHERE' by caller context.
104
115
  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);
116
+ const aliasScope = withoutTags(withProject(recallScopeClause('m.', scopeFilter), 'm.', originProjects), 'm.', excludeTags);
117
+ const plainScope = withoutTags(withProject(recallScopeClause('', scopeFilter), '', originProjects), '', excludeTags);
107
118
  const scopeParams = aliasScope.params;
108
119
  const currentAlias = includeSuperseded ? '' : ` AND ${notSupersededIn('m.')}`;
109
120
  const currentNoAlias = includeSuperseded ? '' : ` AND ${notSupersededIn()}`;
@@ -215,6 +226,11 @@ export function listSearchEntries(db, query, limit = DEFAULT_SEARCH_CANDIDATE_LI
215
226
  * '%:private:%'` runs before the LIMIT so private rows cannot starve admitted ones;
216
227
  * `passesScopeFilterForRecall` is the exact post-filter. */
217
228
  export function listRecallEntries(db, query, options) {
229
+ return listRecallEntriesWithout(db, query, options, []);
230
+ }
231
+ /** `listRecallEntries` with rows tagged `excludeTags` cut before the limit, which the recall port
232
+ * has no option for. */
233
+ export function listRecallEntriesWithout(db, query, options, excludeTags) {
218
234
  const { limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true, originProjects, ownScope, } = options;
219
235
  const scopeFilter = recallScopeFilter(requestedScope, explicitScopeMode, ownScope);
220
236
  return listSearchRows(db, {
@@ -225,6 +241,7 @@ export function listRecallEntries(db, query, options) {
225
241
  scopeFilter,
226
242
  includeSuperseded,
227
243
  originProjects,
244
+ excludeTags,
228
245
  },
229
246
  }).map(rowToEntry);
230
247
  }
@@ -257,8 +274,10 @@ const vocabReady = new WeakSet();
257
274
  function ensureRarestVocab(db) {
258
275
  if (vocabReady.has(db))
259
276
  return;
260
- db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS temp.z1_rarest_vocab USING fts5vocab(main, 'memories_fts', 'row')`);
261
- db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS temp.z1_trigram_vocab USING fts5vocab(main, 'memories_trigram', 'row')`);
277
+ withTempTables(db, () => {
278
+ db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS temp.z1_rarest_vocab USING fts5vocab(main, 'memories_fts', 'row')`);
279
+ db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS temp.z1_trigram_vocab USING fts5vocab(main, 'memories_trigram', 'row')`);
280
+ });
262
281
  vocabReady.add(db);
263
282
  }
264
283
  /** Rarest-K prompt terms for this connection's FTS indexes, as a space-joined query string: words
@@ -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. */
@@ -28,6 +28,9 @@ export function openStore(hippoRoot, { grant, busyWaitMs }) {
28
28
  // this connection cannot write them.
29
29
  if (session?.setupDoneFor === hippoRoot)
30
30
  return db;
31
+ // A read-only store keeps its folder as it is: no mirror folder, due mirror or first-open row.
32
+ if (grant.runtime?.readOnly === true)
33
+ return db;
31
34
  const at = { hippoRoot, runtime: grant.runtime };
32
35
  try {
33
36
  ensureMirrorDirectories(at);
@@ -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