hippo-memory 1.63.2 → 1.64.0

package/dist/memory-quality.d.ts

@@ -0,0 +1,35 @@
+import { type MemoryEntry } from './memory.js';
+export declare const STOP_WORDS: Set<string>;
+export type AutomaticMemoryDefect = 'too-short' | 'release-activity' | 'sentence-fragment' | 'possible-fragment' | 'subjectless-outcome' | 'raw-output' | 'too-vague' | 'no-specificity';
+/** `reason` names a defect even when `accepted`: a possible fragment is stored and listed for review. */
+export interface AutomaticMemoryAssessment {
+    readonly accepted: boolean;
+    readonly reason: AutomaticMemoryDefect | null;
+}
+/** Counts spaced words plus CJK letters without lowering mixed-script counts. */
+export declare function substantiveWordCount(text: string): number;
+/** Preserves the auditor's existing destructive release-noise classification. */
+export declare function isReleaseCommitNoise(text: string): boolean;
+/** Short preferences and rules carry a useful relationship even without a path or number. */
+export declare function hasNoSpecificity(text: string): boolean;
+/** Names automatic-capture defects without inventing missing context. */
+export declare function assessAutomaticMemory(content: string): AutomaticMemoryAssessment;
+export declare function isCertainReason(reason: AutomaticMemoryDefect | null): boolean;
+/** The bar for sleep's derived memories and for repair: a defect the checks are sure of, else null. */
+export declare function certainDefect(content: string): AutomaticMemoryDefect | null;
+export declare const BUNDLE_HEADER: RegExp;
+type Provenance = Pick<MemoryEntry, 'source' | 'confidence' | 'content' | 'extracted_from' | 'dag_level' | 'tags'>;
+/** A row hippo wrote that no person vouched for: hippo's writers stamp observed or inferred, a person's edit or restore verified. */
+export declare function isAutomaticEntry(entry: Provenance): boolean;
+/** The audit's check: a person's row is never judged, and a bundle is flagged only when every part is, as reuse and recent context judge it. */
+export declare function automaticDefect(entry: Provenance): AutomaticMemoryDefect | null;
+/** Whether sleep may derive from a row or share it: a person's text and watch failures always, hippo's own text only without a certain defect. */
+export declare function isReusable(entry: Provenance): boolean;
+/** The person floor's fragment test, on trimmed text. */
+export declare function isFragment(text: string): boolean;
+/** Admission check for text no person typed: capture and compaction items. */
+export declare function isContentWorthStoring(content: string): boolean;
+/** Recent-context floor: rows hippo wrote meet the automatic check, a person's rows only the older, looser floor. */
+export declare function isWorthSurfacing(entry: MemoryEntry): boolean;
+export {};
+//# sourceMappingURL=memory-quality.d.ts.map

package/dist/memory-quality.js

@@ -0,0 +1,191 @@
+import { COMPACTION_MEMORY_TAG, COMPACTION_SOURCE_PREFIX } from './memory.js';
+import { heldTexts } from './same-text.js';
+export const STOP_WORDS = new Set([
+    'the', 'a', 'an', 'is', 'was', 'are', 'were', 'be', 'been', 'being',
+    'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from', 'it',
+    'this', 'that', 'and', 'or', 'but', 'not', 'no', 'so', 'if', 'do',
+    'did', 'does', 'has', 'had', 'have', 'will', 'would', 'could', 'should',
+    'may', 'might', 'can', 'shall', 'we', 'i', 'you', 'they', 'he', 'she',
+    'my', 'our', 'your', 'its', 'his', 'her', 'their', 'up', 'out', 'just',
+    'also', 'then', 'than', 'some', 'all', 'any', 'each', 'very', 'too',
+]);
+const CJK_LETTERS = /(?=\p{L})(?:\p{Script=Han}|\p{Script=Hiragana}|\p{Script=Katakana})/gu;
+const CHAT_ACRONYMS = /^(?:TODO|FYI|LGTM|IIRC|IMO|IMHO|FWIW|TBD|BTW|ASAP|AFAIK|WIP|NB|PS)$/;
+/** Counts spaced words plus CJK letters without lowering mixed-script counts. */
+export function substantiveWordCount(text) {
+    const cjkLetterCount = (text.match(CJK_LETTERS) ?? []).length;
+    const spacedCount = text.toLowerCase().split(/\s+/).filter(w => w.length > 2 && !STOP_WORDS.has(w)).length;
+    return spacedCount + Math.floor(cjkLetterCount / 2);
+}
+/** Preserves the auditor's existing destructive release-noise classification. */
+export function isReleaseCommitNoise(text) {
+    return /^(?:bump|release|prep|tag)\s+(?:to\s+)?v?\d+\.\d+/i.test(text)
+        || /^v?\d+\.\d+\.\d+\s*$/i.test(text)
+        || /^chore(?:\([^)]+\))?:\s*(?:release|bump|version|tag|prep)\b/i.test(text)
+        || /^(?:Merge branch|Merge pull request)\b/i.test(text)
+        || /^WIP\b/i.test(text);
+}
+/** Short preferences and rules carry a useful relationship even without a path or number. */
+export function hasNoSpecificity(text) {
+    const domainAcronyms = (text.match(/\b[A-Z]{2,6}\b/g) ?? []).filter(a => !CHAT_ACRONYMS.test(a));
+    if (/\d|[A-Z][a-z]{2,}|[/\\.]|[`_{}()\[\]]/.test(text))
+        return false;
+    if (domainAcronyms.length > 0 && /[a-z]/.test(text))
+        return false;
+    if (/^(?:prefer|use|avoid|never use|don't use)\s+(?!(?:the|that|this|it|them|those|these|one|other|something)\b)\S+/i.test(text))
+        return false;
+    if (/\b(?:never|always|must)\s+(?!(?:the|that|this|it|them|those|these|one|other|something)\b)\S+/i.test(text))
+        return false;
+    return text.split(/\s+/).length < 8 && /^[\w\s,.'"-]+$/.test(text);
+}
+const RELATION_WORD = /\b(?:when|if|unless|because|since|after|before|until|while|so|instead)\b/i;
+const RULE_WORD = /\b(?:never|always|must|don't|do not|make sure|ensure|prefer|avoid)\b/i;
+function isRoutineReleaseActivity(text) {
+    if (isReleaseCommitNoise(text))
+        return true;
+    // "Deploy only after the migration has run" is a rule about releases, not a log line.
+    if (RELATION_WORD.test(text) || RULE_WORD.test(text))
+        return false;
+    const subject = text.replace(/^(?:chore|ci|build)(?:\([^)]*\))?:\s*/i, '');
+    if (/^(?:bump|increment|increase|update|set)\s+(?:(?:ios|android|app)\s+)?(?:build(?:\s+number)?|version|release)\s+(?:to\s+)?(?:v?\d|#\d)/i.test(subject))
+        return true;
+    return /^(?:deploy(?:ed|ing)?|ship(?:ped|ping)?|release(?:d|ing)?)\s+(?:the\s+)?(?:build|release|version|v?\d)\s*(?:v?\d|#\d|\.\d)/i.test(subject)
+        || /^(?:deployment|release|build)\s+(?:succeeded|completed|finished)\b/i.test(subject);
+}
+const bareText = (text) => text.replace(/[.!?,;:\s]+$/, '');
+// These endings close whole sentences too ("the branch you push to"), so they are only a possible cut.
+const POSSIBLE_CUT_ENDING = /\b(?:needs to|depends on|requires|while|with|without|into|for|of|by|to|is|are|was|were|must|should|could|would|might)$/i;
+/** A short leading condition with no rule word, comma or "then": "If the build fails". */
+function isBareCondition(bare) {
+    return !/[,;]|\bthen\b/i.test(bare) && !RULE_WORD.test(bare) && bare.split(/\s+/).length <= 6;
+}
+function isDanglingAssertion(text) {
+    const bare = bareText(text);
+    // Only a lowercase start is a cut: "To rebuild the index, run ..." opens an instruction.
+    if (/^(?:to|and|for)\s/.test(bare) && bare.length < 50)
+        return true;
+    // Prepositions, modals and "is" can end a whole sentence ("the branch it merges into"), so only cut-off endings count.
+    if (/\b(?:to be|has been|will be|instead of|rather than|such as|than|because|if|unless|when|until|and|or|but)$/i.test(bare) || /\b(?:the|a|an)$/.test(bare))
+        return true;
+    return /^(?:if|unless|when|while|until)\b/.test(bare) && isBareCondition(bare);
+}
+/** A capitalised short condition may carry its rule with no comma: "When CI fails we retry once". */
+function isPossibleFragment(text) {
+    const bare = bareText(text);
+    return POSSIBLE_CUT_ENDING.test(bare) || (/^(?:If|Unless|When|While|Until)\b/.test(bare) && isBareCondition(bare));
+}
+const OUTCOME_LEAD = /^(?:succeeds?|succeeded|fails?|failed|passes|passed|completed|done|successful|success|returned|returns|inserted|updated|deleted)\b/i;
+const OUTCOME_DETAIL = /\b(?:for|on|in|at|to|from|with|without|by|after|before|under|is|are|was|were|be|been|will|can|must|should|never|always)\b/i;
+function isSubjectlessOutcome(text) {
+    const lead = OUTCOME_LEAD.exec(text);
+    if (lead === null || RELATION_WORD.test(text))
+        return false;
+    // "Returns 404 for unknown ids" and "Deleted rows must stay deleted" say when or what; "returned 3 matching rows" does not.
+    return !OUTCOME_DETAIL.test(text.slice(lead[0].length).replace(/\([^)]*\)/g, ' '));
+}
+const OUTPUT_LINE = /^(?:\$\s|>\s|(?:stdout|stderr|exit code):|Command\s+['"].*\s+failed\b|Traceback\b|npm\s+(?:ERR|WARN)\b|error\s+TS\d+\b)/i;
+const STACK_FRAME = /^at\s+\S.*:\d+(?::\d+)?\)?$/;
+const ERROR_LEAD = /^(?:[\w.$]+Error|[\w.$]+Exception):\s/;
+// Log lines say "after" and "while" too, so only a rule word frees a timestamp or level lead: a dated freeze saying never merge.
+const LOG_LEADS = [
+    /^\d{4}-\d{2}-\d{2}[T ][\d:.]+(?:Z|[+-][\d:]+)?\s+(?:\[?\w+\]?\s+)?/,
+    /^\[(?:info|warn|error|debug)\]/i,
+];
+const DATA_LEADS = [/^\{\s*["']?[\w$-]+["']?\s*:/, /^\[\s*(?:[{["]|-?\d[\d.]*\s*[,\]])/];
+/** Prose after the last closing bracket: "{ retries: 3 } is the default policy". */
+function hasProseAfterData(text) {
+    const tail = text.slice(Math.max(text.lastIndexOf('}'), text.lastIndexOf(']')) + 1);
+    return (tail.match(/\p{L}{2,}/gu) ?? []).length >= 2;
+}
+function isRawOutput(text) {
+    if (OUTPUT_LINE.test(text) || STACK_FRAME.test(text))
+        return true;
+    if (ERROR_LEAD.test(text))
+        return !RELATION_WORD.test(text) && !RULE_WORD.test(text);
+    if (LOG_LEADS.some((lead) => lead.test(text)))
+        return !RULE_WORD.test(text);
+    return DATA_LEADS.some((lead) => lead.test(text)) && !hasProseAfterData(text);
+}
+/** Names automatic-capture defects without inventing missing context. */
+export function assessAutomaticMemory(content) {
+    const text = content.trim();
+    let reason = null;
+    if (text.length < 10)
+        reason = 'too-short';
+    else if (isRoutineReleaseActivity(text))
+        reason = 'release-activity';
+    else if (isRawOutput(text))
+        reason = 'raw-output';
+    else if (isDanglingAssertion(text))
+        reason = 'sentence-fragment';
+    else if (isSubjectlessOutcome(text))
+        reason = 'subjectless-outcome';
+    else if (isPossibleFragment(text))
+        reason = 'possible-fragment';
+    else if (substantiveWordCount(text) < 2)
+        reason = 'too-vague';
+    else if (text.length < 40 && hasNoSpecificity(text))
+        reason = 'no-specificity';
+    return { accepted: reason === null || reason === 'possible-fragment', reason };
+}
+/** Reasons the heuristics can get wrong: repair only lists them for review and derivation still admits them. */
+const UNCERTAIN_REASONS = new Set(['too-short', 'possible-fragment', 'too-vague', 'no-specificity']);
+export function isCertainReason(reason) {
+    return reason !== null && !UNCERTAIN_REASONS.has(reason);
+}
+/** The bar for sleep's derived memories and for repair: a defect the checks are sure of, else null. */
+export function certainDefect(content) {
+    const { reason } = assessAutomaticMemory(content);
+    return isCertainReason(reason) ? reason : null;
+}
+// Watch failures ('autolearn') and tool failures keep a fixed "Command 'x' failed" format by design, so they are not judged.
+const AUTOMATIC_SOURCES = new Set(['capture', 'git-learn', 'git', 'consolidation']);
+// Promote and share rewrite the source but keep the tags, so the writer's tag still marks a copy; elsewhere a person may set it.
+const AUTOMATIC_TAGS = new Set(['captured', COMPACTION_MEMORY_TAG, 'git-learned']);
+const COPY_SOURCE = /^(?:promoted|shared):/;
+export const BUNDLE_HEADER = /^\[Consolidated(?: from| pattern from) \d+ related memor(?:y|ies)(?:, newest first)?\]\n\n/;
+/** A row hippo wrote that no person vouched for: hippo's writers stamp observed or inferred, a person's edit or restore verified. */
+export function isAutomaticEntry(entry) {
+    if (entry.confidence !== 'observed' && entry.confidence !== 'inferred')
+        return false;
+    return AUTOMATIC_SOURCES.has(entry.source) || entry.source.startsWith(COMPACTION_SOURCE_PREFIX)
+        || (COPY_SOURCE.test(entry.source) && entry.tags.some((tag) => AUTOMATIC_TAGS.has(tag)))
+        || entry.extracted_from !== null || entry.dag_level >= 1 || BUNDLE_HEADER.test(entry.content);
+}
+/** A bundle's parts are other rows' words, possibly a person's, so a bundle is sure to be junk only when every part is. */
+function bundleParts(entry) {
+    return BUNDLE_HEADER.test(entry.content) ? heldTexts({ content: entry.content, source: 'consolidation' }) : [];
+}
+function hasCertainDefect(entry) {
+    const parts = bundleParts(entry);
+    return (parts.length > 0 ? parts : [entry.content]).every((text) => certainDefect(text) !== null);
+}
+/** The audit's check: a person's row is never judged, and a bundle is flagged only when every part is, as reuse and recent context judge it. */
+export function automaticDefect(entry) {
+    if (!isAutomaticEntry(entry))
+        return null;
+    const parts = bundleParts(entry);
+    const reasons = (parts.length > 0 ? parts : [entry.content.trim()]).map((text) => assessAutomaticMemory(text).reason);
+    return reasons.every((reason) => reason !== null) ? reasons[0] ?? null : null;
+}
+/** Whether sleep may derive from a row or share it: a person's text and watch failures always, hippo's own text only without a certain defect. */
+export function isReusable(entry) {
+    return !isAutomaticEntry(entry) || !hasCertainDefect(entry);
+}
+/** The person floor's fragment test, on trimmed text. */
+export function isFragment(text) {
+    return /^(?:to|for|and) /.test(text) && text.length < 50;
+}
+/** Admission check for text no person typed: capture and compaction items. */
+export function isContentWorthStoring(content) {
+    return assessAutomaticMemory(content).accepted;
+}
+/** Recent-context floor: rows hippo wrote meet the automatic check, a person's rows only the older, looser floor. */
+export function isWorthSurfacing(entry) {
+    if (isAutomaticEntry(entry))
+        return bundleParts(entry).length > 0 ? !hasCertainDefect(entry) : isContentWorthStoring(entry.content);
+    const text = entry.content.trim();
+    return text.length >= 10 && !isReleaseCommitNoise(text) && !isFragment(text)
+        && substantiveWordCount(text) >= 2 && !(text.length < 40 && hasNoSpecificity(text));
+}
+//# sourceMappingURL=memory-quality.js.map

package/dist/memory.d.ts

@@ -87,10 +87,10 @@ export interface MemoryEntry {
     /**
      * Memory scope isolation: owning project for ambient-context
      * partitioning. A lowercased project name, '' for user-global (injectable
-     * everywhere), or null for legacy rows written before the column - ambient
-     * context treats null as other-project (deny). Stamped from the store's location
-     * at write time (store.ts stampOriginProject); undefined only on entries not yet
-     * written.
+     * everywhere), or null for no known project (a legacy row, or a shared-store
+     * write that named none) - ambient context treats null as other-project (deny).
+     * Stamped at write time by store/entry-row.ts stampOriginProject via fallbackOrigin;
+     * undefined only on entries not yet written.
      */
     origin_project?: string | null;
     /**

package/dist/physics-state.js

@@ -100,7 +100,7 @@ export function savePhysicsState(db, particles) {
       last_simulation = excluded.last_simulation,
       updated_at = datetime('now')
   `);
-    db.exec('BEGIN');
+    db.exec('BEGIN IMMEDIATE');
     try {
         for (const p of particles) {
             stmt.run(p.memoryId, float32ToBuffer(p.position), float32ToBuffer(p.velocity), p.mass, p.charge, p.temperature, p.lastSimulation);

package/dist/pilot-arm.d.ts

@@ -1,9 +1,20 @@
 import { type DatabaseSyncLike } from './db.js';
+import { type LedgerRootOpts } from './ledger-db.js';
 export type PilotArm = 'hippo' | 'holdout';
+export interface SessionArmOpts extends LedgerRootOpts {
+    /** Only the caller tenant's arm row counts, so a caller holding another tenant's session id cannot claim that session's arm. */
+    readonly ownTenantOnly?: boolean;
+}
 /** Deterministic split: the same session and rate always land in the same arm. */
 export declare function hashArm(sessionId: string, rateBp: number): PilotArm;
-/** The session's first stored arm, or null; never writes. No tenant filter: a session has one arm. */
-export declare function readPilotArm(db: DatabaseSyncLike, sessionId: string): PilotArm | null;
+/** The session's first stored arm, or null; never writes. Without `tenantId` any tenant's row counts, since on one machine a session has one arm. */
+export declare function readPilotArm(db: DatabaseSyncLike, sessionId: string, tenantId?: string): PilotArm | null;
 /** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
-export declare function ensurePilotArm(db: DatabaseSyncLike, tenantId: string, sessionId: string, rateBp: number, now?: string): PilotArm;
+export declare function ensurePilotArm(db: DatabaseSyncLike, tenantId: string, sessionId: string, rateBp: number, opts?: {
+    ownTenantOnly?: boolean;
+    now?: string;
+}): PilotArm;
+/** The session's arm, or null at rate 0, with no session id, or with no store.
+ *  `write` books the arm row; a read-only caller (env-only id, sub-agent) follows the stored arm, else the hash. */
+export declare function sessionPilotArm(hippoRoot: string, tenantId: string, sessionId: string | undefined, write: boolean, opts?: SessionArmOpts): PilotArm | null;
 //# sourceMappingURL=pilot-arm.d.ts.map

package/dist/pilot-arm.js

@@ -1,34 +1,39 @@
 // Pilot arm: one token_ledger row per session names its arm, `hippo` or `holdout`, so a pilot can compare them.
 // `items` holds the holdout rate in basis points; readers outside this repo depend on these rows, so their shape is fixed.
 import { createHash } from 'node:crypto';
-import { execWithBusyRetry, HOOK_DB_WAIT_MS } from './db.js';
+import { loadConfig } from './config.js';
+import { execWithBusyRetry, HOOK_DB_WAIT_MS, scopedBusyWait } from './db.js';
+import { ledgerRoot, withLedgerDb } from './ledger-db.js';
 import { recordTokenUse } from './token-ledger.js';
 /** Deterministic split: the same session and rate always land in the same arm. */
 export function hashArm(sessionId, rateBp) {
     const bucket = parseInt(createHash('sha256').update(sessionId).digest('hex').slice(0, 8), 16) % 10000;
     return bucket < rateBp ? 'holdout' : 'hippo';
 }
-/** The session's first stored arm, or null; never writes. No tenant filter: a session has one arm. */
-export function readPilotArm(db, sessionId) {
+/** The session's first stored arm, or null; never writes. Without `tenantId` any tenant's row counts, since on one machine a session has one arm. */
+export function readPilotArm(db, sessionId, tenantId) {
+    const params = tenantId === undefined ? [sessionId] : [sessionId, tenantId];
     // SAFETY: the SELECT names exactly this one column.
-    const row = db.prepare(`SELECT block_hash FROM token_ledger WHERE session_id = ? AND surface = 'pilot' AND event = 'arm' ORDER BY id LIMIT 1`).get(sessionId);
+    const row = db.prepare(`SELECT block_hash FROM token_ledger WHERE session_id = ?${tenantId === undefined ? '' : ' AND tenant_id = ?'}
+     AND surface = 'pilot' AND event = 'arm' ORDER BY id LIMIT 1`).get(...params);
     return row?.block_hash === 'holdout' || row?.block_hash === 'hippo' ? row.block_hash : null;
 }
 /** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
-// The hook's lock-wait bound holds only on a handle opened with `busyWaitMs: HOOK_DB_WAIT_MS`, as hook commands are.
-export function ensurePilotArm(db, tenantId, sessionId, rateBp, now) {
+// The wait is the caller's lock-wait scope (a hook's 1 s, a server request's 250 ms); it holds on a handle opened in that scope.
+export function ensurePilotArm(db, tenantId, sessionId, rateBp, opts = {}) {
     const hashed = hashArm(sessionId, rateBp);
+    const readTenant = opts.ownTenantOnly ? tenantId : undefined;
     let began = false;
     try {
         // A stored row is the common case after the first prompt, so it must not take the write lock.
-        const existing = readPilotArm(db, sessionId);
+        const existing = readPilotArm(db, sessionId, readTenant);
         if (existing !== null)
             return existing;
-        execWithBusyRetry(db, 'BEGIN IMMEDIATE', HOOK_DB_WAIT_MS);
+        execWithBusyRetry(db, 'BEGIN IMMEDIATE', scopedBusyWait() ?? HOOK_DB_WAIT_MS);
         began = true;
-        const stored = readPilotArm(db, sessionId);
+        const stored = readPilotArm(db, sessionId, readTenant);
         if (stored === null) {
-            recordTokenUse(db, { tenantId, sessionId, surface: 'pilot', event: 'arm', items: rateBp, tokens: 0, hash: hashed, now });
+            recordTokenUse(db, { tenantId, sessionId, surface: 'pilot', event: 'arm', items: rateBp, tokens: 0, hash: hashed, now: opts.now });
         }
         db.exec('COMMIT');
         return stored ?? hashed;
@@ -44,4 +49,21 @@ export function ensurePilotArm(db, tenantId, sessionId, rateBp, now) {
         return hashed;
     }
 }
+/** The session's arm, or null at rate 0, with no session id, or with no store.
+ *  `write` books the arm row; a read-only caller (env-only id, sub-agent) follows the stored arm, else the hash. */
+export function sessionPilotArm(hippoRoot, tenantId, sessionId, write, opts = {}) {
+    if (sessionId === undefined || sessionId.trim() === '')
+        return null;
+    const root = ledgerRoot(hippoRoot, opts);
+    if (root === null)
+        return null;
+    const rate = loadConfig(root).pilot.holdoutRateBp;
+    if (rate <= 0)
+        return null;
+    const { ownTenantOnly } = opts;
+    const arm = withLedgerDb(hippoRoot, (db) => write
+        ? ensurePilotArm(db, tenantId, sessionId, rate, { ownTenantOnly })
+        : readPilotArm(db, sessionId, ownTenantOnly ? tenantId : undefined) ?? hashArm(sessionId, rate), opts);
+    return arm ?? hashArm(sessionId, rate);
+}
 //# sourceMappingURL=pilot-arm.js.map

package/dist/postinstall.js

@@ -3,6 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { detectRealCodexPath, isCodexWrapperInstalled, repairCodexWrapperIfInstalled } from './hooks/codex-wrapper.js';
+import { claudeConfigDir } from './hooks/shared.js';
 function main() {
     if (envSkipPostinstall())
         return;
@@ -39,8 +40,7 @@ function main() {
  * middle ground.
  */
 function printClaudeCodeNudge() {
-    const home = os.homedir();
-    const claudeDir = path.join(home, '.claude');
+    const claudeDir = claudeConfigDir(os.homedir());
     if (!fs.existsSync(claudeDir))
         return; // Claude Code not installed — silent
     const settingsPath = path.join(claudeDir, 'settings.json');

package/dist/project-briefs.js

@@ -24,7 +24,7 @@ import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { writeEntry } from './store/entry-writes.js';
 import { assertTenantId } from './tenant.js';
-import { RECALL_DEFAULT_DENY_SCOPES } from './recall-scope.js';
+import { scopeAdmitSql } from './recall-scope.js';
 import { markGraphDirty, removeGraphEntitiesForObject } from './graph/write.js';
 import { createMemory, Layer } from './memory.js';
 import { appendAuditEvent } from './audit.js';
@@ -388,7 +388,7 @@ function receiptHeadline(content) {
 function loadBriefReceipts(hippoRoot, tenantId, normalizedRepo) {
     const tag = `path:${normalizedRepo.toLowerCase()}`;
     const likeParam = `%"${escapeLike(tag)}"%`;
-    const denyPlaceholders = RECALL_DEFAULT_DENY_SCOPES.map(() => '?').join(', ');
+    const deny = scopeAdmitSql('');
     const db = openHippoDb(hippoRoot);
     try {
         // SAFETY: SELECT projects exactly id, created, source, content (the
@@ -398,10 +398,10 @@ function loadBriefReceipts(hippoRoot, tenantId, normalizedRepo) {
       WHERE tenant_id = ?
         AND source != 'project_brief'
         AND LOWER(tags_json) LIKE ? ESCAPE '\\'
-        AND (scope IS NULL OR (scope NOT IN (${denyPlaceholders}) AND scope NOT LIKE '%:private:%'))
+        AND ${deny.sql}
       ORDER BY created DESC, id DESC
       LIMIT ?
-    `).all(tenantId, likeParam, ...RECALL_DEFAULT_DENY_SCOPES, MAX_BRIEF_RECEIPTS);
+    `).all(tenantId, likeParam, ...deny.params, MAX_BRIEF_RECEIPTS);
     }
     finally {
         closeHippoDb(db);

package/dist/project-identity.d.ts

@@ -60,15 +60,22 @@ export type ProjectRef = string | Pick<ProjectIdentity, 'name' | 'legacyName' |
 export declare function projectId(project: ProjectRef): string;
 /** Every origin_project value the reader's own rows carry: the id first, then each alias and the legacy name. */
 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. */
+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 is a legacy pre-v39 row and
- * is treated as cross-project (deny by default) - the safe direction for a
- * security partition.
+ * 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.
  */
 export declare function classifyOriginProject(origin: string | null | undefined, current: ProjectRef): 'project' | 'user-global' | 'cross-project';
 /**
@@ -94,12 +101,9 @@ export declare function isGlobalStoreRoot(p: string): boolean;
  * origin evidence. Pure string logic - recorded paths may no longer exist.
  */
 export declare function originFromSource(source: string | null | undefined, homeName?: string): string | null;
-/**
- * The origin project to stamp on a memory written from cwd.
- * Returns the project name, or '' for user-global (written at/under home or
- * in a markerless directory) - injectable everywhere. Write sites must always
- * persist this value; a NULL origin_project column is reserved for legacy
- * pre-migration rows, which ambient context treats as deny.
- */
+/** 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. */
 export declare function deriveOriginProject(cwd?: string, opts?: ResolveProjectIdentityOpts): string;
+/** The origin for a write that names none: NULL on a shared store, whose folder is no caller's project, else the folder's project. */
+export declare function fallbackOrigin(hippoRoot: string): string | null;
 //# sourceMappingURL=project-identity.d.ts.map

package/dist/project-identity.js

@@ -2,7 +2,9 @@ import { envHippoHome, envXdgDataHome } from './env.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { loadConfig } from './config.js';
+import { BadRequestError } from './api-errors.js';
+import { isSharedStore, loadConfig } from './config.js';
+import { MAX_ID_LEN } from './http-util.js';
 import { log } from './log.js';
 import { originRemoteId, projectFileId } from './project-remote.js';
 const MAX_WALK_DEPTH = 64;
@@ -179,6 +181,23 @@ export function projectNames(project) {
         return [projectId(project)];
     return [...new Set([project.name, ...(project.aliases ?? []), project.legacyName])].filter((n) => n !== '');
 }
+// Each project name is matched against every candidate row, so the caller's list stays short.
+export const MAX_PROJECT_ALIASES = 10;
+export 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. */
+export function assertCallerProject(project) {
+    const { name, aliases = [] } = project;
+    if (name.trim() === '')
+        throw new BadRequestError('project name must not be blank');
+    if (aliases.length > MAX_PROJECT_ALIASES)
+        throw new BadRequestError(`project aliases: at most ${MAX_PROJECT_ALIASES}`);
+    if ([name, ...aliases].some((n) => n.length > MAX_ID_LEN)) {
+        throw new BadRequestError(`project names: at most ${MAX_ID_LEN} characters each`);
+    }
+    if ([name, ...aliases].some((n) => n !== n.trim().toLowerCase() || /[:\p{Cc}]/u.test(n))) {
+        throw new BadRequestError('project names: lowercase, not padded, with no colon or control character');
+    }
+}
 /** `origin_project IN (?, ...)` with one placeholder per name; an empty list matches nothing. */
 export function originInSql(names, column = 'origin_project') {
     return names.length === 0 ? '0' : `${column} IN (${names.map(() => '?').join(', ')})`;
@@ -187,9 +206,9 @@ export function originInSql(names, column = 'origin_project') {
  * 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 is a legacy pre-v39 row and
- * is treated as cross-project (deny by default) - the safe direction for a
- * security partition.
+ * 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.
  */
 export function classifyOriginProject(origin, current) {
     if (projectId(current) === '')
@@ -252,14 +271,13 @@ export function originFromSource(source, homeName) {
     }
     return null;
 }
-/**
- * The origin project to stamp on a memory written from cwd.
- * Returns the project name, or '' for user-global (written at/under home or
- * in a markerless directory) - injectable everywhere. Write sites must always
- * persist this value; a NULL origin_project column is reserved for legacy
- * pre-migration rows, which ambient context treats as deny.
- */
+/** 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. */
 export function deriveOriginProject(cwd, opts) {
     return resolveProjectIdentity(cwd, opts).name;
 }
+/** The origin for a write that names none: NULL on a shared store, whose folder is no caller's project, else the folder's project. */
+export function fallbackOrigin(hippoRoot) {
+    return isSharedStore(hippoRoot) ? null : deriveOriginProject(path.dirname(path.resolve(hippoRoot)));
+}
 //# sourceMappingURL=project-identity.js.map

package/dist/project-merge.d.ts

@@ -46,8 +46,6 @@ export interface RepairResult {
 }
 /** Live rows per project name, newest write first, with how many of its imported notes are copies held elsewhere. */
 export declare function listProjects(db: DatabaseSyncLike, tenantId: string): ProjectSummary[];
-/** Copies the database before a repair writes, so the audit ids plus this file are the way back. */
-export declare function backupStore(db: DatabaseSyncLike, hippoRoot: string, label: string, now?: Date): string;
 /** Refuses user-global and unknown: they are not projects, and folding them would leak or hide every row. */
 export declare function validateMergeNames(from: string, into: string): string | null;
 /** Folds project `from` into `into` for one tenant in one transaction; a dry run rolls back and writes nothing, mirrors included. */

package/dist/project-merge.js

@@ -6,6 +6,8 @@ import { transcriptNotesProject } from './agent-memories/claude-code.js';
 import { containerId, containerPrefix } from './agent-memories/source.js';
 import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TOOLS, toolSourcePrefix } from './agent-memories/tools.js';
 import { appendAuditEvent, queryAuditEvents } from './audit.js';
+import { isSharedStore } from './config.js';
+import { withBackup } from './db/backup.js';
 import { getMeta, setMeta } from './db/meta.js';
 import { insertDormantRow, listDormantSnapshots, replaceDormantEntry } from './dormant.js';
 import { processEnv } from './env.js';
@@ -47,14 +49,6 @@ export function listProjects(db, tenantId) {
         };
     }).sort((a, b) => b.newest.localeCompare(a.newest));
 }
-/** Copies the database before a repair writes, so the audit ids plus this file are the way back. */
-export function backupStore(db, hippoRoot, label, now = new Date()) {
-    const dir = path.join(hippoRoot, 'backups');
-    fs.mkdirSync(dir, { recursive: true });
-    const file = path.join(dir, `hippo-${label}-${now.toISOString().replace(/[:.]/g, '-')}.db`);
-    db.prepare('VACUUM INTO ?').run(file);
-    return file;
-}
 function inTransaction(db, dryRun, body) {
     db.exec(dryRun ? 'BEGIN' : 'BEGIN IMMEDIATE');
     try {
@@ -84,12 +78,12 @@ export function mergeProjects(db, hippoRoot, opts) {
     if (refusal)
         throw new Error(refusal);
     const { tenantId, from, into, dryRun } = opts;
-    const backup = dryRun ? null : backupStore(db, hippoRoot, 'before-merge');
-    const result = inTransaction(db, dryRun, () => {
+    const fold = (backup) => inTransaction(db, dryRun, () => {
         const folded = foldInTx(db, tenantId, from, into);
         appendAuditEvent(db, { tenantId, actor: ACTOR, op: 'project_merge', metadata: { from, into, backup, ...folded } });
         return { from, into, ...folded, backup };
     });
+    const result = dryRun ? fold(null) : withBackup(db, hippoRoot, 'before-merge', fold);
     if (!dryRun)
         refreshMirrors(db, hippoRoot, tenantId, result.restamped, result.setAside);
     return result;
@@ -203,6 +197,9 @@ function planFolds(db, hippoRoot, tenantId, globalFolds) {
 }
 /** A project store's rows, dormant snapshots and compaction records written before its id existed carry its folder name. */
 function ownLegacyFold(db, hippoRoot, tenantId) {
+    // A shared store's rows carry their callers' names, so one matching its folder's is a member's project, not a legacy tag.
+    if (isSharedStore(hippoRoot))
+        return [];
     const { name, legacyName } = resolveProjectIdentity(path.dirname(path.resolve(hippoRoot)));
     if (legacyName === '' || legacyName === name)
         return [];
@@ -278,8 +275,7 @@ export function repairProjects(db, hippoRoot, opts) {
     const { tenantId, dryRun, globalFolds = true } = opts;
     if (dryRun)
         return { ...planProjectRepair(db, hippoRoot, tenantId, globalFolds), backup: null };
-    const backup = backupStore(db, hippoRoot, 'before-repair');
-    const { result, rewrite, purge } = inTransaction(db, false, () => {
+    const { result, rewrite, purge } = withBackup(db, hippoRoot, 'before-repair', (backup) => inTransaction(db, false, () => {
         const copies = [];
         for (const row of strayImports(db, hippoRoot, tenantId)) {
             const tag = toolTag(row.source);
@@ -304,7 +300,7 @@ export function repairProjects(db, hippoRoot, opts) {
             rewrite: [...plan.toProject.map((r) => r.id), ...folded.flatMap((f) => f.restamped)],
             purge: [...copies, ...plan.setAside, ...folded.flatMap((f) => f.setAside)],
         };
-    });
+    }));
     refreshMirrors(db, hippoRoot, tenantId, rewrite, purge);
     return result;
 }