hippo-memory 1.59.0 → 1.61.0

package/dist/graph-view.d.ts

@@ -7,7 +7,7 @@
  * stays green. Used by the CLI (`hippo graph show` / `hippo graph view`) and the
  * HTTP `GET /v1/graph` route, which all build the same `GraphModel`.
  */
-import { type EntityType, type RelationType } from './graph.js';
+import { type EntityType, type RelationType } from './graph/types.js';
 export interface GraphNode {
     id: number;
     type: EntityType;

package/dist/graph-view.js

@@ -7,7 +7,7 @@
  * stays green. Used by the CLI (`hippo graph show` / `hippo graph view`) and the
  * HTTP `GET /v1/graph` route, which all build the same `GraphModel`.
  */
-import { loadEntities, loadEntitiesByName, loadEntitiesByIds, loadRelations, loadNeighborRelations, loadRelationsAmong, withGraphReadSnapshot, } from './graph.js';
+import { loadEntities, loadEntitiesByName, loadEntitiesByIds, loadRelations, loadNeighborRelations, loadRelationsAmong, withGraphReadSnapshot, } from './graph/read.js';
 /** Default bound for the CLI viewer / show so an unbounded set is never laid out. */
 export const DEFAULT_VIEW_LIMIT = 500;
 /**

package/dist/half-life-migration.d.ts

@@ -21,7 +21,7 @@
  * moves memories of live decisions, incidents and other objects off the flat 90 days they used to get.
  */
 import { type MemoryEntry } from './memory.js';
-import { HALF_LIFE_BASE_META_KEY } from './store.js';
+import { HALF_LIFE_BASE_META_KEY } from './store/open.js';
 /** The base every store used before the base was recorded. */
 export declare const LEGACY_HALF_LIFE_BASE = 7;
 /** The flat half-life the decision, incident and other object writers gave their memories before they took the default. */

package/dist/half-life-migration.js

@@ -21,7 +21,8 @@
  * moves memories of live decisions, incidents and other objects off the flat 90 days they used to get.
  */
 import { deriveHalfLife } from './memory.js';
-import { openStore, selectAllEntries, HALF_LIFE_BASE_META_KEY, TYPED_HALF_LIFE_META_KEY } from './store.js';
+import { openStore, HALF_LIFE_BASE_META_KEY, TYPED_HALF_LIFE_META_KEY } from './store/open.js';
+import { selectAllEntries } from './store/entry-reads.js';
 import { openHippoDb, closeHippoDb, getMeta, setMeta } from './db.js';
 import { appendAuditEvent } from './audit.js';
 import { loadConfig } from './config.js';

package/dist/handoff.js

@@ -25,6 +25,7 @@ export function rowToSessionHandoff(row) {
         }
     }
     catch {
+        // A corrupt column degrades to empty instead of hiding the whole handoff.
         artifacts = [];
     }
     let constraints = [];
@@ -35,6 +36,7 @@ export function rowToSessionHandoff(row) {
         }
     }
     catch {
+        // Same degrade-to-empty rule as artifacts.
         constraints = [];
     }
     let evidence = null;
@@ -43,6 +45,7 @@ export function rowToSessionHandoff(row) {
         evidence = row.evidence_json ? JSON.parse(row.evidence_json) : null;
     }
     catch {
+        // Same degrade rule as artifacts: bad evidence reads as none.
         evidence = null;
     }
     return {

package/dist/hooks/codex-session.d.ts

@@ -0,0 +1,8 @@
+export interface CodexSessionTranscriptOptions {
+    codexHome: string;
+    historyPath: string;
+    startOffsetBytes: number;
+    startedAtMs: number;
+}
+export declare function resolveCodexSessionTranscript(options: CodexSessionTranscriptOptions): string | null;
+//# sourceMappingURL=codex-session.d.ts.map

package/dist/hooks/codex-session.js

@@ -0,0 +1,76 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { isJsonString } from './shared.js';
+function collectFiles(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    const stack = [dir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (current === undefined)
+            break;
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile()) {
+                out.push(full);
+            }
+        }
+    }
+    return out;
+}
+function readCodexSessionIdsFromHistoryDelta(historyPath, startOffsetBytes) {
+    if (!fs.existsSync(historyPath))
+        return [];
+    const raw = fs.readFileSync(historyPath);
+    if (startOffsetBytes >= raw.length)
+        return [];
+    const delta = raw.subarray(startOffsetBytes).toString('utf8');
+    const seen = new Set();
+    const ordered = [];
+    for (const line of delta.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            const sessionId = parsed.session_id;
+            if (isJsonString(sessionId) && sessionId && !seen.has(sessionId)) {
+                seen.add(sessionId);
+                ordered.push(sessionId);
+            }
+        }
+        catch {
+            // ignore malformed JSONL lines
+        }
+    }
+    return ordered;
+}
+function findCodexTranscriptBySessionId(sessionsDir, sessionId) {
+    const matches = collectFiles(sessionsDir).filter((filePath) => filePath.endsWith('.jsonl') && filePath.includes(sessionId));
+    if (matches.length === 0)
+        return null;
+    matches.sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+    return matches[0];
+}
+function findNewestCodexTranscriptSince(sessionsDir, startedAtMs) {
+    const matches = collectFiles(sessionsDir)
+        .filter((filePath) => filePath.endsWith('.jsonl'))
+        .map((filePath) => ({ filePath, mtimeMs: fs.statSync(filePath).mtimeMs }))
+        .filter((entry) => entry.mtimeMs >= startedAtMs)
+        .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return matches[0]?.filePath ?? null;
+}
+export function resolveCodexSessionTranscript(options) {
+    const { codexHome, historyPath, startOffsetBytes, startedAtMs } = options;
+    const sessionsDir = path.join(codexHome, 'sessions');
+    for (const sessionId of readCodexSessionIdsFromHistoryDelta(historyPath, startOffsetBytes).reverse()) {
+        const transcript = findCodexTranscriptBySessionId(sessionsDir, sessionId);
+        if (transcript)
+            return transcript;
+    }
+    return findNewestCodexTranscriptSince(sessionsDir, startedAtMs);
+}
+//# sourceMappingURL=codex-session.js.map

package/dist/hooks/codex-wrapper.d.ts

@@ -0,0 +1,55 @@
+export interface CodexWrapperPaths {
+    wrapperDir: string;
+    metadataPath: string;
+    wrapperCmdPath: string;
+    wrapperPs1Path: string;
+    wrapperShPath: string;
+    logFile: string;
+    runsDir: string;
+    codexHome: string;
+    historyPath: string;
+}
+export interface CodexWrapperInstallResult {
+    installed: boolean;
+    metadataPath: string;
+    realCodexPath: string;
+    commandPath: string;
+    backupPath: string;
+    installMode: 'same-path' | 'cmd-shim';
+}
+export interface CodexWrapperMetadata {
+    originalCodexPath: string;
+    realCodexPath: string;
+    commandPath: string;
+    backupPath: string;
+    installMode: 'same-path' | 'cmd-shim';
+    logFile: string;
+    installedAt: string;
+}
+export interface EnsureCodexWrapperResult {
+    status: 'installed' | 'already-installed' | 'not-found' | 'source-checkout';
+    metadataPath?: string;
+    realCodexPath?: string;
+    commandPath?: string;
+    backupPath?: string;
+}
+export declare function resolveCodexWrapperPaths(): CodexWrapperPaths;
+export declare function detectRealCodexPath(): string | null;
+export declare function installCodexWrapper(realCodexPath?: string): CodexWrapperInstallResult;
+export declare function uninstallCodexWrapper(): boolean;
+export declare function ensureCodexWrapperInstalled(): EnsureCodexWrapperResult;
+/**
+ * True if Codex wrapper metadata exists on this machine, i.e. the user opted
+ * in to the wrapper at some point (via `hippo hook install codex`).
+ */
+export declare function isCodexWrapperInstalled(): boolean;
+/**
+ * Repair-only variant of `ensureCodexWrapperInstalled`: re-ensures the wrapper
+ * ONLY when wrapper metadata already exists — that metadata is the user's
+ * opt-in record. Never performs a first install. Replacing another vendor's
+ * binary must stay behind the explicit `hippo hook install codex` command;
+ * 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(hippoCliPath?: string): EnsureCodexWrapperResult;
+//# sourceMappingURL=codex-wrapper.d.ts.map

package/dist/hooks/codex-wrapper.js

@@ -0,0 +1,288 @@
+import { envPath } from '../env.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { isJsonString, HIPPO_CODEX_WRAPPER_MARKER, homeDir, codexHomeDir, ensureDir } from './shared.js';
+export function resolveCodexWrapperPaths() {
+    const home = homeDir();
+    const codexHome = codexHomeDir(home);
+    const wrapperDir = path.join(home, '.hippo', 'bin');
+    return {
+        wrapperDir,
+        metadataPath: path.join(home, '.hippo', 'integrations', 'codex.json'),
+        wrapperCmdPath: path.join(wrapperDir, 'codex.cmd'),
+        wrapperPs1Path: path.join(wrapperDir, 'codex.ps1'),
+        wrapperShPath: path.join(wrapperDir, 'codex'),
+        logFile: path.join(home, '.hippo', 'logs', 'codex-sleep.log'),
+        runsDir: path.join(home, '.hippo', 'runs', 'codex'),
+        codexHome,
+        historyPath: path.join(codexHome, 'history.jsonl'),
+    };
+}
+function pathEquals(a, b) {
+    return path.resolve(a).toLowerCase() === path.resolve(b).toLowerCase();
+}
+function readCodexWrapperMetadata() {
+    const { metadataPath } = resolveCodexWrapperPaths();
+    if (!fs.existsSync(metadataPath))
+        return null;
+    try {
+        // This optimistic parse is never trusted directly — every call site reads fields off
+        // the result only after isCodexWrapperMetadataValid has runtime-checked each string
+        // field and the referenced paths.
+        const parsed = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+        return parsed;
+    }
+    catch {
+        // Unreadable metadata is treated like the missing-file case above.
+        return null;
+    }
+}
+function readTextFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        // Callers treat an unreadable file as absent.
+        return null;
+    }
+}
+function isHippoCodexWrapperFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return false;
+    const text = readTextFile(filePath);
+    return text !== null && text.includes(HIPPO_CODEX_WRAPPER_MARKER);
+}
+function isCodexWrapperMetadataValid(metadata) {
+    if (!metadata)
+        return false;
+    return (isJsonString(metadata.originalCodexPath) &&
+        isJsonString(metadata.realCodexPath) &&
+        isJsonString(metadata.commandPath) &&
+        isJsonString(metadata.backupPath) &&
+        fs.existsSync(metadata.realCodexPath) &&
+        fs.existsSync(metadata.backupPath) &&
+        isHippoCodexWrapperFile(metadata.commandPath));
+}
+function resolveHippoCliPath() {
+    return fileURLToPath(new URL('../bin/hippo.js', import.meta.url));
+}
+function quoteForShell(value) {
+    return `"${value.replace(/(["\\$`])/g, '\\$1')}"`;
+}
+function quoteForPowerShell(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function quoteForCmd(value) {
+    return `"${value.replace(/"/g, '""')}"`;
+}
+function resolveCodexInstallPlan(originalCodexPath) {
+    const dir = path.dirname(originalCodexPath);
+    const ext = path.extname(originalCodexPath).toLowerCase();
+    const name = path.basename(originalCodexPath, ext);
+    const backupPath = path.join(dir, `${name}.hippo-real${ext}`);
+    if (process.platform === 'win32' && ext === '.exe') {
+        return {
+            commandPath: path.join(dir, `${name}.cmd`),
+            backupPath,
+            installMode: 'cmd-shim',
+        };
+    }
+    return {
+        commandPath: originalCodexPath,
+        backupPath,
+        installMode: 'same-path',
+    };
+}
+function writeCodexLauncherWrapper(commandPath) {
+    const ext = path.extname(commandPath).toLowerCase();
+    const nodePath = process.execPath;
+    const hippoCliPath = resolveHippoCliPath();
+    if (process.platform === 'win32' && ext === '.ps1') {
+        writeExecutableFile(commandPath, [
+            `# ${HIPPO_CODEX_WRAPPER_MARKER}`,
+            `& ${quoteForPowerShell(nodePath)} ${quoteForPowerShell(hippoCliPath)} codex-run -- @args`,
+            '',
+        ].join('\n'));
+        return;
+    }
+    if (process.platform === 'win32' && (ext === '.cmd' || ext === '.bat')) {
+        writeExecutableFile(commandPath, [
+            '@echo off',
+            `REM ${HIPPO_CODEX_WRAPPER_MARKER}`,
+            `${quoteForCmd(nodePath)} ${quoteForCmd(hippoCliPath)} codex-run -- %*`,
+            '',
+        ].join('\r\n'));
+        return;
+    }
+    writeExecutableFile(commandPath, [
+        '#!/usr/bin/env sh',
+        `# ${HIPPO_CODEX_WRAPPER_MARKER}`,
+        `exec ${quoteForShell(nodePath)} ${quoteForShell(hippoCliPath)} codex-run -- "$@"`,
+        '',
+    ].join('\n'));
+}
+function cleanupLegacyCodexPathWrappers(paths) {
+    for (const filePath of [paths.wrapperCmdPath, paths.wrapperPs1Path, paths.wrapperShPath]) {
+        if (fs.existsSync(filePath))
+            fs.rmSync(filePath, { force: true });
+    }
+}
+export function detectRealCodexPath() {
+    const metadata = readCodexWrapperMetadata();
+    if (isCodexWrapperMetadataValid(metadata))
+        return metadata.realCodexPath;
+    const { wrapperDir } = resolveCodexWrapperPaths();
+    const entries = (envPath() ?? '')
+        .split(path.delimiter)
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .filter((entry) => !pathEquals(entry, wrapperDir));
+    const names = process.platform === 'win32'
+        ? ['codex.cmd', 'codex.ps1', 'codex.exe', 'codex']
+        : ['codex'];
+    for (const entry of entries) {
+        for (const name of names) {
+            const candidate = path.join(entry, name);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+function writeExecutableFile(filePath, content) {
+    fs.writeFileSync(filePath, content, 'utf8');
+    try {
+        fs.chmodSync(filePath, 0o755);
+    }
+    catch {
+        // chmod is best-effort on Windows
+    }
+}
+export function installCodexWrapper(realCodexPath) {
+    const existingMetadata = readCodexWrapperMetadata();
+    if (isCodexWrapperMetadataValid(existingMetadata) && !realCodexPath) {
+        cleanupLegacyCodexPathWrappers(resolveCodexWrapperPaths());
+        return {
+            installed: true,
+            metadataPath: resolveCodexWrapperPaths().metadataPath,
+            realCodexPath: existingMetadata.realCodexPath,
+            commandPath: existingMetadata.commandPath,
+            backupPath: existingMetadata.backupPath,
+            installMode: existingMetadata.installMode,
+        };
+    }
+    const resolvedRealCodexPath = realCodexPath ?? detectRealCodexPath();
+    if (!resolvedRealCodexPath) {
+        throw new Error('Could not locate the real Codex executable on PATH.');
+    }
+    const paths = resolveCodexWrapperPaths();
+    ensureDir(path.dirname(paths.metadataPath));
+    ensureDir(path.dirname(paths.logFile));
+    ensureDir(paths.runsDir);
+    cleanupLegacyCodexPathWrappers(paths);
+    const plan = resolveCodexInstallPlan(resolvedRealCodexPath);
+    ensureDir(path.dirname(plan.commandPath));
+    if (isCodexWrapperMetadataValid(existingMetadata)) {
+        uninstallCodexWrapper();
+    }
+    if (!fs.existsSync(plan.backupPath)) {
+        fs.renameSync(resolvedRealCodexPath, plan.backupPath);
+    }
+    writeCodexLauncherWrapper(plan.commandPath);
+    const metadata = {
+        originalCodexPath: resolvedRealCodexPath,
+        realCodexPath: plan.backupPath,
+        commandPath: plan.commandPath,
+        backupPath: plan.backupPath,
+        installMode: plan.installMode,
+        logFile: paths.logFile,
+        installedAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(paths.metadataPath, JSON.stringify(metadata, null, 2) + '\n', 'utf8');
+    return {
+        installed: true,
+        metadataPath: paths.metadataPath,
+        realCodexPath: metadata.realCodexPath,
+        commandPath: metadata.commandPath,
+        backupPath: metadata.backupPath,
+        installMode: metadata.installMode,
+    };
+}
+export function uninstallCodexWrapper() {
+    const paths = resolveCodexWrapperPaths();
+    let changed = false;
+    const metadata = readCodexWrapperMetadata();
+    if (metadata) {
+        if (fs.existsSync(metadata.commandPath) && isHippoCodexWrapperFile(metadata.commandPath)) {
+            fs.rmSync(metadata.commandPath, { force: true });
+            changed = true;
+        }
+        if (fs.existsSync(metadata.backupPath)) {
+            fs.renameSync(metadata.backupPath, metadata.originalCodexPath);
+            changed = true;
+        }
+    }
+    cleanupLegacyCodexPathWrappers(paths);
+    if (fs.existsSync(paths.metadataPath)) {
+        fs.rmSync(paths.metadataPath, { force: true });
+        changed = true;
+    }
+    return changed;
+}
+export function ensureCodexWrapperInstalled() {
+    const metadata = readCodexWrapperMetadata();
+    if (isCodexWrapperMetadataValid(metadata)) {
+        cleanupLegacyCodexPathWrappers(resolveCodexWrapperPaths());
+        return {
+            status: 'already-installed',
+            metadataPath: resolveCodexWrapperPaths().metadataPath,
+            realCodexPath: metadata.realCodexPath,
+            commandPath: metadata.commandPath,
+            backupPath: metadata.backupPath,
+        };
+    }
+    if (metadata) {
+        uninstallCodexWrapper();
+    }
+    const detectedRealCodexPath = detectRealCodexPath();
+    if (!detectedRealCodexPath) {
+        return { status: 'not-found' };
+    }
+    const result = installCodexWrapper(detectedRealCodexPath);
+    return {
+        status: 'installed',
+        metadataPath: result.metadataPath,
+        realCodexPath: result.realCodexPath,
+        commandPath: result.commandPath,
+        backupPath: result.backupPath,
+    };
+}
+/**
+ * True if Codex wrapper metadata exists on this machine, i.e. the user opted
+ * in to the wrapper at some point (via `hippo hook install codex`).
+ */
+export function isCodexWrapperInstalled() {
+    return readCodexWrapperMetadata() !== null;
+}
+/**
+ * Repair-only variant of `ensureCodexWrapperInstalled`: re-ensures the wrapper
+ * ONLY when wrapper metadata already exists — that metadata is the user's
+ * opt-in record. Never performs a first install. Replacing another vendor's
+ * binary must stay behind the explicit `hippo hook install codex` command;
+ * doing it from postinstall or routine commands is a consent violation and
+ * reads as binary hijacking to security scanners (issue #133).
+ */
+export function repairCodexWrapperIfInstalled(hippoCliPath = resolveHippoCliPath()) {
+    if (readCodexWrapperMetadata() === null) {
+        return { status: 'not-found' };
+    }
+    // A checkout's own `npm install` or CLI would point the user's launcher at a folder that may be deleted.
+    // SHORTCUT: any node_modules copy (npx cache, a project dependency) still repairs; record the opted-in CLI path in the metadata to close that.
+    const packageDir = path.dirname(path.dirname(hippoCliPath));
+    if (path.basename(path.dirname(packageDir)).toLowerCase() !== 'node_modules') {
+        return { status: 'source-checkout' };
+    }
+    return ensureCodexWrapperInstalled();
+}
+//# sourceMappingURL=codex-wrapper.js.map

package/dist/hooks/json-hooks.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 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.
+ *    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
+ *    `hooks` key, so v1.10.x-v1.11.1's JSON-hook installer broke opencode
+ *    launch (issue #24). Hippo now 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.
+ */
+import { type JsonHookTarget } from './shared.js';
+export interface JsonHookPaths {
+    settings: string;
+    logFile: string;
+    display: string;
+}
+export interface InstallResult {
+    target: JsonHookTarget;
+    settingsPath: string;
+    installedSessionEnd: boolean;
+    installedSessionStart: boolean;
+    installedUserPromptSubmit: boolean;
+    installedPreCompact: boolean;
+    installedCompactResume: boolean;
+    /** PostCompact -> `hippo post-compact` (saves the summary's memories, tells the user how many). */
+    installedPostCompact: boolean;
+    /** PostToolUseFailure -> `hippo capture-error` (failed tool calls become error memories). */
+    installedCaptureError: boolean;
+    migratedPinnedInjectRecent: boolean;
+    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 declare function resolveJsonHookPaths(target: JsonHookTarget): JsonHookPaths;
+export declare function installJsonHooks(target: JsonHookTarget): InstallResult;
+export declare function uninstallJsonHooks(target: JsonHookTarget): boolean;
+//# sourceMappingURL=json-hooks.d.ts.map