hippo-memory 1.63.2 → 1.64.0

package/dist/http-util.js

@@ -11,50 +11,95 @@ export function isHeaderString(value) {
 // 1 MB body cap. The CLI never sends payloads near this; anything bigger is
 // almost certainly a misconfigured client or a deliberate memory-blowup attempt.
 const MAX_BODY_BYTES = 1024 * 1024;
+function sizeLabel(bytes) {
+    return bytes % (1024 * 1024) === 0 ? `${bytes / (1024 * 1024)}MB` : `${Math.ceil(bytes / 1024)}KB`;
+}
+// How long a refused upload is still read and discarded after its reply, so a client that never stops cannot hold the socket.
+const REFUSED_UPLOAD_LINGER_MS = 2000;
 // Cap for id-shaped request fields (ids, tenant, session, scope, class): far above real values, small enough to bound logs and indexes.
 export const MAX_ID_LEN = 256;
 export const JSON_HEADERS = { 'content-type': 'application/json' };
 export class HttpError extends Error {
     status;
-    constructor(status, message) {
+    /** Sent as the Retry-After header, so a refused caller knows when to come back. */
+    retryAfterSec;
+    constructor(status, message, retryAfterSec) {
         super(message);
         this.status = status;
+        this.retryAfterSec = retryAfterSec;
     }
 }
 export class BodyTooLargeError extends Error {
 }
+/** The body did not arrive in time. Its own class so mapApiError answers 408 and the server drops the socket. */
+export class BodyTimeoutError extends Error {
+}
 export const INTERNAL_ERROR_MESSAGE = 'internal server error';
 /** Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server log. */
 export function mapApiError(err) {
+    // An add-on can build an HttpError from any number, and writeHead throws on one outside 100-999.
+    if (err instanceof HttpError && !(Number.isInteger(err.status) && err.status >= 100 && err.status <= 999)) {
+        return { status: 500, message: INTERNAL_ERROR_MESSAGE };
+    }
     if (err instanceof HttpError || err instanceof ApiError)
         return { status: err.status, message: err.message };
     if (err instanceof BodyTooLargeError)
         return { status: 413, message: err.message };
+    if (err instanceof BodyTimeoutError)
+        return { status: 408, message: err.message };
     return { status: 500, message: INTERNAL_ERROR_MESSAGE };
 }
+/** Serialises before the head goes out, so a body that is not JSON still reaches the caller's error reply. */
 export function sendJson(res, status, body) {
+    const text = JSON.stringify(body);
+    if (text === undefined)
+        throw new Error('response body is not JSON');
     res.writeHead(status, JSON_HEADERS);
-    res.end(JSON.stringify(body));
+    res.end(text);
 }
-/**
- * Read the entire request body into a Buffer. Caps at MAX_BODY_BYTES to keep
- * a malicious or buggy client from exhausting memory. The cap is enforced
- * mid-stream so we don't wait for an attacker to finish before erroring out.
- */
-export async function readBody(req) {
-    const chunks = [];
-    let total = 0;
-    for await (const chunk of req) {
-        // SAFETY: IncomingMessage never runs setEncoding() here, so every
-        // streamed chunk is a Buffer, not a decoded string.
-        const buf = chunk;
-        total += buf.length;
-        if (total > MAX_BODY_BYTES) {
-            throw new BodyTooLargeError('request body exceeds 1MB');
+/** The body as text, refused mid-stream past maxBytes and past deadlineMs, so an oversized or slow sender cannot tie up the server. */
+export function readBody(req, { maxBytes = MAX_BODY_BYTES, deadlineMs } = {}) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        let timer;
+        const refuse = (err) => {
+            clearTimeout(timer);
+            req.off('data', onData);
+            chunks.length = 0;
+            reject(err);
+        };
+        // Not for-await: leaving that loop early destroys the request, so the socket stops reading and the 413 caller cannot close it cleanly.
+        const onData = (chunk) => {
+            total += chunk.length;
+            if (total <= maxBytes) {
+                chunks.push(chunk);
+                return;
+            }
+            refuse(new BodyTooLargeError(`request body exceeds ${sizeLabel(maxBytes)}`));
+        };
+        if (deadlineMs !== undefined) {
+            timer = setTimeout(() => refuse(new BodyTimeoutError(`request body not received within ${deadlineMs} ms`)), deadlineMs);
         }
-        chunks.push(buf);
-    }
-    return Buffer.concat(chunks).toString('utf8');
+        req.on('data', onData);
+        req.once('end', () => {
+            clearTimeout(timer);
+            resolve(Buffer.concat(chunks).toString('utf8'));
+        });
+        req.on('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+// A full close with request bytes unread sends a TCP reset, which discards the reply before the client reads it (RFC 9112 9.6).
+export function closeAfterReply(req) {
+    const socket = req.socket;
+    req.resume();
+    socket.end();
+    const timer = setTimeout(() => socket.destroy(), REFUSED_UPLOAD_LINGER_MS);
+    timer.unref();
+    socket.once('close', () => clearTimeout(timer));
 }
 // Any other Host on a loopback socket is DNS rebinding: a hostile page resolved to 127.0.0.1.
 export const LOOPBACK_HOST_HEADER = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i;

package/dist/importers/vault.js

@@ -4,6 +4,7 @@ import { createHash } from 'node:crypto';
 import { createMemory } from '../memory.js';
 import { initStore } from '../store/open.js';
 import { remember, archiveRaw, isPrivateScope } from '../api.js';
+import { assertClientScope } from '../recall-scope.js';
 import { openHippoDb, closeHippoDb } from '../db.js';
 import { RejectedValueError, checkRejectionGuard } from '../rejection.js';
 import { loadConfig } from '../config.js';
@@ -118,6 +119,7 @@ function vaultIdentityOrThrow(options) {
     // isPrivateScope as the single source of truth: reject a scope that names a
     // `private` segment yet is NOT a valid `<source>:private:*` (catches `private`,
     // `private:x`, and `vault:private` with a missing trailing segment).
+    assertClientScope(scope);
     if (scope !== null && scope.split(':').includes('private') && !isPrivateScope(scope)) {
         throw new Error(`vault scope '${scope}' is not recognized as private by recall (only '<source>:private:*' scopes are default-denied). Use a source-prefixed scope such as 'vault:private:${vaultName}'.`);
     }

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { loadAllEntries, readEntry } from './store/entry-reads.js';
 export { deleteEntry } from './store/delete-and-batch.js';
 export { loadSearchEntries, loadRecallSearchEntries } from './store/search-rows.js';
 export { loadIndex, rebuildIndex, loadSessionDecayContext, SessionDecayContext } from './store/index-and-stats.js';
-export { saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, } from './store/sessions.js';
+export { saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, type ContinuityKey, } from './store/sessions.js';
 export { listMemoryConflicts, replaceDetectedConflicts, resolveConflict } from './store/conflicts.js';
 export { saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, } from './store/handoffs.js';
 export { createCard, loadCard, listCards, loadCardDeps, loadCardRuns, loadCardComments, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, loadLatestHandoffForCard, } from './store-cards.js';
@@ -30,6 +30,7 @@ export { SessionHandoff, HandoffOutcome, HandoffEvidence, isHandoffOutcome } fro
 export { Card, CardStatus, CardRun, CardComment, CardTransitions, isCardStatus, CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
 export { consolidate } from './consolidate/sleep.js';
 export { ConsolidationResult } from './consolidate/run.js';
+export { sleep, type SleepOpts, type SleepResult } from './api/sleep.js';
 export { strengthBucket } from './dedupe.js';
 export { isEmbeddingAvailable, getEmbedding } from './local-embedding.js';
 export { cosineSimilarity, loadEmbeddingIndex, saveEmbeddingIndex, embedMemory, embedAll, } from './embeddings.js';

package/dist/index.js

@@ -32,6 +32,7 @@ export { isHandoffOutcome } from './handoff.js';
 // W2a: work-queue cards
 export { isCardStatus, CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
 export { consolidate } from './consolidate/sleep.js';
+export { sleep } from './api/sleep.js';
 // Announced public in CHANGELOG 1.26.3 but never re-exported; the rest of dedupe.js stays internal.
 export { strengthBucket } from './dedupe.js';
 // Feature 1: Embedding search

package/dist/json.d.ts

@@ -2,4 +2,6 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 export declare function isJsonString(value: JsonValue | undefined): value is string;
+/** Windows PowerShell 5.1 saves JSON with a UTF-8 byte order mark that JSON.parse rejects, so one leading mark is dropped. */
+export declare function readJsonFile(file: string): JsonValue;
 //# sourceMappingURL=json.d.ts.map

package/dist/json.js

@@ -1,4 +1,11 @@
+// Leaf module: the one value space JSON.parse can produce, so boundary guards narrow a shared type.
+import * as fs from 'fs';
 export function isJsonString(value) {
     return typeof value === 'string';
 }
+/** Windows PowerShell 5.1 saves JSON with a UTF-8 byte order mark that JSON.parse rejects, so one leading mark is dropped. */
+export function readJsonFile(file) {
+    const text = fs.readFileSync(file, 'utf8');
+    return JSON.parse(text.codePointAt(0) === 0xfeff ? text.slice(1) : text);
+}
 //# sourceMappingURL=json.js.map

package/dist/ledger-db.d.ts

@@ -0,0 +1,10 @@
+import { openHippoDb } from './db.js';
+export interface LedgerRootOpts {
+    /** The store serves many people, so the global store of the user running it belongs to none of them. */
+    readonly sharedStore?: boolean;
+}
+/** `hippoRoot` when it holds a store, else the global store (the prompt hook fires where no local one exists), else null. */
+export declare function ledgerRoot(hippoRoot: string, opts?: LedgerRootOpts): string | null;
+/** Runs `fn` on ledgerRoot's store. Best-effort: undefined on any failure, because a ledger failure must not break context or recall. */
+export declare function withLedgerDb<T>(hippoRoot: string, fn: (db: ReturnType<typeof openHippoDb>) => T, opts?: LedgerRootOpts): T | undefined;
+//# sourceMappingURL=ledger-db.d.ts.map

package/dist/ledger-db.js

@@ -0,0 +1,42 @@
+// The store the token ledger writes to for a caller's root; context, recall and the session hooks share it.
+import { closeHippoDb, isSqliteBusy, noteStoreBusy, openHippoDb } from './db.js';
+import { getGlobalRoot } from './shared.js';
+import { isInitialized } from './store/open.js';
+/** `hippoRoot` when it holds a store, else the global store (the prompt hook fires where no local one exists), else null. */
+export function ledgerRoot(hippoRoot, opts) {
+    if (isInitialized(hippoRoot))
+        return hippoRoot;
+    if (opts?.sharedStore)
+        return null;
+    const globalRoot = getGlobalRoot();
+    return isInitialized(globalRoot) ? globalRoot : null;
+}
+/** Runs `fn` on ledgerRoot's store. Best-effort: undefined on any failure, because a ledger failure must not break context or recall. */
+export function withLedgerDb(hippoRoot, fn, opts) {
+    let root = null;
+    try {
+        root = ledgerRoot(hippoRoot, opts);
+    }
+    catch {
+        // An unreadable store root means no ledger write; the ledger must never break context or recall.
+        return undefined;
+    }
+    if (root === null)
+        return undefined;
+    let db;
+    try {
+        db = openHippoDb(root);
+        return fn(db);
+    }
+    catch (error) {
+        // Best effort, but a busy store is the one failure an operator can act on, so it warns once.
+        if (isSqliteBusy(error))
+            noteStoreBusy('token ledger row skipped');
+        return undefined;
+    }
+    finally {
+        if (db)
+            closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=ledger-db.js.map

package/dist/mcp/admin-tools.d.ts

@@ -1,8 +1,8 @@
 import { type ToolCall } from './protocol.js';
 export declare function runPredictBaserateTool({ args, ctx, hippoRoot, tenantId }: ToolCall): string;
 export declare function runStatusTool({ hippoRoot, config, tenantId }: ToolCall): string;
-export declare function runConflictsTool({ hippoRoot, tenantId }: ToolCall): string;
+export declare function runConflictsTool(call: ToolCall): string;
 export declare function runResolveTool({ args, ctx, hippoRoot, tenantId }: ToolCall): string;
-export declare function runShareTool({ args, hippoRoot, tenantId }: ToolCall): string;
+export declare function runShareTool({ args, ctx, hippoRoot, tenantId }: ToolCall): string;
 export declare function runPeersTool({ tenantId }: ToolCall): string;
 //# sourceMappingURL=admin-tools.d.ts.map

package/dist/mcp/admin-tools.js

@@ -2,10 +2,28 @@
 import { calculateStrength } from '../memory.js';
 import { evalNow } from '../ablation.js';
 import { loadStrengthRows } from '../store/candidates.js';
-import { listMemoryConflicts, resolveConflict } from '../store/conflicts.js';
+import { listMemoryConflicts, listTouchableConflicts, resolveConflict } from '../store/conflicts.js';
 import { shareMemory, listPeers } from '../shared.js';
 import { computePredictionBaserate } from '../predictions/store.js';
+import { closeHippoDb, openHippoDb } from '../db.js';
+import { NotFoundError } from '../api-errors.js';
+import { classifyOriginProject } from '../project-identity.js';
+import { canTouchScope, passesScopeFilterForRecall, personalScopeOf } from '../recall-scope.js';
+import { selectEntriesByIds } from '../store/entry-reads.js';
+import { selectMemoryReach } from '../store/tenant-lookup.js';
+import { mcpActor } from './protocol.js';
 import { isJsonString } from '../json.js';
+const NOT_RESOLVED = 'Could not resolve. Check the conflict ID and --keep value.';
+/** The scope of memory `id`, null when it has none or does not exist. */
+function memoryScope(hippoRoot, id) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        return selectMemoryReach(db, id)?.scope ?? null;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 export function runPredictBaserateTool({ args, ctx, hippoRoot, tenantId }) {
     // Text-only reply, matching the other MCP tools; the helper opens its own db
     // and emits the audit, so call sites cannot drift.
@@ -55,8 +73,27 @@ export function runStatusTool({ hippoRoot, config, tenantId }) {
         `Half-life default: ${config.defaultHalfLifeDays}d`,
     ].join('\n');
 }
-export function runConflictsTool({ hippoRoot, tenantId }) {
-    const conflicts = listMemoryConflicts(hippoRoot, 'open', tenantId);
+/** Pairs whose two rows the caller could recall: its repo or user-global, and no scope it was not asked for. */
+function recallablePairs(call, conflicts, project) {
+    const own = personalScopeOf(mcpActor(call.ctx));
+    const db = openHippoDb(call.hippoRoot);
+    try {
+        const rows = selectEntriesByIds(db, conflicts.flatMap((c) => [c.memory_a_id, c.memory_b_id]), call.tenantId);
+        const shown = (id) => {
+            const row = rows.get(id);
+            return row !== undefined && classifyOriginProject(row.origin_project, project) !== 'cross-project'
+                && passesScopeFilterForRecall(row.scope ?? null, undefined, own);
+        };
+        return conflicts.filter((c) => shown(c.memory_a_id) && shown(c.memory_b_id));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+export function runConflictsTool(call) {
+    const { ctx, hippoRoot, tenantId } = call;
+    const touchable = listTouchableConflicts(hippoRoot, 'open', tenantId, mcpActor(ctx));
+    const conflicts = ctx?.project ? recallablePairs(call, touchable, ctx.project) : touchable;
     if (conflicts.length === 0)
         return 'No open conflicts.';
     return conflicts.map((c) => `conflict_${c.id}: ${c.memory_a_id} <-> ${c.memory_b_id} (score=${c.score.toFixed(2)}) — ${c.reason}`).join('\n');
@@ -70,6 +107,8 @@ export function runResolveTool({ args, ctx, hippoRoot, tenantId }) {
     const reason = isJsonString(args.reason) ? args.reason : undefined;
     if (isNaN(conflictId) || !keepId)
         return 'Required: conflict_id and keep.';
+    if (!listTouchableConflicts(hippoRoot, 'open', tenantId, mcpActor(ctx)).some((c) => c.id === conflictId))
+        return NOT_RESOLVED;
     const result = resolveConflict(hippoRoot, conflictId, keepId, forget, tenantId, {
         rejectLoserValue: rejectLoser,
         reason,
@@ -78,15 +117,18 @@ export function runResolveTool({ args, ctx, hippoRoot, tenantId }) {
         rejectedBy: ctx?.actor ?? 'mcp',
     });
     if (!result)
-        return 'Could not resolve. Check the conflict ID and --keep value.';
+        return NOT_RESOLVED;
     const action = rejectLoser ? 'rejected (tombstoned) and removed' : forget ? 'deleted' : 'weakened';
     return `Resolved conflict ${conflictId}: kept ${keepId}, ${action} ${result.loserId}`;
 }
-export function runShareTool({ args, hippoRoot, tenantId }) {
+export function runShareTool({ args, ctx, hippoRoot, tenantId }) {
     const shareId = String(args.id || '');
     if (!shareId)
         return 'Required: id (memory ID to share).';
     const force = Boolean(args.force);
+    // Checked before shareMemory, whose personal-row refusal would tell another person the id exists.
+    if (!canTouchScope(mcpActor(ctx), memoryScope(hippoRoot, shareId)))
+        throw new NotFoundError(`Memory not found: ${shareId}`);
     // Pass tenantId so shareMemory's readEntry filters by tenant. Without
     // this, a Bearer for tenant A could call hippo_share with tenant B's
     // id and copy the row to the global store. The 'Memory not found'

package/dist/mcp/memory-tools.js

@@ -25,15 +25,19 @@ export function runRememberTool({ args, ctx, hippoRoot, config, tenantId }) {
         hippoRoot,
         tenantId,
         actor: mcpActor(ctx),
+        store: ctx?.store,
     };
     const result = apiRemember(apiCtx, {
         content: text,
         tags,
+        personal: args.personal === true,
+        project: ctx?.project,
     });
     const entry = readEntry(hippoRoot, result.id, tenantId);
     // Auto-sleep: one run per store at a time, triggered by what arrived since the last one.
     // Consolidation is host-wide, so only the host tenant's writes may start it.
-    if (config.autoSleep.enabled &&
+    if (ctx?.autoSleep !== false &&
+        config.autoSleep.enabled &&
         tenantId === resolveTenantId({}) &&
         !autoSleepInFlight.has(hippoRoot) &&
         countCreatedSinceLastSleep(hippoRoot, tenantId) >= config.autoSleep.threshold) {
@@ -64,13 +68,14 @@ export function runOutcomeTool({ args, ctx, hippoRoot, tenantId }) {
         hippoRoot,
         tenantId,
         actor: mcpActor(ctx),
+        store: ctx?.store,
     };
     const { applied } = apiOutcome(apiCtx, ids, good);
     return `Applied ${good ? 'positive' : 'negative'} outcome to ${applied} memories`;
 }
 export function runLearnTool({ args, ctx, hippoRoot, tenantId }) {
     const days = Number(args.days) || 7;
-    const result = apiLearn({ hippoRoot, tenantId, actor: mcpActor(ctx) }, { repoPath: process.cwd(), days, profile: MCP_LEARN });
+    const result = apiLearn({ hippoRoot, tenantId, actor: mcpActor(ctx), store: ctx?.store }, { repoPath: process.cwd(), days, profile: MCP_LEARN });
     if (result.status === 'not-a-repo')
         return 'No git history found.';
     if (result.status === 'no-commits')

package/dist/mcp/protocol.d.ts

@@ -2,6 +2,8 @@ import { loadConfig } from '../config.js';
 import type { Actor as ApiActor } from '../api.js';
 import { type ResolveProjectIdentityOpts } from '../project-identity.js';
 import type { JsonValue } from '../json.js';
+import type { CallerProject } from '../prompt-hook.js';
+import type { HippoStore } from '../store-port.js';
 /** Same bounded walk as the CLI (ends at home, so HIPPO_HOME wins over ~/.hippo); cwd/opts are the test seam. */
 export declare function findHippoRoot(cwd?: string, opts?: ResolveProjectIdentityOpts): string | null;
 interface McpRequest {
@@ -50,6 +52,10 @@ export interface McpContext {
     viaAuthResolver?: true;
     /** Set by the HTTP transport for the host's operator; a context without a role is in-process and implies it. */
     hostAdmin?: true;
+    owner?: string;
+    project?: CallerProject;
+    store?: HippoStore;
+    autoSleep?: false;
     /**
      * Per-client key for state isolation under HTTP-MCP. For stdio: 'stdio-${pid}'
      * (one process = one client). For HTTP-SSE / HTTP MCP: hash(bearer + remoteAddr)

package/dist/mcp/protocol.js

@@ -5,7 +5,7 @@ import { INTERNAL_ERROR_MESSAGE, mapApiError } from '../http-util.js';
 import { log } from '../log.js';
 import { getGlobalRoot } from '../shared.js';
 import { findHippoStoreDir } from '../project-identity.js';
-import { isSqliteBusy, STORE_BUSY_MESSAGE } from '../db.js';
+import { isStoreBusy, STORE_BUSY_MESSAGE } from '../db.js';
 // ── Find hippo root ──
 /** Same bounded walk as the CLI (ends at home, so HIPPO_HOME wins over ~/.hippo); cwd/opts are the test seam. */
 export function findHippoRoot(cwd = process.cwd(), opts) {
@@ -18,7 +18,7 @@ export function findHippoRoot(cwd = process.cwd(), opts) {
 }
 /** JSON-RPC reply for a request that threw: typed API errors keep their text; anything else is logged and answered generically. */
 export function mcpErrorResponse(id, err, requestId = randomUUID()) {
-    if (isSqliteBusy(err))
+    if (isStoreBusy(err))
         return { jsonrpc: '2.0', id, error: { code: -32603, message: STORE_BUSY_MESSAGE } };
     const { status, message } = mapApiError(err);
     if (status !== 500)
@@ -41,6 +41,8 @@ export function mcpActor(ctx) {
         actor.viaAuthResolver = true;
     if (ctx?.role === undefined || ctx.hostAdmin)
         actor.hostAdmin = true;
+    if (ctx?.owner !== undefined)
+        actor.owner = ctx.owner;
     return actor;
 }
 // ── JSON-ish domain type for untrusted MCP tool-call arguments ──

package/dist/mcp/recall-tools.js

@@ -5,6 +5,7 @@ import { dropHeldCopies, duplicateKey, storedTextKeys } from '../same-text.js';
 import { retrieve as apiRetrieve, drillDown as apiDrillDown, assemble as apiAssemble, getContext as apiGetContext, buildSuppressionSummary } from '../api.js';
 import { autoDetectContext } from '../context-auto.js';
 import { resolveProjectIdentity } from '../project-identity.js';
+import { isSharedStore } from '../config.js';
 import { appendAuditEvent, auditQueryFields } from '../audit.js';
 import { detectAnchoring, hashQueryText, biasHintEnabled, buildSessionKey, getOrCreateRing, appendRecall, snapshotRing, } from '../recall-history.js';
 import { detectAvailabilityBias } from '../availability.js';
@@ -201,6 +202,7 @@ export async function runRecallTool(call) {
         hippoRoot,
         tenantId,
         actor: mcpActor(ctx),
+        store: ctx?.store,
     };
     const anchorRing = biasHintEnabled('anchoring') && sessionId
         ? getOrCreateRing(sessionRecallHistoryMcp, buildSessionKey(tenantId, sessionId))
@@ -217,6 +219,7 @@ export async function runRecallTool(call) {
         // The hint is computed below over the list MCP shows; the window band's copy would emit its audit row twice.
         suppressAvailabilityHint: true,
         keepHeldCopies: true,
+        project: ctx?.project,
         ...recallExtra,
         showRanked: recallPresenter(budget, includeContinuity, anchorRing, queryHash, out),
     });
@@ -237,6 +240,7 @@ export function runAssembleTool({ args, ctx, hippoRoot, tenantId }) {
         hippoRoot,
         tenantId,
         actor: mcpActor(ctx),
+        store: ctx?.store,
     };
     const explicitScope = isJsonString(args.scope) && args.scope.length > 0
         ? args.scope
@@ -250,6 +254,7 @@ export function runAssembleTool({ args, ctx, hippoRoot, tenantId }) {
         assembleExtra.scope = explicitScope;
     const r = apiAssemble(apiCtx, sessionId, {
         summarizeOlder,
+        project: ctx?.project,
         ...assembleExtra,
         cost: assembleCost(sessionId),
     });
@@ -267,6 +272,7 @@ export function runDrillTool({ args, ctx, hippoRoot, tenantId }) {
         hippoRoot,
         tenantId,
         actor: mcpActor(ctx),
+        store: ctx?.store,
     };
     const drillExtra = {};
     if (Number.isFinite(limit) && limit > 0)
@@ -275,7 +281,7 @@ export function runDrillTool({ args, ctx, hippoRoot, tenantId }) {
         drillExtra.budget = budget;
     if (depth !== undefined)
         drillExtra.depth = depth;
-    const r = apiDrillDown(apiCtx, summaryId, { ...drillExtra, cost: drillCost });
+    const r = apiDrillDown(apiCtx, summaryId, { ...drillExtra, project: ctx?.project, cost: drillCost });
     if ('failure' in r) {
         // Only not_drillable is caller-actionable. not_found merges cross-tenant, scope-blocked and
         // missing, because telling scope_blocked apart would leak private-row existence.
@@ -286,7 +292,15 @@ export function runDrillTool({ args, ctx, hippoRoot, tenantId }) {
     }
     return drillText(r);
 }
+// The served store names the project (an HTTP daemon runs from anywhere); the global root names none, so stdio falls back to its launch cwd.
+function localProject(hippoRoot) {
+    const storeProject = resolveProjectIdentity(path.dirname(path.resolve(hippoRoot)));
+    return storeProject.name !== '' ? storeProject : resolveProjectIdentity(process.cwd());
+}
 export async function runContextTool({ args, ctx, hippoRoot, config, tenantId }) {
+    // Stdio names no project, and the store's folder or the launch cwd is no caller's; HTTP sends X-Hippo-Project.
+    if (isSharedStore(hippoRoot) && ctx?.project === undefined)
+        return 'hippo_context needs a project on a shared store; use hippo_recall';
     const budget = args.budget === undefined
         ? config.defaultContextBudget
         : Number(args.budget);
@@ -299,13 +313,12 @@ export async function runContextTool({ args, ctx, hippoRoot, config, tenantId })
     const exactScope = isJsonString(args.scope) && args.scope.length > 0
         ? args.scope
         : undefined;
-    // The served store names the project (an HTTP daemon runs from anywhere); the global root names none, so stdio falls back to its launch cwd.
-    const storeProject = resolveProjectIdentity(path.dirname(path.resolve(hippoRoot)));
-    const result = await apiGetContext({ hippoRoot, tenantId, actor: mcpActor(ctx) }, {
-        q: autoDetectContext(),
+    const result = await apiGetContext({ hippoRoot, tenantId, actor: mcpActor(ctx), store: ctx?.store }, {
+        // The server's git state is no caller's, so a shared-store caller gets its project's rows without a query.
+        q: ctx?.project ? undefined : autoDetectContext(),
         budget,
         exactScope,
-        currentProject: storeProject.name !== '' ? storeProject : resolveProjectIdentity(process.cwd()),
+        currentProject: ctx?.project ?? localProject(hippoRoot),
         cost: contextCost,
     });
     lastRecalledIds.set(resolveClientKey(ctx), result.entries.map((r) => r.entry.id));

package/dist/mcp/request.js

@@ -12,6 +12,7 @@ import { TOOLS, TOOLS_BY_NAME, ARGS_CHECKED_BY_API } from './tools.js';
 import { runRecallTool, runAssembleTool, runDrillTool, runContextTool } from './recall-tools.js';
 import { runRememberTool, runOutcomeTool, runLearnTool } from './memory-tools.js';
 import { runPredictBaserateTool, runStatusTool, runConflictsTool, runResolveTool, runShareTool, runPeersTool } from './admin-tools.js';
+import { sharedStoreRefusal } from './shared-gate.js';
 import { isJsonString } from '../json.js';
 /**
  * Zero-install first run (`npx -y hippo-memory mcp` with no store anywhere):
@@ -126,6 +127,9 @@ export async function handleMcpRequest(req, ctx) {
             if (!tool) {
                 return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown tool: ${toolName.slice(0, 128)}` } };
             }
+            const refusal = sharedStoreRefusal(toolName, ctx);
+            if (refusal !== undefined)
+                return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: refusal }], isError: true } };
             const argumentsValue = params?.arguments;
             if (argumentsValue !== undefined && argumentsValue !== null && !isJsonObjectRecord(argumentsValue)) {
                 return { jsonrpc: '2.0', id, error: { code: -32602, message: `${toolName}: arguments must be an object` } };

package/dist/mcp/session-state.d.ts

@@ -2,10 +2,14 @@ import type { RingBuffer } from '../recall-history.js';
 export declare const sessionRecallHistoryMcp: Map<string, RingBuffer>;
 /** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
 export declare function __resetSessionRecallHistoryMcp(): void;
+export declare const MAX_RECALL_CLIENTS = 4096;
 export declare const lastRecalledIds: Map<string, string[]>;
 export declare const autoSleepInFlight: Set<string>;
 export declare function resolveClientKey(ctx: {
     clientKey?: string;
     tenantId: string;
+    project?: {
+        name: string;
+    };
 } | undefined): string;
 //# sourceMappingURL=session-state.d.ts.map

package/dist/mcp/session-state.js

@@ -15,13 +15,22 @@ export function __resetSessionRecallHistoryMcp() {
 // back to `'stdio-${pid}'` (one process = one client) or
 // `${tenantId}:default` if a McpContext is constructed in tests without a
 // pid-bound transport.
-export const lastRecalledIds = new Map();
+export const MAX_RECALL_CLIENTS = 4096;
+// The caller names the project half of each key, so a set past the cap drops the client that recalled longest ago.
+class RecentRecalls extends Map {
+    set(key, ids) {
+        this.delete(key);
+        super.set(key, ids);
+        const oldest = this.keys().next().value;
+        if (this.size > MAX_RECALL_CLIENTS && oldest !== undefined)
+            this.delete(oldest);
+        return this;
+    }
+}
+export const lastRecalledIds = new RecentRecalls();
 export const autoSleepInFlight = new Set();
 export function resolveClientKey(ctx) {
-    if (ctx?.clientKey)
-        return ctx.clientKey;
-    if (ctx?.tenantId)
-        return `stdio-${process.pid}:${ctx.tenantId}`;
-    return `stdio-${process.pid}:default`;
+    const base = ctx?.clientKey ? ctx.clientKey : `stdio-${process.pid}:${ctx?.tenantId || 'default'}`;
+    return ctx?.project ? `${base}:${ctx.project.name}` : base;
 }
 //# sourceMappingURL=session-state.js.map

package/dist/mcp/shared-gate.d.ts

@@ -0,0 +1,4 @@
+import type { McpContext } from './protocol.js';
+/** The refusal text for this call, or undefined when it may run; stdio passes no context and is never gated. */
+export declare function sharedStoreRefusal(name: string, ctx: McpContext | undefined): string | undefined;
+//# sourceMappingURL=shared-gate.d.ts.map

package/dist/mcp/shared-gate.js

@@ -0,0 +1,22 @@
+// Which MCP tools run on a shared store, and which need the caller's project first.
+import { isSharedStore } from '../config.js';
+// A shared store holds many repos' rows, so a memory tool needs the caller's project and four tools never run.
+const OFF_ON_SHARED = new Map([
+    ['hippo_learn', "reads the server's git history"],
+    ['hippo_share', "copies into the server's global store"],
+    ['hippo_resolve', 'tombstones across every project; the admin resolves with the CLI'],
+    ['hippo_peers', "lists the server's own global store, not the repos that share this one"],
+]);
+const OPEN_WITHOUT_PROJECT = new Set(['hippo_predict_baserate']);
+/** The refusal text for this call, or undefined when it may run; stdio passes no context and is never gated. */
+export function sharedStoreRefusal(name, ctx) {
+    if (ctx === undefined || !isSharedStore(ctx.hippoRoot))
+        return undefined;
+    const off = OFF_ON_SHARED.get(name);
+    if (off !== undefined)
+        return `${name} is off on a shared store: it ${off}`;
+    if (OPEN_WITHOUT_PROJECT.has(name) || ctx.project !== undefined)
+        return undefined;
+    return `${name} needs the caller's project on a shared store; the client sends it in the X-Hippo-Project header`;
+}
+//# sourceMappingURL=shared-gate.js.map

package/dist/mcp/tools.js

@@ -131,6 +131,7 @@ export const TOOLS = [
                 error: { type: 'boolean', description: 'Mark as error memory (doubles half-life)' },
                 pin: { type: 'boolean', description: 'Pin memory (never decays)' },
                 tag: { type: 'string', description: 'Optional tag for categorization' },
+                personal: { type: 'boolean', description: 'Store it as your own private memory: only you can recall it, in every project. Needs a key you minted or a sign-in.' },
             },
             required: ['text'],
         },