hippo-memory 1.52.7 → 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/extensions/openclaw-plugin/index.js

@@ -172,6 +172,7 @@ function runHippo(args, cwd) {
             encoding: 'utf8',
             timeout: 30_000,
             stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
         });
         // `encoding: 'utf8'` above selects the ExecFileSyncOptionsWithStringEncoding
         // overload, so `result` is always a `string` here — no runtime check needed.

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

@@ -61,12 +61,9 @@ function loadByIdsChunked(root, tenantId, ids) {
     }
     return out;
 }
-/**
- * Traverse one store's graph from the seeds present in it and accumulate new graph hits
- * into `hitsByOrigin`. Mutates `seenMemoryIds` so a memory is surfaced at most once across
- * stores. Pure reads.
- */
-function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds, hitsByOrigin, opts) {
+/** Traverse one store's graph from its seeds into `hitsByOrigin`. Pure reads; mutates `seenMemoryIds`
+ *  and `seenContent` so a memory, or a share/promote copy of it, surfaces at most once across stores. */
+function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds, seenContent, hitsByOrigin, opts) {
     const { hops, maxNeighbors, tenantId, includeSuperseded, asOfDate, recallScope } = opts;
     // Seeds = graph entities (in THIS store) whose source memory is a base result.
     const seedEntities = loadEntitiesByMemoryId(root, tenantId, baseResults.map((r) => r.entry.id));
@@ -147,6 +144,8 @@ function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds,
             continue; // not found / wrong tenant / already in base
         if (seenMemoryIds.has(mem.id))
             continue; // another reached entity already added it
+        if (seenContent.has(mem.content))
+            continue; // share/promote copy: same text, another id
         const via = reached.get(ent.id);
         // A node reached as the `to` endpoint of a `supersedes` edge IS the superseded
         // (older) version — the graph is the authoritative signal (the memory mirror's
@@ -175,6 +174,7 @@ function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds,
         const origin = originMemByEntityId.get(ent.id) ?? baseResults[0].entry.id;
         const originScore = baseScoreByMemId.get(origin) ?? baseResults[baseResults.length - 1].score;
         seenMemoryIds.add(mem.id);
+        seenContent.add(mem.content);
         const hit = {
             entry: mem,
             score: originScore * (1 - HOP_DISCOUNT * via.hops),
@@ -209,11 +209,12 @@ export function graphExpandRecall(baseResults, opts) {
     const recallScope = opts.recallScope ?? {};
     const baseScoreByMemId = new Map(baseResults.map((r) => [r.entry.id, r.score]));
     const seenMemoryIds = new Set(baseResults.map((r) => r.entry.id));
+    const seenContent = new Set(baseResults.map((r) => r.entry.content));
     const hitsByOrigin = new Map();
     // Expand against each distinct store the seeds may live in (local + global).
     const roots = globalRoot && globalRoot !== hippoRoot ? [hippoRoot, globalRoot] : [hippoRoot];
     for (const root of roots) {
-        produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds, hitsByOrigin, {
+        produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds, seenContent, hitsByOrigin, {
             hops, maxNeighbors, tenantId, includeSuperseded, asOfDate, recallScope,
         });
     }
@@ -246,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/handoff.d.ts

@@ -12,6 +12,8 @@ export interface HandoffEvidence {
     gitRef?: string | null;
     dirtyTree?: boolean | null;
     testStatus?: 'pass' | 'fail' | 'unknown' | null;
+    /** 'transcript' when hippo read the handoff off the session's transcript at session end; a later exit may replace it. */
+    derivedFrom?: 'transcript';
 }
 /** Narrows an unvalidated value (e.g. CLI input or event content) to a HandoffOutcome. */
 export declare function isHandoffOutcome(v: string | boolean | string[] | null | undefined): v is HandoffOutcome;

package/dist/hooks.d.ts

@@ -10,12 +10,14 @@
  *        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 and then clears it,
- *        so the user actually sees what was consolidated.
+ *        written by the previous session's detached worker to stderr, which
+ *        keeps it out of the model's context, and then clears it.
  *    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.
+ *    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;
@@ -60,7 +66,7 @@ export interface CodexWrapperMetadata {
     installedAt: string;
 }
 export interface EnsureCodexWrapperResult {
-    status: 'installed' | 'already-installed' | 'not-found';
+    status: 'installed' | 'already-installed' | 'not-found' | 'source-checkout';
     metadataPath?: string;
     realCodexPath?: string;
     commandPath?: 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.
@@ -172,7 +186,7 @@ export declare function isCodexWrapperInstalled(): boolean;
  * doing it from postinstall or routine commands is a consent violation and
  * reads as binary hijacking to security scanners (issue #133).
  */
-export declare function repairCodexWrapperIfInstalled(): EnsureCodexWrapperResult;
+export declare function repairCodexWrapperIfInstalled(hippoCliPath?: string): EnsureCodexWrapperResult;
 export declare function resolveCodexSessionTranscript(options: CodexSessionTranscriptOptions): string | null;
 export declare function resolveJsonHookPaths(target: JsonHookTarget): JsonHookPaths;
 export declare function installJsonHooks(target: JsonHookTarget): InstallResult;