hippo-memory 1.52.8 → 1.52.9

package/dist/dedupe.js

@@ -1,6 +1,6 @@
 /**
- * Store-level deduplication. Scans for near-duplicate memories by content
- * Jaccard overlap, keeps the stronger copy (by strength + retrieval count),
+ * Store-level deduplication. Scans for memories with the same text apart
+ * from spacing, keeps the stronger copy (by strength + retrieval count),
  * removes the rest.
  *
  * Extracted from cli.ts in Episode A (v1.11.3) so `api.sleep` can dedupe
@@ -25,6 +25,7 @@ import { loadAllEntries, deleteEntry } from './store.js';
 import { compareEntryIdentity } from './compare.js';
 import { canAutoDelete } from './memory.js';
 import { derivationPartitionKey } from './recall-scope.js';
+import { duplicateKey } from './same-text.js';
 /** Quantization step for strength-tie comparisons. The historical 0.01
  *  epsilon (see `strengthBucket` below) applied via rounding instead of a
  *  raw abs-diff threshold, so the tiebreak is transitive. */
@@ -55,16 +56,15 @@ export function strengthBucket(strength) {
     return Number.isFinite(s) ? Math.round(s / STRENGTH_TIE_EPSILON) : 0;
 }
 /**
- * Scan the store for near-duplicate memories and remove the weaker copy.
- * Two memories are duplicates if their content has > threshold Jaccard
- * overlap AND they belong to the same tenant: the scan is partitioned by
+ * Scan the store for duplicates and remove the weaker copy: same text apart
+ * from spacing, since a near-duplicate can differ in a value (port, version,
+ * path, name), AND the same tenant: the scan is partitioned by
  * tenantId, so byte-identical content in two tenants is never a duplicate
  * pair (the tenant boundary is an isolation boundary; cross-tenant removal
  * was the v1.32.0 known-issue data-loss bug).
- * Keeps the one with higher strength (or more retrievals if tied).
+ * Keeps the one with higher strength (or more retrievals if tied). `threshold` is accepted for old callers and ignored.
  */
 export function deduplicateStore(hippoRoot, options = {}) {
-    const threshold = options.threshold ?? 0.7;
     const dryRun = options.dryRun ?? false;
     // Only current distilled rows compete: raw rows are append-only (the delete
     // trigger would abort sleep mid-loop) and superseded rows are history, as in consolidate.ts.
@@ -111,15 +111,16 @@ export function deduplicateStore(hippoRoot, options = {}) {
                 return retrievalDiff;
             return compareEntryIdentity(a, b);
         });
+        const texts = tenantEntries.map((e) => duplicateKey(e.content));
         for (let i = 0; i < tenantEntries.length; i++) {
             if (removed.has(tenantEntries[i].id))
                 continue;
             for (let j = i + 1; j < tenantEntries.length; j++) {
                 if (removed.has(tenantEntries[j].id) || !canAutoDelete(tenantEntries[j]))
                     continue;
-                const similarity = textOverlap(tenantEntries[i].content, tenantEntries[j].content);
-                if (similarity <= threshold)
+                if (texts[j] !== texts[i])
                     continue;
+                const similarity = textOverlap(tenantEntries[i].content, tenantEntries[j].content);
                 removed.add(tenantEntries[j].id);
                 pairs.push({
                     kept: tenantEntries[i].id,

package/dist/doctor.d.ts

@@ -19,7 +19,7 @@ export interface DoctorReport {
 /** Inputs for {@link runDoctor}; defaults come from the process. */
 export interface DoctorOpts {
     cwd?: string;
-    /** Home directory used to find agent configuration (~/.claude). */
+    /** Home directory used to find agent configuration (~/.claude, ~/.codex). */
     home?: string;
     version: string;
     nodeVersion?: string;

package/dist/doctor.js

@@ -12,6 +12,7 @@ import { getGlobalRoot } from './shared.js';
 import { isInitialized } from './store.js';
 import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getCurrentSchemaVersion, countTableRows, IncompatibleBinaryError } from './db.js';
 import { isEmbeddingAvailable } from './embeddings.js';
+import { CODEX_TRUST_LINE, codexHomeDir, isCodexPresent, isJsonObject } from './hooks.js';
 /** Minimum Node.js version hippo supports (package.json engines). */
 export const MIN_NODE = '22.16.0';
 function versionAtLeast(actual, min) {
@@ -34,6 +35,29 @@ function readJson(file) {
         return null;
     }
 }
+// Trust lives in Codex's own config.toml rows; doctor reads only the hooks file and reminds.
+function codexCheck(home) {
+    const file = path.join(codexHomeDir(home), 'hooks.json');
+    const parsed = readJson(file);
+    // Codex drops every hook in a hooks.json it cannot parse, hippo's included.
+    if (fs.existsSync(file) && !isJsonObject(parsed)) {
+        return { id: 'codex', status: 'warn', detail: "Codex's hooks.json is not a JSON object, so Codex runs no hook from it", fix: 'repair hooks.json, then run: hippo hook install codex' };
+    }
+    const text = JSON.stringify(parsed ?? '');
+    const codexHooks = [
+        ['hippo context --pinned-only', 'per-prompt memory'],
+        ['hippo compact-resume', 'resume after compaction'],
+    ];
+    const missing = codexHooks.filter(([marker]) => !text.includes(marker)).map(([, what]) => what);
+    if (missing.length === 0)
+        return { id: 'codex', status: 'pass', detail: `Codex: hippo memory hooks installed. ${CODEX_TRUST_LINE}` };
+    return {
+        id: 'codex',
+        status: 'warn',
+        detail: missing.length === codexHooks.length ? "Codex found, but hippo's memory hooks are not installed" : `Codex: hippo hooks missing for ${missing.join(', ')}`,
+        fix: 'hippo hook install codex   (then trust the hooks once in /hooks)',
+    };
+}
 // Migration 46 creates failure_log; a read-only open no longer creates it on an older store.
 const FAILURE_LOG_SCHEMA = 46;
 /** The failed-tool-call count over the last 7 days, or why it could not be read. */
@@ -123,8 +147,15 @@ export function runDoctor(opts) {
             const since = new Date(now.getTime() - 7 * 86_400_000).toISOString();
             try {
                 // SAFETY: COUNT/SUM aggregate row.
-                const row = db.prepare(`SELECT COUNT(*) AS n, COALESCE(SUM(tokens), 0) AS t FROM token_ledger WHERE ts >= ? AND event = 'inject'`).get(since);
-                checks.push({ id: 'tokens', status: 'info', detail: `${Number(row?.n ?? 0)} memory blocks sent to agents in 7 days, about ${Number(row?.t ?? 0)} tokens (hippo tokens for detail)` });
+                const row = db.prepare(`SELECT COUNT(CASE WHEN event = 'inject' THEN 1 END) AS n,
+                  COALESCE(SUM(CASE WHEN event = 'inject' THEN tokens END), 0) AS t,
+                  COALESCE(SUM(CASE WHEN event = 'reread' THEN tokens END), 0) AS r
+           FROM token_ledger WHERE ts >= ?`).get(since);
+                checks.push({
+                    id: 'tokens',
+                    status: 'info',
+                    detail: `${Number(row?.n ?? 0)} memory blocks sent to agents in 7 days, about ${Number(row?.t ?? 0)} tokens sent and ${Number(row?.r ?? 0)} re-read by later model calls (hippo tokens for detail)`,
+                });
             }
             catch {
                 checks.push({ id: 'tokens', status: 'info', detail: 'no token ledger yet (created on the next write)' });
@@ -176,6 +207,8 @@ export function runDoctor(opts) {
     else {
         checks.push({ id: 'claude-code', status: 'info', detail: 'Claude Code not found; other agents can use hippo over MCP (hippo mcp)' });
     }
+    if (isCodexPresent(home))
+        checks.push(codexCheck(home));
     checks.push({ id: 'embeddings', status: 'info', detail: isEmbeddingAvailable() ? 'local embeddings available (hybrid search)' : 'embeddings not installed; recall uses BM25 (optional: hippo embed --help)' });
     return { ok: !checks.some((c) => c.status === 'fail'), version: opts.version, store, checks };
 }

package/dist/dormant.d.ts

@@ -71,6 +71,10 @@ export interface DormantSnapshot {
  * has no dormant memory with that id (another tenant's id reads as absent).
  */
 export declare function readDormantSnapshot(db: DatabaseSyncLike, tenantId: string, id: string): DormantSnapshot | null;
+/** Every dormant memory of a tenant whose snapshot still reads back. */
+export declare function listDormantSnapshots(db: DatabaseSyncLike, tenantId: string): DormantSnapshot[];
+/** Put `entry` in place of a tenant's dormant memory `id`, keeping when and why that one went dormant. */
+export declare function replaceDormantEntry(db: DatabaseSyncLike, tenantId: string, id: string, entry: MemoryEntry): void;
 /** Whether a tenant has a dormant memory with this id (snapshot readable or not). */
 export declare function hasDormantRow(db: DatabaseSyncLike, tenantId: string, id: string): boolean;
 /** Delete a tenant's dormant memory. Returns false when there was none. */

package/dist/dormant.js

@@ -74,8 +74,23 @@ export function readDormantSnapshot(db, tenantId, id) {
     // SAFETY: row's shape matches the seven columns named in the SELECT.
     const row = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
        FROM dormant_memories WHERE tenant_id = ? AND id = ?`).get(tenantId, id);
-    const entry = row ? parseSnapshot(row) : null;
-    return row && entry ? { entry, reason: row.reason, strength: row.strength, dormantAt: row.dormant_at } : null;
+    return row ? toSnapshot(row) : null;
+}
+/** Every dormant memory of a tenant whose snapshot still reads back. */
+export function listDormantSnapshots(db, tenantId) {
+    // SAFETY: rows' shape matches the seven columns named in the SELECT.
+    const rows = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
+       FROM dormant_memories WHERE tenant_id = ?`).all(tenantId);
+    return rows.flatMap((row) => toSnapshot(row) ?? []);
+}
+function toSnapshot(row) {
+    const entry = parseSnapshot(row);
+    return entry ? { entry, reason: row.reason, strength: row.strength, dormantAt: row.dormant_at } : null;
+}
+/** Put `entry` in place of a tenant's dormant memory `id`, keeping when and why that one went dormant. */
+export function replaceDormantEntry(db, tenantId, id, entry) {
+    db.prepare(`UPDATE dormant_memories SET id = ?, content = ?, entry_json = ? WHERE tenant_id = ? AND id = ?`)
+        .run(entry.id, entry.content, JSON.stringify(entry), tenantId, id);
 }
 /** Whether a tenant has a dormant memory with this id (snapshot readable or not). */
 export function hasDormantRow(db, tenantId, id) {

package/dist/embedding-provider.d.ts

@@ -19,7 +19,8 @@
  *   - API provider `id` is `${kind}:${model}`; switching to/from an API embedder
  *     (or a dimension change) flips the identity and triggers the existing
  *     reindex-on-change path.
- *   - `resolveEmbeddingProvider` NEVER throws. `isAvailable()` is provider-aware
+ *   - `resolveEmbeddingProvider` throws on an invalid config (unknown provider,
+ *     bad apiBaseUrl); `embedMemory` turns that into a warning. `isAvailable()` is provider-aware
  *     (local -> dependency installed; api -> key present). `embed()` MAY throw on
  *     a hard transport/auth failure so a reindex can abort atomically; hot paths
  *     wrap it and fall back to BM25.

package/dist/embedding-provider.js

@@ -19,7 +19,8 @@
  *   - API provider `id` is `${kind}:${model}`; switching to/from an API embedder
  *     (or a dimension change) flips the identity and triggers the existing
  *     reindex-on-change path.
- *   - `resolveEmbeddingProvider` NEVER throws. `isAvailable()` is provider-aware
+ *   - `resolveEmbeddingProvider` throws on an invalid config (unknown provider,
+ *     bad apiBaseUrl); `embedMemory` turns that into a warning. `isAvailable()` is provider-aware
  *     (local -> dependency installed; api -> key present). `embed()` MAY throw on
  *     a hard transport/auth failure so a reindex can abort atomically; hot paths
  *     wrap it and fall back to BM25.

package/dist/embeddings.js

@@ -12,6 +12,7 @@ import { openHippoDb, closeHippoDb, getMeta, setMeta } from './db.js';
 import { initializeParticle, savePhysicsState, loadPhysicsState, resetAllPhysicsState } from './physics-state.js';
 import { loadConfig } from './config.js';
 import { resolveEmbeddingProvider } from './embedding-provider.js';
+import { redactSecretsStrict } from './secret-detect.js';
 // Use createRequire for synchronous module resolution check in ESM
 const _require = createRequire(import.meta.url);
 // Cached availability check
@@ -460,11 +461,29 @@ async function withEmbedLock(hippoRoot, fn) {
         resolve();
     }
 }
+// A bad key fails every write; one warning tells the user, N would bury the command's own output.
+let _embedFailureWarned = false;
+function warnEmbedFailureOnce(source, rawMessage) {
+    if (_embedFailureWarned)
+        return;
+    _embedFailureWarned = true;
+    // Strict scrub: this line can land in a hook log file, and an API may echo the key back in its error body.
+    const message = redactSecretsStrict(rawMessage).replace(/\s+/g, ' ').replace(/\.+$/, '');
+    console.error(`hippo: embedding failed (${source}): ${message}. Memories are stored without embeddings until this is fixed.`);
+}
 /**
  * Embed a single memory entry and cache the result in the embedding index.
  */
 export async function embedMemory(hippoRoot, entry, model) {
-    const provider = resolveEmbeddingProvider(hippoRoot, { model });
+    let provider;
+    try {
+        provider = resolveEmbeddingProvider(hippoRoot, { model });
+    }
+    catch (err) {
+        // Callers fire and forget, so this must resolve: a bad config warns once instead of rejecting.
+        warnEmbedFailureOnce('config', err instanceof Error ? err.message : String(err));
+        return;
+    }
     if (!provider.isAvailable())
         return;
     return withEmbedLock(hippoRoot, async () => {
@@ -513,8 +532,9 @@ export async function embedMemory(hippoRoot, entry, model) {
                 // Physics init is best-effort — don't break embedding
             }
         }
-        catch {
-            // Provider failure (API down / bad key). Best-effort: leave the index as-is.
+        catch (err) {
+            // Provider failure (API down / bad key). Best-effort: leave the index as-is, but say so once.
+            warnEmbedFailureOnce(provider.kind, err instanceof Error ? err.message : String(err));
         }
     }).catch((err) => {
         console.error(`hippo: skipped embedding ${entry.id} (${err instanceof Error ? err.message : String(err)}); run 'hippo embed' to backfill`);

package/dist/extract.js

@@ -3,6 +3,7 @@ import { writeEntry } from './store.js';
 import { loadConfig } from './config.js';
 import { RejectedValueError } from './rejection.js';
 import { redactSecrets } from './secret-detect.js';
+import { neverAutoShareTags } from './shared.js';
 function isJsonString(value) {
     return typeof value === 'string';
 }
@@ -81,7 +82,10 @@ export async function extractFacts(text, opts) {
 }
 const INHERITABLE_PREFIXES = ['conv:', 'session:', 'scope:', 'path:'];
 export function storeExtractedFacts(hippoRoot, source, facts) {
-    const inheritedTags = source.tags.filter((t) => INHERITABLE_PREFIXES.some((p) => t.startsWith(p)));
+    const inheritedTags = [
+        ...source.tags.filter((t) => INHERITABLE_PREFIXES.some((p) => t.startsWith(p))),
+        ...neverAutoShareTags([source]),
+    ];
     const entries = [];
     let rejected = 0;
     const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;

package/dist/forward-claim-detector.d.ts

@@ -11,7 +11,7 @@
  * Kahneman 2003 inside-vs-outside view).
  *
  * Iteration signal: the `recall_autodebias_hint_no_class_match` audit op
- * (emitted by computePlanningFallacyHint when a phrase matches but no class
+ * (emitted by computePlanningFallacyOutput when a phrase matches but no class
  * resolves) is the telemetry channel for deciding whether to add an
  * embedding-based detector in J3.3.
  *

package/dist/forward-claim-detector.js

@@ -11,7 +11,7 @@
  * Kahneman 2003 inside-vs-outside view).
  *
  * Iteration signal: the `recall_autodebias_hint_no_class_match` audit op
- * (emitted by computePlanningFallacyHint when a phrase matches but no class
+ * (emitted by computePlanningFallacyOutput when a phrase matches but no class
  * resolves) is the telemetry channel for deciding whether to add an
  * embedding-based detector in J3.3.
  *

package/dist/graph-recall.d.ts

@@ -1,4 +1,4 @@
-import { type SearchResult } from './search.js';
+import { type ResultCost, type SearchResult } from './search.js';
 /** Hard cap on `--hops` (a higher value just walks more of a finite graph; this bounds
  *  worst-case work and keeps the flag honest). */
 export declare const MAX_HOPS = 3;
@@ -23,6 +23,8 @@ export interface GraphExpandOpts {
     asOf?: string;
     /** Token budget for the augmented set (defaults to 4000, matching recall's default). */
     budget?: number;
+    /** Budget cost per result; defaults to the memory text. */
+    cost?: ResultCost;
     /** The recall --min-results floor: this many top base rows are kept regardless of
      *  budget, so graph expansion never violates the floor. Defaults to 1. */
     minResults?: number;

package/dist/graph-recall.js

@@ -247,15 +247,17 @@ export function graphExpandRecall(baseResults, opts) {
     // baseResults is score-ordered, so slice(0, N) is the top N.
     const protectedCount = Math.min(Math.max(minResults, 1), baseResults.length);
     const keep = new Set(baseResults.slice(0, protectedCount));
-    let usedTokens = [...keep].reduce((s, r) => s + r.tokens, 0);
+    const price = opts.cost ?? ((r) => r.tokens);
+    let usedTokens = [...keep].reduce((s, r) => s + price(r), 0);
     // T2 note: PLAIN stable score sort on purpose -- both input lists are
     // deterministically ordered by this point, stability inherits that, and a
     // base-vs-graph-hit tie keeps the BASE result first (the concat order),
     // preserving pre-T2 semantics.
     for (const r of [...baseResults.slice(protectedCount), ...allHits].sort((a, b) => b.score - a.score)) {
-        if (usedTokens + r.tokens > budget)
+        const tokens = price(r);
+        if (usedTokens + tokens > budget)
             continue;
-        usedTokens += r.tokens;
+        usedTokens += tokens;
         keep.add(r);
     }
     // DISPLAY order: base order preserved (it may be MMR-diversified); each kept new hit

package/dist/hooks.d.ts

@@ -16,6 +16,8 @@
  *      - < 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.
+ *    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
@@ -28,7 +30,11 @@
  *    the installer + the migration that removes any pre-existing broken
  *    `hooks` block from opencode.json.
  */
-export type JsonHookTarget = 'claude-code';
+import type { JsonValue, JsonObject } from './working-memory.js';
+/** JSON-value plain-object check (excludes arrays and null), typeof-free for the same
+ *  reason as isJsonString above. */
+export declare function isJsonObject(value: JsonValue | undefined): value is JsonObject;
+export type JsonHookTarget = 'claude-code' | 'codex';
 export interface CodexWrapperPaths {
     wrapperDir: string;
     metadataPath: string;
@@ -93,6 +99,8 @@ export interface InstallResult {
     migratedFromStop: boolean;
     migratedLegacySessionEnd: boolean;
     migratedSplitSessionEnd: boolean;
+    /** The file exists but is not JSON hippo can merge into, so it was left untouched. */
+    invalidJson: boolean;
 }
 export interface ToolDetection {
     name: string;
@@ -141,6 +149,12 @@ declare const HIPPO_OPENCODE_PLUGIN_MARKER = "HIPPO_OPENCODE_PLUGIN_V1";
  */
 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 };
+/** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
+export declare function codexHomeDir(home?: string): 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;
+/** 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 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.

package/dist/hooks.js

@@ -16,6 +16,8 @@
  *      - < 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.
+ *    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 +42,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 +123,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()) {
+    return process.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 +518,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 +578,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 +642,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
@@ -777,8 +836,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 +882,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 +919,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 +1066,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++;