hippo-memory 1.70.0 → 1.72.0

package/dist/core/physics.d.ts

@@ -1,14 +1,6 @@
-/**
- * Memory-as-Physics engine for Hippo.
- *
- * Pure math module: forces, Velocity Verlet integration, physics-based scoring,
- * and cluster amplification. No I/O — all state is passed in and returned.
- *
- * Memories are particles on the unit hypersphere in embedding space (384-dim).
- * Forces act on them: query gravity (retrieval), inter-memory attraction,
- * conflict repulsion, and drag (consolidation). Nearby high-scoring memories
- * amplify each other via constructive interference.
- */
+/** Memory-as-Physics engine: pure math (forces, Velocity Verlet integration, physics-based scoring, cluster amplification), no I/O.
+ * Memories are particles on the unit hypersphere in embedding space (384-dim); query gravity, attraction, conflict repulsion and drag act on them,
+ * and nearby high-scoring memories amplify each other. */
 import { type EmotionalValence } from './memory.js';
 import type { PhysicsConfig } from './physics-config.js';
 export interface PhysicsParticle {
@@ -51,42 +43,16 @@ export declare function vecClampMagnitude(v: number[], maxMag: number): number[]
 export declare function computeMass(strength: number, retrievalCount: number): number;
 export declare function computeCharge(valence: EmotionalValence): number;
 export declare function computeTemperature(ageDays: number, temperatureDecay: number): number;
-/**
- * Query gravity (retrieval-time, virtual — does not update position).
- * Returns scalar force magnitude for ranking.
- *
- * F_query(i) = G_Q * mass(i) * max(0, cosine(pos_i, query))^2
- */
+/** Query gravity (retrieval-time, virtual: does not move the particle): scalar ranking magnitude F = G_Q * mass * max(0, cosine(pos, query))^2. */
 export declare function queryGravityMagnitude(particle: PhysicsParticle, queryEmbedding: number[], G_query: number): number;
-/**
- * Momentum bonus: how aligned is the particle's velocity with the query direction?
- * Returns a value in [0, 1].
- */
+/** Momentum bonus in [0, 1]: how aligned the particle's velocity is with the query direction. */
 export declare function velocityAlignmentBonus(particle: PhysicsParticle, queryEmbedding: number[]): number;
-/**
- * Inter-memory attraction force vector (consolidation-time).
- * Attractive force from particle j on particle i.
- *
- * F_attract(i,j) = G_M * m_i * m_j * max(0, cosine(i,j))^3 * direction(j→i in embedding space)
- *
- * Direction is computed as the component of (pos_j - pos_i) that lies tangent to the
- * unit sphere at pos_i (since we normalize positions back to the sphere after integration).
- */
-export declare function attractionForce(pi: PhysicsParticle, pj: PhysicsParticle, G_memory: number): number[];
-/**
- * Conflict repulsion force vector (consolidation-time).
- * Repulsive force pushing i away from j.
- *
- * F_repel(i,j) = K_R * m_i * m_j / max(0.01, cosine_distance(i,j))^2
- * where cosine_distance = 1 - cosine_similarity
- */
+/** Attraction force on particle i from j (consolidation-time): G_M m_i m_j max(0, cosine)^3, directed along (pos_j - pos_i) projected tangent to the unit
+ * sphere at pos_i (positions are re-normalized to the sphere after integration). Adds into `out` (a fresh zero vector by default) using `diff` as scratch. */
+export declare function attractionForce(pi: PhysicsParticle, pj: PhysicsParticle, G_memory: number, out?: number[], diff?: number[]): number[];
+/** Conflict repulsion on i away from j (consolidation-time): K_R * m_i * m_j / max(0.01, cosine_distance)^2, where cosine_distance = 1 - cosine_similarity. */
 export declare function repulsionForce(pi: PhysicsParticle, pj: PhysicsParticle, K_repulsion: number): number[];
-/**
- * Drag force vector (consolidation-time).
- * F_drag(i) = -drag * velocity(i) / max(1, effective_half_life(i))
- *
- * effectiveHalfLife should be passed in from the memory's current half_life_days.
- */
+/** Drag force (consolidation-time): -drag * velocity / max(1, effectiveHalfLife), with effectiveHalfLife from the memory's current half_life_days. */
 export declare function dragForce(particle: PhysicsParticle, drag: number, effectiveHalfLife: number): number[];
 export interface ForceContext {
     /** Map of memory ID -> list of conflicting memory IDs */
@@ -95,26 +61,14 @@ export interface ForceContext {
     halfLives: Map<string, number>;
     config: PhysicsConfig;
 }
-/**
- * Run the full physics simulation for one sleep cycle.
- * Mutates particles in place. Returns simulation statistics.
- */
+/** Full physics simulation for one sleep cycle; mutates particles in place and returns simulation statistics. */
 export declare function simulate(particles: PhysicsParticle[], ctx: ForceContext): SimulationStats;
 export declare function computeSystemEnergy(particles: PhysicsParticle[], G_memory: number): SystemEnergy;
-/**
- * Score all particles against a query embedding using physics-based ranking.
- * Does NOT modify particle positions (virtual force computation).
- */
+/** Scores all particles against a query embedding; virtual force computation, so it does NOT modify particle positions. */
 export declare function physicsScore(particles: PhysicsParticle[], queryEmbedding: number[], config: PhysicsConfig, 
-/** Cross-ingest-stable tie key per memoryId (typically the memory's
- *  content, supplied by the caller which has entries in scope). Without
- *  it ties fall to memoryId -- per-instance only, which lets the
- *  cluster_top_k amplification set vary across fresh ingests. */
+/** Cross-ingest-stable tie key per memoryId (typically the memory content, from a caller with entries in scope); without it ties fall to memoryId,
+ *  which is per-instance only and lets the cluster_top_k amplification set vary across fresh ingests. */
 tieKeyOf?: (memoryId: string) => string): ScoredPhysicsResult[];
-/**
- * Nudge a particle's position toward (good outcome) or away from (bad outcome)
- * the query embedding. Respects temperature: new memories respond more.
- * Mutates particle in place.
- */
+/** Nudges a particle toward (good outcome) or away from (bad outcome) the query embedding; new memories respond more (temperature). Mutates in place. */
 export declare function applyOutcomeFeedback(particle: PhysicsParticle, queryEmbedding: number[], good: boolean, feedbackAlpha: number): void;
 //# sourceMappingURL=physics.d.ts.map

package/dist/core/physics.js

@@ -1,20 +1,10 @@
-/**
- * Memory-as-Physics engine for Hippo.
- *
- * Pure math module: forces, Velocity Verlet integration, physics-based scoring,
- * and cluster amplification. No I/O — all state is passed in and returned.
- *
- * Memories are particles on the unit hypersphere in embedding space (384-dim).
- * Forces act on them: query gravity (retrieval), inter-memory attraction,
- * conflict repulsion, and drag (consolidation). Nearby high-scoring memories
- * amplify each other via constructive interference.
- */
+/** Memory-as-Physics engine: pure math (forces, Velocity Verlet integration, physics-based scoring, cluster amplification), no I/O.
+ * Memories are particles on the unit hypersphere in embedding space (384-dim); query gravity, attraction, conflict repulsion and drag act on them,
+ * and nearby high-scoring memories amplify each other. */
+import { cosineOf } from './cosine.js';
 import { isRecallBoostAblated } from './ablation.js';
 import { FALLBACK_HALF_LIFE_DAYS } from './memory.js';
 import { comparePhysicsResultsBy } from './compare.js';
-// ---------------------------------------------------------------------------
-// Vector math (hot path — kept inline for performance)
-// ---------------------------------------------------------------------------
 export function vecDot(a, b) {
     let sum = 0;
     for (let i = 0; i < a.length; i++)
@@ -25,25 +15,25 @@ export function vecNorm(v) {
     return Math.sqrt(vecDot(v, v));
 }
 export function vecScale(v, s) {
-    const out = new Array(v.length);
+    const out = v.slice();
     for (let i = 0; i < v.length; i++)
         out[i] = v[i] * s;
     return out;
 }
 export function vecAdd(a, b) {
-    const out = new Array(a.length);
+    const out = a.slice();
     for (let i = 0; i < a.length; i++)
         out[i] = a[i] + b[i];
     return out;
 }
 export function vecSub(a, b) {
-    const out = new Array(a.length);
+    const out = a.slice();
     for (let i = 0; i < a.length; i++)
         out[i] = a[i] - b[i];
     return out;
 }
 export function vecZero(dim) {
-    return new Array(dim).fill(0);
+    return Array(dim).fill(0);
 }
 /** Normalize to unit length. Returns zero vector if magnitude < epsilon. */
 export function vecNormalize(v) {
@@ -59,20 +49,6 @@ export function vecClampMagnitude(v, maxMag) {
         return v;
     return vecScale(v, maxMag / mag);
 }
-/** Cosine similarity between two vectors. */
-function cosine(a, b) {
-    if (a.length === 0 || b.length === 0 || a.length !== b.length)
-        return 0;
-    const dot = vecDot(a, b);
-    const na = vecNorm(a);
-    const nb = vecNorm(b);
-    if (na < 1e-10 || nb < 1e-10)
-        return 0;
-    return Math.min(1, Math.max(-1, dot / (na * nb)));
-}
-// ---------------------------------------------------------------------------
-// Property derivation from memory attributes
-// ---------------------------------------------------------------------------
 const CHARGE_MAP = {
     neutral: 0,
     positive: 0.3,
@@ -80,9 +56,8 @@ const CHARGE_MAP = {
     critical: -1.0,
 };
 export function computeMass(strength, retrievalCount) {
-    // EVAL-ONLY ablation (see ablation.ts): under the recall-boost flag mass ignores retrieval history, since
-    // query gravity ranks by mass and prior counts would leak strengthening into the ablated arm's
-    // physics-pool rankings. Covers both the init and refresh callers in physics-state.ts.
+    // EVAL-ONLY ablation (ablation.ts): under the recall-boost flag mass ignores retrieval history, which would otherwise leak strengthening into the ablated
+    // arm's physics-pool rankings (query gravity ranks by mass). Covers both init and refresh callers in physics-state.ts.
     const effectiveCount = isRecallBoostAblated() ? 0 : retrievalCount;
     return Math.max(0.01, strength * (1 + 0.1 * Math.log2(effectiveCount + 1)));
 }
@@ -92,23 +67,12 @@ export function computeCharge(valence) {
 export function computeTemperature(ageDays, temperatureDecay) {
     return 1 / (ageDays * temperatureDecay + 1);
 }
-// ---------------------------------------------------------------------------
-// Force computations
-// ---------------------------------------------------------------------------
-/**
- * Query gravity (retrieval-time, virtual — does not update position).
- * Returns scalar force magnitude for ranking.
- *
- * F_query(i) = G_Q * mass(i) * max(0, cosine(pos_i, query))^2
- */
+/** Query gravity (retrieval-time, virtual: does not move the particle): scalar ranking magnitude F = G_Q * mass * max(0, cosine(pos, query))^2. */
 export function queryGravityMagnitude(particle, queryEmbedding, G_query) {
-    const cos = cosine(particle.position, queryEmbedding);
+    const cos = cosineOf(particle.position, queryEmbedding);
     return G_query * particle.mass * Math.pow(Math.max(0, cos), 2);
 }
-/**
- * Momentum bonus: how aligned is the particle's velocity with the query direction?
- * Returns a value in [0, 1].
- */
+/** Momentum bonus in [0, 1]: how aligned the particle's velocity is with the query direction. */
 export function velocityAlignmentBonus(particle, queryEmbedding) {
     if (particle.velocity.length === 0 || particle.velocity.length !== queryEmbedding.length)
         return 0;
@@ -119,79 +83,71 @@ export function velocityAlignmentBonus(particle, queryEmbedding) {
     const alignment = vecDot(particle.velocity, queryEmbedding) / (velMag * qNorm);
     return Math.max(0, alignment);
 }
-/**
- * Inter-memory attraction force vector (consolidation-time).
- * Attractive force from particle j on particle i.
- *
- * F_attract(i,j) = G_M * m_i * m_j * max(0, cosine(i,j))^3 * direction(j→i in embedding space)
- *
- * Direction is computed as the component of (pos_j - pos_i) that lies tangent to the
- * unit sphere at pos_i (since we normalize positions back to the sphere after integration).
- */
-export function attractionForce(pi, pj, G_memory) {
-    const cos = cosine(pi.position, pj.position);
+/** Attraction force on particle i from j (consolidation-time): G_M m_i m_j max(0, cosine)^3, directed along (pos_j - pos_i) projected tangent to the unit
+ * sphere at pos_i (positions are re-normalized to the sphere after integration). Adds into `out` (a fresh zero vector by default) using `diff` as scratch. */
+export function attractionForce(pi, pj, G_memory, out = vecZero(pi.position.length), diff = vecZero(pi.position.length)) {
+    const cos = cosineOf(pi.position, pj.position);
     if (cos <= 0)
-        return vecZero(pi.position.length);
+        return out;
     const magnitude = G_memory * pi.mass * pj.mass * Math.pow(cos, 3);
     // Direction: from i toward j (tangent projection handled by normalization after integration)
-    const direction = vecNormalize(vecSub(pj.position, pi.position));
-    return vecScale(direction, magnitude);
+    for (let k = 0; k < out.length; k++)
+        diff[k] = pj.position[k] - pi.position[k];
+    const norm = vecNorm(diff);
+    if (norm < 1e-10)
+        return out;
+    const inv = 1 / norm;
+    for (let k = 0; k < out.length; k++)
+        out[k] += diff[k] * inv * magnitude;
+    return out;
 }
-/**
- * Conflict repulsion force vector (consolidation-time).
- * Repulsive force pushing i away from j.
- *
- * F_repel(i,j) = K_R * m_i * m_j / max(0.01, cosine_distance(i,j))^2
- * where cosine_distance = 1 - cosine_similarity
- */
+/** Conflict repulsion on i away from j (consolidation-time): K_R * m_i * m_j / max(0.01, cosine_distance)^2, where cosine_distance = 1 - cosine_similarity. */
 export function repulsionForce(pi, pj, K_repulsion) {
-    const cos = cosine(pi.position, pj.position);
+    const cos = cosineOf(pi.position, pj.position);
     const dist = Math.max(0.01, 1 - cos);
     const magnitude = K_repulsion * pi.mass * pj.mass / (dist * dist);
     // Direction: away from j
     const direction = vecNormalize(vecSub(pi.position, pj.position));
     return vecScale(direction, magnitude);
 }
-/**
- * Drag force vector (consolidation-time).
- * F_drag(i) = -drag * velocity(i) / max(1, effective_half_life(i))
- *
- * effectiveHalfLife should be passed in from the memory's current half_life_days.
- */
+/** Drag force (consolidation-time): -drag * velocity / max(1, effectiveHalfLife), with effectiveHalfLife from the memory's current half_life_days. */
 export function dragForce(particle, drag, effectiveHalfLife) {
     const damping = drag / Math.max(1, effectiveHalfLife);
     return vecScale(particle.velocity, -damping);
 }
-/**
- * Compute net force on particle i from all other particles + drag.
- */
-function computeNetForce(i, particles, ctx) {
+function addInto(net, force) {
+    for (let k = 0; k < net.length; k++)
+        net[k] += force[k];
+}
+/** The net force on particle i, accumulated into one new array; `diff` is the caller's scratch for pair directions. */
+function computeNetForce(i, particles, ctx, diff) {
     const pi = particles[i];
     const dim = pi.position.length;
-    let net = vecZero(dim);
+    const net = vecZero(dim);
     const conflicts = ctx.conflictPairs.get(pi.memoryId);
     for (let j = 0; j < particles.length; j++) {
         if (i === j)
             continue;
         const pj = particles[j];
         // Attraction (all pairs)
-        const fa = attractionForce(pi, pj, ctx.config.G_memory);
-        net = vecAdd(net, fa);
+        attractionForce(pi, pj, ctx.config.G_memory, net, diff);
         // Repulsion (conflict pairs only)
-        if (conflicts?.has(pj.memoryId)) {
-            const fr = repulsionForce(pi, pj, ctx.config.K_repulsion);
-            net = vecAdd(net, fr);
-        }
+        if (conflicts?.has(pj.memoryId))
+            addInto(net, repulsionForce(pi, pj, ctx.config.K_repulsion));
     }
     // Drag
-    const fd = dragForce(pi, ctx.config.drag, ctx.halfLives.get(pi.memoryId) ?? FALLBACK_HALF_LIFE_DAYS);
-    net = vecAdd(net, fd);
+    addInto(net, dragForce(pi, ctx.config.drag, ctx.halfLives.get(pi.memoryId) ?? FALLBACK_HALF_LIFE_DAYS));
     return net;
 }
-/**
- * Run one Velocity Verlet integration step for all particles.
- * Mutates particles in place for performance.
- */
+/** Acceleration of particle i: its net force divided by mass, scaled in place. */
+function computeAcceleration(i, particles, ctx, diff) {
+    const accel = computeNetForce(i, particles, ctx, diff);
+    const inv = 1 / Math.max(0.01, particles[i].mass);
+    for (let k = 0; k < accel.length; k++)
+        accel[k] *= inv;
+    return accel;
+}
+/** One Velocity Verlet step for all particles; mutates in place for performance. */
 function verletStep(particles, accelerations, ctx) {
     const dt = ctx.config.dt;
     const maxVel = ctx.config.max_velocity;
@@ -203,11 +159,10 @@ function verletStep(particles, accelerations, ctx) {
         p.position = vecAdd(vecAdd(p.position, velDt), accelDt2);
     }
     // Compute new accelerations
+    const diff = vecZero(particles[0].position.length);
     const newAccelerations = [];
-    for (let i = 0; i < particles.length; i++) {
-        const force = computeNetForce(i, particles, ctx);
-        newAccelerations.push(vecScale(force, 1 / Math.max(0.01, particles[i].mass)));
-    }
+    for (let i = 0; i < particles.length; i++)
+        newAccelerations.push(computeAcceleration(i, particles, ctx, diff));
     // Velocity update: vel += 0.5*(accel_old + accel_new)*dt
     for (let i = 0; i < particles.length; i++) {
         const p = particles[i];
@@ -222,10 +177,7 @@ function verletStep(particles, accelerations, ctx) {
         accelerations[i] = newAccelerations[i];
     }
 }
-/**
- * Run the full physics simulation for one sleep cycle.
- * Mutates particles in place. Returns simulation statistics.
- */
+/** Full physics simulation for one sleep cycle; mutates particles in place and returns simulation statistics. */
 export function simulate(particles, ctx) {
     if (particles.length === 0) {
         return {
@@ -237,10 +189,8 @@ export function simulate(particles, ctx) {
         };
     }
     // Initial accelerations
-    const accelerations = particles.map((_, i) => {
-        const force = computeNetForce(i, particles, ctx);
-        return vecScale(force, 1 / Math.max(0.01, particles[i].mass));
-    });
+    const diff = vecZero(particles[0].position.length);
+    const accelerations = particles.map((_, i) => computeAcceleration(i, particles, ctx, diff));
     // Run substeps
     for (let step = 0; step < ctx.config.substeps; step++) {
         verletStep(particles, accelerations, ctx);
@@ -268,9 +218,6 @@ export function simulate(particles, ctx) {
         substepsRun: ctx.config.substeps,
     };
 }
-// ---------------------------------------------------------------------------
-// System energy (health monitoring)
-// ---------------------------------------------------------------------------
 export function computeSystemEnergy(particles, G_memory) {
     let kinetic = 0;
     let potential = 0;
@@ -280,24 +227,16 @@ export function computeSystemEnergy(particles, G_memory) {
     }
     for (let i = 0; i < particles.length; i++) {
         for (let j = i + 1; j < particles.length; j++) {
-            const cos = cosine(particles[i].position, particles[j].position);
+            const cos = cosineOf(particles[i].position, particles[j].position);
             potential -= G_memory * particles[i].mass * particles[j].mass * Math.max(0, cos);
         }
     }
     return { kinetic, potential, total: kinetic + potential };
 }
-// ---------------------------------------------------------------------------
-// Physics-based scoring (retrieval-time)
-// ---------------------------------------------------------------------------
-/**
- * Score all particles against a query embedding using physics-based ranking.
- * Does NOT modify particle positions (virtual force computation).
- */
+/** Scores all particles against a query embedding; virtual force computation, so it does NOT modify particle positions. */
 export function physicsScore(particles, queryEmbedding, config, 
-/** Cross-ingest-stable tie key per memoryId (typically the memory's
- *  content, supplied by the caller which has entries in scope). Without
- *  it ties fall to memoryId -- per-instance only, which lets the
- *  cluster_top_k amplification set vary across fresh ingests. */
+/** Cross-ingest-stable tie key per memoryId (typically the memory content, from a caller with entries in scope); without it ties fall to memoryId,
+ *  which is per-instance only and lets the cluster_top_k amplification set vary across fresh ingests. */
 tieKeyOf) {
     if (particles.length === 0 || queryEmbedding.length === 0)
         return [];
@@ -312,10 +251,8 @@ tieKeyOf) {
             finalScore: gravity + momentum,
         };
     });
-    // Sort by base score for top-K selection: score desc -> tie key asc.
-    // The tie order here picks the cluster_top_k amplification SET (which
-    // mutates scores), so it must be cross-ingest-stable when the caller
-    // supplies a content tie key. See compare.ts comparePhysicsResultsBy.
+    // Base-score order picks the cluster_top_k amplification SET (which mutates scores), so ties must be cross-ingest-stable
+    // when the caller supplies a content tie key (see comparePhysicsResultsBy in compare.ts).
     const tie = tieKeyOf ? (r) => tieKeyOf(r.memoryId) : undefined;
     results.sort(comparePhysicsResultsBy((r) => r.baseScore, tie));
     // Pass 2: cluster amplification on top K
@@ -324,10 +261,7 @@ tieKeyOf) {
     results.sort(comparePhysicsResultsBy((r) => r.finalScore, tie));
     return results;
 }
-/**
- * Cluster amplification: nearby high-scoring memories reinforce each other.
- * Mutates results in place.
- */
+/** Cluster amplification: nearby high-scoring memories reinforce each other; mutates results in place. */
 function applyClusterAmplification(results, particles, config) {
     const topK = Math.min(config.cluster_top_k, results.length);
     if (topK < 2)
@@ -348,7 +282,7 @@ function applyClusterAmplification(results, particles, config) {
             const pj = particleMap.get(top[j].memoryId);
             if (!pj)
                 continue;
-            const proximity = cosine(pi.position, pj.position);
+            const proximity = cosineOf(pi.position, pj.position);
             if (proximity > config.cluster_threshold) {
                 clusterSignal += top[j].baseScore * proximity;
             }
@@ -358,14 +292,7 @@ function applyClusterAmplification(results, particles, config) {
         top[i].finalScore = top[i].baseScore * amplification;
     }
 }
-// ---------------------------------------------------------------------------
-// Outcome feedback (micro-nudge)
-// ---------------------------------------------------------------------------
-/**
- * Nudge a particle's position toward (good outcome) or away from (bad outcome)
- * the query embedding. Respects temperature: new memories respond more.
- * Mutates particle in place.
- */
+/** Nudges a particle toward (good outcome) or away from (bad outcome) the query embedding; new memories respond more (temperature). Mutates in place. */
 export function applyOutcomeFeedback(particle, queryEmbedding, good, feedbackAlpha) {
     if (particle.position.length === 0 || particle.position.length !== queryEmbedding.length)
         return;

package/dist/core/prediction.d.ts

@@ -0,0 +1,3 @@
+export type ClosureState = 'open' | 'closed' | 'closed-unknown';
+export declare const VALID_CLOSURE_STATES: ReadonlySet<ClosureState>;
+//# sourceMappingURL=prediction.d.ts.map

package/dist/core/prediction.js

@@ -0,0 +1,6 @@
+export const VALID_CLOSURE_STATES = new Set([
+    'open',
+    'closed',
+    'closed-unknown',
+]);
+//# sourceMappingURL=prediction.js.map

package/dist/core/project-identity.d.ts

@@ -1,22 +1,5 @@
-/**
- * Project identity resolution for memory scope isolation.
- *
- * Resolution rules:
- * - The nearest ancestor of cwd (including cwd itself) containing a `.hippo`
- *   directory is the project root; if none exists, the nearest ancestor
- *   containing `.git` (directory or worktree file).
- * - The user home directory is NEVER a project, even though it contains the
- *   global store at `~/.hippo`. Reaching home or the temp root (inside home on Windows) ends the walk.
- * - A directory with no marker anywhere up the walk is NOT a project: it
- *   resolves to the user-global identity (empty name), so memories written
- *   there stay injectable everywhere (matches pre-isolation behavior).
- * - A project's name is its id: `.hippo-project.json` at the root, else the
- *   checkout's normalised `origin` remote, else the folder rule (legacyName),
- *   so two repos in folders of one name stay apart.
- *
- * NOTE: this module must stay free of imports from shared.ts / store.ts /
- * api.ts so any of them can import it without creating a cycle.
- */
+/** Project = nearest ancestor of cwd with `.hippo` (else `.git`); home and the temp root never are, and no marker means user-global (empty name).
+ * Name: `.hippo-project.json`, else the normalised `origin`, else the folder name. Must not import shared.ts / store.ts / api/index.ts (cycle). */
 /** The project a working directory belongs to. */
 export interface ProjectIdentity {
     /** Realpath-resolved root directory of the project (the start dir when not in a project). */
@@ -25,30 +8,28 @@ export interface ProjectIdentity {
     name: string;
     /** The folder rule rows written before ids carry: the root's lowercased basename, or its repo's for a linked worktree with no `.hippo`. */
     legacyName: string;
-    /** Every other name this root resolves to (the project file id, the origin remote even with the rule off, legacyName), so rows written under an earlier id stay readable. */
+    /** Every other name this root resolves to (the project file id, the origin remote even
+     * with the rule off, legacyName), so rows written under an earlier id stay readable. */
     aliases?: readonly string[];
     /** True when the directory resolves to the user home working set. */
     isHome: boolean;
 }
-/**
- * Options for resolveProjectIdentity. Both fields are test seams; results are
- * not cached when either is set. stopDir bounds the upward walk so tests in a
- * temp sandbox never escape it and hit the host machine's real markers.
- */
+/** Options for resolveProjectIdentity. Both fields are test seams and disable caching;
+ * stopDir bounds the upward walk so tests in a temp sandbox never reach the host's real markers. */
 export interface ResolveProjectIdentityOpts {
     homeDir?: string;
     stopDir?: string;
 }
 /** Clear the per-process identity cache and the remote switch it read (test seam). */
 export declare function clearProjectIdentityCache(): void;
-/**
- * Resolve the project identity for a working directory.
- * Defaults to process.cwd(). Results are cached per resolved input path.
- */
+/** Resolves the project identity for a working directory (default process.cwd()); results are cached per resolved input path. */
 export declare function resolveProjectIdentity(cwd?: string, opts?: ResolveProjectIdentityOpts): ProjectIdentity;
 /** Nearest ancestor `.hippo` below home and the temp root (never projects; on Windows the temp root sits inside home).
  *  Everything is realpath'd so a symlinked temp root or cwd still matches its bound. */
 export declare function findHippoStoreDir(cwd?: string, opts?: ResolveProjectIdentityOpts): string | null;
+/** Nearest ancestor store like git; the strict join is the fallback so `hippo init` still creates `<cwd>/.hippo`. */
+export declare function getHippoRoot(cwd?: string, opts?: ResolveProjectIdentityOpts): string;
+export declare function isInitialized(hippoRoot: string): boolean;
 /** A reader's project: a bare name, or an identity whose own rows may also carry its legacy folder name. */
 export type ProjectRef = string | Pick<ProjectIdentity, 'name' | 'legacyName' | 'aliases'>;
 /** The id a reader's new rows are stamped with; '' outside a project. */
@@ -57,44 +38,25 @@ export declare function projectId(project: ProjectRef): string;
 export declare function projectNames(project: ProjectRef): readonly string[];
 export declare const MAX_PROJECT_ALIASES = 10;
 export declare const MCP_PROJECT_SCOPED_HEADER = "X-Hippo-Project-Scoped";
-/** Refuses a caller's project that is blank (it would stamp user-global), past the caps, or unlike the resolver's ids: rows match verbatim, so a rewrite would split a project. Inner spaces pass, since a checkout with no remote is named by its folder. */
+/** Refuses a caller's project that is blank (it would stamp user-global), past the caps, or unlike the resolver's ids: rows match
+ * verbatim, so a rewrite would split a project. Inner spaces pass, since a checkout with no remote is named by its folder. */
 export declare function assertCallerProject(project: {
     readonly name: string;
     readonly aliases?: readonly string[];
 }): void;
 /** `origin_project IN (?, ...)` with one placeholder per name; an empty list matches nothing. */
 export declare function originInSql(names: readonly string[], column?: string): string;
-/**
- * v39 memory scope isolation: classify a memory's origin_project against the
- * active project. An empty current id means the session is not in a project
- * (home dir or markerless cwd) - everything is in scope there, matching
- * pre-isolation behavior. NULL/undefined origin means no known project (a legacy
- * row, or a shared-store write that named none) and is treated as cross-project
- * (deny by default) - the safe direction for a security partition.
- */
+/** Classifies a memory's origin_project against the active project. An empty current id (home or markerless cwd) puts everything in scope;
+ * NULL/undefined origin (legacy row, or a shared-store write naming none) counts as cross-project: deny by default for a security partition. */
 export declare function classifyOriginProject(origin: string | null | undefined, current: ProjectRef): 'project' | 'user-global' | 'cross-project';
-/**
- * The global Hippo store directory, resolved the same way shared.ts does:
- * $HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo. Lives here (leaf module) so
- * db.ts migrations can use it without importing shared.ts (store.ts cycle);
- * shared.getGlobalRoot delegates to this.
- */
+/** The global Hippo store directory ($HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo); getGlobalRoot (sharing/global-store.ts) returns it.
+ * Leaf module so store migrations can use it without importing sharing/ (store cycle). */
 export declare function resolveGlobalRootDir(): string;
-/**
- * True when `p` IS the global store root. Used by the v39 migration so a
- * global store whose parent chain happens to contain `.git`/`.hippo`
- * (git-managed HIPPO_HOME, dotfiles setups) still backfills as user-global
- * ('') instead of being stamped with the surrounding repo's name - which
- * would hide the user's entire global corpus from every project.
- */
+/** True when `p` IS the global store root, so a global store whose parent chain contains `.git`/`.hippo` (git-managed HIPPO_HOME) still backfills as
+ * user-global ('') instead of being stamped with the surrounding repo's name, which would hide the global corpus from every project. */
 export declare function isGlobalStoreRoot(p: string): boolean;
-/**
- * Parse a memory's origin from its provenance `source` string, mirroring the
- * v39 migration's evidence rules: `shared:<project>:<ts>` and
- * `promoted:<localRoot>` identify the owning project; the user home dir's
- * basename maps to '' (user-global). Returns null when the source carries no
- * origin evidence. Pure string logic - recorded paths may no longer exist.
- */
+/** Parses a memory's origin from its provenance `source`: `shared:<project>:<ts>` and `promoted:<localRoot>` name the owning project; the home dir basename
+ * maps to '' (user-global). Returns null without origin evidence. Pure string logic, since recorded paths may no longer exist. */
 export declare function originFromSource(source: string | null | undefined, homeName?: string): string | null;
 /** The origin to stamp on a memory written from cwd: its project name, or '' (user-global, injectable everywhere) outside a project.
  *  NULL means no known project: a legacy row with no evidence, or a write to a shared store that named none; ambient context treats it as deny. */