hippo-memory 3.7.1 → 3.9.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 (64) hide show
  1. package/README.md +36 -34
  2. package/dist/api/agent-memories.d.ts +3 -2
  3. package/dist/api/agent-memories.js +21 -5
  4. package/dist/base/memory/agent-memory-report.js +1 -0
  5. package/dist/base/util/env.d.ts +1 -0
  6. package/dist/base/util/env.js +2 -0
  7. package/dist/base/util/secret-detect.d.ts +8 -0
  8. package/dist/base/util/secret-detect.js +31 -11
  9. package/dist/base/util/version.d.ts +1 -1
  10. package/dist/base/util/version.js +1 -1
  11. package/dist/domain/agent-memories/apply.js +2 -1
  12. package/dist/domain/agent-memories/claude-code.d.ts +4 -0
  13. package/dist/domain/agent-memories/claude-code.js +24 -1
  14. package/dist/domain/agent-memories/container-steps.js +19 -3
  15. package/dist/domain/agent-memories/folder-store.d.ts +1 -0
  16. package/dist/domain/agent-memories/handover.js +2 -2
  17. package/dist/domain/agent-memories/keys.d.ts +4 -2
  18. package/dist/domain/agent-memories/keys.js +6 -3
  19. package/dist/domain/agent-memories/legacy.js +15 -8
  20. package/dist/domain/agent-memories/markdown.d.ts +5 -0
  21. package/dist/domain/agent-memories/markdown.js +7 -2
  22. package/dist/domain/agent-memories/note-parts.d.ts +4 -0
  23. package/dist/domain/agent-memories/note-parts.js +232 -0
  24. package/dist/domain/agent-memories/plan.d.ts +9 -4
  25. package/dist/domain/agent-memories/plan.js +35 -15
  26. package/dist/domain/agent-memories/source.d.ts +5 -0
  27. package/dist/domain/agent-memories/source.js +12 -0
  28. package/dist/domain/agent-memories/sync.js +5 -1
  29. package/dist/domain/agent-memories/types.d.ts +5 -1
  30. package/dist/store/sqlite/entries/set-aside.d.ts +2 -2
  31. package/dist/store/sqlite/entries/set-aside.js +5 -3
  32. package/dist/surface/capture/compact.d.ts +1 -1
  33. package/dist/surface/capture/compact.js +1 -1
  34. package/dist/surface/cli/doctor.js +1 -0
  35. package/dist/surface/cli/embedder-install.d.ts +18 -0
  36. package/dist/surface/cli/embedder-install.js +121 -0
  37. package/dist/surface/cli/hook-runtime.d.ts +3 -0
  38. package/dist/surface/cli/hook-runtime.js +13 -0
  39. package/dist/surface/cli/hook.js +3 -0
  40. package/dist/surface/cli/hooks/note-import-worker.d.ts +15 -0
  41. package/dist/surface/cli/hooks/note-import-worker.js +44 -0
  42. package/dist/surface/cli/hooks/note-written.d.ts +4 -0
  43. package/dist/surface/cli/hooks/note-written.js +41 -0
  44. package/dist/surface/cli/hooks/post-compact.js +9 -18
  45. package/dist/surface/cli/hooks/session-end.js +2 -14
  46. package/dist/surface/cli/init.js +35 -1
  47. package/dist/surface/cli/maintenance.js +2 -2
  48. package/dist/surface/cli/setup.js +2 -0
  49. package/dist/surface/cli/verbs/memory.js +3 -1
  50. package/dist/surface/cli/verbs/sessions.d.ts +2 -0
  51. package/dist/surface/cli/verbs/sessions.js +16 -2
  52. package/dist/surface/cli/verbs.d.ts +2 -0
  53. package/dist/surface/hooks-install/json-hooks.js +2 -2
  54. package/dist/surface/hooks-install/rules/claude-hooks.d.ts +3 -2
  55. package/dist/surface/hooks-install/rules/claude-hooks.js +25 -2
  56. package/dist/surface/hooks-install/rules/install-plan.js +1 -0
  57. package/dist/surface/hooks-install/rules/json-hooks.d.ts +4 -2
  58. package/dist/surface/hooks-install/rules/json-hooks.js +3 -2
  59. package/dist/surface/hooks-install/rules/shared.d.ts +3 -0
  60. package/dist/surface/hooks-install/rules/shared.js +5 -0
  61. package/extensions/openclaw-plugin/openclaw.plugin.json +1 -1
  62. package/extensions/openclaw-plugin/package.json +1 -1
  63. package/openclaw.plugin.json +1 -1
  64. package/package.json +1 -1
@@ -0,0 +1,121 @@
1
+ // The init step that installs the local embedder beside a global hippo, so a default install
2
+ // recalls by meaning as well as by keyword while the package itself keeps no runtime dependencies.
3
+ import * as fs from 'node:fs';
4
+ import * as path from 'node:path';
5
+ import { execFileSync } from 'node:child_process';
6
+ import { PACKAGE_ROOT } from '../../base/config/package-root.js';
7
+ import { isEmbeddingAvailable } from '../../base/embeddings/local.js';
8
+ import { envSkipEmbedderInstall } from '../../base/util/env.js';
9
+ import { errorCode, errorFields, errorMessage, log } from '../../base/util/log.js';
10
+ /** Exact: a global install has no lockfile, so this pin is the one review gate on the tree. */
11
+ const EMBEDDER_PACKAGE = '@huggingface/transformers@4.3.2';
12
+ const INSTALL_TIMEOUT_MS = 10 * 60_000;
13
+ const NPM_CLI = path.join('node_modules', 'npm', 'bin', 'npm-cli.js');
14
+ const PROJECT_ADD = [
15
+ ['pnpm-lock.yaml', 'pnpm add'],
16
+ ['yarn.lock', 'yarn add --ignore-scripts'],
17
+ ['bun.lock', 'bun add'],
18
+ ['bun.lockb', 'bun add'],
19
+ ];
20
+ const MACHINE = {
21
+ run: execFileSync,
22
+ installed: isEmbeddingAvailable,
23
+ exists: fs.existsSync,
24
+ packageRoot: PACKAGE_ROOT,
25
+ platform: process.platform,
26
+ nodePath: process.execPath,
27
+ };
28
+ /** npm puts globals in `{prefix}/node_modules` on Windows and `{prefix}/lib/node_modules`
29
+ * elsewhere, with no package.json above; pnpm, yarn, bun and npm projects are all projects. */
30
+ function layoutOf(deps) {
31
+ const parts = deps.packageRoot.split(/[\\/]/);
32
+ if (parts.includes('_npx'))
33
+ return { kind: 'npx' };
34
+ const first = parts.indexOf('node_modules');
35
+ if (first < 0)
36
+ return { kind: 'project', dir: deps.packageRoot };
37
+ const dir = parts.slice(0, first).join(path.sep) || path.sep;
38
+ const direct = first === parts.length - 2;
39
+ if (direct && !deps.exists(path.join(dir, 'package.json'))) {
40
+ if (deps.platform === 'win32')
41
+ return { kind: 'npm-global', prefix: dir };
42
+ if (path.basename(dir) === 'lib')
43
+ return { kind: 'npm-global', prefix: path.dirname(dir) };
44
+ }
45
+ return { kind: 'project', dir };
46
+ }
47
+ function adviceFor(layout, deps) {
48
+ if (layout.kind === 'npm-global') {
49
+ return `run: npm install -g --ignore-scripts ${EMBEDDER_PACKAGE}`;
50
+ }
51
+ if (layout.kind === 'npx') {
52
+ return 'install hippo globally (npm install -g hippo-memory), then run hippo init again';
53
+ }
54
+ const add = PROJECT_ADD.find(([lockfile]) => deps.exists(path.join(layout.dir, lockfile)))?.[1] ??
55
+ 'npm install --ignore-scripts';
56
+ return `run \`${add} ${EMBEDDER_PACKAGE}\` in ${layout.dir}`;
57
+ }
58
+ /** How to install the local embedder where this hippo resolves it, as the end of a sentence. */
59
+ export function embedderInstallAdvice(deps = MACHINE) {
60
+ return adviceFor(layoutOf(deps), deps);
61
+ }
62
+ /** The npm that owns hippo's global folder, else the one shipped beside this node. */
63
+ function npmCliFor(prefix, deps) {
64
+ const lib = deps.platform === 'win32' ? '' : 'lib';
65
+ const nodeHome = path.dirname(deps.nodePath);
66
+ const beside = deps.platform === 'win32' ? nodeHome : path.join(path.dirname(nodeHome), 'lib');
67
+ return [path.join(prefix, lib, NPM_CLI), path.join(beside, NPM_CLI)].find(deps.exists);
68
+ }
69
+ /** execFileSync puts npm's exit code on the error it throws; a kill or a failed start leaves none. */
70
+ function failureLine(error) {
71
+ if (errorCode(error) === 'ETIMEDOUT')
72
+ return 'npm ran for 10 minutes, so hippo stopped it.';
73
+ if ('status' in error && Number.isInteger(error.status)) {
74
+ return `npm stopped with exit code ${String(error.status)}; its error is above.`;
75
+ }
76
+ return `npm did not start (${error.message.split(/\r?\n/, 1)[0]}).`;
77
+ }
78
+ /** Installs the local embedder into hippo's own npm global folder, else prints how; never throws.
79
+ * --ignore-scripts: the tree ships prebuilt binaries, so no transitive install script runs. */
80
+ export function installLocalEmbedder(embeddings, deps = MACHINE) {
81
+ if (embeddings.enabled === false || (embeddings.provider ?? 'local') !== 'local')
82
+ return false;
83
+ if (deps.installed())
84
+ return false;
85
+ if (envSkipEmbedderInstall()) {
86
+ console.log('HIPPO_SKIP_EMBEDDER_INSTALL=1, so init did not install local embeddings.');
87
+ return false;
88
+ }
89
+ const layout = layoutOf(deps);
90
+ const npmCli = layout.kind === 'npm-global' ? npmCliFor(layout.prefix, deps) : undefined;
91
+ if (layout.kind !== 'npm-global' || !npmCli) {
92
+ console.log(`Embeddings are off. For recall by meaning, ${adviceFor(layout, deps)}`);
93
+ return false;
94
+ }
95
+ console.log(`Installing local embeddings (${EMBEDDER_PACKAGE}, about 480 MB, and an 87 MB model on ` +
96
+ 'first use) for recall by meaning. This can take a few minutes; --no-embeddings skips it.');
97
+ try {
98
+ deps.run(deps.nodePath, [
99
+ npmCli,
100
+ 'install',
101
+ '--global',
102
+ '--prefix',
103
+ layout.prefix,
104
+ '--ignore-scripts',
105
+ EMBEDDER_PACKAGE,
106
+ ], { stdio: ['ignore', 'inherit', 'inherit'], timeout: INSTALL_TIMEOUT_MS });
107
+ }
108
+ catch (err) {
109
+ const error = err instanceof Error ? err : new Error(errorMessage(err));
110
+ log.info(`embedder install failed: ${error.message}`, errorFields(error));
111
+ console.log(`${failureLine(error)} For recall by meaning, ${adviceFor(layout, deps)}`);
112
+ return false;
113
+ }
114
+ if (!deps.installed()) {
115
+ console.log(`npm finished, but hippo cannot find the package. For recall by meaning, ${adviceFor(layout, deps)}`);
116
+ return false;
117
+ }
118
+ console.log('Local embeddings are on.');
119
+ return true;
120
+ }
121
+ //# sourceMappingURL=embedder-install.js.map
@@ -21,6 +21,9 @@ export declare function appendSessionEndCloseLog(logFile: string | null, message
21
21
  startFresh?: boolean;
22
22
  fields?: LogFields;
23
23
  }): void;
24
+ /** Starts `workerArgs` as a detached child that outlives the host's teardown; `name` labels a
25
+ * failed start. */
26
+ export declare function spawnDetachedWorker(name: string, workerArgs: readonly string[]): void;
24
27
  /** Runs `run` with the held lines written on exit too, as sleep may end the process before the
25
28
  * run writes them. */
26
29
  export declare function flushingOnExit(held: HeldLog, run: () => Promise<void>): Promise<void>;
@@ -3,6 +3,7 @@
3
3
  import { envClaudeCodeSessionId, envHippoSessionId } from '../../base/util/env.js';
4
4
  import * as path from 'node:path';
5
5
  import * as fs from 'node:fs';
6
+ import { spawn } from 'node:child_process';
6
7
  import { bookTokenUse } from '../../api/ledger-db.js';
7
8
  import { sessionPilotArm } from '../../api/pilot-arm.js';
8
9
  import { cliDetached, cliFolder, cliInfra, cliLedgerReach, cliSyncOptions } from './api-context.js';
@@ -63,6 +64,18 @@ export function appendSessionEndCloseLog(logFile, message, opts = {}) {
63
64
  log.warn(`session-end log not written: ${errorMessage(err)}`, errorFields(err));
64
65
  }
65
66
  }
67
+ /** Starts `workerArgs` as a detached child that outlives the host's teardown; `name` labels a
68
+ * failed start. */
69
+ export function spawnDetachedWorker(name, workerArgs) {
70
+ const child = spawn(process.execPath, workerArgs, {
71
+ detached: true,
72
+ stdio: 'ignore',
73
+ windowsHide: true,
74
+ });
75
+ // With no 'error' listener an async spawn failure is an uncaught exception.
76
+ child.on('error', (err) => log.warn(`hippo ${name}: the worker did not start: ${errorMessage(err)}`, errorFields(err)));
77
+ child.unref();
78
+ }
66
79
  /** Runs `run` with the held lines written on exit too, as sleep may end the process before the
67
80
  * run writes them. */
68
81
  export async function flushingOnExit(held, run) {
@@ -122,6 +122,9 @@ function printClaudeHookInstall(result) {
122
122
  if (result.installedCaptureError) {
123
123
  console.log(`Installed hippo capture-error PostToolUseFailure hook in ${result.target} settings`);
124
124
  }
125
+ if (result.installedNoteWritten) {
126
+ console.log(`Installed hippo note-written PostToolUse hook in ${result.target} settings`);
127
+ }
125
128
  if (result.migratedFromStop) {
126
129
  console.log(`Migrated legacy Stop hook → SessionEnd (was running every turn; now fires once on session exit)`);
127
130
  }
@@ -0,0 +1,15 @@
1
+ import { type CommandContext } from '../flag-values.js';
2
+ /** What a hook hands the worker: the session's transcript, which names its notes folder. */
3
+ export interface NoteImportJob {
4
+ /** The hook that asked, which prefixes each log line. */
5
+ readonly from: 'note-written' | 'post-compact';
6
+ readonly transcriptPath: string;
7
+ readonly cwd: string | null;
8
+ readonly logFile: string | null;
9
+ }
10
+ /** Starts the import in a detached worker and returns at once; the worker finds its store from
11
+ * the folder it inherits. */
12
+ export declare function startNoteImport({ from, transcriptPath, cwd, logFile }: NoteImportJob): void;
13
+ /** Never throws: a failed import is a log line, since nothing waits on this process. */
14
+ export declare function handleNoteImportWorker({ hippoRoot, tenantId, flags, }: CommandContext): Promise<void>;
15
+ //# sourceMappingURL=note-import-worker.d.ts.map
@@ -0,0 +1,44 @@
1
+ // The detached agent-note import (`__note-import-worker`): one session folder's notes, with no
2
+ // hook time limit, and a log line for what it did.
3
+ import { importSessionFolder } from '../../../api/agent-memories.js';
4
+ import { summaryLine } from '../../../base/memory/agent-memory-report.js';
5
+ import { isInitialized } from '../../../host/project-identity.js';
6
+ import { currentMachine } from '../../../infra/machine.js';
7
+ import { cliSyncOptions } from '../api-context.js';
8
+ import { stringFlag } from '../flag-values.js';
9
+ import { appendSessionEndCloseLog, hookStoreRoot, reportSessionEndFailure, spawnDetachedWorker, } from '../hook-runtime.js';
10
+ /** Starts the import in a detached worker and returns at once; the worker finds its store from
11
+ * the folder it inherits. */
12
+ export function startNoteImport({ from, transcriptPath, cwd, logFile }) {
13
+ const args = [process.argv[1], '__note-import-worker', '--transcript', transcriptPath];
14
+ args.push('--from', from);
15
+ if (cwd !== null)
16
+ args.push('--cwd', cwd);
17
+ if (logFile !== null)
18
+ args.push('--log-file', logFile);
19
+ spawnDetachedWorker(from, args);
20
+ }
21
+ /** Never throws: a failed import is a log line, since nothing waits on this process. */
22
+ export async function handleNoteImportWorker({ hippoRoot, tenantId, flags, }) {
23
+ const transcript = stringFlag(flags, 'transcript');
24
+ const logFile = stringFlag(flags, 'log-file') ?? null;
25
+ const from = stringFlag(flags, 'from') ?? 'note-written';
26
+ const say = (line) => appendSessionEndCloseLog(logFile, `${from}: ${line}`);
27
+ const store = hookStoreRoot(hippoRoot);
28
+ // A hook fires in every folder, and none may create a store.
29
+ if (transcript === undefined || !isInitialized(store))
30
+ return;
31
+ try {
32
+ const sync = cliSyncOptions(tenantId, currentMachine());
33
+ const report = await importSessionFolder(store, transcript, stringFlag(flags, 'cwd') ?? null, sync);
34
+ const summary = summaryLine(report);
35
+ if (summary !== null)
36
+ say(summary);
37
+ for (const warning of report.warnings)
38
+ say(`agent memories: ${warning}`);
39
+ }
40
+ catch (err) {
41
+ reportSessionEndFailure(logFile, `${from}: agent memory import`, err);
42
+ }
43
+ }
44
+ //# sourceMappingURL=note-import-worker.js.map
@@ -0,0 +1,4 @@
1
+ import { type CommandContext } from '../flag-values.js';
2
+ /** Every path exits 0, so a failure never blocks the session. */
3
+ export declare function handleNoteWritten({ flags }: CommandContext): Promise<void>;
4
+ //# sourceMappingURL=note-written.d.ts.map
@@ -0,0 +1,41 @@
1
+ // The PostToolUse hook for Claude Code's memory notes: a write of one starts the import in a
2
+ // detached worker; any other write ends here, before a store opens.
3
+ import { isClaudeMemoryNote } from '../../../api/agent-memories.js';
4
+ import { isJsonObjectLiteral, isJsonString, tryParseJson } from '../../../base/util/json.js';
5
+ import { errorFields, errorMessage, log } from '../../../base/util/log.js';
6
+ import { processHomes } from '../../../host/agent-homes.js';
7
+ import { currentMachine } from '../../../infra/machine.js';
8
+ import { defaultNoteWrittenLogPath } from '../../hooks-install/rules/shared.js';
9
+ import { readHookStdin } from '../stdin.js';
10
+ import { stringFlag } from '../flag-values.js';
11
+ import { startNoteImport } from './note-import-worker.js';
12
+ function writtenFile(text) {
13
+ const payload = tryParseJson((text ?? '').trim());
14
+ if (!isJsonObjectLiteral(payload))
15
+ return null;
16
+ const input = payload.tool_input;
17
+ const file = isJsonObjectLiteral(input) ? input.file_path : undefined;
18
+ const { transcript_path: transcriptPath, cwd } = payload;
19
+ if (!isJsonString(file) || !isJsonString(transcriptPath))
20
+ return null;
21
+ return { file, transcriptPath, cwd: isJsonString(cwd) ? cwd : null };
22
+ }
23
+ /** Every path exits 0, so a failure never blocks the session. */
24
+ export async function handleNoteWritten({ flags }) {
25
+ try {
26
+ const { text } = await readHookStdin();
27
+ const written = writtenFile(text);
28
+ if (written === null || !isClaudeMemoryNote(written.file, currentMachine()))
29
+ return;
30
+ startNoteImport({
31
+ from: 'note-written',
32
+ transcriptPath: written.transcriptPath,
33
+ cwd: written.cwd,
34
+ logFile: stringFlag(flags, 'log-file') ?? defaultNoteWrittenLogPath(processHomes()),
35
+ });
36
+ }
37
+ catch (err) {
38
+ log.warn(`note-written skipped: ${errorMessage(err)}`, errorFields(err));
39
+ }
40
+ }
41
+ //# sourceMappingURL=note-written.js.map
@@ -1,35 +1,26 @@
1
1
  // The PostCompact hook: saves the compaction summary and its memories, then prints one plain line,
2
2
  // because Claude Code shows this hook's stdout as-is.
3
- import { importSessionFolder } from '../../../api/agent-memories.js';
4
- import { summaryLine } from '../../../base/memory/agent-memory-report.js';
5
- import { COMPACTION_DB_WAIT_MS } from '../../../base/session/compaction-timing.js';
6
- import { currentMachine } from '../../../infra/machine.js';
3
+ import { processHomes } from '../../../host/agent-homes.js';
7
4
  import { postCompactHook } from '../../capture/compact.js';
5
+ import { defaultPreCompactLogPath } from '../../hooks-install/rules/shared.js';
8
6
  import { readHookStdin } from '../stdin.js';
9
- import { cliHookRequest, cliStore, cliSyncOptions } from '../api-context.js';
7
+ import { cliHookRequest, cliStore } from '../api-context.js';
10
8
  import { stringFlag } from '../flag-values.js';
11
9
  import { hookStoreRoot } from '../hook-runtime.js';
10
+ import { startNoteImport } from './note-import-worker.js';
12
11
  /** Always exits 0. */
13
12
  export async function handlePostCompact({ hippoRoot, tenantId, flags, }) {
14
13
  const { text, timedOut } = await readHookStdin();
15
14
  const store = hookStoreRoot(hippoRoot);
15
+ const logFile = stringFlag(flags, 'log-file') ?? defaultPreCompactLogPath(processHomes());
16
16
  const line = await cliHookRequest(() => postCompactHook(store, cliStore(store), {
17
17
  tenantId,
18
18
  stdinText: text,
19
19
  stdinTimedOut: timedOut,
20
- logFile: stringFlag(flags, 'log-file'),
21
- // Passed in, since src/surface/capture/ importing the sync would close an import cycle.
22
- afterSave: async (transcriptPath, cwd, log) => {
23
- const sync = cliSyncOptions(tenantId, currentMachine(), {
24
- busyWaitMs: COMPACTION_DB_WAIT_MS,
25
- });
26
- const report = await importSessionFolder(store, transcriptPath, cwd, sync);
27
- const summary = summaryLine(report);
28
- if (summary !== null)
29
- log(summary);
30
- for (const warning of report.warnings)
31
- log(`agent memories: ${warning}`);
32
- },
20
+ logFile,
21
+ // A first import is thousands of rows, more than the hook's time limit, so a detached worker runs
22
+ // it; passed in, since src/surface/capture/ importing the worker would close an import cycle.
23
+ afterSave: (transcriptPath, cwd) => startNoteImport({ from: 'post-compact', transcriptPath, cwd, logFile }),
33
24
  }));
34
25
  if (line !== null && line !== undefined)
35
26
  console.log(line);
@@ -1,7 +1,6 @@
1
1
  // The SessionEnd hook: reads the payload inline, then hands the slow work to a detached worker
2
2
  // before the host exits.
3
3
  import * as fs from 'node:fs';
4
- import { spawn } from 'node:child_process';
5
4
  import { defaultSleepLogPath, resolveJsonHookPaths } from '../../hooks-install/json-hooks.js';
6
5
  import { copilotTranscriptFor } from '../../capture/copilot-transcript.js';
7
6
  import { SESSION_ID_RE } from '../../../base/util/session-id.js';
@@ -11,7 +10,7 @@ import { flushDeliveryRecorder, startDeliveryRecorder } from '../../../api/ledge
11
10
  import { normalizeHookPayload, readStdinBounded } from '../stdin.js';
12
11
  import { cliApiContext, cliHookRequest } from '../api-context.js';
13
12
  import { boolFlag, stringFlag } from '../flag-values.js';
14
- import { hookRuntime, hookStoreRoot, hostSessionId, payloadCwdRoot } from '../hook-runtime.js';
13
+ import { hookRuntime, hookStoreRoot, hostSessionId, payloadCwdRoot, spawnDetachedWorker, } from '../hook-runtime.js';
15
14
  import { handleSessionEndWorker } from './session-end-worker.js';
16
15
  /** Copilot's hook command and OpenCode's plugin carry no path, since one quoted into them would
17
16
  * need escaping for each shell. Copilot's log goes where its hook table used to point,
@@ -61,7 +60,7 @@ function workerTranscriptPath(input, runtime) {
61
60
  }
62
61
  async function runSessionEndWorker(worker, { root, tenantId, flags, rec }) {
63
62
  try {
64
- spawnSessionEndWorker(sessionEndWorkerArgs(worker));
63
+ spawnDetachedWorker('session-end', sessionEndWorkerArgs(worker));
65
64
  }
66
65
  catch (err) {
67
66
  log.debug(`session-end: the worker did not spawn, running inline: ${errorMessage(err)}`, errorFields(err));
@@ -138,17 +137,6 @@ function inlineWorkerFlags(flags, w) {
138
137
  out['no-share'] = true;
139
138
  return out;
140
139
  }
141
- function spawnSessionEndWorker(workerArgs) {
142
- const child = spawn(process.execPath, workerArgs, {
143
- detached: true,
144
- stdio: 'ignore',
145
- windowsHide: true,
146
- });
147
- // An async spawn failure arrives as an 'error' event, which with no listener is an uncaught
148
- // exception.
149
- child.on('error', (err) => log.warn(`hippo session-end: the worker did not start: ${errorMessage(err)}`, errorFields(err)));
150
- child.unref();
151
- }
152
140
  /** The input of a VS Code Stop payload with a session id that can name the lock file; null makes
153
141
  * turn mode a silent no-op. */
154
142
  function vscodeStopInput(raw) {
@@ -12,7 +12,7 @@ import { installOpencodePlugin } from '../hooks-install/opencode.js';
12
12
  import { initMemoryStore } from '../../api/store-init.js';
13
13
  import { isInitialized } from '../../host/project-identity.js';
14
14
  import { hippoHomeDir } from '../../host/agent-homes.js';
15
- import { memoryList } from '../../api/memories/memories.js';
15
+ import { memoryCountAll, memoryList } from '../../api/memories/memories.js';
16
16
  import { cliApiContext, cliInitGlobal, cliSyncOptions } from './api-context.js';
17
17
  import { isGitRepo } from '../../base/ports/git.js';
18
18
  import { processGit } from '../../infra/git-runner.js';
@@ -28,6 +28,9 @@ import { learnFromRepo, skipLearnOnSharedStore } from './shared.js';
28
28
  import { appendHookBlock, HOOK_MARKERS, HOOKS, hippoBlock } from '../hooks-install/instructions.js';
29
29
  import { HIPPO_DIR } from '../../base/util/agent-homes.js';
30
30
  import { SEED_DAYS_SCAN, SEED_DAYS_SINGLE } from './flag-defaults.js';
31
+ import { installLocalEmbedder } from './embedder-install.js';
32
+ import { loadConfig } from '../../host/config-file.js';
33
+ import { plural } from '../../base/util/format.js';
31
34
  // An unreadable or vanished folder is expected while scanning; any other failure is worth a line.
32
35
  const QUIET_SCAN_ERRORS = new Set(['EACCES', 'EPERM', 'ENOENT', 'ENOTDIR']);
33
36
  function scanForGitRepos(rootDir, maxDepth = 2) {
@@ -157,6 +160,9 @@ async function initScannedRepos(scanDir, tenantId, flags) {
157
160
  return;
158
161
  }
159
162
  console.log(`Found ${repos.length} repositories:\n`);
163
+ const stores = [hippoHomeDir(), ...repos.map((repo) => path.join(repo, HIPPO_DIR))];
164
+ const hadStores = stores.some((store) => isInitialized(store));
165
+ const embedderAdded = maybeInstallEmbedder(hippoHomeDir(), flags);
160
166
  const globalRoot = initGlobalFirst();
161
167
  const seedDays = numberFlag(flags, 'days') ?? SEED_DAYS_SCAN;
162
168
  const machine = currentMachine();
@@ -170,6 +176,10 @@ async function initScannedRepos(scanDir, tenantId, flags) {
170
176
  printAgentImport(agentImport, '');
171
177
  }
172
178
  console.log(`Global store: ${globalRoot}`);
179
+ if (embedderAdded && hadStores) {
180
+ console.log('Memories stored before this run have no vectors yet: run `hippo embed` in each project ' +
181
+ 'and `hippo embed --global` to add them.');
182
+ }
173
183
  if (initInstallsIntegrations(flags))
174
184
  installScanHooks(repos);
175
185
  if (!boolFlag(flags, 'no-schedule')) {
@@ -179,8 +189,11 @@ async function initScannedRepos(scanDir, tenantId, flags) {
179
189
  }
180
190
  async function initGlobalOnly(tenantId, flags) {
181
191
  const globalRoot = hippoHomeDir();
192
+ const embedderAdded = maybeInstallEmbedder(globalRoot, flags);
182
193
  if (isInitialized(globalRoot)) {
183
194
  console.log('Already initialized global store at', globalRoot);
195
+ if (embedderAdded)
196
+ await printEmbedHint(globalRoot, tenantId, 'hippo embed --global');
184
197
  }
185
198
  else {
186
199
  cliInitGlobal();
@@ -219,8 +232,11 @@ export async function handleInit({ hippoRoot, tenantId, flags }) {
219
232
  return;
220
233
  }
221
234
  const alreadyExists = isInitialized(hippoRoot);
235
+ const embedderAdded = maybeInstallEmbedder(hippoRoot, flags);
222
236
  if (alreadyExists) {
223
237
  console.log('Already initialized at', hippoRoot);
238
+ if (embedderAdded)
239
+ await printEmbedHint(hippoRoot, tenantId, 'hippo embed');
224
240
  }
225
241
  else {
226
242
  await initMemoryStore(cliApiContext(hippoRoot, tenantId));
@@ -247,6 +263,21 @@ export async function handleInit({ hippoRoot, tenantId, flags }) {
247
263
  printAgentImport(await importForStore(hippoRoot, cliSyncOptions(tenantId, currentMachine())));
248
264
  }
249
265
  }
266
+ /** First in every init path: a killed install leaves no store to skip the first-run seed, and
267
+ * the memories init writes get vectors as they land. */
268
+ function maybeInstallEmbedder(configRoot, flags) {
269
+ if (boolFlag(flags, 'no-embeddings'))
270
+ return false;
271
+ return installLocalEmbedder(loadConfig(configRoot).embeddings);
272
+ }
273
+ /** The embedder arrived after this store already held memories, and those have no vectors yet. */
274
+ async function printEmbedHint(root, tenantId, command) {
275
+ const count = await memoryCountAll(cliApiContext(root, tenantId));
276
+ if (count > 0) {
277
+ const stored = plural(count, 'memory', 'memories');
278
+ console.log(` Run \`${command}\` to add vectors to the ${stored} stored before now.`);
279
+ }
280
+ }
250
281
  /**
251
282
  * Every write init makes into agent config (instruction blocks, hooks, plugins) is an automatic
252
283
  * integration, so one switch skips them all.
@@ -349,6 +380,9 @@ function installClaudeCodeSettingsHooks(hook) {
349
380
  if (result.installedCaptureError) {
350
381
  console.log(` Auto-installed hippo capture-error PostToolUseFailure hook in ${hook} settings`);
351
382
  }
383
+ if (result.installedNoteWritten) {
384
+ console.log(` Auto-installed hippo note-written PostToolUse hook in ${hook} settings`);
385
+ }
352
386
  if (result.migratedFromStop) {
353
387
  console.log(` Migrated legacy Stop hook → SessionEnd (no longer runs every turn)`);
354
388
  }
@@ -11,6 +11,7 @@ import { boolFlag, numberFlag, stringFlagOrExit, hasFlag, } from './flag-values.
11
11
  import { requireInit, resolveAuthRoot } from './shared.js';
12
12
  import { errorMessage } from '../../base/util/log.js';
13
13
  import { fail } from './exit.js';
14
+ import { embedderInstallAdvice } from './embedder-install.js';
14
15
  const MAX_FAILED_SHOWN = 5;
15
16
  const MAX_PAIRS_SHOWN = 15;
16
17
  const PAIR_PREVIEW_CHARS = 90;
@@ -178,8 +179,7 @@ function readyEmbedProvider(ctx, given) {
178
179
  return null;
179
180
  }
180
181
  if (embedProvider.kind === 'local') {
181
- console.log('Embeddings not available. Install @huggingface/transformers to enable:');
182
- console.log(' npm install @huggingface/transformers');
182
+ console.log(`Embeddings not available. To turn them on, ${embedderInstallAdvice()}`);
183
183
  process.exitCode = 1;
184
184
  }
185
185
  else {
@@ -116,6 +116,8 @@ function setupJsonTool(tool, dryRun) {
116
116
  bits.push('PostCompact (post-compact)');
117
117
  if (result.installedCaptureError)
118
118
  bits.push('PostToolUseFailure (capture-error)');
119
+ if (result.installedNoteWritten)
120
+ bits.push('PostToolUse (note-written)');
119
121
  if (result.migratedFromStop)
120
122
  bits.push('migrated legacy Stop');
121
123
  if (result.migratedSplitSessionEnd)
@@ -15,7 +15,7 @@ export const MEMORY_VERBS = {
15
15
  repairsCodexWrapper: true,
16
16
  scoped: true,
17
17
  flags: {
18
- switches: ['global', 'no-hooks', 'no-learn', 'no-schedule'],
18
+ switches: ['global', 'no-embeddings', 'no-hooks', 'no-learn', 'no-schedule'],
19
19
  values: ['scan'],
20
20
  numbers: ['days'],
21
21
  },
@@ -28,6 +28,8 @@ export const MEMORY_VERBS = {
28
28
  --no-hooks Skip auto-detecting and installing agent hooks
29
29
  (HIPPO_SKIP_AUTO_INTEGRATIONS=1 does the same)
30
30
  --no-schedule Skip auto-creating the machine-level daily runner
31
+ --no-embeddings Skip installing the local embedder (@huggingface/transformers)
32
+ (HIPPO_SKIP_EMBEDDER_INSTALL=1 does the same)
31
33
  --no-learn Skip seeding memories from git history and importing
32
34
  coding agents' own memories (every init imports those)`,
33
35
  ],
@@ -25,6 +25,8 @@ export declare const SESSION_VERBS: {
25
25
  'pre-compact': VerbSpec;
26
26
  'compact-resume': VerbSpec;
27
27
  'post-compact': VerbSpec;
28
+ 'note-written': VerbSpec;
29
+ '__note-import-worker': VerbSpec;
28
30
  'codex-run': VerbSpec;
29
31
  '__codex-session-end-worker': VerbSpec;
30
32
  hook: VerbSpec;
@@ -307,7 +307,7 @@ export const SESSION_VERBS = {
307
307
  usage: [
308
308
  `
309
309
  setup One-shot: detect installed AI tools and install their hooks:
310
- claude-code gets 8 hooks in $CLAUDE_CONFIG_DIR/settings.json
310
+ claude-code gets 9 hooks in $CLAUDE_CONFIG_DIR/settings.json
311
311
  (~/.claude by default), opencode a plugin, codex 2 hooks in
312
312
  its hooks.json plus a launcher wrapper, copilot 4 hooks, the
313
313
  MCP server and an instructions block under $COPILOT_HOME
@@ -400,6 +400,20 @@ export const SESSION_VERBS = {
400
400
  --log-file <p> Same log path as pre-compact (default: ~/.hippo/logs/pre-compact.log)`,
401
401
  ],
402
402
  }),
403
+ 'note-written': verb(() => import('../hooks/note-written.js'), 'handleNoteWritten', {
404
+ readOnly: 'skip',
405
+ flags: { values: ['log-file'] },
406
+ usage: [
407
+ `
408
+ note-written PostToolUse hook: when Claude Code writes a memory note, import it in a
409
+ detached worker (any other write exits at once)
410
+ --log-file <p> Where the worker logs (default: ~/.hippo/logs/note-written.log)`,
411
+ ],
412
+ }),
413
+ '__note-import-worker': verb(() => import('../hooks/note-import-worker.js'), 'handleNoteImportWorker', {
414
+ readOnly: 'skip',
415
+ flags: { values: ['cwd', 'from', 'log-file', 'transcript'] },
416
+ }),
403
417
  'codex-run': verb(() => import('../hooks/codex-run.js'), 'handleCodexRun', {
404
418
  flags: {},
405
419
  usage: [
@@ -418,7 +432,7 @@ export const SESSION_VERBS = {
418
432
  hook <sub> [target] Manage framework integrations
419
433
  hook list Show available hooks
420
434
  hook install <target> Install hook (claude-code|codex|copilot|cursor|openclaw|opencode|pi)
421
- claude-code adds 8 hooks to $CLAUDE_CONFIG_DIR/settings.json
435
+ claude-code adds 9 hooks to $CLAUDE_CONFIG_DIR/settings.json
422
436
  (~/.claude by default); opencode installs a plugin; codex
423
437
  adds 2 hooks to $CODEX_HOME/hooks.json (trust them once in /hooks) and
424
438
  wraps the detected launcher in place; copilot writes
@@ -42,6 +42,8 @@ export declare const COMMANDS: {
42
42
  'pre-compact': import("./verb-row.js").VerbSpec;
43
43
  'compact-resume': import("./verb-row.js").VerbSpec;
44
44
  'post-compact': import("./verb-row.js").VerbSpec;
45
+ 'note-written': import("./verb-row.js").VerbSpec;
46
+ '__note-import-worker': import("./verb-row.js").VerbSpec;
45
47
  'codex-run': import("./verb-row.js").VerbSpec;
46
48
  '__codex-session-end-worker': import("./verb-row.js").VerbSpec;
47
49
  hook: import("./verb-row.js").VerbSpec;
@@ -6,7 +6,7 @@ import { readJsonFile, tryReadJsonFile } from '../../host/json-file.js';
6
6
  import { errorFields, errorMessage, log } from '../../base/util/log.js';
7
7
  import { processHomes } from '../../host/agent-homes.js';
8
8
  import { canEditHooks, jsonHookPathsOn, planCopilotHooks, planHookRemoval, planJsonHooks, settingsText, } from './rules/json-hooks.js';
9
- import { defaultPreCompactLogPath, sleepLogPathOn } from './rules/shared.js';
9
+ import { defaultNoteWrittenLogPath, defaultPreCompactLogPath, sleepLogPathOn, } from './rules/shared.js';
10
10
  // What a caller of the installer names beside it: the reminder Codex needs before it runs a new hook.
11
11
  export { CODEX_TRUST_LINE } from './rules/shared.js';
12
12
  /** The paths for `target` under this process's home folder; reads and writes nothing. */
@@ -35,7 +35,7 @@ export function installJsonHooks(target) {
35
35
  fs.mkdirSync(dir, { recursive: true });
36
36
  const plan = target === 'copilot'
37
37
  ? planCopilotHooks(paths.settings, fs.existsSync(paths.settings) ? fs.readFileSync(paths.settings, 'utf8') : null)
38
- : planJsonHooks(target, paths, readSettings(paths.settings), defaultPreCompactLogPath(processHomes()));
38
+ : planJsonHooks(target, paths, readSettings(paths.settings), defaultPreCompactLogPath(processHomes()), defaultNoteWrittenLogPath(processHomes()));
39
39
  if (plan.write !== null)
40
40
  writeSettingsFile(paths.settings, plan.write);
41
41
  return plan.result;
@@ -1,12 +1,13 @@
1
1
  import { type JsonObject } from '../../../base/util/json.js';
2
2
  import { type HookInstallPlan } from './install-plan.js';
3
- /** Where Claude Code's settings live and where its session and compaction hooks log. */
3
+ /** Where Claude Code's settings live and where its session, compaction and note hooks log. */
4
4
  interface ClaudeHookPaths {
5
5
  readonly settingsPath: string;
6
6
  readonly logFile: string;
7
7
  readonly compactLog: string;
8
+ readonly noteLog: string;
8
9
  }
9
- export declare function planClaudeCodeHooks(settings: JsonObject, { settingsPath, logFile, compactLog }: ClaudeHookPaths): HookInstallPlan;
10
+ export declare function planClaudeCodeHooks(settings: JsonObject, { settingsPath, logFile, compactLog, noteLog }: ClaudeHookPaths): HookInstallPlan;
10
11
  /** The Claude Code handlers uninstall kept that still mention a hippo command (`nice hippo
11
12
  * sleep`, `pnpm exec hippo ...`), so the user can be told to remove them by hand. */
12
13
  export declare function keptHippoHandlers(hooks: JsonObject): string[];