hippo-memory 1.70.0 → 1.72.0

package/dist/hooks/json-hooks.js

@@ -1,41 +1,9 @@
-/**
- * Hook install/uninstall for AI coding tools.
- *
- * Two integration models live in this file:
- *
- * 1. JSON-hook install (Claude Code only). Writes a `hooks` block into the
- *    tool's settings.json with two entries:
- *      - SessionEnd: `hippo session-end --log-file <path>` - spawns a detached
- *        child that runs `hippo sleep` then `hippo capture --last-session` in
- *        sequence, writing both outputs to the log file. The parent returns in
- *        <100ms so the TUI teardown can't kill the child before it finishes.
- *      - SessionStart: `hippo last-sleep --path <path>` - prints the log
- *        written by the previous session's detached worker on stderr and
- *        clears it. Stdout carries only a `systemMessage` problems line,
- *        because Claude Code shows that to the user, not the model.
- *    Earlier Claude Code forms are detected and migrated automatically:
- *      - < 0.20.2: `Stop` hook firing `hippo sleep` on every assistant turn.
- *      - < 0.21.0: bare `hippo sleep` in SessionEnd, no `--log-file`.
- *      - 0.22.x: separate sleep + capture SessionEnd entries.
- *    PreCompact and PostCompact entries go in too: the first records the compaction and
- *    asks the summariser for a "Memories for hippo" list, the second saves that list.
- *    Codex's hooks.json gets only two groups (per-prompt memory and
- *    compact-resume); see installCodexHooks. Copilot gets a file of its own; see installCopilotHooks.
- *
- * 2. Plugin install (OpenCode only). OpenCode does NOT share Claude Code's
- *    JSON-hook schema — its config has `additionalProperties: false` and no
- *    `hooks` key, so a JSON-hook install breaks opencode launch. Hippo
- *    installs a TypeScript plugin at
- *    `~/.config/opencode/plugins/hippo.ts` subscribing to opencode's
- *    `session.idle` (→ `hippo session-end`) and `session.created` (→
- *    `hippo last-sleep`) events. See OPENCODE_PLUGIN_SOURCE below for the
- *    plugin file content + design rationale; see installOpencodePlugin for
- *    the installer + the migration that removes any pre-existing broken
- *    `hooks` block from opencode.json.
- */
+/** Hook install/uninstall for AI coding tools. Claude Code gets a JSON `hooks` block in settings.json; older forms are migrated automatically.
+ * OpenCode rejects the JSON-hook schema (no `hooks` key), so it gets a TS plugin (OPENCODE_PLUGIN_SOURCE); see installCodexHooks, installCopilotHooks. */
 import * as fs from 'fs';
 import * as path from 'path';
-import { HIPPO_SLEEP_MARKER, HIPPO_LAST_SLEEP_MARKER, HIPPO_CAPTURE_MARKER, HIPPO_SESSION_END_MARKER, HIPPO_PINNED_INJECT_MARKER, HIPPO_PINNED_INJECT_COMMAND, HIPPO_PRE_COMPACT_MARKER, HIPPO_COMPACT_RESUME_MARKER, HIPPO_CAPTURE_ERROR_MARKER, HIPPO_POST_COMPACT_MARKER, homeDir, claudeConfigDir, codexHomeDir, copilotHooksFile, defaultPreCompactLogPath } from './shared.js';
+import { HIPPO_SLEEP_MARKER, HIPPO_LAST_SLEEP_MARKER, HIPPO_CAPTURE_MARKER, HIPPO_SESSION_END_MARKER, HIPPO_PINNED_INJECT_MARKER, HIPPO_PINNED_INJECT_COMMAND, HIPPO_PRE_COMPACT_MARKER, HIPPO_COMPACT_RESUME_MARKER, HIPPO_CAPTURE_ERROR_MARKER, HIPPO_POST_COMPACT_MARKER, copilotHooksFile, defaultPreCompactLogPath } from './shared.js';
+import { claudeConfigDir, codexHomeDir, homeDir } from '../util/agent-homes.js';
 import { isJsonString, readJsonFile, isJsonObjectLiteral } from '../util/json.js';
 import { escapeRegex } from '../util/escape.js';
 import { writeFileAtomic } from '../util/atomic-write.js';
@@ -66,7 +34,8 @@ export function resolveJsonHookPaths(target) {
 }
 // An unterminated quote runs to the end, as in a shell, which also keeps the scan linear.
 const QUOTED_SPAN = /'[^']*(?:'|$)|"(?:[^"\\]|\\[\s\S]?)*(?:"|$)/g;
-/** Hippo's command only at string start or after `(`, past env assignments and an install path, with quoted text ignored: `say hippo sleep`, `echo "a; hippo sleep"` and `./backup.sh && hippo sleep` stay a user's. */
+/** Hippo's command only at string start or after `(`, past env assignments and an install path, with quoted
+ * text ignored: `say hippo sleep`, `echo "a; hippo sleep"` and `./backup.sh && hippo sleep` stay a user's. */
 function isHippoCommand(command, marker) {
     const unquoted = command.replace(QUOTED_SPAN, '');
     return new RegExp(`(?:^|\\()\\s*(?:[A-Za-z_]\\w*=\\S*\\s+)*(?:[^\\s(]*[/\\\\])?${escapeRegex(marker)}(?![\\w.-])`).test(unquoted);
@@ -167,7 +136,8 @@ function nothingInstalled(target, settingsPath) {
 function codexCommandHook(command, timeout) {
     return { type: 'command', command, commandWindows: command.replace(/^hippo /, 'hippo.cmd '), timeout };
 }
-/** Assigns `settings.hooks = {}` when it is absent, then returns it if it is an object whose `events`, where present, are arrays; null when appending would overwrite anything else. */
+/** Assigns `settings.hooks = {}` when it is absent, then returns it if it is an object whose
+ * `events`, where present, are arrays; null when appending would overwrite anything else. */
 function ensureHooksObject(settings, events) {
     if (settings.hooks === undefined)
         settings.hooks = {};
@@ -310,27 +280,18 @@ const CLAUDE_APPENDED_EVENTS = CLAUDE_HOOK_MARKERS.map(([event]) => event).filte
 function appendSessionHooks(hooks, logFile) {
     const installedSessionEnd = appendHookIfMissing(hooks, 'SessionEnd', HIPPO_SESSION_END_MARKER, claudeCommandGroup(`hippo session-end --log-file "${logFile}"`, 5));
     const installedSessionStart = appendHookIfMissing(hooks, 'SessionStart', HIPPO_LAST_SLEEP_MARKER, claudeCommandGroup(`hippo last-sleep --path "${logFile}"`, 5));
-    // Mid-session pinned-rule re-injection: UserPromptSubmit runs every turn,
-    // so pinned memories stay in context even after the model would otherwise
-    // "forget" them in a long session. Include the fresh write tail so lessons
-    // saved earlier in the same session become visible on the next prompt even
-    // before the user pins them explicitly.
+    // Mid-session pinned-rule re-injection: UserPromptSubmit runs every turn, so pinned memories stay in context; the fresh write tail
+    // makes lessons saved earlier in the session visible on the next prompt even before they are pinned.
     const migratedPinnedInjectRecent = migratePinnedInjectRecentCommands(hooks.UserPromptSubmit);
     const installedUserPromptSubmit = appendHookIfMissing(hooks, 'UserPromptSubmit', HIPPO_PINNED_INJECT_MARKER, claudeCommandGroup(HIPPO_PINNED_INJECT_COMMAND, 5));
     return { installedSessionEnd, installedSessionStart, migratedPinnedInjectRecent, installedUserPromptSubmit };
 }
 function appendCompactionHooks(hooks) {
-    // PreCompact: fires on manual AND auto compaction (no matcher). Records the compaction, asks the
-    // summariser for a "Memories for hippo" list and saves a working-state snapshot before the summary drops detail.
-    // Exit-0 contract lives in the verb itself (src/capture.ts cmdPreCompact),
-    // not here — this is install-time wiring only.
+    // PreCompact: fires on manual AND auto compaction (no matcher); records it, asks the summariser for a "Memories for hippo" list and saves a snapshot.
+    // The exit-0 contract lives in the verb itself (cmdPreCompact, src/capture/compact.ts), not in this install-time wiring.
     const installedPreCompact = appendHookIfMissing(hooks, 'PreCompact', HIPPO_PRE_COMPACT_MARKER, claudeCommandGroup(`hippo pre-compact --log-file "${defaultPreCompactLogPath()}"`, 30));
-    // SessionStart(compact): a SECOND SessionStart entry alongside the
-    // un-matched last-sleep entry above. The matcher is an optimization, not
-    // a dependency — compact-resume itself checks payload.source too, so an
-    // older Claude Code that ignores the matcher just runs a silent no-op on
-    // normal starts. Marker check keys on the command string, so this stays
-    // idempotent alongside the sibling last-sleep entry.
+    // SessionStart(compact): a second SessionStart entry beside the unmatched last-sleep one. The matcher is an optimization, not a dependency:
+    // compact-resume checks payload.source itself, and the marker check keys on the command string, so this stays idempotent.
     const installedCompactResume = appendHookIfMissing(hooks, 'SessionStart', HIPPO_COMPACT_RESUME_MARKER, claudeCommandGroup('hippo compact-resume', 10, 'compact'));
     // PostCompact: saves the memories the summariser listed and prints one line, which Claude Code only shows.
     // PreCompact stdout, by contrast, is handed to the summariser as instructions, so pre-compact prints just the request.
@@ -346,9 +307,8 @@ function installClaudeCodeHooks(settingsPath, settings, logFile) {
     const migration = migrateLegacyClaudeHooks(hooks);
     const { installedSessionEnd, installedSessionStart, migratedPinnedInjectRecent, installedUserPromptSubmit } = appendSessionHooks(hooks, logFile);
     const { installedPreCompact, installedCompactResume, installedPostCompact } = appendCompactionHooks(hooks);
-    // PostToolUseFailure: a failed tool call becomes an error memory, after
-    // `hippo capture-error` drops routine failures (interrupts, declined
-    // permissions, empty searches) and repeats. Same hook the plugin ships.
+    // PostToolUseFailure: a failed tool call becomes an error memory, after `hippo capture-error` drops routine failures
+    // (interrupts, declined permissions, empty searches) and repeats. Same hook the plugin ships.
     const installedCaptureError = appendHookIfMissing(hooks, 'PostToolUseFailure', HIPPO_CAPTURE_ERROR_MARKER, claudeCommandGroup('hippo capture-error', 10, '.*'));
     const result = {
         target: 'claude-code',
@@ -380,7 +340,8 @@ function uninstallCodexHooks(hooks) {
         changed = stripHandlers(hooks, event, (c) => c === command) || changed;
     return changed;
 }
-/** One stderr line naming the handlers uninstall kept that still mention a hippo command (`nice hippo sleep`, `pnpm exec hippo ...`), so the user can remove them by hand. */
+/** One stderr line naming the handlers uninstall kept that still mention a hippo command
+ * (`nice hippo sleep`, `pnpm exec hippo ...`), so the user can remove them by hand. */
 function warnKeptHippoHandlers(settingsPath, hooks) {
     const kept = CLAUDE_HOOK_MARKERS.flatMap(([event, markers]) => {
         const groups = hooks[event];
@@ -388,7 +349,8 @@ function warnKeptHippoHandlers(settingsPath, hooks) {
     });
     if (kept.length === 0)
         return;
-    process.stderr.write(`hippo kept these hook handlers in ${settingsPath} because they do not start with a hippo command; remove any that are hippo's by hand: ${kept.map((c) => JSON.stringify(c)).join(', ')}\n`);
+    process.stderr.write(`hippo kept these hook handlers in ${settingsPath} because they do not start with a hippo command; ` +
+        `remove any that are hippo's by hand: ${kept.map((c) => JSON.stringify(c)).join(', ')}\n`);
 }
 /** Removes hippo's own hook handlers from `target`'s settings file and keeps every other handler; true when the file changed. */
 export function uninstallJsonHooks(target) {
@@ -421,7 +383,8 @@ export function uninstallJsonHooks(target) {
     writeSettingsFile(settingsPath, settings);
     return true;
 }
-/** Whether uninstall can edit settings.json; `invalidJson` marks a file that exists but is not JSON hippo can edit, which `uninstallJsonHooks` reports only as false. */
+/** Whether uninstall can edit settings.json; `invalidJson` marks a file that exists
+ * but is not JSON hippo can edit, which `uninstallJsonHooks` reports only as false. */
 export function checkUninstallable(target) {
     const { settings: settingsPath } = resolveJsonHookPaths(target);
     if (!fs.existsSync(settingsPath))

package/dist/hooks/opencode.d.ts

@@ -1,42 +1,4 @@
 declare const HIPPO_OPENCODE_PLUGIN_MARKER = "HIPPO_OPENCODE_PLUGIN_V1";
-/**
- * The opencode plugin file we install at ~/.config/opencode/plugins/hippo.ts.
- *
- * Per https://opencode.ai/docs/plugins/, plugins are TS/JS modules exporting an
- * async function returning hooks. We subscribe to `event` and route:
- *   session.idle    → `hippo session-end` (Claude Code's SessionEnd equiv)
- *   session.created → `hippo last-sleep` (Claude Code's SessionStart equiv)
- *
- * Design choices:
- *
- * 1. No `import type { Plugin } from "@opencode-ai/plugin"`. The package's npm
- *    publication status was unverifiable from the build sandbox (npmjs.com
- *    returned 403); an unresolved type-only import would still crash the TS
- *    runtime opencode uses to load the plugin. opencode infers plugin shape
- *    from the returned object, so the type was convenience-only.
- *
- * 2. Defensive `typeof $ !== 'function'` guard. opencode runs in Bun (where
- *    `$` is the shell-template helper), but a future Node-mode deployment
- *    would have `$` undefined in the destructured context and the plugin
- *    would throw on every session.idle, killing opencode sessions in a
- *    hard-to-recover way (the idempotence marker prevents auto-reinstall).
- *    Fail closed, let opencode continue.
- *
- * 3. `.quiet().nothrow()` on each `$\`...\`` so a missing hippo binary
- *    (e.g. PATH-misconfigured user) does NOT throw out of the event handler.
- *    The surrounding try/catch is belt-and-braces.
- *
- * 4. UserPromptSubmit equivalent NOT wired. opencode's `message.updated`
- *    fires per-token, not per-prompt-submit; no clean per-prompt event.
- *    Users wanting pinned-context auto-injection can call `hippo context`
- *    via the MCP server (`hippo mcp`).
- *
- * 5. Versioned marker `HIPPO_OPENCODE_PLUGIN_V1` allows future versions to
- *    overwrite cleanly. The installer's idempotence check requires BOTH
- *    marker match AND content equality, so a plugin-source revision under
- *    the same V1 marker re-writes the file on next install.
- */
-export declare const OPENCODE_PLUGIN_SOURCE = "// HIPPO_OPENCODE_PLUGIN_V1\n// hippo-memory opencode plugin. DO NOT EDIT \u2014 regenerated on every\n// `hippo hook install opencode` from src/hooks.ts OPENCODE_PLUGIN_SOURCE\n// in https://github.com/kitfunso/hippo-memory. Local changes will be lost.\n\nexport const HippoPlugin = async ({ $ }) => {\n  return {\n    event: async ({ event }) => {\n      // Defense in depth: opencode currently runs in Bun where $ is the shell\n      // template helper. A non-Bun runtime would have $ as undefined; fail\n      // closed instead of crashing the host session.\n      if (typeof $ !== \"function\") return;\n      try {\n        if (event.type === \"session.idle\") {\n          await $`hippo session-end`.quiet().nothrow();\n        } else if (event.type === \"session.created\") {\n          await $`hippo last-sleep`.quiet().nothrow();\n        }\n      } catch {\n        // hippo CLI not on PATH or other failure \u2014 never crash the host session.\n      }\n    },\n  };\n};\n";
 export { HIPPO_OPENCODE_PLUGIN_MARKER };
 export interface OpencodePluginInstallResult {
     installed: boolean;

package/dist/hooks/opencode.js

@@ -1,47 +1,12 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { homeDir } from './shared.js';
+import { homeDir } from '../util/agent-homes.js';
 import { writeFileAtomic } from '../util/atomic-write.js';
 import { isJsonString, isJsonObjectLiteral } from '../util/json.js';
 const HIPPO_OPENCODE_PLUGIN_MARKER = 'HIPPO_OPENCODE_PLUGIN_V1';
-/**
- * The opencode plugin file we install at ~/.config/opencode/plugins/hippo.ts.
- *
- * Per https://opencode.ai/docs/plugins/, plugins are TS/JS modules exporting an
- * async function returning hooks. We subscribe to `event` and route:
- *   session.idle    → `hippo session-end` (Claude Code's SessionEnd equiv)
- *   session.created → `hippo last-sleep` (Claude Code's SessionStart equiv)
- *
- * Design choices:
- *
- * 1. No `import type { Plugin } from "@opencode-ai/plugin"`. The package's npm
- *    publication status was unverifiable from the build sandbox (npmjs.com
- *    returned 403); an unresolved type-only import would still crash the TS
- *    runtime opencode uses to load the plugin. opencode infers plugin shape
- *    from the returned object, so the type was convenience-only.
- *
- * 2. Defensive `typeof $ !== 'function'` guard. opencode runs in Bun (where
- *    `$` is the shell-template helper), but a future Node-mode deployment
- *    would have `$` undefined in the destructured context and the plugin
- *    would throw on every session.idle, killing opencode sessions in a
- *    hard-to-recover way (the idempotence marker prevents auto-reinstall).
- *    Fail closed, let opencode continue.
- *
- * 3. `.quiet().nothrow()` on each `$\`...\`` so a missing hippo binary
- *    (e.g. PATH-misconfigured user) does NOT throw out of the event handler.
- *    The surrounding try/catch is belt-and-braces.
- *
- * 4. UserPromptSubmit equivalent NOT wired. opencode's `message.updated`
- *    fires per-token, not per-prompt-submit; no clean per-prompt event.
- *    Users wanting pinned-context auto-injection can call `hippo context`
- *    via the MCP server (`hippo mcp`).
- *
- * 5. Versioned marker `HIPPO_OPENCODE_PLUGIN_V1` allows future versions to
- *    overwrite cleanly. The installer's idempotence check requires BOTH
- *    marker match AND content equality, so a plugin-source revision under
- *    the same V1 marker re-writes the file on next install.
- */
-export const OPENCODE_PLUGIN_SOURCE = `// ${HIPPO_OPENCODE_PLUGIN_MARKER}
+/** The opencode plugin installed at ~/.config/opencode/plugins/hippo.ts: session.idle runs `hippo session-end`, session.created runs `hippo last-sleep`.
+ * No `@opencode-ai/plugin` type import (unresolved, it would crash the loader); `$` is guarded and `.nothrow()` keeps a missing hippo binary from throwing. */
+const OPENCODE_PLUGIN_SOURCE = `// ${HIPPO_OPENCODE_PLUGIN_MARKER}
 // hippo-memory opencode plugin. DO NOT EDIT — regenerated on every
 // \`hippo hook install opencode\` from src/hooks.ts OPENCODE_PLUGIN_SOURCE
 // in https://github.com/kitfunso/hippo-memory. Local changes will be lost.
@@ -55,12 +20,15 @@ export const HippoPlugin = async ({ $ }) => {
       if (typeof $ !== "function") return;
       try {
         if (event.type === "session.idle") {
-          await $\`hippo session-end\`.quiet().nothrow();
+          const r = await $\`hippo session-end\`.quiet().nothrow();
+          if (r && r.exitCode !== 0) console.error("[hippo] session-end exited " + r.exitCode);
         } else if (event.type === "session.created") {
-          await $\`hippo last-sleep\`.quiet().nothrow();
+          const r = await $\`hippo last-sleep\`.quiet().nothrow();
+          if (r && r.exitCode !== 0) console.error("[hippo] last-sleep exited " + r.exitCode);
         }
-      } catch {
-        // hippo CLI not on PATH or other failure — never crash the host session.
+      } catch (err) {
+        // hippo CLI not on PATH or other failure: never crash the host session.
+        console.error("[hippo] plugin hook failed: " + (err && err.message ? err.message : err));
       }
     },
   };
@@ -73,23 +41,8 @@ export function resolveOpencodePluginPath() {
 function resolveOpencodeConfigPath() {
     return path.join(homeDir(), '.config', 'opencode', 'opencode.json');
 }
-/**
- * Return true iff a single hook-array entry's command string starts with
- * `hippo ` (the verb-prefix). Used to surgically remove only hippo-owned
- * commands when migrating an opencode.json. We own the install side, so only
- * the canonical `hippo <verb>` form needs to match — and only canonical verbs
- * hippo itself installs (session-end, last-sleep, sleep, capture, context),
- * not any third-party tool that happens to be named `hippo`.
- *
- * Structural check: substring matching against
- * arbitrary user content is unsafe — a user's
- * `echo "remember to hippo sleep your laptop"` is not a hippo-owned hook.
- *
- * Per-hook (not per-entry) granularity: an entry whose inner
- * hooks array mixes hippo-installed commands with user-authored commands
- * must NOT lose the user-authored commands. The migration filters the inner
- * array per-hook, then drops the entry only when its inner array is empty.
- */
+/** True iff a hook entry's command starts with `hippo ` plus a verb hippo itself installs (session-end, last-sleep, sleep, capture, context).
+ * Structural, not substring (`echo "remember to hippo sleep"` is not ours), and per hook so user-authored hooks in the same entry survive. */
 const HIPPO_OWNED_COMMAND_RE = /^\s*hippo\s+(session-end|last-sleep|sleep|capture|context)(?=\s|$)/;
 function hookIsHippoOwned(hook) {
     if (!isJsonObjectLiteral(hook))
@@ -97,23 +50,8 @@ function hookIsHippoOwned(hook) {
     const cmd = hook.command;
     return isJsonString(cmd) && HIPPO_OWNED_COMMAND_RE.test(cmd);
 }
-/**
- * Structurally strip every hippo-owned hook from opencode.json's hooks key.
- * Returns one of:
- *   { migrated: true,  jsonRepairFailed: false } — at least one hook removed.
- *   { migrated: false, jsonRepairFailed: false } — file fine, nothing to do.
- *   { migrated: false, jsonRepairFailed: true  } — file present but unparseable.
- *
- * Per-hook surgery:
- *   - For each entry in each event-key array, filter the inner `hooks` array
- *     to remove hippo-owned hooks only. User-authored hooks in the same
- *     inner array are preserved.
- *   - When an entry's inner `hooks` array becomes empty, that entry is
- *     removed from the outer array.
- *   - When an event-key array becomes empty, the key is deleted.
- *   - When the top-level `hooks` object becomes empty, it is deleted.
- *   - Other keys (theme, etc.) are always preserved.
- */
+/** Strip every hippo-owned hook from opencode.json's `hooks` key, deleting entries, keys and the object as they empty; user-authored hooks and other keys stay.
+ * Returns `{ migrated, jsonRepairFailed }`; jsonRepairFailed means the file is present but unparseable. */
 function migrateLegacyOpencodeHooksBlock() {
     const configPath = resolveOpencodeConfigPath();
     if (!fs.existsSync(configPath))
@@ -180,10 +118,8 @@ function stripHippoHooksFromEntries(entries) {
 export function installOpencodePlugin() {
     const pluginPath = resolveOpencodePluginPath();
     const { migrated, jsonRepairFailed } = migrateLegacyOpencodeHooksBlock();
-    // Idempotence: skip the write only if BOTH the marker is present AND the
-    // content matches the current source. Marker-only matches (with stale
-    // content) overwrite cleanly so future plugin-source patches reach
-    // existing installs.
+    // Skip the write only if BOTH the marker is present and the content matches; a marker-only match with stale
+    // content is rewritten so plugin-source patches reach existing installs.
     if (fs.existsSync(pluginPath)) {
         const existing = fs.readFileSync(pluginPath, 'utf8');
         if (existing.includes(HIPPO_OPENCODE_PLUGIN_MARKER) && existing === OPENCODE_PLUGIN_SOURCE) {

package/dist/hooks/shared.d.ts

@@ -17,13 +17,9 @@ export declare const HIPPO_PRE_COMPACT_MARKER = "hippo pre-compact";
 export declare const HIPPO_COMPACT_RESUME_MARKER = "hippo compact-resume";
 export declare const HIPPO_CAPTURE_ERROR_MARKER = "hippo capture-error";
 export declare const HIPPO_POST_COMPACT_MARKER = "hippo post-compact";
-export declare function homeDir(): string;
-/** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
-export declare function codexHomeDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
-/** Copilot's config folder: $COPILOT_HOME, else ~/.copilot under os.homedir(), as the Copilot apps resolve it (a HOME that differs from the profile must not move it). */
+/** Copilot's config folder: $COPILOT_HOME, else ~/.copilot under os.homedir(), as the
+ * Copilot apps resolve it (a HOME that differs from the profile must not move it). */
 export declare function copilotHomeDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
-/** Claude Code's config folder, where it reads settings.json: $CLAUDE_CONFIG_DIR when set and non-empty, else ~/.claude under os.homedir(), as Claude Code does (a HOME that differs from the profile must not move it). */
-export declare function claudeConfigDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
 /** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
 export declare function isCodexPresent(home?: string): boolean;
 /** hippo's own hooks file, in the hooks folder the Copilot CLI reads. */
@@ -36,23 +32,12 @@ export declare function vscodeUserDirs(env?: Readonly<Record<string, string | un
 export declare function isCopilotPresent(home?: string): boolean;
 /** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */
 export declare const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus up to 5 that match the prompt. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
-/**
- * Default log path consumed by `hippo last-sleep`. Shared fallback when
- * a caller doesn't pass --path explicitly.
- */
+/** Default log path consumed by `hippo last-sleep` when a caller passes no --path. */
 export declare function defaultSleepLogPath(): string;
-/**
- * Diagnostic-only log path for `hippo pre-compact`. Deliberately separate
- * from the SessionEnd sleep log: `hippo last-sleep` truncates that file on
- * every SessionStart, which would wipe pre-compact lines before anyone
- * could read them. Nothing consumes this file programmatically — it exists
- * for manual troubleshooting only. Overridden by `--log-file`.
- */
+/** Diagnostic-only log path for `hippo pre-compact`, kept apart from the SessionEnd sleep log because `hippo last-sleep` truncates that one every SessionStart.
+ * Nothing reads it programmatically; overridden by `--log-file`. */
 export declare function defaultPreCompactLogPath(): string;
 export declare function ensureDir(dir: string): void;
-/**
- * Detect which AI coding tools are installed based on config directory presence.
- * Used by `hippo setup` to decide which JSON-hook installs to run.
- */
+/** Detect which AI coding tools are installed from config directory presence; `hippo setup` uses it to pick JSON-hook installs. */
 export declare function detectInstalledTools(): ToolDetection[];
 //# sourceMappingURL=shared.d.ts.map

package/dist/hooks/shared.js

@@ -1,8 +1,8 @@
-import { envHomeDir, processEnv } from '../util/env.js';
+import { processEnv } from '../util/env.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { vscodeDataFolders } from '../agent-memories/copilot.js';
+import { claudeConfigDir, codexHomeDir, homeDir, vscodeDataFolders } from '../util/agent-homes.js';
 export const HIPPO_SLEEP_MARKER = 'hippo sleep';
 export const HIPPO_LAST_SLEEP_MARKER = 'hippo last-sleep';
 export const HIPPO_CAPTURE_MARKER = 'hippo capture --last-session';
@@ -14,21 +14,11 @@ export const HIPPO_PRE_COMPACT_MARKER = 'hippo pre-compact';
 export const HIPPO_COMPACT_RESUME_MARKER = 'hippo compact-resume';
 export const HIPPO_CAPTURE_ERROR_MARKER = 'hippo capture-error';
 export const HIPPO_POST_COMPACT_MARKER = 'hippo post-compact';
-export function homeDir() {
-    return envHomeDir() || os.homedir();
-}
-/** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
-export function codexHomeDir(home = homeDir(), env = processEnv()) {
-    return env.CODEX_HOME || path.join(home, '.codex');
-}
-/** Copilot's config folder: $COPILOT_HOME, else ~/.copilot under os.homedir(), as the Copilot apps resolve it (a HOME that differs from the profile must not move it). */
+/** Copilot's config folder: $COPILOT_HOME, else ~/.copilot under os.homedir(), as the
+ * Copilot apps resolve it (a HOME that differs from the profile must not move it). */
 export function copilotHomeDir(home = os.homedir(), env = processEnv()) {
     return env.COPILOT_HOME || path.join(home, '.copilot');
 }
-/** Claude Code's config folder, where it reads settings.json: $CLAUDE_CONFIG_DIR when set and non-empty, else ~/.claude under os.homedir(), as Claude Code does (a HOME that differs from the profile must not move it). */
-export function claudeConfigDir(home = os.homedir(), env = processEnv()) {
-    return env.CLAUDE_CONFIG_DIR || path.join(home, '.claude');
-}
 /** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
 export function isCodexPresent(home = homeDir()) {
     return fs.statSync(codexHomeDir(home), { throwIfNoEntry: false })?.isDirectory() === true;
@@ -53,20 +43,12 @@ export function isCopilotPresent(home = os.homedir()) {
 }
 /** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */
 export const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus up to 5 that match the prompt. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
-/**
- * Default log path consumed by `hippo last-sleep`. Shared fallback when
- * a caller doesn't pass --path explicitly.
- */
+/** Default log path consumed by `hippo last-sleep` when a caller passes no --path. */
 export function defaultSleepLogPath() {
     return path.join(homeDir(), '.hippo', 'logs', 'last-sleep.log');
 }
-/**
- * Diagnostic-only log path for `hippo pre-compact`. Deliberately separate
- * from the SessionEnd sleep log: `hippo last-sleep` truncates that file on
- * every SessionStart, which would wipe pre-compact lines before anyone
- * could read them. Nothing consumes this file programmatically — it exists
- * for manual troubleshooting only. Overridden by `--log-file`.
- */
+/** Diagnostic-only log path for `hippo pre-compact`, kept apart from the SessionEnd sleep log because `hippo last-sleep` truncates that one every SessionStart.
+ * Nothing reads it programmatically; overridden by `--log-file`. */
 export function defaultPreCompactLogPath() {
     return path.join(homeDir(), '.hippo', 'logs', 'pre-compact.log');
 }
@@ -74,21 +56,37 @@ export function ensureDir(dir) {
     if (!fs.existsSync(dir))
         fs.mkdirSync(dir, { recursive: true });
 }
-/**
- * Detect which AI coding tools are installed based on config directory presence.
- * Used by `hippo setup` to decide which JSON-hook installs to run.
- */
+/** Detect which AI coding tools are installed from config directory presence; `hippo setup` uses it to pick JSON-hook installs. */
 export function detectInstalledTools() {
     const home = homeDir();
     const exists = (...parts) => fs.existsSync(path.join(home, ...parts));
     const claudeDir = claudeConfigDir();
     return [
         { name: 'claude-code', configDir: claudeDir, detected: fs.existsSync(claudeDir), kind: 'json-hook' },
-        { name: 'opencode', configDir: '~/.config/opencode', detected: exists('.config', 'opencode'), kind: 'plugin', notes: 'installs a TS plugin at ~/.config/opencode/plugins/hippo.ts' },
+        {
+            name: 'opencode',
+            configDir: '~/.config/opencode',
+            detected: exists('.config', 'opencode'),
+            kind: 'plugin',
+            notes: 'installs a TS plugin at ~/.config/opencode/plugins/hippo.ts'
+        },
         { name: 'openclaw', configDir: '~/.openclaw', detected: exists('.openclaw'), kind: 'plugin', notes: 'install via `openclaw plugins install hippo-memory`' },
-        { name: 'codex', configDir: '~/.codex', detected: isCodexPresent(home), kind: 'wrapper', notes: 'memory hooks in hooks.json, and wraps the detected codex launcher for session-end consolidation' },
-        { name: 'copilot', configDir: copilotHomeDir(), detected: isCopilotPresent(), kind: 'json-hook', notes: 'hooks in hooks/hippo.json, the MCP server in mcp-config.json and a block in copilot-instructions.md; for VS Code, the server in each User mcp.json and prompts/hippo.instructions.md' },
-        { name: 'cursor', configDir: '~/.cursor', detected: exists('.cursor'), kind: 'markdown-instruction', notes: 'no hook API - patches AGENTS.md in the project' },
+        {
+            name: 'codex',
+            configDir: '~/.codex',
+            detected: isCodexPresent(home),
+            kind: 'wrapper',
+            notes: 'memory hooks in hooks.json, and wraps the detected codex launcher for session-end consolidation'
+        },
+        { name: 'copilot', configDir: copilotHomeDir(), detected: isCopilotPresent(), kind: 'json-hook', notes: 'hooks in hooks/hippo.json, the MCP server in ' +
+                'mcp-config.json and a block in copilot-instructions.md; for VS Code, the server in each User mcp.json and prompts/hippo.instructions.md' },
+        {
+            name: 'cursor',
+            configDir: '~/.cursor',
+            detected: exists('.cursor'),
+            kind: 'markdown-instruction',
+            notes: 'no hook API - patches AGENTS.md in the project'
+        },
         { name: 'pi', configDir: '~/.pi', detected: exists('.pi'), kind: 'markdown-instruction', notes: 'no hook API - patches AGENTS.md in the project' },
     ];
 }

package/dist/importers/core.d.ts

@@ -1,21 +1,12 @@
-/**
- * Memory importers for Hippo.
- * Imports memories from ChatGPT, Claude, Cursor, generic files, and structured markdown.
- */
+/** Memory importers for Hippo.
+ *  Imports memories from ChatGPT, Claude, Cursor, generic files, and structured markdown. */
 import { MemoryEntry } from '../core/memory.js';
 export interface ImportResult {
     total: number;
     imported: number;
     skipped: number;
-    /** AT1: refused by the rejection-value guard — kept distinct from
-     *  `skipped` (dedup) so a tombstoned value is distinguishable from a
-     *  plain duplicate in import summaries (plan §3 containment, round-2 low).
-     *  AT1 P2 fix (codex, published-surface compat): optional, not required —
-     *  `ImportResult` is re-exported from the package root (index.ts), and a
-     *  required field breaks any existing consumer constructing the pre-AT1
-     *  shape. Every producer in this file still always sets a real number;
-     *  `?? 0` at read sites (this file's own accumulation, cli.ts's summary
-     *  prints) tolerates a caller-supplied object that omits it. */
+    /** Entries refused by the rejection-value guard, kept apart from `skipped` (dedup) so a tombstoned value is distinguishable in summaries.
+     *  Optional because `ImportResult` is exported from the package root and a required field breaks existing consumers; read sites use `?? 0`. */
     rejected?: number;
     /** K1 vault import: rows archived this run (changed + source-deleted). In a
      *  dryRun this is the would-be count (a true deletion-sync preview). */
@@ -29,33 +20,17 @@ export interface ImportOptions {
     global?: boolean;
     extraTags?: string[];
     hippoRoot: string;
-    /**
-     * L9: tenant scope for the dedup read. When provided AND `global` is
-     * false, the dedup check only considers this tenant's existing entries.
-     * Ignored when `global: true` (global writes are host-wide by definition).
-     * Undefined preserves pre-1.12.1 host-wide dedup behaviour.
-     */
+    /** Tenant scope for the dedup read: when set and `global` is false, only this tenant's entries count.
+     *  Ignored when `global: true` (host-wide); undefined means host-wide dedup. */
     tenantId?: string;
-    /**
-     * K1 vault import only. Logical vault name used in the `vault:<name>` tag and
-     * the `artifactRef='vault:<name>:<relpath>'` key. REQUIRED by importVault: it
-     * is the identity key for the destructive source-deletion sync, so it must be
-     * set explicitly rather than inferred from the folder basename (two vaults
-     * sharing a basename would collide and clobber each other). importVault throws
-     * if it is missing or blank. Optional in this shared type only because the
-     * other importers ignore it. Operator-supplied, so the loader query LIKE-escapes
-     * it (`escapeLike` in src/util/escape.ts).
-     */
+    /** K1 vault import only: logical vault name for the `vault:<name>` tag and `artifactRef` key. REQUIRED by importVault (throws if missing or blank),
+     *  because it keys the destructive deletion sync and two vaults sharing a basename would clobber each other. LIKE-escaped by the loader. */
     name?: string;
-    /**
-     * K1 vault import only. Memory scope stamped on every imported note. Defaults
-     * to null (unscoped) when unset.
-     */
+    /** K1 vault import only. Memory scope stamped on every imported note. Defaults
+     *  to null (unscoped) when unset. */
     scope?: string;
 }
-/**
- * Given an array of raw text chunks, deduplicate against existing memories,
- * create MemoryEntry objects, write them (unless dry-run), and return a result.
- */
+/** Given an array of raw text chunks, deduplicate against existing memories,
+ *  create MemoryEntry objects, write them (unless dry-run), and return a result. */
 export declare function importEntries(chunks: string[], source: string, tags: string[], options: ImportOptions): ImportResult;
 //# sourceMappingURL=core.d.ts.map

package/dist/importers/core.js

@@ -1,25 +1,19 @@
-/**
- * Memory importers for Hippo.
- * Imports memories from ChatGPT, Claude, Cursor, generic files, and structured markdown.
- */
+/** Memory importers for Hippo.
+ *  Imports memories from ChatGPT, Claude, Cursor, generic files, and structured markdown. */
+import { DEFAULT_TENANT_ID } from '../util/env.js';
 import { createMemory, Layer } from '../core/memory.js';
 import { writeEntry } from '../store/entry-writes.js';
 import { loadAllEntries } from '../store/entry-reads.js';
 import { duplicateKey, storedTextKeys } from '../util/same-text.js';
-import { getGlobalRoot, initGlobal } from '../sharing/shared.js';
+import { getGlobalRoot, initGlobal } from '../sharing/global-store.js';
 import { withRequestStoresSync } from '../db/request-stores.js';
-import { RejectedValueError } from '../store/rejection.js';
+import { RejectedValueError } from '../core/api-errors.js';
 import { rejectionGuardRefuses } from '../store/rejected-values.js';
 import { loadConfig } from '../core/config.js';
 import { vetSecrets } from '../util/secret-detect.js';
 import { log } from '../util/log.js';
-// ---------------------------------------------------------------------------
-// Shared core: dedup + write
-// ---------------------------------------------------------------------------
-/**
- * Given an array of raw text chunks, deduplicate against existing memories,
- * create MemoryEntry objects, write them (unless dry-run), and return a result.
- */
+/** Given an array of raw text chunks, deduplicate against existing memories,
+ *  create MemoryEntry objects, write them (unless dry-run), and return a result. */
 export function importEntries(chunks, source, tags, options) {
     const { targetRoot, keys } = openImportTarget(options);
     const allTags = [...new Set([...tags, ...(options.extraTags ?? [])])];
@@ -87,17 +81,8 @@ function prepareImportChunk(raw, allTags) {
     return { chunk: trimmed.slice(0, 1000), wasRedacted };
 }
 function createImportEntry(chunk, source, allTags, options, baseHalfLifeDays) {
-    // A3: kind defaults to 'distilled'. ChatGPT/Claude/Cursor exports are curated
-    // user pastes, not raw transcripts from a system of record, so distilled is
-    // correct here. E1.3 (Slack ingestion) shipped 2026-04-29 in src/connectors/slack/
-    // and sets kind: 'raw' + routes deletions through archiveRawMemory() — these
-    // importers stay 'distilled' per the original reasoning. See MEMORY_ENVELOPE.md.
-    // L9: the dedup read above is scoped by options.tenantId — the WRITE
-    // must match, or scoped-dedup-passes-then-default-tenant-write breaks
-    // the per-tenant contract. Mirror the dedup-read guard: global=true
-    // → host-wide write to global store (tenantId irrelevant, createMemory
-    // defaults to 'default'). global=false → write to the same tenant as
-    // the dedup read.
+    // kind defaults to 'distilled': these exports are curated user pastes, not raw transcripts from a system of record (see MEMORY_ENVELOPE.md).
+    // The write must use the same tenant as the scoped dedup read above: global=true writes host-wide, global=false writes to options.tenantId.
     return createMemory(chunk, {
         layer: Layer.Episodic,
         tags: allTags,
@@ -110,7 +95,7 @@ function createImportEntry(chunk, source, allTags, options, baseHalfLifeDays) {
 /** Writes the entry, or on a dry run only probes the guard; false when a rejected value refuses it. */
 function writeOrProbeImport(targetRoot, entry, options) {
     if (options.dryRun)
-        return !rejectionGuardRefuses(targetRoot, entry.tenantId ?? 'default', entry.id, entry.content);
+        return !rejectionGuardRefuses(targetRoot, entry.tenantId ?? DEFAULT_TENANT_ID, entry.id, entry.content);
     // A rejection refuses one chunk, not the whole import, so siblings still land.
     try {
         writeEntry(targetRoot, entry);
@@ -122,7 +107,4 @@ function writeOrProbeImport(targetRoot, entry, options) {
     }
     return true;
 }
-// ---------------------------------------------------------------------------
-// ChatGPT importer
-// ---------------------------------------------------------------------------
 //# sourceMappingURL=core.js.map