hippo-memory 1.69.0 → 1.71.0

package/dist/sharing/global-store.js

@@ -0,0 +1,75 @@
+// The global store: where it lives, creating it, and copying a local memory into it.
+import { BadRequestError, NotFoundError } from '../core/api-errors.js';
+import * as fs from 'fs';
+import { generateId } from '../core/memory.js';
+import { initStore } from '../store/open.js';
+import { writeEntry } from '../store/entry-writes.js';
+import { readEntry } from '../store/entry-reads.js';
+import { isPersonalScope } from '../store/recall-scope.js';
+import { fallbackOrigin, resolveGlobalRootDir } from '../core/project-identity.js';
+import { isSharedStore } from '../core/config.js';
+import { detectSecret } from '../util/secret-detect.js';
+import { isQuarantineScope } from '../trust/quarantine.js';
+import { embedMemory } from '../store/embeddings/index.js';
+import { appendAuditEvent } from '../store/audit.js';
+/** Returns the path to the global Hippo store.
+ *  Resolution order: $HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo/ */
+export function getGlobalRoot() {
+    // Single source of truth lives in project-identity.ts (leaf) so db migrations
+    // can resolve the same path without a shared.ts import cycle.
+    return resolveGlobalRootDir();
+}
+/** Ensure the global store exists. */
+export function initGlobal() {
+    const globalRoot = getGlobalRoot();
+    if (!fs.existsSync(globalRoot)) {
+        initStore(globalRoot);
+    }
+    else {
+        // Ensure subdirectories exist in case partially initialized
+        initStore(globalRoot);
+    }
+}
+/** The copy's write hook: the `promote` row when asked for, then the caller's own hook, both in the copy's transaction. */
+function promoteHook(sourceId, auditAs, afterWrite) {
+    if (!auditAs)
+        return afterWrite;
+    return (db, globalId) => {
+        appendAuditEvent(db, { tenantId: auditAs.tenantId, actor: auditAs.actor, op: 'promote', targetId: globalId, metadata: { sourceId } });
+        afterWrite?.(db, globalId);
+    };
+}
+/** Copies a local memory to the global store and returns the copy, which gets a new `g_` id so it cannot collide. */
+export function promoteToGlobal(localRoot, id, opts) {
+    const entry = readEntry(localRoot, id, opts?.tenantId);
+    if (!entry)
+        throw new NotFoundError(`Memory not found: ${id}`);
+    // Same quarantine veto as shareMemory; a promoted copy would have no quarantine record to review.
+    if (isQuarantineScope(entry.scope)) {
+        throw new BadRequestError(`Refusing to promote ${id}: it is quarantined pending review. Approve it first via 'hippo quarantine approve ${id}'.`);
+    }
+    if (isPersonalScope(entry.scope ?? null)) {
+        throw new BadRequestError(`Refusing to promote ${id}: it is a personal memory and stays with its owner on this server.`);
+    }
+    // Secret producer veto: promote is a producer path to the global store
+    // exactly like shareMemory - same hard rule.
+    const promoteSecret = detectSecret(entry);
+    if (promoteSecret.flagged) {
+        throw new BadRequestError(`Refusing to promote ${id} to the global store: content matches secret material (${promoteSecret.reason}). ` +
+            `Secrets stay in their owning project's store.`);
+    }
+    initGlobal();
+    const globalRoot = getGlobalRoot();
+    // A project store's NULL row gets its folder back; a shared store's folder is no caller's project, so NULL stays and the label names no path.
+    const globalEntry = {
+        ...entry,
+        id: generateId('g'),
+        source: isSharedStore(localRoot) ? `shared::${new Date().toISOString()}` : `promoted:${localRoot}`,
+        origin_project: entry.origin_project ?? fallbackOrigin(localRoot),
+    };
+    writeEntry(globalRoot, globalEntry, { actor: opts?.actor, afterWrite: promoteHook(id, opts?.auditAs, opts?.afterWrite) });
+    // Fire-and-forget: embedMemory gates on availability and never rejects.
+    void embedMemory(globalRoot, globalEntry);
+    return globalEntry;
+}
+//# sourceMappingURL=global-store.js.map

package/dist/sharing/global-sync.d.ts

@@ -0,0 +1,6 @@
+/** Copy all global memories into the local store, skipping entries that already exist locally by ID or text (promote and share copy under a new ID).
+ *  Returns the count of newly copied entries. */
+export declare function syncGlobalToLocal(localRoot: string, globalRoot: string, opts?: {
+    includeCrossProject?: boolean;
+}): number;
+//# sourceMappingURL=global-sync.d.ts.map

package/dist/sharing/global-sync.js

@@ -0,0 +1,80 @@
+// Copying the global store's memories down into a local store.
+import { BadRequestError } from '../core/api-errors.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENT_MEMORY_SOURCE_PREFIX } from '../core/agent-memory-tools.js';
+import { writeEntry } from '../store/entry-writes.js';
+import { loadAllEntries } from '../store/entry-reads.js';
+import { classifyOriginProject, resolveProjectIdentity } from '../core/project-identity.js';
+import { isSharedStore } from '../core/config.js';
+import { detectSecret } from '../util/secret-detect.js';
+import { RejectedValueError } from '../store/rejection.js';
+import { embedAll } from '../store/embeddings/index.js';
+import { log } from '../util/log.js';
+import { logEmbedAllFailure } from './search-both.js';
+/** Copy all global memories into the local store, skipping entries that already exist locally by ID or text (promote and share copy under a new ID).
+ *  Returns the count of newly copied entries. */
+export function syncGlobalToLocal(localRoot, globalRoot, opts = {}) {
+    if (isSharedStore(localRoot)) {
+        throw new BadRequestError(`Refusing to sync into ${localRoot}: a shared store takes no copies of a personal global store, whose rows would reach every member.`);
+    }
+    if (!fs.existsSync(globalRoot))
+        return 0;
+    // Host-wide read: the global union is copied into a tenant-scoped local store, and writeEntry carries the tenant if the local-root context has one.
+    const globalEntries = loadAllEntries(globalRoot);
+    const textKey = (e) => `${e.tenantId}\n${e.content}`;
+    const localEntries = loadAllEntries(localRoot);
+    const localIds = new Set(localEntries.map((e) => e.id));
+    const localText = new Set(localEntries.map(textKey));
+    // Syncing down must not re-import what ambient context excludes: other-project rows are skipped by default and secret rows never copied.
+    // origin_project is preserved on the copy (writeEntry stamps it only when missing).
+    const currentProject = resolveProjectIdentity(path.dirname(path.resolve(localRoot)));
+    let count = 0;
+    // A locally rejected value must not come back through sync down: caught per item, printed as one line.
+    let rejected = 0;
+    for (const entry of globalEntries) {
+        // Skip if already present by ID
+        if (localIds.has(entry.id))
+            continue;
+        // Only the global store's user pass sets an imported note's row aside, so a copy would outlive the note.
+        if (entry.source.startsWith(AGENT_MEMORY_SOURCE_PREFIX))
+            continue;
+        if (localText.has(textKey(entry)))
+            continue;
+        if (detectSecret(entry).flagged)
+            continue;
+        if (!opts.includeCrossProject && classifyOriginProject(entry.origin_project, currentProject) === 'cross-project')
+            continue;
+        if (!writeUnlessRejected(localRoot, entry)) {
+            rejected++;
+            continue;
+        }
+        localText.add(textKey(entry));
+        count++;
+    }
+    finishSyncDown(localRoot, count, rejected);
+    return count;
+}
+/** False when the local store rejects the value; any other failure still throws. */
+function writeUnlessRejected(localRoot, entry) {
+    try {
+        writeEntry(localRoot, entry);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof RejectedValueError)
+            return false;
+        throw err;
+    }
+}
+function finishSyncDown(localRoot, count, rejected) {
+    if (rejected > 0) {
+        log.warn(`syncGlobalToLocal: skipped ${rejected} rejected value(s) (run \`hippo unreject\` on the local store to allow).`);
+    }
+    // Batch producer: one embedAll() on the destination rather than an
+    // embedMemory() per copied row (same batching invariant as autoShare).
+    if (count > 0) {
+        void embedAll(localRoot).catch((err) => logEmbedAllFailure('syncGlobalToLocal', err));
+    }
+}
+//# sourceMappingURL=global-sync.js.map

package/dist/{project-merge.d.ts → sharing/project-merge.d.ts}

@@ -1,4 +1,4 @@
-import type { DatabaseSyncLike } from './db.js';
+import { type DatabaseSyncLike } from '../db/index.js';
 export interface ProjectSummary {
     /** '' is user-global, null is unknown; neither can be merged. */
     readonly origin: string | null;
@@ -59,15 +59,14 @@ export declare function mergeProjects(db: DatabaseSyncLike, hippoRoot: string, o
 export declare function namesFoldedInto(db: DatabaseSyncLike, tenantId: string, names: readonly string[]): string[];
 /** Reads only, so doctor and a dry run take no write lock; merged rows are planned before any fold, so a few may re-tag differently once folds apply. */
 export declare function planProjectRepair(db: DatabaseSyncLike, hippoRoot: string, tenantId: string, globalFolds?: boolean): Omit<RepairResult, 'backup'>;
-/** Sets aside stray imports, folds the names the resolver now maps elsewhere, then re-tags sleep's user-global merges by their parents; a dry run only plans. */
+/** Sets aside stray imports, folds the names the resolver now maps elsewhere, then
+ * re-tags sleep's user-global merges by their parents; a dry run only plans. */
 export declare function repairProjects(db: DatabaseSyncLike, hippoRoot: string, opts: {
     tenantId: string;
     dryRun: boolean;
     globalFolds?: boolean;
 }): RepairResult;
-/**
- * Sleep runs repair once per store, so an upgrade needs no command. Global-store folds stay
- * with `hippo projects repair`: their evidence is compaction folders, blind to a same-named repo that never compacted.
- */
+/** Sleep runs repair once per store, so an upgrade needs no command. Global-store folds stay
+ *  with `hippo projects repair`: their evidence is compaction folders, blind to a same-named repo that never compacted. */
 export declare function repairOnceOnSleep(db: DatabaseSyncLike, hippoRoot: string, tenantId: string): RepairResult | null;
 //# sourceMappingURL=project-merge.d.ts.map

package/dist/{project-merge.js → sharing/project-merge.js}

@@ -1,23 +1,25 @@
 // `hippo projects`: list the project names a store holds, fold one into another, and repair old tags in one reversible pass.
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { setAsideRow } from './agent-memories/apply.js';
-import { transcriptNotesProject } from './agent-memories/claude-code.js';
-import { containerId, containerPrefix } from './agent-memories/source.js';
-import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TOOLS, toolSourcePrefix } from './agent-memories/tools.js';
-import { appendAuditEvent, queryAuditEvents } from './audit.js';
-import { isSharedStore } from './config.js';
-import { withBackup } from './db/backup.js';
-import { getMeta, setMeta } from './db/meta.js';
-import { insertDormantRow, listDormantSnapshots, replaceDormantEntry } from './dormant.js';
-import { processEnv } from './env.js';
-import { calculateStrength } from './memory.js';
-import { isObjectLike, isStringValue } from './capture-contract.js';
-import { isGlobalStoreRoot, projectNames, resolveProjectIdentity } from './project-identity.js';
-import { duplicateKey } from './same-text.js';
-import { removeEntryMirrors } from './store/mirrors.js';
-import { deleteEntryRowInTx, writeEntryMirrors } from './store/entry-writes.js';
-import { selectAllEntries, selectLiveEntriesBySourcePrefix } from './store/entry-reads.js';
+import { setAsideRow } from '../agent-memories/apply.js';
+import { transcriptNotesProject } from '../agent-memories/claude-code.js';
+import { containerId, containerPrefix } from '../agent-memories/source.js';
+import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TOOLS, toolSourcePrefix } from '../core/agent-memory-tools.js';
+import { appendAuditEvent, queryAuditEvents } from '../store/audit.js';
+import { isSharedStore } from '../core/config.js';
+import { withTrialScope, withWriteScope } from '../db/index.js';
+import { withBackup } from '../db/backup.js';
+import { getMeta, setMeta } from '../db/meta.js';
+import { insertDormantRow, listDormantSnapshots, replaceDormantEntry } from '../store/dormant.js';
+import { processEnv } from '../util/env.js';
+import { calculateStrength } from '../core/memory.js';
+import { isObjectLike, isStringValue } from '../core/capture-contract.js';
+import { isGlobalStoreRoot, projectNames, resolveProjectIdentity } from '../core/project-identity.js';
+import { duplicateKey } from '../util/same-text.js';
+import { compactionOriginsWithCwd, compactionTranscripts, holdsOrigin, restampCompactionOrigin } from '../store/compactions.js';
+import { removeEntryMirrors } from '../store/mirrors.js';
+import { deleteEntryRowInTx, restampOriginProjectAt, stampOriginProjectsAt, writeEntryMirrors } from '../store/entry-writes.js';
+import { selectAllEntries, selectLiveEntriesBySourcePrefix } from '../store/entry-reads.js';
 const ACTOR = 'cli';
 function isImport(entry) {
     return entry.source.startsWith(AGENT_MEMORY_SOURCE_PREFIX);
@@ -50,19 +52,7 @@ export function listProjects(db, tenantId) {
     }).sort((a, b) => b.newest.localeCompare(a.newest));
 }
 function inTransaction(db, dryRun, body) {
-    db.exec(dryRun ? 'BEGIN' : 'BEGIN IMMEDIATE');
-    try {
-        const out = body();
-        db.exec(dryRun ? 'ROLLBACK' : 'COMMIT');
-        return out;
-    }
-    catch (err) {
-        try {
-            db.exec('ROLLBACK');
-        }
-        catch { /* already rolled back; keep the original error */ }
-        throw err;
-    }
+    return dryRun ? withTrialScope(db, 'merge_projects', body) : withWriteScope(db, 'merge_projects', body);
 }
 /** Refuses user-global and unknown: they are not projects, and folding them would leak or hide every row. */
 export function validateMergeNames(from, into) {
@@ -103,8 +93,7 @@ function foldInTx(db, tenantId, from, into) {
     }
     const gone = new Set(setAside);
     const restamped = rows.filter((e) => !gone.has(e.id)).map((e) => e.id);
-    db.prepare(`UPDATE memories SET origin_project = ?, updated_at = datetime('now') WHERE tenant_id = ? AND origin_project = ?`)
-        .run(into, tenantId, from);
+    restampOriginProjectAt(db, tenantId, from, into);
     const dormantRestamped = [];
     for (const snap of listDormantSnapshots(db, tenantId)) {
         if (snap.entry.origin_project !== from || gone.has(snap.entry.id))
@@ -112,8 +101,7 @@ function foldInTx(db, tenantId, from, into) {
         replaceDormantEntry(db, tenantId, snap.entry.id, { ...snap.entry, origin_project: into });
         dormantRestamped.push(snap.entry.id);
     }
-    const compactions = Number(db.prepare(`UPDATE compactions SET origin_project = ? WHERE tenant_id = ? AND origin_project = ?`)
-        .run(into, tenantId, from).changes ?? 0);
+    const compactions = restampCompactionOrigin(db, tenantId, from, into);
     return { setAside, restamped, dormantRestamped, compactions };
 }
 /** Tool, note key and hash of an import, without the container, whose id hashes the project name. */
@@ -127,16 +115,15 @@ function importCopies(db, tenantId) {
     const userGlobal = new Set(live.filter((e) => e.origin_project === '').map((e) => duplicateKey(e.content)));
     return live.filter((e) => e.origin_project && e.kind !== 'raw' && !e.pinned && toolTag(e.source) !== null && userGlobal.has(duplicateKey(e.content)));
 }
-/** Imports to set aside. The global store also checks each Claude session folder a compaction recorded: its notes under any other project are misfiled, edited or not, and a text copy in the right folder is kept. */
+/** Imports to set aside. The global store also checks each Claude session folder a compaction recorded: its
+ * notes under any other project are misfiled, edited or not, and a text copy in the right folder is kept. */
 function strayImports(db, hippoRoot, tenantId) {
     const copies = importCopies(db, tenantId);
     if (!isGlobalStoreRoot(hippoRoot))
         return copies;
     const machine = { platform: process.platform, env: processEnv() };
     const { platform } = machine;
-    // SAFETY: the SELECT names the two columns of the row type.
-    const sessions = db.prepare(`SELECT DISTINCT transcript_path AS transcript, cwd FROM compactions WHERE tenant_id = ? AND transcript_path IS NOT NULL`)
-        .all(tenantId);
+    const sessions = compactionTranscripts(db, tenantId);
     const owners = new Map();
     for (const { transcript, cwd } of sessions) {
         const project = transcriptNotesProject(transcript, cwd, machine);
@@ -172,9 +159,7 @@ function planFolds(db, hippoRoot, tenantId, globalFolds) {
     const chosen = new Set(queryAuditEvents(db, { tenantId, op: 'project_merge', limit: 10000 }).map((e) => e.metadata.into));
     if (!isGlobalStoreRoot(hippoRoot))
         return { folds: ownLegacyFold(db, hippoRoot, tenantId).filter((f) => !chosen.has(f.from)), collisions: [] };
-    // SAFETY: the SELECT names the two columns of the row type.
-    const rows = db.prepare(`SELECT DISTINCT origin_project AS origin, cwd FROM compactions WHERE tenant_id = ? AND origin_project <> '' AND cwd IS NOT NULL`)
-        .all(tenantId);
+    const rows = compactionOriginsWithCwd(db, tenantId);
     const today = new Map();
     for (const { origin, cwd } of rows) {
         if (fs.existsSync(cwd))
@@ -203,8 +188,9 @@ function ownLegacyFold(db, hippoRoot, tenantId) {
     const { name, legacyName } = resolveProjectIdentity(path.dirname(path.resolve(hippoRoot)));
     if (legacyName === '' || legacyName === name)
         return [];
-    const heldIn = (table) => db.prepare(`SELECT 1 FROM ${table} WHERE tenant_id = ? AND origin_project = ? LIMIT 1`).get(tenantId, legacyName) !== undefined;
-    const held = heldIn('memories') || heldIn('compactions') || listDormantSnapshots(db, tenantId).some((s) => s.entry.origin_project === legacyName);
+    const held = holdsOrigin(db, 'memories', tenantId, legacyName)
+        || holdsOrigin(db, 'compactions', tenantId, legacyName)
+        || listDormantSnapshots(db, tenantId).some((s) => s.entry.origin_project === legacyName);
     return held ? [{ from: legacyName, into: name }] : [];
 }
 function foldOf(value) {
@@ -270,7 +256,8 @@ function planUserGlobalRepair(db, tenantId, folds) {
     }
     return { toProject, setAside, untraced };
 }
-/** Sets aside stray imports, folds the names the resolver now maps elsewhere, then re-tags sleep's user-global merges by their parents; a dry run only plans. */
+/** Sets aside stray imports, folds the names the resolver now maps elsewhere, then
+ * re-tags sleep's user-global merges by their parents; a dry run only plans. */
 export function repairProjects(db, hippoRoot, opts) {
     const { tenantId, dryRun, globalFolds = true } = opts;
     if (dryRun)
@@ -285,9 +272,7 @@ export function repairProjects(db, hippoRoot, opts) {
         const { folds, collisions } = planFolds(db, hippoRoot, tenantId, globalFolds);
         const folded = folds.map((f) => foldInTx(db, tenantId, f.from, f.into));
         const plan = planUserGlobalRepair(db, tenantId, []);
-        const stamp = db.prepare(`UPDATE memories SET origin_project = ?, updated_at = datetime('now') WHERE tenant_id = ? AND id = ?`);
-        for (const { id, origin } of plan.toProject)
-            stamp.run(origin, tenantId, id);
+        stampOriginProjectsAt(db, tenantId, plan.toProject);
         const aside = new Set(plan.setAside);
         const now = new Date();
         for (const row of selectAllEntries(db, tenantId).filter((e) => aside.has(e.id))) {
@@ -309,10 +294,8 @@ const AUTO_REPAIR_META_KEY = 'project_repair_auto';
 function repairIsEmpty(r) {
     return r.copies.length + r.folds.length + r.toProject.length + r.setAside.length === 0;
 }
-/**
- * Sleep runs repair once per store, so an upgrade needs no command. Global-store folds stay
- * with `hippo projects repair`: their evidence is compaction folders, blind to a same-named repo that never compacted.
- */
+/** Sleep runs repair once per store, so an upgrade needs no command. Global-store folds stay
+ *  with `hippo projects repair`: their evidence is compaction folders, blind to a same-named repo that never compacted. */
 export function repairOnceOnSleep(db, hippoRoot, tenantId) {
     if (getMeta(db, AUTO_REPAIR_META_KEY) === '1')
         return null;

package/dist/sharing/scope.d.ts

@@ -0,0 +1,7 @@
+/** Detect the current operational scope from env (HIPPO_SCOPE > GSTACK_SKILL > OPENCLAW_SKILL); returns the name without prefix, or null.
+ *  Pure env reads, no I/O, so it is safe on hot paths such as the UserPromptSubmit hook. */
+export declare function detectScope(): string | null;
+/** Compute scope match between a memory's scope tags and the active scope.
+ *  Returns: 1 if matching scope, -1 if mismatching scope, 0 if neutral (no scope on either side). */
+export declare function scopeMatch(memoryTags: string[], activeScope: string | null): -1 | 0 | 1;
+//# sourceMappingURL=scope.d.ts.map

package/dist/{scope.js → sharing/scope.js}

@@ -1,11 +1,6 @@
-import { envGstackSkill, envOpenclawSkill, envScope } from './env.js';
-/**
- * Detect the current operational scope from environment signals.
- * Returns a scope name string (no prefix), or null if no scope detected.
- * Priority: HIPPO_SCOPE > GSTACK_SKILL > OPENCLAW_SKILL.
- *
- * Pure env var reads: no I/O, safe to call from hot paths (e.g. UserPromptSubmit hook).
- */
+import { envGstackSkill, envOpenclawSkill, envScope } from '../util/env.js';
+/** Detect the current operational scope from env (HIPPO_SCOPE > GSTACK_SKILL > OPENCLAW_SKILL); returns the name without prefix, or null.
+ *  Pure env reads, no I/O, so it is safe on hot paths such as the UserPromptSubmit hook. */
 export function detectScope() {
     const explicit = envScope();
     if (explicit && explicit.trim())
@@ -18,10 +13,8 @@ export function detectScope() {
         return openclawSkill.trim();
     return null;
 }
-/**
- * Compute scope match between a memory's scope tags and the active scope.
- * Returns: 1 if matching scope, -1 if mismatching scope, 0 if neutral (no scope on either side).
- */
+/** Compute scope match between a memory's scope tags and the active scope.
+ *  Returns: 1 if matching scope, -1 if mismatching scope, 0 if neutral (no scope on either side). */
 export function scopeMatch(memoryTags, activeScope) {
     const scopeTags = memoryTags.filter(t => t.startsWith('scope:'));
     if (scopeTags.length === 0)

package/dist/sharing/search-both.d.ts

@@ -0,0 +1,60 @@
+import { MemoryEntry } from '../core/memory.js';
+import { type SearchResult, type ResultCost } from '../core/search-types.js';
+import { type HybridVectorCandidates } from '../search/vector.js';
+export declare function logEmbedAllFailure<E>(caller: string, err: E): void;
+export interface SearchOptions {
+    budget?: number;
+    now?: Date;
+    minResults?: number;
+    /** Tenant scope for both stores. Undefined = no filter (legacy single-tenant). */
+    tenantId?: string;
+}
+/** Search both local and global stores and merge: local results are boosted 1.2x to prefer project context.
+ *  Returns results sorted by adjusted score within the combined token budget. */
+export declare function searchBoth(query: string, localRoot: string, globalRoot: string, options?: SearchOptions): SearchResult[];
+export interface HybridSearchOptions extends SearchOptions {
+    embeddingWeight?: number;
+    explain?: boolean;
+    mmr?: boolean;
+    mmrLambda?: number;
+    /** Multiplier applied to local-store scores when merging with global.
+     *  Defaults to 1.2. Use 1.0 to remove the local bias for eval comparisons. */
+    localBump?: number;
+    /** Active scope for scope-boost scoring. Auto-detected if not provided. */
+    scope?: string | null;
+    /** Include superseded memories in results. Default false. */
+    includeSuperseded?: boolean;
+    /** Filter to memories current at this ISO date string. */
+    asOf?: string;
+    /** Budget cost per result, spent the same way in each store and in the merged list. */
+    cost?: ResultCost;
+    /** Propagated to underlying hybridSearch calls.
+     *  Per-call > env HIPPO_SUMMARY_DEBOOST > 0.85 default. */
+    summaryDeboost?: number;
+    /** Propagated. Default true (1.05 boost if rebuilt within 7d). */
+    summaryFreshness?: boolean;
+    /** Optional admission predicate applied to the loaded candidates of BOTH stores before ranking, cross-store dedupe and budgeting,
+     *  so an excluded row cannot shadow its admitted duplicate or saturate the budget. Undefined (recall paths never set it) means no filter. */
+    entryFilter?: (entry: MemoryEntry) => boolean;
+    /** Recall scope filter for `searchBothHybrid`: absent is the only unfiltered mode; present uses `loadRecallSearchEntries` plus a JS post-filter.
+     *  `{}` = default-deny (legacy and `<source>:private:*` excluded); `{ requested: 'X' }` = exact; `{ requested: 'X', additive: true }` = default plus X.
+     *  An object, not `string | null`, because the sibling `scope` option already gives null a different meaning.
+     *  Do not pass `{}` casually from non-recall paths. */
+    recallScope?: {
+        requested?: string;
+        additive?: boolean;
+        ownScope?: string;
+    };
+}
+/** Hybrid search across both local and global stores, using embeddings when available.
+ *  Async version of searchBoth that calls hybridSearch instead of search. */
+export declare function searchBothHybrid(query: string, localRoot: string, globalRoot: string, options?: HybridSearchOptions): Promise<SearchResult[]>;
+/** Hybrid ranking of rows already loaded from each store: the local bump, one copy per text, then the shared budget. */
+export declare function rankBothStores(query: string, roots: {
+    local: string;
+    global: string;
+}, entries: {
+    local: MemoryEntry[];
+    global: MemoryEntry[];
+}, vectorCandidates: HybridVectorCandidates, options?: HybridSearchOptions): Promise<SearchResult[]>;
+//# sourceMappingURL=search-both.d.ts.map

package/dist/sharing/search-both.js

@@ -0,0 +1,138 @@
+// Search across the local and global stores, merged into one ranked, budgeted list.
+import { compareScoresDesc } from '../core/compare.js';
+import * as fs from 'fs';
+import { loadSearchEntries, loadRecallSearchEntries, recallScopeFilter } from '../store/search-rows.js';
+import { passesScopeFilterForRecall, passesCliRecallScopeFilter } from '../store/recall-scope.js';
+import { search } from '../search/bm25-search.js';
+import { hybridSearch } from '../search/hybrid.js';
+import { fitBudget } from '../search/finalize.js';
+import { DEFAULT_LOCAL_BUMP, DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
+import { startQueryEmbedDeadline } from '../search/vector.js';
+import { evalNow } from '../core/ablation.js';
+import { duplicateKey } from '../util/same-text.js';
+import { errorMessage, log } from '../util/log.js';
+// The rows are already copied; a failed background embed only delays vectors, so it warns instead of throwing.
+export function logEmbedAllFailure(caller, err) {
+    log.warn(`${caller}: background embed failed (${errorMessage(err)}); run 'hippo embed' to backfill`);
+}
+/** Search both local and global stores and merge: local results are boosted 1.2x to prefer project context.
+ *  Returns results sorted by adjusted score within the combined token budget. */
+export function searchBoth(query, localRoot, globalRoot, options = {}) {
+    const { budget = DEFAULT_RECALL_BUDGET, now = evalNow(), minResults, tenantId } = options;
+    const effectiveMin = minResults ?? 1;
+    const localEntries = fs.existsSync(localRoot) ? loadSearchEntries(localRoot, query, undefined, tenantId) : [];
+    const globalEntries = fs.existsSync(globalRoot) ? loadSearchEntries(globalRoot, query, undefined, tenantId) : [];
+    if (localEntries.length === 0 && globalEntries.length === 0)
+        return [];
+    // Search each store with full budget, then blend
+    const localResults = search(query, localEntries, { budget, now, minResults });
+    const globalResults = search(query, globalEntries, { budget, now, minResults });
+    const deduped = dedupeByContent(tagLocalAndGlobal(localResults, globalResults));
+    // PLAIN stable score sort on purpose: both inputs are deterministically ordered,
+    // and an exact tie keeps the LOCAL result ahead of the global one (concat order).
+    deduped.sort((a, b) => compareScoresDesc(a.score, b.score));
+    // Apply combined token budget (guarantee at least minResults items)
+    const results = [];
+    let usedTokens = 0;
+    for (let i = 0; i < deduped.length; i++) {
+        if (results.length >= effectiveMin && usedTokens + deduped[i].tokens > budget)
+            continue;
+        usedTokens += deduped[i].tokens;
+        results.push(deduped[i]);
+    }
+    return results;
+}
+function tagLocalAndGlobal(localResults, globalResults) {
+    // Tag global results. Local memories get a configurable priority bump.
+    return [
+        ...localResults.map((r) => ({
+            ...r,
+            isGlobal: false,
+            score: r.score * DEFAULT_LOCAL_BUMP,
+            breakdown: r.breakdown
+                ? { ...r.breakdown, sourceBump: DEFAULT_LOCAL_BUMP, final: r.breakdown.final * DEFAULT_LOCAL_BUMP }
+                : undefined,
+        })),
+        ...globalResults.map((r) => ({ ...r, isGlobal: true })),
+    ];
+}
+function dedupeByContent(tagged) {
+    // Remove duplicates by content (local/global IDs differ after promote/share)
+    const seen = new Set();
+    return tagged.filter((r) => {
+        const key = duplicateKey(r.entry.content);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/** Hybrid search across both local and global stores, using embeddings when available.
+ *  Async version of searchBoth that calls hybridSearch instead of search. */
+export async function searchBothHybrid(query, localRoot, globalRoot, options = {}) {
+    const { includeSuperseded, asOf, tenantId, entryFilter, recallScope } = options;
+    // With an admission filter, lift the per-store candidate cap (default 200) to a bounded 5000: excluded rows could otherwise fill the window first.
+    const searchWindow = entryFilter ? 5000 : undefined;
+    // Recall mode: push the scope predicate into SQL like api.recall, so quarantine/private rows never enter the candidates, shadow duplicates or use budget.
+    // The JS post-filter below is the regex-only `<source>:private:*` half plus defense in depth on exact match.
+    const loadEntries = (root) => {
+        if (!fs.existsSync(root))
+            return [];
+        return recallScope
+            ? loadRecallSearchEntries(root, query, searchWindow, tenantId, recallScope.requested, recallScope.additive ? 'additive' : 'exact', Boolean(includeSuperseded) || Boolean(asOf), undefined, recallScope.ownScope)
+            : loadSearchEntries(root, query, searchWindow, tenantId);
+    };
+    const passesScope = (e) => !recallScope || (recallScope.additive
+        ? passesCliRecallScopeFilter(e.scope ?? null, recallScope.requested) || passesScopeFilterForRecall(e.scope ?? null, undefined, recallScope.ownScope)
+        : passesScopeFilterForRecall(e.scope ?? null, recallScope.requested, recallScope.ownScope));
+    const admit = (e) => passesScope(e) && (!entryFilter || entryFilter(e));
+    const localEntries = loadEntries(localRoot).filter(admit);
+    const globalEntries = loadEntries(globalRoot).filter(admit);
+    // The vector arm loads under the same SQL rules as loadEntries, then the same JS admission.
+    const vectorCandidates = {
+        tenantId,
+        scope: recallScope ? recallScopeFilter(recallScope.requested, recallScope.additive ? 'additive' : 'exact', recallScope.ownScope) : undefined,
+        includeSuperseded: !recallScope || Boolean(includeSuperseded) || Boolean(asOf),
+        admit,
+    };
+    return rankBothStores(query, { local: localRoot, global: globalRoot }, { local: localEntries, global: globalEntries }, vectorCandidates, options);
+}
+/** Hybrid ranking of rows already loaded from each store: the local bump, one copy per text, then the shared budget. */
+export async function rankBothStores(query, roots, entries, vectorCandidates, options = {}) {
+    const { budget = DEFAULT_RECALL_BUDGET, now = evalNow(), embeddingWeight, explain, mmr, mmrLambda, localBump = DEFAULT_LOCAL_BUMP, minResults, cost, scope, includeSuperseded, asOf, summaryDeboost, summaryFreshness } = options;
+    if (entries.local.length === 0 && entries.global.length === 0)
+        return [];
+    // One deadline for both stores, so a provider that stalls on the first is not waited on again for the second.
+    const shared = {
+        budget, now, embeddingWeight, explain, mmr, mmrLambda, minResults, cost, scope, includeSuperseded, asOf, summaryDeboost, summaryFreshness,
+        vectorCandidates, queryEmbedDeadline: startQueryEmbedDeadline(),
+    };
+    const localResults = await hybridSearch(query, entries.local, { ...shared, hippoRoot: roots.local });
+    const globalResults = await hybridSearch(query, entries.global, { ...shared, hippoRoot: roots.global });
+    // Tag global results. Local memories get a configurable priority bump.
+    const tagged = [
+        ...localResults.map((r) => ({
+            ...r,
+            isGlobal: false,
+            score: r.score * localBump,
+            breakdown: r.breakdown
+                ? { ...r.breakdown, sourceBump: localBump, final: r.breakdown.final * localBump }
+                : undefined,
+        })),
+        ...globalResults.map((r) => ({ ...r, isGlobal: true })),
+    ];
+    // Remove duplicates by content (local/global IDs differ after promote/share)
+    const seen = new Set();
+    const deduped = tagged.filter((r) => {
+        const key = duplicateKey(r.entry.content);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    // PLAIN stable score sort on purpose -- see searchBoth above;
+    // same rationale (deterministic inputs + stability; local-first on ties).
+    deduped.sort((a, b) => compareScoresDesc(a.score, b.score));
+    return fitBudget(deduped, budget, minResults ?? 1, cost);
+}
+//# sourceMappingURL=search-both.js.map

package/dist/sharing/share.d.ts

@@ -0,0 +1,38 @@
+import { MemoryEntry } from '../core/memory.js';
+/** Tags whose rows only a hand-run share or promote may copy to the global store; derived rows inherit them. */
+export declare const NEVER_AUTO_SHARE_TAGS: ReadonlySet<string>;
+export declare function neverAutoShareTags(sources: readonly MemoryEntry[]): string[];
+/** Tags whose rows sleep keeps as written: never merged, never sent to LLM extraction. Conflict detection keeps its own list. */
+export declare const NO_MERGE_TAGS: ReadonlySet<string>;
+/** Estimate how well a memory would transfer to other projects.
+ *  Returns 0..1 where >0.5 = good candidate for sharing. */
+export declare function transferScore(entry: MemoryEntry): number;
+/** Share a memory to the global store with attribution (source enriched with project path and timestamp).
+ *  Returns the new entry, or null if the transfer score is too low. */
+export declare function shareMemory(localRoot: string, id: string, options?: {
+    force?: boolean;
+    tenantId?: string;
+    skipEmbed?: boolean;
+}): MemoryEntry | null;
+/** List all projects that contributed memories to the global store, parsed from 'shared:<project>:' or 'promoted:<path>' sources.
+ *  `tenantId` filters to one tenant; undefined is host-wide (legacy callers: CLI standalone, dashboard). */
+export declare function listPeers(globalRoot?: string, tenantId?: string): Array<{
+    project: string;
+    count: number;
+    latest: string;
+}>;
+type AutoShareStats = {
+    secretSkipped: number;
+    rejectedSkipped?: number;
+    neverAutoShareSkipped?: number;
+};
+/** Auto-share local memories with high transfer scores, not already global and without a NEVER_AUTO_SHARE_TAGS tag; `options.tenantId` scopes the LOCAL read.
+ *  `options.stats` is an opt-in out-param: `secretSkipped` counts shares the secret veto prevented, `rejectedSkipped` rejection refusals (0 under `dryRun`). */
+export declare function autoShare(localRoot: string, options?: {
+    minScore?: number;
+    dryRun?: boolean;
+    tenantId?: string;
+    stats?: AutoShareStats;
+}): MemoryEntry[];
+export {};
+//# sourceMappingURL=share.d.ts.map