hippo-memory 1.58.0 → 1.59.0

package/README.md

@@ -535,6 +535,18 @@ removes pinned memories, raw receipts (Slack, GitHub, vault imports) or the memo
 Claude Code compaction saved either way, and duplicate removal and junk cleanup still
 delete other memories. `hippo forget` still deletes a compaction memory.
 
+**Clean up project names left by older versions.** Older versions tagged memories saved in
+a git worktree with the worktree's folder name, and older sleep saved merged memories as
+user-global, so every project could see them. Upgrading stops new damage; these commands
+repair old rows. Each is a dry run until you add `--apply`. With `--apply`, it backs up the
+database to `.hippo/backups/` first and logs every id it touched in the audit log:
+
+```bash
+hippo projects --global                        # names, counts, live worktrees of this repo
+hippo projects merge hippo-wt-fix hippo --global   # fold an old worktree name into its repo
+hippo projects repair --global                 # re-tag user-global merges by their parents
+```
+
 **See what memory costs in tokens.** Every block of memory text hippo hands an agent (the
 per-prompt hook, the block `hippo compact-resume` restores after compaction, `hippo context`,
 `hippo recall`, the MCP tools, the HTTP API) is recorded in a token ledger: counts, surface
@@ -1126,7 +1138,7 @@ Mark it, and it drops out of the top results. `hippo outcome --bad` weakens the
 
 ### Where does hippo keep my data?
 
-On your machine, in SQLite: `.hippo/hippo.db` in each project, plus a global store in `~/.hippo/` for lessons shared across projects, with markdown mirrors you can read and commit. Recall makes no network call by default. Text goes to an outside provider only through features that use one: an API embedder, the Jev or LLM reranker, `hippo refine`, and the fact extraction `hippo sleep` runs through Anthropic's API whenever `ANTHROPIC_API_KEY` is set in its environment. To turn that last one off, set `{"extraction":{"enabled":false}}` in `.hippo/config.json`.
+On your machine, in SQLite: `.hippo/hippo.db` in each project, plus a global store in `~/.hippo/` for lessons shared across projects, with markdown mirrors you can read and commit. Recall makes no network call by default. Text goes to an outside provider only through features that use one: an API embedder, the Jev, CLEF or LLM reranker, `hippo refine`, and the fact extraction `hippo sleep` runs through Anthropic's API whenever `ANTHROPIC_API_KEY` is set in its environment. To turn that last one off, set `{"extraction":{"enabled":false}}` in `.hippo/config.json`.
 
 ### What does hippo cost?
 

package/dist/agent-memories/apply.d.ts

@@ -34,7 +34,7 @@ export interface ContainerOutcome {
 }
 /** Throws SQLITE_BUSY when another writer holds the store past its busy timeout; nothing is written then. */
 export declare function syncContainer(s: StoreSession, work: ContainerWork): ContainerOutcome;
-export type SetAsideWhy = 'note-gone' | 'note-changed' | 'handover';
+export type SetAsideWhy = 'note-gone' | 'note-changed' | 'handover' | 'project-merge';
 export type SetAsideResult = {
     readonly kind: 'untagged';
     readonly entry: MemoryEntry;

package/dist/agent-memories/legacy.js

@@ -1,6 +1,7 @@
 // Rows the old Claude import wrote (`claude-memory:<file>`), taken over by the notes they came from (plan design 10).
 import path from 'node:path';
 import { duplicateKey } from '../same-text.js';
+import { maskEmails } from '../secret-detect.js';
 import { selectLiveEntriesBySourcePrefix } from '../store.js';
 import { matchLegacy } from './plan.js';
 import { MIN_ITEM_CHARS, storedText } from './source.js';
@@ -25,7 +26,9 @@ export function legacyWork(db, tenantId, listings) {
             refs.push({ dir: container.path, key: item.key });
         }
     }
-    const match = matchLegacy(rows.map((r) => ({ id: r.id, file: r.source.slice(LEGACY_SOURCE_PREFIX.length), textKey: duplicateKey(r.content) })), targets);
+    const match = matchLegacy(
+    // The old import kept emails in clear, and targets are masked; without the mask those rows never matched and imported twice.
+    rows.map((r) => ({ id: r.id, file: r.source.slice(LEGACY_SOURCE_PREFIX.length), textKey: duplicateKey(maskEmails(r.content)) })), targets);
     const byId = new Map(rows.map((r) => [r.id, r]));
     const add = (pick, ref, id) => {
         const { dir, key } = refs[Number(ref)];

package/dist/audit.d.ts

@@ -18,7 +18,7 @@ export declare function auditMemory(entry: MemoryEntry, backsObject?: boolean):
 /** `backing`: ids of memories that back an object (store.memoriesBackingObjects). */
 export declare function auditMemories(entries: MemoryEntry[], backing: ReadonlySet<string>): AuditResult;
 export declare function isContentWorthStoring(content: string): boolean;
-export declare const AUDIT_OPS: readonly ["remember", "recall", "promote", "supersede", "forget", "archive_raw", "auth_revoke", "auth_create", "outcome", "consolidate", "audit_prune", "summary_marked_dirty", "summary_marked_clean", "summary_rebuilt", "predict_create", "predict_close", "predict_baserate", "recall_autodebias_hint", "recall_autodebias_hint_no_class_match", "recall_autodebias_hint_tiebreak", "recall_anchor_detected_query_repeat", "recall_anchor_detected_memory_dominance", "recall_anchor_skipped_no_session", "recall_availability_detected", "decision_create", "decision_supersede", "decision_close", "incident_open", "incident_resolve", "incident_close", "process_create", "process_supersede", "process_close", "policy_create", "policy_supersede", "policy_close", "skill_create", "skill_supersede", "skill_close", "project_brief_create", "project_brief_supersede", "project_brief_close", "customer_note_create", "customer_note_supersede", "customer_note_close", "mv_rescue", "reject_value", "reject_refusal", "unreject_value", "conflict_resolve", "half_life_migrate", "dormant_restore", "auth_grant", "auth_ungrant", "quarantine", "quarantine_approve", "quarantine_reject", "agent_memory_restore", "agent_memory_set_aside"];
+export declare const AUDIT_OPS: readonly ["remember", "recall", "promote", "supersede", "forget", "archive_raw", "auth_revoke", "auth_create", "outcome", "consolidate", "audit_prune", "summary_marked_dirty", "summary_marked_clean", "summary_rebuilt", "predict_create", "predict_close", "predict_baserate", "recall_autodebias_hint", "recall_autodebias_hint_no_class_match", "recall_autodebias_hint_tiebreak", "recall_anchor_detected_query_repeat", "recall_anchor_detected_memory_dominance", "recall_anchor_skipped_no_session", "recall_availability_detected", "decision_create", "decision_supersede", "decision_close", "incident_open", "incident_resolve", "incident_close", "process_create", "process_supersede", "process_close", "policy_create", "policy_supersede", "policy_close", "skill_create", "skill_supersede", "skill_close", "project_brief_create", "project_brief_supersede", "project_brief_close", "customer_note_create", "customer_note_supersede", "customer_note_close", "mv_rescue", "reject_value", "reject_refusal", "unreject_value", "conflict_resolve", "half_life_migrate", "dormant_restore", "auth_grant", "auth_ungrant", "quarantine", "quarantine_approve", "quarantine_reject", "agent_memory_restore", "agent_memory_set_aside", "project_merge", "project_repair"];
 export type AuditOp = (typeof AUDIT_OPS)[number];
 export interface AppendAuditOpts {
     tenantId: string;

package/dist/audit.js

@@ -235,6 +235,8 @@ export const AUDIT_OPS = [
     'quarantine_reject', // emitted by api.quarantineReject
     'agent_memory_restore', // emitted by the agent memory sync when a deleted note comes back
     'agent_memory_set_aside', // emitted by the agent memory sync when a note is deleted or refused
+    'project_merge', // emitted by `hippo projects merge --apply` with every id it touched
+    'project_repair', // emitted by `hippo projects repair --apply` with every id it touched
 ];
 function isBigIntValue(value) {
     return typeof value === 'bigint';

package/dist/cli/output.d.ts

@@ -0,0 +1,3 @@
+/** Writes a message the user asked for, or must act on, to stderr. */
+export declare function printError(...args: unknown[]): void;
+//# sourceMappingURL=output.d.ts.map

package/dist/cli/output.js

@@ -0,0 +1,7 @@
+// User-facing CLI messages (usage, not-found, refusals) print at every HIPPO_LOG level; diagnostics go to `log`.
+// Both forward to console.error so the bytes match the old calls and console spies in tests still see them.
+/** Writes a message the user asked for, or must act on, to stderr. */
+export function printError(...args) {
+    console.error(...args);
+}
+//# sourceMappingURL=output.js.map

package/dist/cli/projects.d.ts

@@ -0,0 +1,4 @@
+type Flags = Record<string, string | boolean | string[]>;
+export declare function cmdProjects(hippoRoot: string, args: string[], flags: Flags): void;
+export {};
+//# sourceMappingURL=projects.d.ts.map

package/dist/cli/projects.js

@@ -0,0 +1,90 @@
+// The `hippo projects` verb: list a store's project names, fold an old worktree name into its repo, repair sleep's user-global merges.
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+import { closeHippoDb, openHippoDb } from '../db.js';
+import { listProjects, mergeProjects, repairUserGlobalMerges } from '../project-merge.js';
+import { resolveTenantId } from '../tenant.js';
+import { resolveAuthRoot } from './shared.js';
+import { printError } from './output.js';
+/** Old per-worktree project names of the repo at cwd, mapped to the repo's main checkout name; empty outside git. */
+function worktreeNames() {
+    try {
+        const out = execFileSync('git', ['worktree', 'list', '--porcelain'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+        const paths = out.split(/\r?\n/).filter((l) => l.startsWith('worktree ')).map((l) => path.basename(l.slice('worktree '.length)));
+        return new Map(paths.slice(1).map((name) => [name, paths[0]]));
+    }
+    catch {
+        // Outside a git checkout, or no git on PATH: the list just has no worktree hints.
+        return new Map();
+    }
+}
+function label(origin) {
+    return origin === null ? '(unknown)' : origin === '' ? '(user-global)' : origin;
+}
+function hint(p, worktrees) {
+    const main = p.origin ? worktrees.get(p.origin) : undefined;
+    if (main)
+        return `\n    a worktree of ${main}: hippo projects merge ${p.origin} ${main}`;
+    return p.copiesElsewhere > 0 ? `\n    ${p.copiesElsewhere} of its imported notes are copies also held under another name` : '';
+}
+function count(n, one, many = `${one}s`) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+export function cmdProjects(hippoRoot, args, flags) {
+    const root = resolveAuthRoot(hippoRoot, flags);
+    const tenantId = resolveTenantId({});
+    const apply = flags['apply'] === true;
+    const sub = args[0] ?? 'list';
+    const db = openHippoDb(root);
+    try {
+        if (sub === 'list') {
+            const projects = listProjects(db, tenantId);
+            if (flags['json']) {
+                console.log(JSON.stringify({ store: root, projects }, null, 2));
+                return;
+            }
+            const worktrees = worktreeNames();
+            console.log(`${count(projects.length, 'project name')} in ${root} (newest write first):\n`);
+            for (const p of projects) {
+                console.log(`${label(p.origin)}  ${count(p.live, 'memory', 'memories')}, ${p.imported} imported from agent notes, newest ${p.newest.slice(0, 10)}${hint(p, worktrees)}`);
+            }
+            return;
+        }
+        if (sub === 'merge') {
+            const [from, into] = [args[1] ?? '', args[2] ?? ''];
+            const r = mergeProjects(db, root, { tenantId, from, into, dryRun: !apply });
+            if (flags['json']) {
+                console.log(JSON.stringify(r, null, 2));
+                return;
+            }
+            console.log(`${apply ? 'Merged' : 'Dry run: would merge'} ${from} into ${into}:`);
+            console.log(`  ${count(r.setAside.length, 'imported note copy', 'imported note copies')} set aside (dormant; the next sync under ${into} imports the notes still on disk)`);
+            console.log(`  ${count(r.restamped.length, 'memory', 'memories')} re-tagged, plus ${r.dormantRestamped.length} dormant and ${count(r.compactions, 'compaction record')}`);
+            console.log(apply ? `Backup: ${r.backup}\nEvery id is in the audit log: hippo audit list --op project_merge` : 'Nothing written. Add --apply to run it.');
+            return;
+        }
+        if (sub === 'repair') {
+            const r = repairUserGlobalMerges(db, root, { tenantId, dryRun: !apply });
+            if (flags['json']) {
+                console.log(JSON.stringify(r, null, 2));
+                return;
+            }
+            console.log(`${apply ? 'Repaired' : 'Dry run: would repair'} sleep's user-global merged rows:`);
+            console.log(`  ${r.toProject.length} re-tagged to their parents' project`);
+            console.log(`  ${r.setAside.length} set aside (parents in two projects; sleep re-merges them per project)`);
+            console.log(`  ${r.untraced.length} left as they are (no parent left to show which project; check them with hippo inspect <id>)`);
+            console.log(apply ? `Backup: ${r.backup}\nEvery id is in the audit log: hippo audit list --op project_repair` : 'Nothing written. Add --apply to run it.');
+            return;
+        }
+        printError('Usage: hippo projects [list] [--json] | merge <from> <into> [--apply] | repair [--apply]  [--global]');
+        process.exitCode = 1;
+    }
+    catch (err) {
+        printError(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=projects.js.map

package/dist/cli/shared.js

@@ -28,6 +28,8 @@ import * as client from '../client.js';
 import { detectServer, removePidfileIfOwned } from '../server-detect.js';
 import { resolveTenantId } from '../tenant.js';
 import { snapshotText, sessionTrailText, handoffText } from '../context-render.js';
+import { log } from '../log.js';
+import { printError } from './output.js';
 export function parseLimitFlag(value) {
     if (!value)
         return Infinity;
@@ -45,13 +47,13 @@ export function parseBudgetFlag(value, fallback) {
         return fallback;
     // A value-less flag and a junk value are different typos; the --hops guard already splits them.
     if (typeof value !== 'string') {
-        console.error('--budget requires an integer value (e.g. --budget 1500).');
+        printError('--budget requires an integer value (e.g. --budget 1500).');
         process.exit(1);
     }
     // Number(), like the --hops guard: parseInt('12abc') is 12, silently accepting what this message rejects.
     const parsed = Number(value);
     if (!Number.isInteger(parsed) || parsed < 0) {
-        console.error(`Invalid --budget: "${value}". Must be a non-negative integer.`);
+        printError(`Invalid --budget: "${value}". Must be a non-negative integer.`);
         process.exit(1);
     }
     return parsed;
@@ -84,7 +86,7 @@ export function emitCliAudit(hippoRoot, op, targetId, metadata) {
 }
 export function requireInit(hippoRoot) {
     if (!isInitialized(hippoRoot)) {
-        console.error(`No hippo store at ${hippoRoot} (searched ${process.cwd()} and its parents up to your home directory). Run \`hippo init\` first.`);
+        printError(`No hippo store at ${hippoRoot} (searched ${process.cwd()} and its parents up to your home directory). Run \`hippo init\` first.`);
         process.exit(1);
     }
 }
@@ -149,7 +151,7 @@ export async function runViaServerIfAvailable(hippoRoot, httpFn) {
         const failure = client.classifyTransportFailure(err);
         if (failure === 'never-sent') {
             failIfServerRequired('the server pidfile was stale (connection refused)');
-            console.error('hippo: stale server pidfile detected, falling back to direct mode');
+            log.warn('stale server pidfile detected, falling back to direct mode');
             // Clear the pidfile only if it still names the dead server we just
             // probed — a newer server may have rewritten it (removePidfileIfOwned).
             removePidfileIfOwned(hippoRoot, { pid: info.pid, startedAt: info.started_at });
@@ -159,7 +161,7 @@ export async function runViaServerIfAvailable(hippoRoot, httpFn) {
             // Every caller of this helper is a non-idempotent write, so replaying on
             // the direct path would store a row the server may already have committed.
             // Leave the pidfile alone: the next command's connect-phase failure heals it.
-            console.error(`hippo: the connection to ${info.url} dropped or timed out mid-request, so the write may already have been applied. Not retrying locally. Check with \`hippo recall\` before running this again.`);
+            printError(`hippo: the connection to ${info.url} dropped or timed out mid-request, so the write may already have been applied. Not retrying locally. Check with \`hippo recall\` before running this again.`);
             process.exit(1);
         }
         throw err;
@@ -216,7 +218,7 @@ export function printAgentImport(report, indent = '   ') {
     if (line !== null)
         console.log(`${indent}${line}`);
     for (const warning of report.warnings)
-        console.error(`hippo: agent memories: ${warning}`);
+        printError(`hippo: agent memories: ${warning}`);
 }
 /** The first hippo block in `text` and the agent whose current or shipped text it is; `owner` is undefined for an edited block. */
 export function hippoBlock(text) {
@@ -301,6 +303,7 @@ export function setupDailySchedule(globalRoot) {
             console.log(`   Scheduled machine-level daily runner (6:15am) via crontab`);
         }
         catch {
+            // No crontab or no permission: print the line for the user to add by hand.
             const cronLine = `15 6 * * * ${cmd}`;
             console.log(`   To schedule the machine-level daily runner, add to crontab (crontab -e):`);
             console.log(`   ${cronLine}`);
@@ -310,7 +313,7 @@ export function setupDailySchedule(globalRoot) {
 export function parseAsOfFlag(flags) {
     const asOf = typeof flags['as-of'] === 'string' ? flags['as-of'] : undefined;
     if (asOf !== undefined && Number.isNaN(new Date(asOf).getTime())) {
-        console.error(`Error: --as-of value "${asOf}" is not a valid ISO date (e.g. 2026-04-22 or 2026-04-22T12:00:00Z).`);
+        printError(`Error: --as-of value "${asOf}" is not a valid ISO date (e.g. 2026-04-22 or 2026-04-22T12:00:00Z).`);
         process.exit(1);
     }
     return asOf;
@@ -342,6 +345,7 @@ export function collectHandoffEvidence(cwd, testStatus) {
         }).trim() || null;
     }
     catch {
+        // No git, not a repo, or timed out: evidence is optional, so the field stays null.
         gitRef = null;
     }
     let dirtyTree = null;
@@ -352,6 +356,7 @@ export function collectHandoffEvidence(cwd, testStatus) {
         dirtyTree = status.trim().length > 0;
     }
     catch {
+        // Same as gitRef: unknown tree state is reported as null, never as an error.
         dirtyTree = null;
     }
     return { gitRef, dirtyTree, testStatus };
@@ -408,7 +413,7 @@ export function cardStringFlag(flags, key) {
     if (v === undefined)
         return undefined;
     if (v === true || v === false || Array.isArray(v)) {
-        console.error(`--${key} requires a value`);
+        printError(`--${key} requires a value`);
         process.exit(1);
     }
     return v.trim();
@@ -477,6 +482,7 @@ export function withLedgerDb(hippoRoot, fn) {
             root = getGlobalRoot();
     }
     catch {
+        // An unreadable store root means no ledger write; the ledger must never break context or recall.
         return undefined;
     }
     if (root === null)

package/dist/cli/sleep.js

@@ -8,7 +8,9 @@ import { replayCompactionsAt } from '../compaction-record.js';
 import * as api from '../api.js';
 import { resolveTenantId } from '../tenant.js';
 import { renderAmbientSummary } from '../ambient.js';
+import { log } from '../log.js';
 import { requireInit, learnFromRepo, runChurnStaleForRepo, printAgentImport } from './shared.js';
+import { printError } from './output.js';
 /** Runs `hippo sleep`; with `--log-file` it also tees its output to that file. */
 export async function cmdSleep(hippoRoot, flags) {
     // Tee stdout/stderr to a log file when --log-file is set. The SessionEnd
@@ -45,7 +47,7 @@ export async function cmdSleep(hippoRoot, flags) {
             };
         }
         catch (err) {
-            console.error(`[hippo] warning: could not open log file ${logFile}: ${err.message}`);
+            log.warn(`could not open log file ${logFile}: ${err.message}`);
         }
     }
     try {
@@ -145,14 +147,14 @@ async function cmdSleepCore(hippoRoot, flags) {
                 if (result.marked > 0)
                     console.log(`Tagged ${result.marked} memories churn-stale in ${root}.`);
                 if (result.error)
-                    console.error(`Churn-staleness check failed for ${root}: ${result.error}`);
+                    printError(`Churn-staleness check failed for ${root}: ${result.error}`);
             }
         }
         printAgentImport(importForStore(hippoRoot, { machine: currentMachine() }), '');
     }
     // Finishes compactions a killed or busy post-compact hook left; never throws, and a dry run writes nothing.
     if (!flags['dry-run']) {
-        const finished = replayCompactionsAt(hippoRoot, (message) => console.error(`compaction replay: ${message}`));
+        const finished = replayCompactionsAt(hippoRoot, (message) => log.warn(`compaction replay: ${message}`));
         if (finished > 0)
             console.log(`Finished saving ${finished} compaction${finished === 1 ? '' : 's'} left over from earlier sessions.`);
     }

package/dist/cli.d.ts

@@ -20,6 +20,7 @@
  *   hippo rejections
  *   hippo unreject <digest-prefix>
  *   hippo dormant [<query>] [--limit <n>] [--json] | restore <id> | forget <id>
+ *   hippo projects [--json] | merge <from> <into> [--apply] | repair [--apply]
  *   hippo tokens [--days <n>] [--json] [--global]
  *   hippo doctor [--json]
  *   hippo inspect <id>