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,7 @@ import { cleanupArchivedMirrors } from './raw-archive-mirror-cleanup.js';
4
4
  import { errorCode, errorFields, errorMessage, log } from '../base/util/log.js';
5
5
  import { DatabaseSync } from './sqlite.js';
6
6
  import { DEFAULT_BUSY_WAIT_MS, execWithBusyRetry } from './busy.js';
7
- import { importLegacyVectors, runMigrations, settledStoreFacts, } from './migrate.js';
7
+ import { currentStoreFacts, importLegacyVectors, runMigrations, settledStoreFacts, } from './migrate.js';
8
8
  import { autoCheckpointPages } from './wal-checkpointer.js';
9
9
  import { storeKey } from './store-runtime.js';
10
10
  import { PRIVATE_DIR } from '../host/private-dir.js';
@@ -61,6 +61,24 @@ function sweepArchivedMirrorsIfDue(hippoRoot, db, pending) {
61
61
  cleanupArchivedMirrors(hippoRoot, db);
62
62
  }
63
63
  const SCHEMA_STEP = 'schema';
64
+ // Connections behind the read-only gate, so a read can still make the temp tables it needs.
65
+ const gated = new WeakSet();
66
+ /** Whether `db` was opened under a read-only runtime, so it refuses every write. */
67
+ export function isReadOnlyHandle(db) {
68
+ return gated.has(db);
69
+ }
70
+ /** Runs `fn` with the gate open on `db`: a temp table lives in no store file. */
71
+ export function withTempTables(db, fn) {
72
+ if (!gated.has(db))
73
+ return fn();
74
+ db.exec('PRAGMA query_only = OFF');
75
+ try {
76
+ return fn();
77
+ }
78
+ finally {
79
+ db.exec('PRAGMA query_only = ON');
80
+ }
81
+ }
64
82
  /** Makes the next connection under `runtime` prove this store's schema again; `hippo init` calls
65
83
  * it because it is the explicit ask to set a store up. */
66
84
  export function reproveStoreSchema({ hippoRoot, runtime }) {
@@ -83,6 +101,59 @@ function settleSchema(db, at, busyWaitMs) {
83
101
  oncePerStore(at, SCHEMA_STEP, () => undefined);
84
102
  return facts;
85
103
  }
104
+ // Shut after the schema step; only withTempTables opens it again, and only for a temp table.
105
+ function closeGate(db, facts) {
106
+ db.exec('PRAGMA query_only = ON');
107
+ gated.add(db);
108
+ return { db, facts };
109
+ }
110
+ // A read-only open never makes a store, so a missing one reads as an empty one held in memory.
111
+ function emptyReadOnlyStore(busyWaitMs) {
112
+ const db = new DatabaseSync(':memory:');
113
+ try {
114
+ return closeGate(db, runMigrations(db, undefined, busyWaitMs));
115
+ }
116
+ catch (error) {
117
+ db.close();
118
+ throw error;
119
+ }
120
+ }
121
+ // A store with a WAL opens read-only, whose close folds no frame into hippo.db; null sends a store
122
+ // with no WAL, or one behind the schema, down the read-write path.
123
+ function walReadOnlyStore(hippoRoot, busyWaitMs) {
124
+ const file = getHippoDbPath(hippoRoot);
125
+ if (!fs.existsSync(`${file}-wal`))
126
+ return null;
127
+ const db = new DatabaseSync(file, { readOnly: true });
128
+ let facts;
129
+ try {
130
+ db.exec(`PRAGMA busy_timeout = ${busyWaitMs}`);
131
+ db.exec('PRAGMA foreign_keys = ON');
132
+ facts = currentStoreFacts(db);
133
+ if (facts !== null)
134
+ return closeGate(db, facts);
135
+ }
136
+ catch (error) {
137
+ db.close();
138
+ throw error;
139
+ }
140
+ db.close();
141
+ return null;
142
+ }
143
+ const READ_WRITE_GATE = 'read-only-via-read-write';
144
+ // A missing store reads as empty and one mid-WAL without a checkpoint at close. The first open picks
145
+ // for the runtime, since its read-write connection makes the WAL a later open would find.
146
+ function readOnlyStore(at, busyWaitMs) {
147
+ const { hippoRoot, runtime } = at;
148
+ if (!fs.existsSync(getHippoDbPath(hippoRoot)))
149
+ return emptyReadOnlyStore(busyWaitMs);
150
+ if (runtime?.hasRun(storeKey(hippoRoot), READ_WRITE_GATE))
151
+ return null;
152
+ const opened = walReadOnlyStore(hippoRoot, busyWaitMs);
153
+ if (opened === null)
154
+ runtime?.markRun(storeKey(hippoRoot), READ_WRITE_GATE);
155
+ return opened;
156
+ }
86
157
  /**
87
158
  * A new connection with the store's pragmas and migrations applied and the mirror cleanup run when
88
159
  * it is due; the caller owns and closes it. `busyWaitMs` is the default lock wait when unset. An
@@ -90,6 +161,10 @@ function settleSchema(db, at, busyWaitMs) {
90
161
  */
91
162
  export function connectWithFacts(at, busyWaitMs = DEFAULT_BUSY_WAIT_MS) {
92
163
  const { hippoRoot } = at;
164
+ const readOnly = at.runtime?.readOnly === true;
165
+ const settled = readOnly ? readOnlyStore(at, busyWaitMs) : null;
166
+ if (settled !== null)
167
+ return settled;
93
168
  createStoreFilesOwnerOnly(at);
94
169
  const db = new DatabaseSync(getHippoDbPath(hippoRoot));
95
170
  try {
@@ -99,6 +174,9 @@ export function connectWithFacts(at, busyWaitMs = DEFAULT_BUSY_WAIT_MS) {
99
174
  db.exec(`PRAGMA wal_autocheckpoint = ${autoCheckpointPages(getHippoDbPath(hippoRoot), at.runtime)}`);
100
175
  db.exec('PRAGMA foreign_keys = ON');
101
176
  const facts = settleSchema(db, at, busyWaitMs);
177
+ // After the schema step, so an older store still migrates; the mirror sweep below writes too.
178
+ if (readOnly)
179
+ return closeGate(db, facts);
102
180
  // Orphan mirrors of archived raw rows go here; a filesystem failure must not block the open.
103
181
  try {
104
182
  sweepArchivedMirrorsIfDue(hippoRoot, db, facts?.archivePending);
package/dist/db/grant.js CHANGED
@@ -52,7 +52,7 @@ export class DbGrant {
52
52
  const file = getHippoDbPath(hippoRoot);
53
53
  if (!existsSync(file))
54
54
  throw new Error(`No existing Hippo database at ${file}`);
55
- const db = new DatabaseSync(file, { readOnly });
55
+ const db = new DatabaseSync(file, { readOnly: readOnly || this.#runtime?.readOnly === true });
56
56
  try {
57
57
  db.exec(`PRAGMA busy_timeout = ${DEFAULT_BUSY_WAIT_MS}`);
58
58
  return fn(db);
@@ -17,6 +17,9 @@ export interface OpenFacts {
17
17
  /** Whether any markdown mirror is marked due for a rewrite. */
18
18
  readonly mirrorsDue: boolean;
19
19
  }
20
+ /** The probe's facts when the store is current and whole, so the open can skip every DDL
21
+ * statement; else null. Runs the binary check either way. */
22
+ export declare function currentStoreFacts(db: DatabaseSyncLike): OpenFacts | null;
20
23
  /** For a store this process has proven: one cheap statement returns the open's facts when both
21
24
  * schema stamps still name the current schema, else null; it refuses when another binary has
22
25
  * since raised the minimum. */
@@ -62,7 +62,7 @@ export const SCHEMA_PROBE_SQL = `SELECT
62
62
  ${MIRRORS_DUE}`;
63
63
  /** The probe's facts when the store is current and whole, so the open can skip every DDL
64
64
  * statement; else null. Runs the binary check either way. */
65
- function currentStoreFacts(db) {
65
+ export function currentStoreFacts(db) {
66
66
  let probe;
67
67
  try {
68
68
  probe = db.prepare(SCHEMA_PROBE_SQL).get();
@@ -1,5 +1,5 @@
1
1
  import type { Migration } from './types.js';
2
- export declare const CURRENT_SCHEMA_VERSION = 62;
2
+ export declare const CURRENT_SCHEMA_VERSION = 63;
3
3
  /** Every schema migration in version order; runMigrations applies each one above the stored
4
4
  * version. */
5
5
  export declare const MIGRATIONS: Migration[];
@@ -60,7 +60,8 @@ import { v59 } from './v59.js';
60
60
  import { v60 } from './v60.js';
61
61
  import { v61 } from './v61.js';
62
62
  import { v62 } from './v62.js';
63
- export const CURRENT_SCHEMA_VERSION = 62;
63
+ import { v63 } from './v63.js';
64
+ export const CURRENT_SCHEMA_VERSION = 63;
64
65
  /** Every schema migration in version order; runMigrations applies each one above the stored
65
66
  * version. */
66
67
  export const MIGRATIONS = [
@@ -126,5 +127,6 @@ export const MIGRATIONS = [
126
127
  v60,
127
128
  v61,
128
129
  v62,
130
+ v63,
129
131
  ];
130
132
  //# sourceMappingURL=index.js.map
@@ -0,0 +1,3 @@
1
+ import type { Migration } from './types.js';
2
+ export declare const v63: Migration;
3
+ //# sourceMappingURL=v63.d.ts.map
@@ -0,0 +1,9 @@
1
+ export const v63 = {
2
+ version: 63,
3
+ up: (db) => {
4
+ // Skip a NULL or unknown kind: trg_memories_kind_check_update is not column-scoped and would abort the open.
5
+ db.exec(`UPDATE memories SET superseded_by = NULL WHERE superseded_by = '' ` +
6
+ `AND kind IN ('raw','distilled','superseded','archived')`);
7
+ },
8
+ };
9
+ //# sourceMappingURL=v63.js.map
@@ -12,10 +12,17 @@ interface OpenSession {
12
12
  }
13
13
  /** The resolved path of a store's hippo.db, the key every per-store record here uses. */
14
14
  export declare function storeKey(hippoRoot: string): string;
15
+ /** What a root states when it makes its runtime. */
16
+ export interface StoreRuntimeOptions {
17
+ /** Every connection opened under the runtime refuses writes once its schema is settled. */
18
+ readonly readOnly?: boolean;
19
+ }
15
20
  export declare class StoreRuntime {
16
21
  #private;
17
22
  /** Mirror and stats writes held back to at most one per interval per root. */
18
23
  readonly held: HeldWrites;
24
+ readonly readOnly: boolean;
25
+ constructor(opts?: StoreRuntimeOptions);
19
26
  /** Whether `step` has run to its end on the store at `key`. */
20
27
  hasRun(key: string, step: string): boolean;
21
28
  markRun(key: string, step: string): void;
@@ -16,12 +16,16 @@ export function storeKey(hippoRoot) {
16
16
  export class StoreRuntime {
17
17
  /** Mirror and stats writes held back to at most one per interval per root. */
18
18
  held = new HeldWrites();
19
+ readOnly;
19
20
  #settled = new Map();
20
21
  #open = new Set();
21
22
  #idle = new Map();
22
23
  #background = new Set();
23
24
  #stats = new Map();
24
25
  #detached = new DetachedSet();
26
+ constructor(opts = {}) {
27
+ this.readOnly = opts.readOnly === true;
28
+ }
25
29
  /** Whether `step` has run to its end on the store at `key`. */
26
30
  hasRun(key, step) {
27
31
  return this.#settled.get(key)?.has(step) ?? false;
@@ -135,8 +135,8 @@ async function partitionMergeCandidates(run) {
135
135
  /** Returns how many clusters were skipped because their merged text matches a rejected value. */
136
136
  export async function mergePass(run) {
137
137
  const used = new Set();
138
- // The rejection guard reuses the run's tombstone checks; a dry-run never reaches
139
- // batchWriteAndDelete's guard bypass, so it has nothing to protect there.
138
+ // The rejection guard reuses the run's tombstone checks; a dry run reads them too, so it counts a
139
+ // refused cluster as refused though it never reaches batchWriteAndDelete's guard bypass.
140
140
  let mergesSkippedRejected = 0;
141
141
  for (const bucket of (await partitionMergeCandidates(run)).values()) {
142
142
  const { ids, lengths } = bucket;
@@ -179,9 +179,9 @@ async function mergeCluster({ run, partition, cluster, related, used, }) {
179
179
  const mergedContent = mergeContents(cluster);
180
180
  // Build the semantic entry FIRST (createMemory is cheap and pure) so the tombstone check below
181
181
  // runs under the partition's tenant, the one every cluster member shares and the row will land
182
- // in.
183
- const semantic = dryRun ? null : semanticSummary(mergedContent, cluster, partition, run);
184
- if (semantic && (await mergeRejected({ run, semantic, cluster, related, used })))
182
+ // in. A dry run builds it too, so it refuses the cluster a real run would.
183
+ const semantic = semanticSummary(mergedContent, cluster, partition, run);
184
+ if (await mergeRejected({ run, semantic, cluster, related, used }))
185
185
  return false;
186
186
  for (const e of cluster)
187
187
  used.add(e.id);
@@ -191,7 +191,7 @@ async function mergeCluster({ run, partition, cluster, related, used, }) {
191
191
  count: cluster.length,
192
192
  preview: mergedContent.slice(0, MERGE_DETAIL_PREVIEW_CHARS),
193
193
  });
194
- if (!dryRun && semantic) {
194
+ if (!dryRun) {
195
195
  run.pendingWrites.push(semantic);
196
196
  run.units.push([semantic.id, ...cluster.map((e) => e.id)]);
197
197
  result.semanticCreated++;
@@ -2,10 +2,9 @@ import type { StoreWith } from '../../base/ports/store.js';
2
2
  import type { RejectedValueRow } from '../../base/ports/store/rejections.js';
3
3
  import type { AppendAuditOptions } from '../../base/ports/store/types.js';
4
4
  export interface TombstoneChecks {
5
- /** The tenant's tombstone for `digest`; null when there is none, and always under dryRun. */
5
+ /** The tenant's tombstone for `digest`; null when there is none. */
6
6
  find(tenantId: string, digest: string): Promise<RejectedValueRow | null>;
7
- /** The digests among `digests` the tenant holds a tombstone for, in one store call; none under
8
- * dryRun, as `find`. */
7
+ /** The digests among `digests` the tenant holds a tombstone for, in one store call. */
9
8
  rejectedAmong(tenantId: string, digests: readonly string[]): Promise<Set<string>>;
10
9
  /** One audit row; nothing under dryRun. */
11
10
  audit(event: AppendAuditOptions): Promise<void>;
@@ -13,6 +12,6 @@ export interface TombstoneChecks {
13
12
  * stands without its row. */
14
13
  auditOrCount(event: AppendAuditOptions): Promise<void>;
15
14
  }
16
- /** The checks of one sleep on `store`; under dryRun no call reaches the store. */
15
+ /** The checks of one sleep on `store`; under dryRun the lookups read and no audit row is written. */
17
16
  export declare function tombstoneChecks(store: StoreWith<'consolidation'>, dryRun: boolean): TombstoneChecks;
18
17
  //# sourceMappingURL=tombstones.d.ts.map
@@ -1,14 +1,14 @@
1
1
  import { reportAuditWriteFailure } from '../../base/records/audit-report.js';
2
- /** The checks of one sleep on `store`; under dryRun no call reaches the store. */
2
+ /** The checks of one sleep on `store`; under dryRun the lookups read and no audit row is written. */
3
3
  export function tombstoneChecks(store, dryRun) {
4
4
  const audit = async (event) => {
5
5
  if (!dryRun)
6
6
  await store.appendAuditEvents([event]);
7
7
  };
8
8
  return {
9
- find: async (tenantId, digest) => dryRun ? null : ((await store.consolidation.rejected(tenantId, [digest]))[0] ?? null),
9
+ find: async (tenantId, digest) => (await store.consolidation.rejected(tenantId, [digest]))[0] ?? null,
10
10
  async rejectedAmong(tenantId, digests) {
11
- if (dryRun || digests.length === 0)
11
+ if (digests.length === 0)
12
12
  return new Set();
13
13
  return new Set((await store.consolidation.rejected(tenantId, digests)).map((row) => row.digest));
14
14
  },
@@ -3,9 +3,8 @@
3
3
  * `active` despite memory decay. The memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for
4
4
  * recall only; saveDecision commits both in one `objects` transaction.
5
5
  */
6
- import type { MemoryEntry } from '../../base/memory/entry.js';
7
6
  import type { KeysetPosition } from '../../base/util/keyset.js';
8
- import type { EntryWrites, Objects } from '../../base/ports/store.js';
7
+ import type { Objects } from '../../base/ports/store.js';
9
8
  import type { SavableDescriptor } from './descriptor.js';
10
9
  import type { Decision, DecisionStatus } from '../../base/records/object-types.js';
11
10
  export type { Decision, DecisionStatus } from '../../base/records/object-types.js';
@@ -16,6 +15,9 @@ export interface SaveDecisionOptions {
16
15
  /** Table id of an ACTIVE decision this one supersedes; the CLI resolves a `--supersedes <memory-id>` via
17
16
  * resolveActiveDecisionIdByMemory, HTTP/SDK pass the table id. */
18
17
  supersedesDecisionId?: number;
18
+ /** A memory of the tenant the save also weakens, for a `--supersedes <memory-id>` that names one
19
+ * no active decision backs; the save is refused when the tenant holds none. */
20
+ weakensMemoryId?: string;
19
21
  /** Extra memory tags merged after ['decision'] (the CLI passes path-context tags; HTTP/SDK
20
22
  * pass none). */
21
23
  extraTags?: string[];
@@ -27,11 +29,6 @@ export interface ListDecisionsOptions {
27
29
  after?: KeysetPosition;
28
30
  }
29
31
  export declare const DECISION: SavableDescriptor<'decision', SaveDecisionOptions>;
30
- /**
31
- * Weaken the memory a new decision replaces, once the save has committed: marked stale, tagged
32
- * `superseded`, and its half-life halved to a day at least the first time only.
33
- */
34
- export declare function weakenSupersededMemory(writes: EntryWrites, entry: MemoryEntry, actor?: string): Promise<void>;
35
32
  export declare function loadDecisions(objects: Objects, tenantId: string, opts?: ListDecisionsOptions): Promise<Decision[]>;
36
33
  /** Resolve a `--supersedes <memory-id>` to the table id of the ACTIVE decision backed by that memory, or null.
37
34
  * Exported so the CLI's backward-compat path is testable at the store layer. */
@@ -3,12 +3,10 @@
3
3
  * `active` despite memory decay. The memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for
4
4
  * recall only; saveDecision commits both in one `objects` transaction.
5
5
  */
6
- import { markStale, SUPERSEDED_TAG } from '../../base/memory/stale-mark.js';
7
6
  import { assertTenantId } from '../../base/scope/tenant-id.js';
8
7
  import { MAX_SHORT_FIELD_LEN } from '../../base/util/limits.js';
9
8
  import { requireText } from './fields.js';
10
9
  import { listObjects } from './lifecycle.js';
11
- import { CLI_ACTOR } from '../../base/scope/actor.js';
12
10
  export const VALID_DECISION_STATES = new Set([
13
11
  'active',
14
12
  'superseded',
@@ -27,17 +25,11 @@ export const DECISION = {
27
25
  content: opts.context ? `${decisionText}\n\nContext: ${opts.context}` : decisionText,
28
26
  tags: opts.extraTags ?? [],
29
27
  supersedesId: opts.supersedesDecisionId,
28
+ weakensMemoryId: opts.weakensMemoryId,
30
29
  at: now.toISOString(),
31
30
  };
32
31
  },
33
32
  };
34
- /**
35
- * Weaken the memory a new decision replaces, once the save has committed: marked stale, tagged
36
- * `superseded`, and its half-life halved to a day at least the first time only.
37
- */
38
- export function weakenSupersededMemory(writes, entry, actor = CLI_ACTOR) {
39
- return writes.writeEntry({ entry: markStale(entry, SUPERSEDED_TAG), actor });
40
- }
41
33
  export function loadDecisions(objects, tenantId, opts = {}) {
42
34
  return listObjects(objects, DECISION, tenantId, opts);
43
35
  }
@@ -22,6 +22,8 @@ export interface ObjectDraft<K extends SavableKind> {
22
22
  readonly supersedesId: number | undefined;
23
23
  /** What changed; stored only on a versioned successor. */
24
24
  readonly changeSummary?: string;
25
+ /** A decision only: a memory the save also weakens, beside the one the replaced row mirrors. */
26
+ readonly weakensMemoryId?: string;
25
27
  /** Read once the checks pass, so one instant stamps everything the save writes. */
26
28
  readonly at: string;
27
29
  }
@@ -3,7 +3,7 @@
3
3
  // whatever store the caller holds: the CLI's, a served one, or a test's. The tenant, the fields and
4
4
  // the list status are checked first, so a bad request fails before a store is asked.
5
5
  import { DEFAULT_LIST_LIMIT } from '../../base/util/limits.js';
6
- import { BadRequestError, ConflictError, NotFoundError } from '../../base/errors/api-errors.js';
6
+ import { BadRequestError, ConflictError, memoryNotFoundText, NotFoundError, } from '../../base/errors/api-errors.js';
7
7
  import { createMemory, Layer } from '../../base/memory/entry.js';
8
8
  import { isObjectRefusal, } from '../../base/records/object-types.js';
9
9
  import { assertTenantId } from '../../base/scope/tenant-id.js';
@@ -73,12 +73,16 @@ function objectSave(site, kind, draft) {
73
73
  fields: draft.fields,
74
74
  supersedesId: draft.supersedesId,
75
75
  changeSummary: draft.changeSummary,
76
+ weakensMemoryId: draft.weakensMemoryId,
76
77
  actor: site.actor,
77
78
  at: draft.at,
78
79
  };
79
80
  }
81
+ function isSaveRefusal(written) {
82
+ return 'refused' in written;
83
+ }
80
84
  function saved(d, tenantId, replaced, written) {
81
- if (!isObjectRefusal(written))
85
+ if (!isSaveRefusal(written))
82
86
  return written;
83
87
  switch (written.refused) {
84
88
  case 'missing':
@@ -89,6 +93,8 @@ function saved(d, tenantId, replaced, written) {
89
93
  throw new ConflictError(`${d.label} ${replaced} could not be superseded (no longer active or self-reference).`);
90
94
  case 'vanished':
91
95
  throw new Error(`failed to reload saved ${d.label} row`);
96
+ case 'memory_missing':
97
+ throw new NotFoundError(memoryNotFoundText(written.memoryId));
92
98
  }
93
99
  }
94
100
  /** Creates an object, or the version that replaces the one its options name, with its mirror
@@ -18,17 +18,29 @@ export declare const AUTO_SHARE_MIN_SCORE = 0.6;
18
18
  /** Estimate how well a memory would transfer to other projects.
19
19
  * Returns 0..1 where >0.5 = good candidate for sharing. */
20
20
  export declare function transferScore(entry: MemoryEntry): number;
21
- /** Share a memory to the global store with attribution (source enriched with project path and timestamp).
22
- * Returns the new entry, or null if the transfer score is too low. */
21
+ /** What a hand-run share did: wrote a copy, left a row below the transfer score alone, or found
22
+ * the global store already holding its text (`existingId` is that row). */
23
+ export type ShareOutcome = {
24
+ readonly kind: 'shared';
25
+ readonly entry: MemoryEntry;
26
+ } | {
27
+ readonly kind: 'low-score';
28
+ } | {
29
+ readonly kind: 'already-shared';
30
+ readonly existingId: string;
31
+ };
32
+ /** Share a memory to the global store with attribution (source enriched with project path and
33
+ * timestamp). Writes nothing when the global store holds the text, `force` or not; throws when the
34
+ * row may not be shared. */
23
35
  export declare function shareMemory(local: {
24
36
  readonly store: StoreWith<'folderFiles'>;
25
- }, global: ConfiguredFolder<SharingStore & StoreWith<'vectors' | 'vectorWrites'>>, id: string, options: {
37
+ }, global: ConfiguredFolder<SharingStore & StoreWith<'vectors' | 'vectorWrites' | 'captures'>>, id: string, options: {
26
38
  force?: boolean;
27
39
  tenantId: string;
28
40
  skipEmbed?: boolean;
29
41
  embed: EmbedRun;
30
42
  detached: DetachedWork;
31
- }): Promise<MemoryEntry | null>;
43
+ }): Promise<ShareOutcome>;
32
44
  /** List all projects that contributed memories to the global store, parsed from
33
45
  * 'shared:<project>:' or 'promoted:<path>' sources; ALL_TENANTS is the host-wide view. */
34
46
  export declare function listPeers(global: {
@@ -8,7 +8,7 @@ import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TAGS, } from '../../base/memor
8
8
  import { isPersonalScope, isQuarantineScope } from '../../base/scope/recall-scope.js';
9
9
  import { detectSecret } from '../../base/util/secret-detect.js';
10
10
  import { embedMemoryDetached, embedAll, folderEmbedTarget, } from '../search/embed-memories.js';
11
- import { duplicateKey, storedTextKeys } from '../../base/util/same-text.js';
11
+ import { duplicateKey, heldTextKeys } from '../../base/util/same-text.js';
12
12
  import { chunked } from '../../base/util/chunked.js';
13
13
  import { ALL_TENANTS } from '../../base/util/tenant.js';
14
14
  import { isReusable } from '../../base/memory/memory-quality.js';
@@ -111,16 +111,25 @@ export function transferScore(entry) {
111
111
  }
112
112
  return Math.min(1, Math.max(0, score));
113
113
  }
114
- /** Share a memory to the global store with attribution (source enriched with project path and timestamp).
115
- * Returns the new entry, or null if the transfer score is too low. */
114
+ /** Share a memory to the global store with attribution (source enriched with project path and
115
+ * timestamp). Writes nothing when the global store holds the text, `force` or not; throws when the
116
+ * row may not be shared. */
116
117
  export async function shareMemory(local, global, id, options) {
117
118
  // Tenant A cannot share tenant B's memory to global: the read finds no row of another tenant.
118
119
  const [entry] = await local.store.entriesByIds([id], options.tenantId);
119
120
  if (!entry)
120
121
  throw new NotFoundError(`Memory not found: ${id}`);
121
- const globalEntry = toGlobalEntry(await local.store.folderFiles.home(), entry, options.force === true, options.embed.clock());
122
- if (!globalEntry)
123
- return null;
122
+ // Built first because it throws for a row that may not be shared, ahead of the held-text answer.
123
+ const globalEntry = toGlobalEntry(await local.store.folderFiles.home(), entry, options.embed.clock());
124
+ // The caller's tenant and the default scope filter, not autoShare's whole-store view: a copy
125
+ // carries its row's tenant, so another tenant's twin is no copy of this row and must stay unnamed.
126
+ const held = await heldGlobalTexts(global.store.captures, [entry.content], options.tenantId);
127
+ const twin = held.get(duplicateKey(entry.content));
128
+ if (twin?.id !== undefined)
129
+ return { kind: 'already-shared', existingId: twin.id };
130
+ const lowScore = transferScore(entry) < SHARE_MIN_SCORE && options.force !== true;
131
+ if (lowScore)
132
+ return { kind: 'low-score' };
124
133
  await global.store.entryWrites.writeEntry({ entry: globalEntry, actor: CLI_ACTOR });
125
134
  // Embed here unless the caller opts out: autoShare sets skipEmbed to batch one embedAll(), since
126
135
  // embedMemory rewrites the whole index per call.
@@ -135,15 +144,11 @@ export async function shareMemory(local, global, id, options) {
135
144
  };
136
145
  embedMemoryDetached(target, globalEntry, options.detached);
137
146
  }
138
- return globalEntry;
147
+ return { kind: 'shared', entry: globalEntry };
139
148
  }
140
- /** The global copy of a local row, or null when its transfer score is too low and `force` is
141
- * off; throws when the row may not be shared. */
142
- function toGlobalEntry(local, entry, force, now) {
149
+ /** The global copy of a local row; throws when the row may not be shared. */
150
+ function toGlobalEntry(local, entry, now) {
143
151
  assertShareable(entry, entry.id);
144
- const score = transferScore(entry);
145
- if (score < SHARE_MIN_SCORE && !force)
146
- return null;
147
152
  // The label keeps the folder name for a user-global row; a NULL row gets `shared::`, which
148
153
  // originFromSource reads as no project.
149
154
  const fallbackName = local.folderName;
@@ -256,20 +261,31 @@ async function* autoSharePages(store, minScore, tenantId) {
256
261
  after = next;
257
262
  } while (after !== null);
258
263
  }
264
+ /** Each text key `texts` have that a row in the global store holds, with the first such row;
265
+ * `tenantId` and `opts` pick which rows count. */
266
+ async function heldGlobalTexts(captures, texts, tenantId, opts) {
267
+ const rows = await captures.textsHolding(tenantId, texts.filter((text) => duplicateKey(text) !== ''), opts);
268
+ const held = new Map();
269
+ for (const row of rows) {
270
+ for (const key of heldTextKeys(row))
271
+ if (!held.has(key))
272
+ held.set(key, row);
273
+ }
274
+ return held;
275
+ }
259
276
  /** The page's rows that share. The global store, the union of every tenant, is asked only for
260
277
  * the rows that may hold a page row's text. */
261
278
  async function pageCandidates(to, page, minScore, stats) {
262
279
  const scored = page.filter((entry) => clearsShareRules(entry, minScore, stats));
263
280
  if (scored.length === 0)
264
281
  return [];
265
- const texts = scored.map((entry) => entry.content).filter((text) => duplicateKey(text) !== '');
266
- const globalKeys = storedTextKeys(await to.textsHolding(ALL_TENANTS, texts, { everyScope: true }));
267
- return scored.filter((entry) => isNewAndClean(entry, globalKeys, stats));
282
+ const held = await heldGlobalTexts(to, scored.map((entry) => entry.content), ALL_TENANTS, { everyScope: true });
283
+ return scored.filter((entry) => isNewAndClean(entry, held, stats));
268
284
  }
269
285
  /** Writes one page of candidates in one transaction; returns the copies written and how many a
270
286
  * tombstone refused. */
271
287
  async function sharePage(local, to, page, now) {
272
- const copies = page.flatMap((entry) => toGlobalEntry(local, entry, true, now) ?? []);
288
+ const copies = page.map((entry) => toGlobalEntry(local, entry, now));
273
289
  const written = new Set(await to.lessonWrites.writeSkippingRejected(copies, CLI_ACTOR));
274
290
  const shared = copies.filter((copy) => written.has(copy.id));
275
291
  return { shared, refused: copies.length - shared.length };
@@ -35,7 +35,8 @@ export { bufferToFloat32, float32ToBuffer } from '../base/util/vector-codec.js';
35
35
  export { replacesIndex } from '../base/embeddings/index-identity.js';
36
36
  // An add-on's ContextReads applies hippo.db's scope, secret, tally and rarest-term rules with the
37
37
  // same code. An add-on's ambientCandidates and summaryWithDescendants admit rows by hippo.db's
38
- // rule.
38
+ // rule. A store that ignores `admit.excludeTags` or `recall.excludeTags` gets only core's after-load
39
+ // filter, so its recent-N or recall pool can come short.
39
40
  export { ambientRefusal, descendantAdmits, } from '../base/scope/read-admission.js';
40
41
  export { SECRET_TAGS } from '../base/util/secret-detect.js';
41
42
  /** An add-on's ambient tallies, scored as hippo.db's are under the environment's eval switches. */
@@ -25,13 +25,25 @@ const INSTALLED_TRANSFORMERS = {
25
25
  installed: () => resolveTransformersPackage() !== null,
26
26
  load: () => importTransformers(),
27
27
  };
28
+ // Sharing the model-load backoff is deliberate: one window, one attempt.
29
+ const INSTALL_RECHECK_MS = MODEL_LOAD_POLICY.backoffMs;
28
30
  /** One pipeline per model for the embedder's life, since a pipeline is expensive to load. */
29
31
  export function createLocalEmbedder(transformers = INSTALLED_TRANSFORMERS) {
30
- let available = null;
32
+ let state = { kind: 'no', retryAt: 0 };
31
33
  const gates = new Map();
32
34
  const pipelines = createModelLoads(MODEL_LOAD_POLICY, warnLoadFailure);
33
35
  const load = (model) => pipelines.load(model, () => createPipeline(transformers, model, gates));
34
- const isAvailable = () => (available ??= transformers.installed());
36
+ const isAvailable = () => {
37
+ if (state.kind === 'yes')
38
+ return true;
39
+ const now = Date.now();
40
+ if (now < state.retryAt)
41
+ return false;
42
+ state = transformers.installed()
43
+ ? { kind: 'yes' }
44
+ : { kind: 'no', retryAt: now + INSTALL_RECHECK_MS };
45
+ return state.kind === 'yes';
46
+ };
35
47
  return {
36
48
  isAvailable,
37
49
  requirePipeline: (model, signal) => waitForPipeline(load(model), signal && gateOf(gates, model).opened, signal),
@@ -35,8 +35,8 @@ interface MoveBadOptions {
35
35
  * busy write puts the claim back.
36
36
  */
37
37
  export declare function moveBad(fsx: SpoolFs, dir: string, claim: string, options: MoveBadOptions): boolean;
38
- /** Removes a claim once the store holds its summary; a claim left behind is imported again, so
39
- * the log says so. */
38
+ /** Removes a claim once the store holds its summary; a claim left behind comes back for another
39
+ * import, so the log names it. */
40
40
  export declare function removeClaim(fsx: SpoolFs, claim: string, name: string, log: Log): void;
41
41
  export {};
42
42
  //# sourceMappingURL=spool-claims.d.ts.map
@@ -54,12 +54,13 @@ export function moveBad(fsx, dir, claim, options) {
54
54
  settle(() => fsx.unlinkSync(claim), log, what);
55
55
  return true;
56
56
  }
57
- /** Removes a claim once the store holds its summary; a claim left behind is imported again, so
58
- * the log says so. */
57
+ /** Removes a claim once the store holds its summary; a claim left behind comes back for another
58
+ * import, so the log names it. */
59
59
  export function removeClaim(fsx, claim, name, log) {
60
60
  const removed = settleCode(() => fsx.unlinkSync(claim), log, `spool file ${name} claim not removed`);
61
61
  if (removed.settled === 'busy') {
62
- log(`spool file ${name} saved; its claim could not be removed (${removed.code}); it will be imported again`);
62
+ log(`spool file ${name} saved; its claim could not be removed (${removed.code}); ` +
63
+ 'a later import reuses the saved record');
63
64
  }
64
65
  }
65
66
  //# sourceMappingURL=spool-claims.js.map
@@ -61,7 +61,7 @@ export async function importFile(options) {
61
61
  };
62
62
  let failure;
63
63
  try {
64
- failure = await importOne(spooled, markRecorded);
64
+ failure = await importOne({ ...spooled, importKey: entry.stem }, markRecorded);
65
65
  }
66
66
  catch (err) {
67
67
  failure = { busy: isStoreBusy(err), message: errorMessage(err), fields: errorFields(err) };
@@ -5,6 +5,8 @@ export interface SpooledCompaction {
5
5
  payload: PostCompactPayload;
6
6
  text: CompactionText;
7
7
  at: Date;
8
+ /** The spool file's stem, which a put-back keeps, so the store can tell two imports of one file. */
9
+ importKey: string;
8
10
  }
9
11
  /**
10
12
  * Records one spooled compaction; it calls `recorded` once the store holds the summary, so the file
@@ -15,5 +17,5 @@ export type SpoolImporter = (spooled: SpooledCompaction, recorded: () => void) =
15
17
  /** The JSON text of one spooled compaction, which parseSpooled reads back. */
16
18
  export declare function spoolBody(tenantId: string, payload: PostCompactPayload, text: CompactionText, at: Date): string;
17
19
  /** null when the text is not a spooled compaction. */
18
- export declare function parseSpooled(text: string, fallbackTenantId: string): SpooledCompaction | null;
20
+ export declare function parseSpooled(text: string, fallbackTenantId: string): Omit<SpooledCompaction, 'importKey'> | null;
19
21
  //# sourceMappingURL=spool-record.d.ts.map