hippo-memory 3.5.1 → 3.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/README.md +37 -25
  2. package/dist/api/context/context-pools.js +2 -2
  3. package/dist/api/context/context.d.ts +1 -1
  4. package/dist/api/context/context.js +13 -9
  5. package/dist/api/ledger-db.d.ts +4 -2
  6. package/dist/api/ledger-db.js +11 -1
  7. package/dist/api/pilot-arm.js +4 -1
  8. package/dist/api/recall/finish.js +3 -2
  9. package/dist/api/recall/recall.js +3 -1
  10. package/dist/api/recall/request.d.ts +1 -1
  11. package/dist/api/recall/request.js +3 -1
  12. package/dist/api/tokens.d.ts +1 -1
  13. package/dist/api/tokens.js +3 -0
  14. package/dist/api/types.d.ts +2 -0
  15. package/dist/api/types.js +4 -0
  16. package/dist/base/config/config-keys.js +2 -1
  17. package/dist/base/config/config.d.ts +5 -1
  18. package/dist/base/config/config.js +1 -0
  19. package/dist/base/errors/read-only.d.ts +3 -0
  20. package/dist/base/errors/read-only.js +4 -0
  21. package/dist/base/memory/entry.d.ts +10 -2
  22. package/dist/base/memory/entry.js +12 -4
  23. package/dist/base/scope/read-admission.js +2 -2
  24. package/dist/base/util/env.d.ts +1 -0
  25. package/dist/base/util/env.js +3 -0
  26. package/dist/base/util/version.d.ts +1 -1
  27. package/dist/base/util/version.js +1 -1
  28. package/dist/cli.js +14 -1
  29. package/dist/db/connect.d.ts +4 -0
  30. package/dist/db/connect.js +79 -1
  31. package/dist/db/grant.js +1 -1
  32. package/dist/db/migrate.d.ts +3 -0
  33. package/dist/db/migrate.js +1 -1
  34. package/dist/db/store-runtime.d.ts +7 -0
  35. package/dist/db/store-runtime.js +4 -0
  36. package/dist/domain/consolidate/conflicts.js +3 -1
  37. package/dist/domain/context/select-policy.d.ts +1 -1
  38. package/dist/domain/context/select-policy.js +3 -3
  39. package/dist/domain/sharing/share.js +3 -1
  40. package/dist/store/sqlite/capture/captures.js +19 -6
  41. package/dist/store/sqlite/index.d.ts +1 -1
  42. package/dist/store/sqlite/learning/prediction-baserate.js +4 -2
  43. package/dist/store/sqlite/recall/candidates.js +3 -2
  44. package/dist/store/sqlite/recall/search-rows.js +5 -2
  45. package/dist/store/sqlite/runtime/handles.js +3 -0
  46. package/dist/surface/capture/capture-error.d.ts +4 -1
  47. package/dist/surface/capture/capture-error.js +2 -1
  48. package/dist/surface/capture/command.d.ts +8 -3
  49. package/dist/surface/capture/command.js +61 -11
  50. package/dist/surface/capture/extract.d.ts +2 -0
  51. package/dist/surface/capture/extract.js +7 -0
  52. package/dist/surface/capture/failure-caller.js +1 -0
  53. package/dist/surface/capture/user-messages.d.ts +9 -0
  54. package/dist/surface/capture/user-messages.js +42 -0
  55. package/dist/surface/cli/api-context.js +1 -0
  56. package/dist/surface/cli/cli-runtime.js +2 -1
  57. package/dist/surface/cli/hooks/capture-error.js +7 -1
  58. package/dist/surface/cli/hooks/codex-session-end-worker.js +1 -0
  59. package/dist/surface/cli/hooks/session-end-worker.js +14 -2
  60. package/dist/surface/cli/serve.js +4 -1
  61. package/dist/surface/cli/verb-row.d.ts +2 -0
  62. package/dist/surface/cli/verbs/health.js +3 -0
  63. package/dist/surface/cli/verbs/memory.js +5 -0
  64. package/dist/surface/cli/verbs/objects.js +2 -0
  65. package/dist/surface/cli/verbs/sessions.js +11 -0
  66. package/dist/surface/mcp/request.js +6 -2
  67. package/dist/surface/mcp/tools.d.ts +2 -0
  68. package/dist/surface/mcp/tools.js +8 -0
  69. package/dist/surface/open-store.d.ts +2 -2
  70. package/dist/surface/open-store.js +2 -2
  71. package/extensions/openclaw-plugin/openclaw.plugin.json +1 -1
  72. package/extensions/openclaw-plugin/package.json +1 -1
  73. package/openclaw.plugin.json +1 -1
  74. package/package.json +1 -1
@@ -47,6 +47,7 @@ export declare const envSkipAutoIntegrations: () => boolean;
47
47
  export declare const envSkipSchedule: () => boolean;
48
48
  export declare const envMcpStdio: () => boolean;
49
49
  export declare const envRequireServer: () => boolean;
50
+ export declare const envReadOnly: () => boolean;
50
51
  export declare const envStdinWaitMs: () => number | undefined;
51
52
  export declare function envLogLevel(): string;
52
53
  /** `HIPPO_LOG_FORMAT=json` writes each log line as one JSON object; anything else keeps the text
@@ -20,6 +20,7 @@ const FLAGS = {
20
20
  HIPPO_REQUIRE_SERVER: false,
21
21
  HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL: false,
22
22
  HIPPO_ALLOW_CLEARTEXT: false,
23
+ HIPPO_READ_ONLY: true,
23
24
  SLACK_ALLOW_UNKNOWN_TEAM_FALLBACK: false,
24
25
  GITHUB_ALLOW_UNKNOWN_INSTALLATION_FALLBACK: false,
25
26
  };
@@ -152,6 +153,7 @@ export function envRuntimeSettings() {
152
153
  dagRebuildCap: envDagRebuildCap(),
153
154
  activeScope: envActiveScope() ?? undefined,
154
155
  lossAversionRatio: envLossAversionRatio(),
156
+ readOnly: envReadOnly(),
155
157
  clef: envClefSettings(),
156
158
  };
157
159
  }
@@ -200,6 +202,7 @@ export const envSkipAutoIntegrations = bool('HIPPO_SKIP_AUTO_INTEGRATIONS');
200
202
  export const envSkipSchedule = bool('HIPPO_SKIP_SCHEDULE');
201
203
  export const envMcpStdio = bool('HIPPO_MCP_STDIO');
202
204
  export const envRequireServer = bool('HIPPO_REQUIRE_SERVER');
205
+ export const envReadOnly = bool('HIPPO_READ_ONLY');
203
206
  const envRequireSessionScopedFreshTail = bool('HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL');
204
207
  export const envStdinWaitMs = posInt('HIPPO_STDIN_WAIT_MS');
205
208
  export function envLogLevel() {
@@ -2,7 +2,7 @@
2
2
  * Single source of truth for the package version, written by scripts/sync-version.mjs; never
3
3
  * edit by hand. Read by the db rollback guard, /health, MCP. A constant, not a runtime
4
4
  * package.json read: the published bundle may lack package.json on a path ESM can resolve. */
5
- export declare const PACKAGE_VERSION = "3.5.1";
5
+ export declare const PACKAGE_VERSION = "3.7.0";
6
6
  /** The floor a store takes on its first expiring key: the first release with schema v53, set by
7
7
  * hand in that release; scripts/checks/check-expiring-keys-floor.mjs gates it. */
8
8
  export declare const EXPIRING_KEYS_MIN_BINARY = "1.64.0";
@@ -2,7 +2,7 @@
2
2
  * Single source of truth for the package version, written by scripts/sync-version.mjs; never
3
3
  * edit by hand. Read by the db rollback guard, /health, MCP. A constant, not a runtime
4
4
  * package.json read: the published bundle may lack package.json on a path ESM can resolve. */
5
- export const PACKAGE_VERSION = '3.5.1';
5
+ export const PACKAGE_VERSION = '3.7.0';
6
6
  /** The floor a store takes on its first expiring key: the first release with schema v53, set by
7
7
  * hand in that release; scripts/checks/check-expiring-keys-floor.mjs gates it. */
8
8
  export const EXPIRING_KEYS_MIN_BINARY = '1.64.0';
package/dist/cli.js CHANGED
@@ -1,7 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  // Hippo CLI entry point: parses argv and dispatches each verb through the table in
3
3
  // surface/cli/verbs.ts. `hippo help` prints the verb list from that table, so no list is kept here.
4
- import { envSkipAutoIntegrations, envTenant, validateFlags } from './base/util/env.js';
4
+ import { envReadOnly, envSkipAutoIntegrations, envTenant, validateFlags } from './base/util/env.js';
5
+ import { READ_ONLY_REFUSAL } from './base/errors/read-only.js';
5
6
  import * as fs from 'node:fs';
6
7
  import { fileURLToPath } from 'node:url';
7
8
  import { repairCodexWrapperIfInstalled } from './surface/hooks-install/codex-wrapper.js';
@@ -214,6 +215,14 @@ function checkUnknownFlags(command, flags, spec) {
214
215
  printError(`hippo: ignoring unknown flag ${flagNames(ignored)}. A later release will reject it.`);
215
216
  }
216
217
  }
218
+ // Before the verb reads stdin or opens a store, so a hook leaves no row, mirror file or worker.
219
+ function stopReadOnly(command, mode) {
220
+ if (mode === 'skip') {
221
+ log.warn(`hippo ${command}: skipped under HIPPO_READ_ONLY=1`);
222
+ return;
223
+ }
224
+ fail(READ_ONLY_REFUSAL);
225
+ }
217
226
  async function main(command, args, flags, hippoRoot) {
218
227
  if (command === '--version' || command === '-v' || boolFlag(flags, 'version'))
219
228
  printVersion();
@@ -245,6 +254,10 @@ async function main(command, args, flags, hippoRoot) {
245
254
  throw new CliExit(1);
246
255
  }
247
256
  assertVerbPorted(spec, CLI_STORE);
257
+ if (spec.readOnly !== undefined && envReadOnly()) {
258
+ stopReadOnly(command, spec.readOnly);
259
+ return;
260
+ }
248
261
  const run = () => spec.run({ hippoRoot, tenantId: envTenant(), args, flags });
249
262
  await (spec.scoped ? (await import('./surface/cli/api-context.js')).cliRequest(run) : run());
250
263
  }
@@ -11,6 +11,10 @@ export interface StoreAt {
11
11
  /** Runs `step` on the store unless it already ran to the end under the store's runtime; a throw
12
12
  * leaves it due, and with no runtime it always runs. */
13
13
  export declare function oncePerStore({ hippoRoot, runtime }: StoreAt, name: string, step: () => void): void;
14
+ /** Whether `db` was opened under a read-only runtime, so it refuses every write. */
15
+ export declare function isReadOnlyHandle(db: DatabaseSyncLike): boolean;
16
+ /** Runs `fn` with the gate open on `db`: a temp table lives in no store file. */
17
+ export declare function withTempTables<T>(db: DatabaseSyncLike, fn: () => T): T;
14
18
  /** Makes the next connection under `runtime` prove this store's schema again; `hippo init` calls
15
19
  * it because it is the explicit ask to set a store up. */
16
20
  export declare function reproveStoreSchema({ hippoRoot, runtime }: StoreAt): void;
@@ -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();
@@ -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;
@@ -1,4 +1,4 @@
1
- import { EXTRACTED_TAG, Layer } from '../../base/memory/entry.js';
1
+ import { EXTRACTED_TAG, Layer, isUserMessage } from '../../base/memory/entry.js';
2
2
  import { calculateStrength, } from '../../base/memory/strength.js';
3
3
  import { jaccardMinShared, overlapPartners } from './overlap-index.js';
4
4
  import { isQuarantineScope } from '../trust/quarantine.js';
@@ -30,6 +30,8 @@ export async function detectConflicts(entries, now, options) {
30
30
  const live = entry.layer !== Layer.Semantic &&
31
31
  // An unreviewed quarantined row must not taint a visible memory as conflicted.
32
32
  !isQuarantineScope(entry.scope ?? null) &&
33
+ // A message is a dated record of what the person said, not a claim kept true.
34
+ !isUserMessage(entry) &&
33
35
  (rescuedIds.has(entry.id) ||
34
36
  calculateStrength(entry, now, strength, decayOpts) >= DECAY_THRESHOLD);
35
37
  if (!live)
@@ -25,7 +25,7 @@ export declare function reservePinned(rankedPinned: readonly PricedRow[], budget
25
25
  export declare function admitWithinBudget<T extends PricedRow>(rows: readonly T[], picked: Picked<T>, budget: number, onOverBudget?: (row: T) => void): void;
26
26
  /** The prompt-recall gate a config asks for; a value that is not a number reads as its default. */
27
27
  export declare function promptRecallGateOf(inject: HippoConfig['pinnedInject']): PromptRecallGate;
28
- /** The newest `limit` rows worth surfacing; a pin always is, a captured note never is. */
28
+ /** The newest `limit` rows worth surfacing; a pin always is, a recall-only row never is. */
29
29
  export declare function newestWorthSurfacing<T extends {
30
30
  entry: MemoryEntry;
31
31
  }>(rows: readonly T[], limit: number): T[];
@@ -1,6 +1,6 @@
1
1
  // The ranking and budget policy of a context block, on plain rows: the api reads the stores, prices
2
2
  // the rows and asks these functions who gets in.
3
- import { isCapturedNote } from '../../base/memory/entry.js';
3
+ import { isRecallOnly } from '../../base/memory/entry.js';
4
4
  import { isWorthSurfacing } from '../../base/memory/memory-quality.js';
5
5
  import { compareScoredResults } from '../../base/rank/compare.js';
6
6
  // Overlap a candidate needs with the prompt when the config sets none.
@@ -58,7 +58,7 @@ export function promptRecallGateOf(inject) {
58
58
  }),
59
59
  };
60
60
  }
61
- /** The newest `limit` rows worth surfacing; a pin always is, a captured note never is. */
61
+ /** The newest `limit` rows worth surfacing; a pin always is, a recall-only row never is. */
62
62
  export function newestWorthSurfacing(rows, limit) {
63
63
  return ([...rows]
64
64
  // Newest first, then id: stable within one store, but same-millisecond rows fall to random ids across ingests.
@@ -68,7 +68,7 @@ export function newestWorthSurfacing(rows, limit) {
68
68
  })
69
69
  // Filter before slice so a junk row is backfilled past, not counted against N. Pins bypass the floor: a dropped
70
70
  // pin's share of the shared budget would go to a backfilled row, and the pin loop could not win it back.
71
- .filter(({ entry }) => entry.pinned || (isWorthSurfacing(entry) && !isCapturedNote(entry)))
71
+ .filter(({ entry }) => entry.pinned || (isWorthSurfacing(entry) && !isRecallOnly(entry)))
72
72
  .slice(0, limit));
73
73
  }
74
74
  /** No query: the strongest rows first, each kept if it still fits `left` tokens. */
@@ -1,7 +1,7 @@
1
1
  // Sharing local memories to the global store: transfer scoring, share, peers and auto-share.
2
2
  import { BadRequestError, NotFoundError } from '../../base/errors/api-errors.js';
3
3
  import * as path from 'node:path';
4
- import { generateId, COMPACTION_MEMORY_TAG, ERROR_TAG, EXTRACTED_TAG, CAPTURED_NOTE_TAG, } from '../../base/memory/entry.js';
4
+ import { generateId, COMPACTION_MEMORY_TAG, ERROR_TAG, EXTRACTED_TAG, CAPTURED_NOTE_TAG, USER_MESSAGE_TAG, } from '../../base/memory/entry.js';
5
5
  import { strengthModelFor } from '../../base/memory/eval-switches.js';
6
6
  import { CLI_ACTOR } from '../../base/scope/actor.js';
7
7
  import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TAGS, } from '../../base/memory/agent-memory-tools.js';
@@ -50,6 +50,7 @@ const TRANSFERABLE_TAGS = new Set([
50
50
  * inherit them. */
51
51
  export const NEVER_AUTO_SHARE_TAGS = new Set([
52
52
  CAPTURED_NOTE_TAG,
53
+ USER_MESSAGE_TAG,
53
54
  'git-learned',
54
55
  'session-digest',
55
56
  ...AGENT_MEMORY_TAGS,
@@ -61,6 +62,7 @@ export function neverAutoShareTags(sources) {
61
62
  * detection keeps its own list. */
62
63
  export const NO_MERGE_TAGS = new Set([
63
64
  CAPTURED_NOTE_TAG,
65
+ USER_MESSAGE_TAG,
64
66
  EXTRACTED_TAG,
65
67
  'session-digest',
66
68
  COMPACTION_MEMORY_TAG,
@@ -1,7 +1,7 @@
1
1
  // hippo.db's Captures: the whole batch on one handle, opened with openStore since a write sets up
2
2
  // the mirror folders.
3
3
  import { withWriteScope } from '../../../db/index.js';
4
- import { USER_RULE_TAG } from '../../../base/memory/entry.js';
4
+ import { isUserMessage, USER_RULE_TAG } from '../../../base/memory/entry.js';
5
5
  import { duplicateKey, heldTextKeys, storedTextKeys } from '../../../base/util/same-text.js';
6
6
  import { ruleReplaces } from '../../../base/memory/rule-replaces.js';
7
7
  import { CLI_ACTOR } from '../../../base/scope/actor.js';
@@ -36,8 +36,12 @@ function writeCapturedEntries(db, files, entries, opts) {
36
36
  const written = [];
37
37
  const actor = opts.actor ?? CLI_ACTOR;
38
38
  const outcomes = withWriteScope(db, 'capture_write', () => {
39
- const rows = heldRows(db, entries, opts.dedup);
39
+ // A message is the transcript and an item is what capture made of it, so each lane dedupes
40
+ // only against its own rows, and a held message never stops a rule.
41
+ const all = heldRows(db, entries, opts.dedup);
42
+ const rows = all.filter((row) => !isUserMessage(row));
40
43
  const held = storedTextKeys(rows);
44
+ const heldMessages = storedTextKeys(all.filter(isUserMessage));
41
45
  return entries.map((entry) => {
42
46
  const stamped = stampOriginProject(files, entry);
43
47
  // A stated rule replaces an unpinned or untagged-pin capture copy of its own project, which
@@ -45,11 +49,17 @@ function writeCapturedEntries(db, files, entries, opts) {
45
49
  const project = entry.tags.includes(USER_RULE_TAG)
46
50
  ? ruleProjectNames(stamped, opts.dedup)
47
51
  : null;
48
- const stops = project ? storedTextKeys(rows.filter((r) => !ruleReplaces(r, project))) : held;
52
+ const stops = isUserMessage(entry)
53
+ ? heldMessages
54
+ : project
55
+ ? storedTextKeys(rows.filter((r) => !ruleReplaces(r, project)))
56
+ : held;
49
57
  if (stops.has(duplicateKey(entry.content)))
50
58
  return 'skipped';
51
- // One rejected entry must not abort the rest of this capture's entries.
52
- const outcome = gatedWrite(db, files, stamped, { actor: opts.actor });
59
+ // One rejected entry must not abort the rest of this capture's entries. A person wrote a
60
+ // message, as with imported notes, and the worth check drops a one-line fact.
61
+ const worthCheck = !isUserMessage(stamped);
62
+ const outcome = gatedWrite(db, files, stamped, { actor: opts.actor, worthCheck });
53
63
  if (outcome === 'skipped:rejected')
54
64
  return 'rejected';
55
65
  if (outcome !== 'written')
@@ -63,8 +73,11 @@ function writeCapturedEntries(db, files, entries, opts) {
63
73
  return 'captured';
64
74
  });
65
75
  });
76
+ // A message gets no markdown mirror: the transcript is its source, and a mirror is a file a team
77
+ // may commit.
66
78
  for (const entry of written)
67
- writeEntryMirrors(files.hippoRoot, entry);
79
+ if (!isUserMessage(entry))
80
+ writeEntryMirrors(files.hippoRoot, entry);
68
81
  if (!opts.lean && written.length > 0)
69
82
  updateStatsOn(db, files, { remembered: written.length });
70
83
  return outcomes;
@@ -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 }) {
@@ -1,4 +1,4 @@
1
- import { CAPTURED_NOTE_TAG, ERROR_TAG, Layer, schemaFitFrom, } from '../../../base/memory/entry.js';
1
+ import { RECALL_ONLY_TAGS, ERROR_TAG, Layer, schemaFitFrom, } from '../../../base/memory/entry.js';
2
2
  import { FALLBACK_HALF_LIFE_DAYS, PRODUCTION_STRENGTH, calculateStrength, confidenceFacets, } from '../../../base/memory/strength.js';
3
3
  import { strengthSql, originInSql, rewardFactorSql, scopeAdmitSql } from '../runtime/rule-sql.js';
4
4
  import { DECAY_KEY_HALF_LIVES, DECAY_KEY_SLACK_DAYS, DECAY_KEY_SQL, DECAY_KEY_WHERE, } from '../../../db/decay-key.js';
@@ -255,8 +255,9 @@ function decayKeySubsetRows(db, rows, cap, now) {
255
255
  * cap, every such row. */
256
256
  export function listContextCandidates(db, model, tenantId, filter) {
257
257
  // In the SQL, before the cap: a filter after it would let notes fill the cap and starve other rows.
258
+ const notRecallOnly = RECALL_ONLY_TAGS.map((tag) => `instr(tags_json, '"${tag}"') = 0`);
258
259
  const rowsWhere = contextRowsWhere(tenantId, filter, [
259
- `(pinned = 1 OR instr(tags_json, '"${CAPTURED_NOTE_TAG}"') = 0)`,
260
+ `(pinned = 1 OR (${notRecallOnly.join(' AND ')}))`,
260
261
  ]);
261
262
  const { params } = rowsWhere;
262
263
  const cap = Math.max(0, Math.trunc(filter.cap));
@@ -8,6 +8,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';
@@ -273,8 +274,10 @@ const vocabReady = new WeakSet();
273
274
  function ensureRarestVocab(db) {
274
275
  if (vocabReady.has(db))
275
276
  return;
276
- db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS temp.z1_rarest_vocab USING fts5vocab(main, 'memories_fts', 'row')`);
277
- 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
+ });
278
281
  vocabReady.add(db);
279
282
  }
280
283
  /** Rarest-K prompt terms for this connection's FTS indexes, as a space-joined query string: words
@@ -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);
@@ -1,10 +1,13 @@
1
1
  import type { ContextWith } from '../../api/types.js';
2
2
  import type { InfraPorts } from '../../base/ports/infra.js';
3
+ import { type MemoryEntry } from '../../base/memory/entry.js';
3
4
  import type { JsonValue } from '../../base/util/json.js';
4
5
  import type { CaptureErrorOutcome } from '../../base/ports/store/rejections.js';
5
6
  /** The store a failure is logged and its lesson kept in, with that store's config. */
6
7
  export type FailureTarget = Pick<ContextWith<'failureLog' | 'lessonWrites'>, 'tenantId' | 'store' | 'config'> & {
7
8
  readonly infra: Pick<InfraPorts, 'clock'>;
9
+ /** Embeds a stored lesson off the hook's path; without it the row has no vector. */
10
+ readonly embed?: (entry: MemoryEntry) => void;
8
11
  };
9
12
  /**
10
13
  * Store a failure as an error memory unless it is routine or a repeat, and log it either way, even
@@ -18,5 +21,5 @@ export interface LessonCaller {
18
21
  originProject: string;
19
22
  origins: readonly string[];
20
23
  }
21
- export declare function storeLesson({ tenantId, store, config, infra }: FailureTarget, text: string, caller?: LessonCaller): Promise<'stored' | 'duplicate'>;
24
+ export declare function storeLesson({ tenantId, store, config, infra, embed }: FailureTarget, text: string, caller?: LessonCaller): Promise<'stored' | 'duplicate'>;
22
25
  //# sourceMappingURL=capture-error.d.ts.map
@@ -41,7 +41,7 @@ function logFailure({ store, tenantId }, payload, lesson, outcome) {
41
41
  detailHash: hash(lesson.detail),
42
42
  });
43
43
  }
44
- export async function storeLesson({ tenantId, store, config, infra }, text, caller) {
44
+ export async function storeLesson({ tenantId, store, config, infra, embed }, text, caller) {
45
45
  const sig = failureSignature(text);
46
46
  const held = await store.lessonWrites.contentsWithTag(tenantId, 'auto-captured', caller?.origins);
47
47
  if (held.some((content) => failureSignature(content) === sig))
@@ -58,6 +58,7 @@ export async function storeLesson({ tenantId, store, config, infra }, text, call
58
58
  ? { entry, actor: CLI_ACTOR }
59
59
  : { entry: { ...entry, originProject: caller.originProject }, actor: caller.actor };
60
60
  await store.entryWrites.writeEntry(write);
61
+ embed?.(write.entry);
61
62
  return 'stored';
62
63
  }
63
64
  //# sourceMappingURL=capture-error.js.map
@@ -18,6 +18,11 @@ export interface CaptureOptions {
18
18
  stdinText?: string;
19
19
  stdinTimedOut?: boolean;
20
20
  sessionTurns?: readonly SessionTurn[];
21
+ /** The session the turns came from; without it a transcript's file name stands in. */
22
+ sessionId?: string;
23
+ /** Save the messages the person typed too. Only a session-end worker sets it, and only for the
24
+ * folder's own store, so a scanned transcript or the global store never gets them. */
25
+ saveMessages?: boolean;
21
26
  /** False when `sessionTurns` is a later slice of the session (a turn capture), so its first user
22
27
  * turn answers the agent. */
23
28
  fromStart?: boolean;
@@ -54,12 +59,12 @@ export declare function runCapture(target: CaptureTarget, options: CaptureOption
54
59
  * items one, and the first stays unless a later one is the person's rule. */
55
60
  export declare function scrubbedItems(items: readonly ExtractedItem[], scrub: (text: string) => string): ExtractedItem[];
56
61
  /** Held keys, each twin's clean text too when a held row has its old text and repair keeps that
57
- * row: a pinned row, or one whose text is no certain defect. */
58
- export declare function heldKeysOf(rows: readonly HeldText[], twins: readonly BoldTwin[]): Set<string>;
62
+ * row: a pinned row, or one whose text is no certain defect. A held message adds its lane key. */
63
+ export declare function heldKeysOf(all: readonly HeldText[], twins: readonly BoldTwin[]): Set<string>;
59
64
  /** The held keys that also stop a stated rule written for `ruleProject` (its names): every copy
60
65
  * but one the store's write replaces, which holds the rule's exact text, so a bold twin still
61
66
  * stops it. */
62
- export declare function ruleHeldKeysOf(rows: readonly HeldText[], twins: readonly BoldTwin[], ruleProject: readonly string[]): Set<string>;
67
+ export declare function ruleHeldKeysOf(all: readonly HeldText[], twins: readonly BoldTwin[], ruleProject: readonly string[]): Set<string>;
63
68
  export interface CaptureTally {
64
69
  captured: number;
65
70
  skipped: number;