hippo-memory 1.70.0 → 1.71.0

package/dist/server/server-detect.js

@@ -1,46 +1,28 @@
 import { existsSync, readFileSync, writeFileSync, unlinkSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
 import { envHealthProbeMs } from '../util/env.js';
-// Pidfile sits directly inside hippoRoot. `hippoRoot` is the `.hippo`
-// directory itself (the same convention used by api.ts / store.ts /
-// openHippoDb), so this resolves to `${hippoRoot}/server.pid`.
+// Pidfile sits directly inside hippoRoot (the `.hippo` directory itself, as for openHippoDb), i.e. `${hippoRoot}/server.pid`.
 const PIDFILE = 'server.pid';
-/**
- * How long detectServer waits for the `/health` liveness probe before
- * treating the pidfile as stale. Short by design: the probe only fires on
- * the rare path where a pidfile exists and its pid is live, and the target
- * is always loopback, so a healthy server answers well within this bound. HIPPO_HEALTH_PROBE_MS overrides it.
- */
+/** How long detectServer waits for the `/health` probe before treating the pidfile as stale; short because it fires only when a pidfile exists with a live
+ * pid on loopback. HIPPO_HEALTH_PROBE_MS overrides it. */
 const HEALTH_PROBE_TIMEOUT_MS = 300;
-/**
- * Hard cap on the /health response body detectServer will buffer. A real
- * hippo /health payload is well under 1 KB; a larger body means the process
- * answering on the recorded port is not hippo, so the pidfile is stale.
- */
+/** Hard cap on the /health body detectServer buffers: a real payload is well under 1 KB, so a larger body means the process on the recorded port is not
+ * hippo. */
 const HEALTH_BODY_MAX_BYTES = 64 * 1024;
-/**
- * Loopback hosts the recorded pidfile url is allowed to point at. serve()
- * only binds these (it mirrors LOOPBACK_HOSTS in server.ts); a pidfile url
- * with any other host is malformed or forged and must not be probed.
- */
+/** Loopback hosts a recorded pidfile url may point at (serve() only binds these); any other host is malformed or forged and is not probed. */
 const PIDFILE_LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
 /** False when the pidfile's pid is dead or its url could not be one serve() wrote. */
 function isLiveLoopbackTarget(info) {
-    // Probe the process. Sending signal 0 throws if the pid is dead or owned
-    // by another user we cannot signal. Either way, treat as stale.
-    // Node's process.kill(pid, 0) is implemented on Windows via OpenProcess +
-    // GetExitCodeProcess, so this works cross-platform for the dead-pid case.
+    // Signal 0 throws if the pid is dead or owned by another user we cannot signal; either way, treat as stale.
+    // process.kill(pid, 0) works cross-platform for the dead-pid case (OpenProcess + GetExitCodeProcess on Windows).
     try {
         process.kill(info.pid, 0);
     }
     catch {
         return false;
     }
-    // The pid is live, but it may have been reused by an unrelated process, and
-    // the recorded url is read from a file anyone could forge. serve() only ever
-    // binds a loopback host, so a url that is not http on a loopback host and the
-    // recorded port is malformed or forged. Reject it before probing: the probe,
-    // and the routed request that may follow, can carry HIPPO_API_KEY.
+    // The pid may have been reused and the recorded url is read from a forgeable file; serve() only binds loopback, so a url that is not http on a loopback
+    // host and the recorded port is malformed or forged. Reject it before probing, since the probe and any routed request can carry HIPPO_API_KEY.
     let probeUrl;
     try {
         probeUrl = new URL(info.url);
@@ -54,9 +36,8 @@ function isLiveLoopbackTarget(info) {
 }
 /** The whole body as text, or null once it passes HEALTH_BODY_MAX_BYTES (the stream is then cancelled). */
 async function readCappedBody(body) {
-    // Read the body under a hard byte cap. The process answering on info.url
-    // may not be hippo (pid reuse is the case this probe guards against), so
-    // its response is untrusted: never hand an unbounded stream to a parser.
+    // Read the body under a hard byte cap: the process on info.url may not be hippo (pid reuse), so its response is untrusted and never goes unbounded into a
+    // parser.
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let raw = '';
@@ -77,12 +58,8 @@ async function readCappedBody(body) {
 }
 /** True when /health on info.url reports the pidfile's started_at; unlinks the pidfile on any definitive mismatch. */
 async function healthMatchesPidfile(hippoRoot, info) {
-    // Confirm the process answering on info.url is this hippo server by matching
-    // the /health `started_at` against the pidfile. A connection refusal, a
-    // non-200, or a malformed body unlink the pidfile as stale. A probe timeout
-    // is deliberately left ambiguous: a live but momentarily-busy server (e.g.
-    // blocked on a synchronous query) can miss the 300ms window, so a timeout
-    // returns null WITHOUT unlinking. The pidfile survives for the next probe.
+    // Confirm the answering process is this server by matching /health `started_at` against the pidfile; refusal, non-200 or a malformed body unlink the
+    // pidfile as stale. A probe timeout is ambiguous (a live but busy server can miss the 300ms window), so it returns null WITHOUT unlinking.
     try {
         const res = await fetch(`${info.url}/health`, {
             signal: AbortSignal.timeout(envHealthProbeMs() ?? HEALTH_PROBE_TIMEOUT_MS),
@@ -104,32 +81,16 @@ async function healthMatchesPidfile(hippoRoot, info) {
         return true;
     }
     catch (err) {
-        // A timeout is ambiguous (the server may be alive but busy), so keep the
-        // pidfile. Any other failure (connection refused, malformed body) is
-        // definitive: unlink it as stale.
-        // SAFETY: err's shape is unknown (catch clause); reading an optional
-        // .name property structurally is safe regardless of the object's actual type.
+        // A timeout is ambiguous (the server may be busy), so keep the pidfile; any other failure (refused, malformed body) is definitive: unlink as stale.
+        // SAFETY: err's shape is unknown (catch clause); reading an optional .name property structurally is safe regardless of the actual type.
         if (err?.name !== 'TimeoutError') {
             removePidfile(hippoRoot);
         }
         return false;
     }
 }
-/**
- * Read .hippo/server.pid and return the embedded ServerInfo if a live hippo
- * server is genuinely answering on the recorded url. Returns null on missing,
- * malformed, or stale pidfiles, and best-effort unlinks the file in the
- * stale/malformed cases.
- *
- * Liveness is proven in two steps. `process.kill(pid, 0)` rules out dead
- * pids. But a pid can be reused by an unrelated process, so a GET /health
- * then confirms the process that answers is *this* hippo server: its
- * `started_at` must equal the pidfile's. A mismatch, non-200, malformed
- * body, or timeout all mean the pidfile is stale.
- *
- * The /health probe runs only when a pidfile exists and the pid is live, so
- * the common no-server path stays a single fast file existence check.
- */
+/** Returns the pidfile's ServerInfo if a live hippo server answers on the recorded url, else null (best-effort unlinking of missing/stale/malformed pidfiles).
+ * `process.kill(pid, 0)` rules out dead pids; GET /health must then return the pidfile's `started_at` (pids get reused). Probes only if the pid is live. */
 export async function detectServer(hippoRoot) {
     const path = join(hippoRoot, PIDFILE);
     if (!existsSync(path))
@@ -148,14 +109,8 @@ export async function detectServer(hippoRoot) {
     }
     return (await healthMatchesPidfile(hippoRoot, info)) ? info : null;
 }
-/**
- * Atomically write the pidfile. Writes to a process-scoped temp file then
- * renames into place, which is atomic on POSIX and on NTFS via MoveFileEx.
- *
- * `startedAt` is supplied by the caller (`serve()`) rather than generated
- * here, so the pidfile and the server's GET /health response carry the same
- * timestamp — detectServer's liveness probe compares the two for equality.
- */
+/** Atomically writes the pidfile (process-scoped temp file, then rename; atomic on POSIX and NTFS). `startedAt` comes from the caller (`serve()`) so the
+ * pidfile and GET /health carry the same timestamp, which detectServer's liveness probe compares. */
 export function writePidfile(hippoRoot, opts) {
     const path = join(hippoRoot, PIDFILE);
     const tmp = `${path}.tmp.${process.pid}`;
@@ -169,13 +124,8 @@ export function writePidfile(hippoRoot, opts) {
     writeFileSync(tmp, JSON.stringify(info));
     renameSync(tmp, path);
 }
-/**
- * Best-effort pidfile removal. Silent on ENOENT or any other error so the
- * caller can use this in shutdown paths without fear of throwing.
- *
- * Identity-blind: deletes whatever pidfile is on disk. A shutdown path that
- * must not clobber a newer server's pidfile should use removePidfileIfOwned.
- */
+/** Best-effort pidfile removal, silent on any error so shutdown paths can call it. Identity-blind: a shutdown that must not clobber a newer server's pidfile
+ * uses removePidfileIfOwned. */
 export function removePidfile(hippoRoot) {
     const path = join(hippoRoot, PIDFILE);
     try {
@@ -183,24 +133,8 @@ export function removePidfile(hippoRoot) {
     }
     catch { /* already gone or undeletable; the next detectServer probe re-checks */ }
 }
-/**
- * Remove the pidfile only if it still describes the caller's own server.
- * Reads and parses the pidfile and unlinks it ONLY when both `pid` and
- * `started_at` match `owner`. A pidfile rewritten by a newer server is left
- * intact, so a shutting-down older server cannot orphan the newer one by
- * deleting its pidfile out from under it.
- *
- * Best-effort and never throws: a missing, unreadable, malformed, or
- * non-object pidfile (including a literal JSON `null`) is "not provably mine"
- * and left alone — detectServer unlinks a malformed pidfile on its next
- * probe, so it does not leak. Returns true iff a matching pidfile was removed.
- *
- * Residual TOCTOU: the pidfile could be rewritten between the read and the
- * unlink. The window is microseconds and the shape is the same read-check-
- * unlink detectServer already uses; this narrows the clobber from an
- * unbounded window (any time between writePidfile and stop) to a negligible
- * one.
- */
+/** Removes the pidfile ONLY when both `pid` and `started_at` match `owner`, so an older shutting-down server cannot orphan a newer one; never throws.
+ * Anything unreadable or malformed is "not provably mine" and left alone (detectServer unlinks it). Returns true iff removed. */
 export function removePidfileIfOwned(hippoRoot, owner) {
     const path = join(hippoRoot, PIDFILE);
     try {

package/dist/server/sleep-offload.js

@@ -23,7 +23,10 @@ function runInChild(job) {
     const deadlineMs = envSleepTimeoutMs() ?? DEFAULT_SLEEP_DEADLINE_MS;
     return new Promise((resolve, reject) => {
         // The child's stderr is the server's log, so Node's SQLite notice would repeat there on every sleep.
-        const child = spawn(process.execPath, ['--disable-warning=ExperimentalWarning', CHILD_ENTRY], { stdio: ['ignore', 'inherit', 'inherit', 'ipc'], windowsHide: true });
+        const child = spawn(process.execPath, ['--disable-warning=ExperimentalWarning', CHILD_ENTRY], {
+            stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+            windowsHide: true
+        });
         let reply;
         let timedOut = false;
         // SIGKILL because the child is inside synchronous SQLite work and cannot run a handler; the OS drops its write lock.

package/dist/server/types.d.ts

@@ -7,17 +7,16 @@ export interface ServerHandle {
     port: number;
     url: string;
     stop: () => Promise<void>;
-    /** Introspection-only: the underlying node:http Server, exposed so
-     *  tests can assert keep-alive/headers timeout hardening without reaching
-     *  into serve()'s closure. Additive field — do not depend on it for control
-     *  flow outside tests. */
+    /** Introspection-only: the underlying node:http Server, so tests can assert keep-alive/headers timeout hardening without reaching into serve()'s closure.
+     * Do not use for control flow. */
     server?: import('node:http').Server;
 }
 /** Identity an {@link AuthResolver} vouches for. The core sanitises it before use. */
 export interface ResolvedBearer {
     tenantId: string;
     subject: string;
-    /** Not 'admin' means 'member'. Admin is tenant-only, yet can mint member API keys (POST /v1/auth/keys); an add-on revokes them through the exported authRevoke when the IdP deprovisions the minter. */
+    /** Not 'admin' means 'member'. Admin is tenant-only, yet can mint member API keys (POST /v1/auth/keys);
+     * an add-on revokes them through the exported authRevoke when the IdP deprovisions the minter. */
     role: 'admin' | 'member';
     scopes?: readonly string[];
 }
@@ -28,7 +27,8 @@ export interface AddonCall {
     readonly ctx: Context;
     readonly body: Readonly<Record<string, JsonValue>>;
 }
-/** A POST /v1 route an add-on mounts through serve(): core authenticates and parses first, then sends the returned value as 200 JSON. Under another store it runs only when that store has its `storeReady` group. */
+/** A POST /v1 route an add-on mounts through serve(): core authenticates and parses first, then sends the
+ * returned value as 200 JSON. Under another store it runs only when that store has its `storeReady` group. */
 export interface AddonRoute {
     readonly path: string;
     readonly handler: (call: AddonCall) => Promise<JsonValue>;
@@ -46,7 +46,8 @@ export interface ServeOpts {
     authResolverTimeoutMs?: number;
     port?: number;
     host?: string;
-    /** Stop and exit on SIGINT/SIGTERM, and drain then exit 1 on an uncaught exception or unhandled rejection. Only `hippo serve` owns the process, so only it sets this. */
+    /** Stop and exit on SIGINT/SIGTERM, and drain then exit 1 on an uncaught exception or unhandled rejection. A stop still running
+     * 10 s past `shutdownDrainMs` ends the process with a failure exit. Only `hippo serve` owns the process, so only it sets this. */
     handleSignals?: boolean;
     /** How long stop() lets in-flight requests finish before closing their sockets; defaults to 5000 ms. */
     shutdownDrainMs?: number;
@@ -59,7 +60,8 @@ export interface ServeOpts {
     mintBodyDeadlineMs?: number;
     /** Tests only: shortens the wait for a signed webhook's body, which defaults to 10 s. */
     webhookBodyDeadlineMs?: number;
-    /** PEM certificate and key: serve() then answers HTTPS only. Unset means cleartext HTTP, which needs a TLS-terminating proxy in front on any non-loopback bind. */
+    /** PEM certificate and key: serve() then answers HTTPS only. Unset means cleartext
+     * HTTP, which needs a TLS-terminating proxy in front on any non-loopback bind. */
     tls?: {
         cert: string | Buffer;
         key: string | Buffer;
@@ -94,8 +96,8 @@ type StoreStatus = {
     sqliteOnly: string;
     storeReady?: never;
 };
-/** One /v1 route: an exact path, a matchPath pattern, or a regex, each paired with the handler for one method. Under another store it runs only when that store has its `storeReady` group; a `sqliteOnly` route never does.
- *  `loop: 'off'` declares that the route's SQLite work runs on a worker thread, so its handler opens no hippo.db on the server thread. */
+/** One /v1 route: an exact path, a matchPath pattern, or a regex, each paired with one method's handler. Under another store it runs only with its
+ * store's `storeReady` group; `loop: 'off'` runs its SQLite work on a worker thread, so the handler opens no hippo.db on the server thread. */
 export type Route = {
     method: string;
     loop?: 'off';

package/dist/server/validation.d.ts

@@ -2,9 +2,11 @@ import type { IncomingMessage } from 'node:http';
 import type { Context, RememberOpts } from '../api/index.js';
 import { type JsonValue } from '../util/json.js';
 export declare function isSetMember<T extends string>(set: ReadonlySet<T>, value: string): value is T;
+export declare const MAX_SHORT_FIELD_LEN = 4096;
 export declare const MAX_LIST_LIMIT = 1000;
 export declare function parseListLimit(limitRaw: string | null, defaultLimit?: number, maxLimit?: number): number;
-/** `_authed` is proof the caller passed auth, so a full-size body is read only for an authenticated caller; the key mint reads first under its own small cap. */
+/** `_authed` is proof the caller passed auth, so a full-size body is read only for
+ * an authenticated caller; the key mint reads first under its own small cap. */
 export declare function parseJsonBody(req: IncomingMessage, _authed: Context): Promise<Record<string, JsonValue>>;
 export declare function parseJsonObjectText(raw: string): Record<string, JsonValue>;
 export declare function getString(obj: Record<string, JsonValue>, key: string): string | undefined;

package/dist/server/validation.js

@@ -1,18 +1,13 @@
 import { HttpError, MAX_ID_LEN, readBody } from '../util/http-util.js';
 import { isJsonString, isJsonObject } from '../util/json.js';
-// Runtime membership check for a `ReadonlySet<T>` of string-literal union
-// members, used at every `body` field validated against a VALID_* set below.
-// Set<T>.has(value: T) itself gives no narrowing (its parameter type is T,
-// not a type predicate) so callers previously needed a separate `as T` cast
-// at both the check and the later usage; this helper is the one place that
-// assertion lives, so downstream call sites narrow via the `value is T`
-// return instead of re-asserting.
+// Runtime membership check for a `ReadonlySet<T>` of string-literal members: Set<T>.has gives no narrowing, so this is the one place the `as T` assertion lives
+// and callers narrow via the `value is T` return.
 export function isSetMember(set, value) {
-    // SAFETY: `value as T` is discarded unless `set.has` (the real runtime
-    // check) confirms membership; the `value is T` return type is what
-    // performs the actual narrowing for callers.
+    // SAFETY: `value as T` is discarded unless `set.has` (the real runtime check) confirms membership; the `value is T` return type does the narrowing.
     return set.has(value);
 }
+// Cap for short free-text HTTP fields (names, text, context, change summaries) on the object routes.
+export const MAX_SHORT_FIELD_LEN = 4096;
 // Number.isInteger, not isFinite: SQLite `LIMIT ?` rejects "1.5" with a 500.
 // Shared by every first-class-object list route so the guard cannot drift.
 export const MAX_LIST_LIMIT = 1000;
@@ -25,7 +20,8 @@ export function parseListLimit(limitRaw, defaultLimit = 100, maxLimit = MAX_LIST
     }
     return limit;
 }
-/** `_authed` is proof the caller passed auth, so a full-size body is read only for an authenticated caller; the key mint reads first under its own small cap. */
+/** `_authed` is proof the caller passed auth, so a full-size body is read only for
+ * an authenticated caller; the key mint reads first under its own small cap. */
 export async function parseJsonBody(req, _authed) {
     return parseJsonObjectText(await readBody(req));
 }
@@ -72,18 +68,9 @@ export function getCallerProject(body) {
     }
     return { name: v.name, aliases: v.aliases };
 }
-/**
- * Charset + length validation for `:id` route captures. Routes call
- * this immediately after `matchPath` to reject empty / overlong / illegal
- * ids with a useful 400 instead of silently falling through to "not found".
- *
- * Allowed charset matches all production id shapes Hippo emits: `mem_<hex>`,
- * `sum_<hex>`, `sess-<id>`, Slack bot ids like `B01ABCD`, etc. The `:` and
- * `.` are allowed for forward-compat. The `/` is intentionally absent —
- * Hippo never emits ids with slashes, and `rejectEncodedSlash` already
- * stops `%2F`-smuggled ones at the front door.
- */
-const ID_SEGMENT_RE = /^[A-Za-z0-9_:.\-]+$/;
+/** Charset + length validation for `:id` captures, called right after `matchPath` so empty/overlong/illegal ids get a 400, not "not found".
+ * Allows every production id shape (`mem_<hex>`, `sess-<id>`, Slack ids) plus `:` and `.`; no `/`, since `rejectEncodedSlash` stops `%2F` smuggling. */
+const ID_SEGMENT_RE = /^[A-Za-z0-9_:.-]+$/;
 export function validateIdSegment(id, fieldName) {
     if (id.length === 0)
         throw new HttpError(400, `${fieldName} is required`);

package/dist/server.d.ts

@@ -35,12 +35,12 @@ export type { AmbientLoadResult, AmbientRecallRequest, ContextCandidateFilter, R
 export type { AmbientStoreFilter } from './store/ambient.js';
 export type { AmbientTallies } from './core/ambient.js';
 export type { TokenUse } from './store/token-ledger.js';
-export type { EmbeddingIndexState } from './store/embeddings/index.js';
+export type { EmbeddingIndexState } from './store/vector-index.js';
 export type { PhysicsParticle } from './core/physics.js';
 export { StoreBusyError } from './db/index.js';
 export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows, type VectorMatch, type VectorRow } from './db/vector-store.js';
 export { bufferToFloat32, float32ToBuffer } from './db/physics-state.js';
-export { replacesIndex } from './store/embeddings/index.js';
+export { replacesIndex } from './store/vector-index.js';
 export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from './store/recall-scope.js';
 export { SECRET_TAGS } from './util/secret-detect.js';
 export { tallyAmbientEntries } from './core/ambient.js';

package/dist/server.js

@@ -9,7 +9,8 @@ export { isCrossSite, LOOPBACK_HOST_HEADER } from './util/http-util.js';
 export { __resetSessionRecallHistoryHttp } from './server/routes/recall.js';
 export { clientIpForRateLimit } from './server/client-ip.js';
 export { isLoopback, isReservedActor } from './server/auth.js';
-// What an add-on route handler needs: HttpError for its 4xx replies, promptHookContext for a caller that renders the prompt hook elsewhere, JsonValue for its body.
+// What an add-on route handler needs: HttpError for its 4xx replies, promptHookContext
+// for a caller that renders the prompt hook elsewhere, JsonValue for its body.
 export { HttpError } from './util/http-util.js';
 export { promptHookContext } from './api/prompt-hook.js';
 // A session-end route stores the turns its caller read from a transcript on the caller's own machine.
@@ -26,7 +27,7 @@ export { StoreBusyError } from './db/index.js';
 // so both stores keep the same bytes and return the same ids in the same order.
 export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows } from './db/vector-store.js';
 export { bufferToFloat32, float32ToBuffer } from './db/physics-state.js';
-export { replacesIndex } from './store/embeddings/index.js';
+export { replacesIndex } from './store/vector-index.js';
 // An add-on's ContextReads applies hippo.db's scope, secret, tally and rarest-term rules with the same code.
 export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from './store/recall-scope.js';
 export { SECRET_TAGS } from './util/secret-detect.js';

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

@@ -0,0 +1,19 @@
+import { MemoryEntry } from '../core/memory.js';
+import type { DatabaseSyncLike } from '../db/index.js';
+/** Returns the path to the global Hippo store.
+ *  Resolution order: $HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo/ */
+export declare function getGlobalRoot(): string;
+/** Ensure the global store exists. */
+export declare function initGlobal(): void;
+/** Copies a local memory to the global store and returns the copy, which gets a new `g_` id so it cannot collide. */
+export declare function promoteToGlobal(localRoot: string, id: string, opts?: {
+    actor?: string;
+    tenantId?: string;
+    afterWrite?: (db: DatabaseSyncLike, globalId: string) => void;
+    /** Also writes one `promote` audit row for the copy ({sourceId}), in the copy's own transaction. */
+    auditAs?: {
+        tenantId: string;
+        actor: string;
+    };
+}): MemoryEntry;
+//# sourceMappingURL=global-store.d.ts.map

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/sharing/project-merge.d.ts

@@ -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/sharing/project-merge.js

@@ -115,7 +115,8 @@ 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))
@@ -187,7 +188,9 @@ function ownLegacyFold(db, hippoRoot, tenantId) {
     const { name, legacyName } = resolveProjectIdentity(path.dirname(path.resolve(hippoRoot)));
     if (legacyName === '' || legacyName === name)
         return [];
-    const held = holdsOrigin(db, 'memories', tenantId, legacyName) || holdsOrigin(db, 'compactions', tenantId, legacyName) || 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) {
@@ -253,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)
@@ -290,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;