hippo-memory 1.52.8 → 1.53.0

package/dist/hooks.js

@@ -16,6 +16,10 @@
  *      - < 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.
  *
  * 2. Plugin install (OpenCode only). OpenCode does NOT share Claude Code's
  *    JSON-hook schema — its config has `additionalProperties: false` and no
@@ -40,7 +44,7 @@ function isJsonString(value) {
 }
 /** JSON-value plain-object check (excludes arrays and null), typeof-free for the same
  *  reason as isJsonString above. */
-function isJsonObject(value) {
+export function isJsonObject(value) {
     return value !== undefined && value !== null && !Array.isArray(value) && value.constructor === Object;
 }
 const HIPPO_SLEEP_MARKER = 'hippo sleep';
@@ -121,6 +125,16 @@ export { HIPPO_OPENCODE_PLUGIN_MARKER };
 function homeDir() {
     return process.env.HOME || process.env.USERPROFILE || os.homedir();
 }
+/** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
+export function codexHomeDir(home = homeDir(), env = process.env) {
+    return env.CODEX_HOME || path.join(home, '.codex');
+}
+/** 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;
+}
+/** 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 the five most recent ones. 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.
@@ -506,6 +520,12 @@ export function resolveJsonHookPaths(target) {
                 logFile: path.join(logsDir, 'claude-code-sleep.log'),
                 display: 'Claude Code',
             };
+        case 'codex':
+            return {
+                settings: path.join(codexHomeDir(home), 'hooks.json'),
+                logFile: path.join(logsDir, 'codex-sleep.log'),
+                display: 'Codex',
+            };
     }
 }
 function hookArrayContains(hookArray, marker) {
@@ -560,6 +580,59 @@ function hasLegacySplitSessionEnd(hookArray) {
     const hasCapture = serialized.includes(HIPPO_CAPTURE_MARKER);
     return (hasSleep || hasCapture) && !serialized.includes(HIPPO_SESSION_END_MARKER);
 }
+function nothingInstalled(target, settingsPath) {
+    return {
+        target,
+        settingsPath,
+        installedSessionEnd: false,
+        installedSessionStart: false,
+        installedUserPromptSubmit: false,
+        installedPreCompact: false,
+        installedCompactResume: false,
+        installedPostCompact: false,
+        installedCaptureError: false,
+        migratedPinnedInjectRecent: false,
+        migratedFromStop: false,
+        migratedLegacySessionEnd: false,
+        migratedSplitSessionEnd: false,
+        invalidJson: false,
+    };
+}
+/** A command hook with a Windows form: Codex runs hooks in PowerShell there, whose execution policy can block npm's hippo.ps1. */
+function codexCommandHook(command, timeout) {
+    return { type: 'command', command, commandWindows: command.replace(/^hippo /, 'hippo.cmd '), timeout };
+}
+/** Codex keys trust to each hook's position and hash and re-asks for a changed one, so hippo only appends and never edits an entry. */
+function installCodexHooks(settingsPath, settings) {
+    const result = nothingInstalled('codex', settingsPath);
+    if (!isJsonObject(settings))
+        return { ...result, invalidJson: true };
+    if (settings.hooks === undefined)
+        settings.hooks = {};
+    const hooks = settings.hooks;
+    const events = ['UserPromptSubmit', 'SessionStart'];
+    if (!isJsonObject(hooks) || events.some((e) => hooks[e] !== undefined && !Array.isArray(hooks[e]))) {
+        return { ...result, invalidJson: true };
+    }
+    const append = (event, marker, group) => {
+        const groups = hooks[event];
+        if (hookArrayContains(groups, marker))
+            return false;
+        hooks[event] = [...(Array.isArray(groups) ? groups : []), group];
+        return true;
+    };
+    const installedUserPromptSubmit = append('UserPromptSubmit', HIPPO_PINNED_INJECT_MARKER, {
+        hooks: [codexCommandHook(HIPPO_PINNED_INJECT_COMMAND, 5)],
+    });
+    const installedCompactResume = append('SessionStart', HIPPO_COMPACT_RESUME_MARKER, {
+        matcher: 'compact',
+        hooks: [codexCommandHook(HIPPO_COMPACT_RESUME_MARKER, 10)],
+    });
+    if (installedUserPromptSubmit || installedCompactResume) {
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    }
+    return { ...result, installedUserPromptSubmit, installedCompactResume };
+}
 export function installJsonHooks(target) {
     const { settings: settingsPath, logFile } = resolveJsonHookPaths(target);
     const dir = path.dirname(settingsPath);
@@ -571,23 +644,11 @@ export function installJsonHooks(target) {
             settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
         }
         catch {
-            return {
-                target,
-                settingsPath,
-                installedSessionEnd: false,
-                installedSessionStart: false,
-                installedUserPromptSubmit: false,
-                installedPreCompact: false,
-                installedCompactResume: false,
-                installedPostCompact: false,
-                installedCaptureError: false,
-                migratedPinnedInjectRecent: false,
-                migratedFromStop: false,
-                migratedLegacySessionEnd: false,
-                migratedSplitSessionEnd: false,
-            };
+            return { ...nothingInstalled(target, settingsPath), invalidJson: true };
         }
     }
+    if (target === 'codex')
+        return installCodexHooks(settingsPath, settings);
     if (!settings.hooks)
         settings.hooks = {};
     // SAFETY: settings.hooks is either freshly initialised to {} on the line above, or an
@@ -672,8 +733,8 @@ export function installJsonHooks(target) {
         });
         installedUserPromptSubmit = true;
     }
-    // PreCompact: fires on manual AND auto compaction (no matcher). Writes a
-    // working-state snapshot before the transcript summary drops detail.
+    // 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.
     let installedPreCompact = false;
@@ -713,9 +774,8 @@ export function installJsonHooks(target) {
         });
         installedCompactResume = true;
     }
-    // PostCompact: tells the user what pre-compact saved. PreCompact itself
-    // must stay silent, because Claude Code hands PreCompact stdout to the
-    // summarising model as instructions; PostCompact stdout is only shown.
+    // 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.
     let installedPostCompact = false;
     if (!hookArrayContains(hooks.PostCompact, HIPPO_POST_COMPACT_MARKER)) {
         if (!Array.isArray(hooks.PostCompact))
@@ -777,8 +837,41 @@ export function installJsonHooks(target) {
         migratedFromStop,
         migratedLegacySessionEnd,
         migratedSplitSessionEnd,
+        invalidJson: false,
     };
 }
+/** The exact command hippo writes for each Codex event; uninstall removes only these handlers. */
+const CODEX_HOOK_COMMANDS = [
+    ['UserPromptSubmit', HIPPO_PINNED_INJECT_COMMAND],
+    ['SessionStart', HIPPO_COMPACT_RESUME_MARKER],
+];
+/** A group loses only hippo's handlers and goes only once empty, so a user's hook beside or like hippo's stays. */
+function uninstallCodexHooks(hooks) {
+    let changed = false;
+    for (const [event, command] of CODEX_HOOK_COMMANDS) {
+        const groups = hooks[event];
+        if (!Array.isArray(groups))
+            continue;
+        let removed = false;
+        const kept = groups.flatMap((group) => {
+            if (!isJsonObject(group) || !Array.isArray(group.hooks))
+                return [group];
+            const handlers = group.hooks.filter((h) => !(isJsonObject(h) && h.command === command));
+            if (handlers.length === group.hooks.length)
+                return [group];
+            removed = true;
+            return handlers.length > 0 ? [{ ...group, hooks: handlers }] : [];
+        });
+        if (!removed)
+            continue;
+        changed = true;
+        if (kept.length > 0)
+            hooks[event] = kept;
+        else
+            delete hooks[event];
+    }
+    return changed;
+}
 export function uninstallJsonHooks(target) {
     const { settings: settingsPath } = resolveJsonHookPaths(target);
     if (!fs.existsSync(settingsPath))
@@ -790,11 +883,19 @@ export function uninstallJsonHooks(target) {
     catch {
         return false;
     }
-    // SAFETY: Claude Code's settings.json always stores `hooks` as an object when
-    // present; each event key below is still re-validated with Array.isArray before use.
-    const hooks = settings.hooks;
-    if (!hooks)
+    if (!isJsonObject(settings) || !isJsonObject(settings.hooks))
+        return false;
+    const changed = target === 'codex' ? uninstallCodexHooks(settings.hooks) : uninstallClaudeCodeHooks(settings.hooks);
+    if (!changed)
         return false;
+    if (Object.keys(settings.hooks).length === 0)
+        delete settings.hooks;
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    return true;
+}
+function uninstallClaudeCodeHooks(settingsHooks) {
+    // SAFETY: each event key below is re-validated with Array.isArray before use.
+    const hooks = settingsHooks;
     let changed = false;
     const markersByKey = {
         SessionEnd: [HIPPO_SESSION_END_MARKER, HIPPO_SLEEP_MARKER, HIPPO_CAPTURE_MARKER],
@@ -819,12 +920,7 @@ export function uninstallJsonHooks(target) {
                 delete hooks[key];
         }
     }
-    if (!changed)
-        return false;
-    if (Object.keys(hooks).length === 0)
-        delete settings.hooks;
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
-    return true;
+    return changed;
 }
 export function resolveOpencodePluginPath() {
     return path.join(homeDir(), '.config', 'opencode', 'plugins', 'hippo.ts');
@@ -971,7 +1067,7 @@ export function detectInstalledTools() {
         { name: 'claude-code', configDir: '~/.claude', detected: exists('.claude'), 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: 'openclaw', configDir: '~/.openclaw', detected: exists('.openclaw'), kind: 'plugin', notes: 'install via `openclaw plugins install hippo-memory`' },
-        { name: 'codex', configDir: '~/.codex', detected: exists('.codex'), kind: 'wrapper', notes: 'wraps the detected codex launcher for session-end consolidation' },
+        { 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: '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.js

@@ -7,7 +7,7 @@ import * as path from 'path';
 import { createHash } from 'node:crypto';
 import { createMemory, Layer } from './memory.js';
 import { initStore, loadAllEntries, writeEntry } from './store.js';
-import { textOverlap } from './search.js';
+import { duplicateKey, storedTextKeys } from './same-text.js';
 import { getGlobalRoot, initGlobal } from './shared.js';
 import { remember, archiveRaw, isPrivateScope } from './api.js';
 import { openHippoDb, closeHippoDb } from './db.js';
@@ -26,7 +26,7 @@ export function importEntries(chunks, source, tags, options) {
     if (options.global) {
         initGlobal();
     }
-    const existing = loadAllEntries(targetRoot, options.global ? undefined : options.tenantId);
+    const keys = storedTextKeys(loadAllEntries(targetRoot, options.global ? undefined : options.tenantId));
     const allTags = [...new Set([...tags, ...(options.extraTags ?? [])])];
     const baseHalfLifeDays = loadConfig(targetRoot).defaultHalfLifeDays;
     let total = 0;
@@ -53,15 +53,8 @@ export function importEntries(chunks, source, tags, options) {
                 continue;
             }
             total++;
-            // Dedup check: textOverlap > 0.7 with any existing memory = skip
-            let isDuplicate = false;
-            for (const existing_entry of existing) {
-                if (textOverlap(chunk, existing_entry.content) > 0.7) {
-                    isDuplicate = true;
-                    break;
-                }
-            }
-            if (isDuplicate) {
+            // Dedup check: skip only when the same text is already stored
+            if (keys.has(duplicateKey(chunk))) {
                 skipped++;
                 continue;
             }
@@ -112,7 +105,7 @@ export function importEntries(chunks, source, tags, options) {
                     throw err;
                 }
                 // Add to existing so subsequent chunks dedup against freshly imported ones
-                existing.push(entry);
+                keys.add(duplicateKey(chunk));
             }
             entries.push(entry);
             imported++;

package/dist/judgment.d.ts

@@ -0,0 +1,30 @@
+/** Typed judgment over capture candidates via TypeSafe's Jev (System One).
+ *  Regex picks WHAT is a candidate; it cannot say what is worth keeping, so
+ *  every captured memory currently lands on a flat schema_fit of 0.5. */
+import { ConfidenceLevel, EmotionalValence } from './memory.js';
+export type JudgedKind = 'error' | 'decision' | 'convention' | 'preference' | 'trivia';
+export interface Judgment {
+    /** Jev noul, 0..1. Maps to `schema_fit` on the written entry. */
+    durable: number;
+    kind: JudgedKind;
+    valence: EmotionalValence;
+    confidence: ConfidenceLevel;
+    /** Jev's calibrated confidence on the kind choice, 0..1. */
+    kindConfidence: number;
+}
+export interface JudgeOptions {
+    apiKey: string;
+    model?: string;
+    /** Injected for testing — defaults to the real fetch. */
+    fetcher?: typeof fetch;
+    /** Bounded parallelism for `judgeAll`. */
+    concurrency?: number;
+}
+/** Absent key means hippo keeps its pre-Jev behaviour and makes no HTTP call. */
+export declare function judgmentApiKey(): string | undefined;
+/** `null` on any failure, so a Jev outage degrades capture to today's
+ *  behaviour instead of blocking the write. */
+export declare function judge(content: string, opts: JudgeOptions): Promise<Judgment | null>;
+/** Judge many candidates under a bounded concurrency pool, order preserved. */
+export declare function judgeAll(contents: readonly string[], opts: JudgeOptions): Promise<(Judgment | null)[]>;
+//# sourceMappingURL=judgment.d.ts.map

package/dist/judgment.js

@@ -0,0 +1,122 @@
+/** Typed judgment over capture candidates via TypeSafe's Jev (System One).
+ *  Regex picks WHAT is a candidate; it cannot say what is worth keeping, so
+ *  every captured memory currently lands on a flat schema_fit of 0.5. */
+const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
+const DEFAULT_MODEL = 'jev-1.13.0';
+const MAX_CONCURRENCY = 8;
+const RETRY_STATUS = new Set([429, 529]);
+const QUESTIONS = {
+    durable: {
+        type: 'noul',
+        instructions: 'This text was extracted from an AI coding agent transcript as a candidate memory. It is worth storing long-term only if it would still be useful to a future agent working on this codebase weeks from now: a durable preference, a convention, a decision with a reason, or a gotcha that will recur. Transient chatter, one-off status, restatements of code already in the repo, and anything only true inside this one session are not worth storing.',
+    },
+    kind: {
+        type: 'choice',
+        instructions: 'Classify what kind of durable knowledge this is.',
+        criteria: {
+            error: 'A failure, gotcha, or thing that went wrong, and why.',
+            decision: 'A choice that was made, ideally with its reason.',
+            convention: 'A rule, standard, or way this project does things.',
+            preference: 'A stated preference of the user or team.',
+            trivia: 'None of the above; incidental detail with no reuse value.',
+        },
+    },
+    valence: {
+        type: 'choice',
+        instructions: 'Classify the emotional charge of this memory for replay priority.',
+        criteria: {
+            critical: 'A costly failure or a rule whose violation causes real damage.',
+            negative: 'Something that went wrong, or a warning.',
+            positive: 'Something that worked, or a confirmed good approach.',
+            neutral: 'Plain fact with no success or failure charge.',
+        },
+    },
+};
+const KINDS = ['error', 'decision', 'convention', 'preference', 'trivia'];
+const VALENCES = ['critical', 'negative', 'positive', 'neutral'];
+/** Absent key means hippo keeps its pre-Jev behaviour and makes no HTTP call. */
+export function judgmentApiKey() {
+    const key = process.env.TYPESAFE_API_KEY?.trim();
+    return key ? key : undefined;
+}
+function oneOf(value, allowed) {
+    return allowed.find((option) => option === value) ?? null;
+}
+/** `verified` is unreachable: that tier means a human or a test confirmed it. */
+function toConfidenceTier(kindConfidence) {
+    if (kindConfidence >= 0.8)
+        return 'observed';
+    return 'inferred';
+}
+async function postOnce(content, opts) {
+    const fetchFn = opts.fetcher ?? fetch;
+    let res;
+    try {
+        res = await fetchFn(ENDPOINT, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${opts.apiKey}`,
+            },
+            body: JSON.stringify({
+                state: content,
+                model: opts.model ?? DEFAULT_MODEL,
+                questions: QUESTIONS,
+            }),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (RETRY_STATUS.has(res.status))
+        return { retryable: true };
+    if (!res.ok)
+        return null;
+    return { res };
+}
+/** `null` on any failure, so a Jev outage degrades capture to today's
+ *  behaviour instead of blocking the write. */
+export async function judge(content, opts) {
+    const trimmed = content.trim();
+    if (trimmed.length < 3)
+        return null;
+    let attempt = await postOnce(trimmed, opts);
+    if (attempt && 'retryable' in attempt) {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        attempt = await postOnce(trimmed, opts);
+    }
+    if (!attempt || 'retryable' in attempt)
+        return null;
+    let data;
+    try {
+        // SAFETY: the documented Jev response is `{ answers: { <name>: Answer } }`
+        // keyed by the question names posted above; every field read below is
+        // optional-chained and range-checked before use, so a lie here returns null.
+        data = await attempt.res.json();
+    }
+    catch {
+        return null;
+    }
+    const durable = data.answers?.durable?.noul;
+    const kind = oneOf(data.answers?.kind?.choice, KINDS);
+    const valence = oneOf(data.answers?.valence?.choice, VALENCES);
+    if (durable === undefined || durable < 0 || durable > 1 || !kind || !valence)
+        return null;
+    const kindConfidence = data.answers?.kind?.confidence ?? 0;
+    return { durable, kind, valence, confidence: toConfidenceTier(kindConfidence), kindConfidence };
+}
+/** Judge many candidates under a bounded concurrency pool, order preserved. */
+export async function judgeAll(contents, opts) {
+    const out = Array.from({ length: contents.length }, () => null);
+    const limit = Math.max(1, opts.concurrency ?? MAX_CONCURRENCY);
+    let cursor = 0;
+    const worker = async () => {
+        while (cursor < contents.length) {
+            const i = cursor++;
+            out[i] = await judge(contents[i], opts);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, contents.length) }, worker));
+    return out;
+}
+//# sourceMappingURL=judgment.js.map