hippo-memory 1.48.0 → 1.49.0

package/dist/api.d.ts

@@ -40,6 +40,8 @@ export interface Actor {
     /** 'cli' | 'localhost:cli' | 'api_key:<key_id>' | 'mcp' | 'connector:slack' | 'connector:github' */
     subject: string;
     role: 'admin' | 'member';
+    /** EI2: restricted scopes a member key may read (auth.ts grantScope). Unused for admin actors. */
+    scopes?: readonly string[];
 }
 export interface Context {
     hippoRoot: string;
@@ -875,6 +877,14 @@ export interface AuthRevokeResult {
     revokedAt: string;
 }
 export declare function authRevoke(ctx: Context, keyId: string): AuthRevokeResult;
+/** Shared result shape for authGrant/authUngrant, named per the file's oxlint anti-slop rule. */
+export interface AuthGrantResult {
+    ok: true;
+}
+/** Grant `keyId` read access to one restricted `scope` (ROADMAP Part VIII EI2). Admin only. */
+export declare function authGrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
+/** Revoke `keyId`'s grant on `scope`. Same authorization and lookup rules as authGrant. */
+export declare function authUngrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
 export interface AuditListOpts {
     op?: AuditOp;
     /** ISO timestamp lower bound. */

package/dist/api.js

@@ -21,7 +21,7 @@ import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './s
 import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
 import { evalNow } from './ablation.js';
 import { archiveRawMemory } from './raw-archive.js';
-import { createApiKey, listApiKeys, revokeApiKey, } from './auth.js';
+import { createApiKey, listApiKeys, revokeApiKey, grantScope, ungrantScope, } from './auth.js';
 import { applyGoalStackBoost } from './goals.js';
 import { markRetrieved, estimateTokens, hybridSearch, physicsSearch } from './search.js';
 import { compareEntryIdentity, compareScoredResults } from './compare.js';
@@ -87,7 +87,7 @@ export class ForbiddenError extends Error {
 // back-compat (`api.isPrivateScope`, test imports). NOTE: the import statement
 // is required — a bare `export { x } from` re-export does not bind the local
 // names this module's ~9 call sites use.
-import { isPrivateScope, passesScopeFilterForRecall, assertScopeRequestAllowed } from './recall-scope.js';
+import { isPrivateScope, passesScopeFilterForRecall, assertScopeRequestAllowed, isRestrictedScope } from './recall-scope.js';
 export { isPrivateScope, passesScopeFilterForRecall };
 export { passesCliRecallScopeFilter, ScopeForbiddenError } from './recall-scope.js';
 // v39: classifyOriginProject lives in project-identity.ts (leaf) so
@@ -188,13 +188,13 @@ export function buildSuppressionSummary(counts) {
  */
 export function recall(ctx, opts) {
     // A member key may not unlock a private or quarantined scope by naming it.
-    assertScopeRequestAllowed(ctx.actor.role, opts.scope);
+    assertScopeRequestAllowed(ctx.actor, opts.scope);
     const windowSize = recallWindowSize(opts);
     return recallFrom(ctx, opts, windowSize, loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false));
 }
 /** Mode-aware recall that strengthens each returned row; never writes last_retrieval_ids (v1.11.5 lock). */
 export async function retrieve(ctx, opts) {
-    assertScopeRequestAllowed(ctx.actor.role, opts.scope);
+    assertScopeRequestAllowed(ctx.actor, opts.scope);
     const windowSize = recallWindowSize(opts);
     let candidates = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false);
     if (opts.mode === 'hybrid' || opts.mode === 'physics') {
@@ -288,7 +288,7 @@ function recallFrom(ctx, opts, windowSize, all) {
         // anchored `<source>:private:*` rule (v1.2.1 generalization) and
         // defense-in-depth: connector authors cannot silently surface private
         // rows to no-scope callers even if the SQL clause regresses.
-        entries = current.filter((e) => !isPrivateScope(e.scope ?? null));
+        entries = current.filter((e) => !isRestrictedScope(e.scope ?? null));
     }
     // v1.12.13 / C5 — WYSIATI dropped_pre_rank counter (JS scope filter drops
     // for api.recall; cmdRecall pipeline rolls --outcome/--layer/--as-of/etc.
@@ -725,7 +725,7 @@ function recallFrom(ctx, opts, windowSize, all) {
  *   - all rows fail the scope/tenant filter
  */
 export function assemble(ctx, sessionId, opts = {}) {
-    assertScopeRequestAllowed(ctx.actor.role, opts.scope);
+    assertScopeRequestAllowed(ctx.actor, opts.scope);
     const budget = opts.budget ?? 4000;
     const freshTailCount = opts.freshTailCount ?? 10;
     const summarizeOlder = opts.summarizeOlder ?? true;
@@ -1152,6 +1152,7 @@ export function supersede(ctx, oldId, newContent) {
         source: old.source,
         confidence: 'verified',
         tenantId: ctx.tenantId,
+        scope: old.scope,
     });
     // Race-safe transition: open a fresh db handle, BEGIN IMMEDIATE, run all
     // three steps (CAS on old + writeEntryDbOnly(new) + supersede audit row)
@@ -1401,6 +1402,50 @@ export function authRevoke(ctx, keyId) {
         closeHippoDb(db);
     }
 }
+/** Grant `keyId` read access to one restricted `scope` (ROADMAP Part VIII EI2). Admin only. */
+export function authGrant(ctx, keyId, scope) {
+    return changeScopeGrant(ctx, keyId, scope, 'auth_grant');
+}
+/** Revoke `keyId`'s grant on `scope`. Same authorization and lookup rules as authGrant. */
+export function authUngrant(ctx, keyId, scope) {
+    return changeScopeGrant(ctx, keyId, scope, 'auth_ungrant');
+}
+function changeScopeGrant(ctx, keyId, scope, op) {
+    if (ctx.actor.role !== 'admin') {
+        throw new ForbiddenError('Only an admin key can change scope grants');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        // SAFETY: row's shape matches the single tenant_id column in the SELECT.
+        const row = db
+            .prepare(`SELECT tenant_id, revoked_at FROM api_keys WHERE key_id = ?`)
+            .get(keyId);
+        if (!row || row.tenant_id !== ctx.tenantId) {
+            throw new Error(`Unknown key_id: ${keyId}`);
+        }
+        if (op === 'auth_grant' && row.revoked_at) {
+            throw new Error(`${keyId} is revoked; a grant on it would never apply`);
+        }
+        if (!isRestrictedScope(scope)) {
+            throw new Error(`${scope} is not a restricted scope; it is already readable by default`);
+        }
+        if (op === 'auth_grant')
+            grantScope(db, keyId, scope);
+        else
+            ungrantScope(db, keyId, scope);
+        try {
+            appendAuditEvent(db, { tenantId: ctx.tenantId, actor: ctx.actor.subject, op, targetId: keyId, metadata: { scope } });
+        }
+        catch (err) {
+            // Audit must not undo a grant change that already committed; surface it instead.
+            console.error(`auth: audit write failed for ${op} ${keyId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return { ok: true };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 /**
  * Read audit events scoped to `ctx.tenantId`. Read-only — no audit emit (matches
  * A5: cmdAuditList does not record a 'recall'-style read event).

package/dist/audit.d.ts

@@ -16,7 +16,7 @@ export interface AuditResult {
 export declare function auditMemory(entry: MemoryEntry): AuditIssue | null;
 export declare function auditMemories(entries: MemoryEntry[]): AuditResult;
 export declare function isContentWorthStoring(content: string): boolean;
-export type AuditOp = 'remember' | 'recall' | 'promote' | 'supersede' | 'forget' | 'archive_raw' | 'auth_revoke' | 'auth_create' | 'outcome' | 'consolidate' | 'audit_prune' | 'summary_marked_dirty' | 'summary_marked_clean' | 'summary_rebuilt' | 'predict_create' | 'predict_close' | 'predict_baserate' | 'recall_autodebias_hint' | 'recall_autodebias_hint_no_class_match' | 'recall_autodebias_hint_tiebreak' | 'recall_anchor_detected_query_repeat' | 'recall_anchor_detected_memory_dominance' | 'recall_anchor_skipped_no_session' | 'recall_availability_detected' | 'decision_create' | 'decision_supersede' | 'decision_close' | 'incident_open' | 'incident_resolve' | 'incident_close' | 'process_create' | 'process_supersede' | 'process_close' | 'policy_create' | 'policy_supersede' | 'policy_close' | 'skill_create' | 'skill_supersede' | 'skill_close' | 'project_brief_create' | 'project_brief_supersede' | 'project_brief_close' | 'customer_note_create' | 'customer_note_supersede' | 'customer_note_close' | 'mv_rescue' | 'reject_value' | 'reject_refusal' | 'unreject_value' | 'half_life_migrate' | 'dormant_restore' | 'conflict_resolve';
+export type AuditOp = 'remember' | 'recall' | 'promote' | 'supersede' | 'forget' | 'archive_raw' | 'auth_revoke' | 'auth_create' | 'outcome' | 'consolidate' | 'audit_prune' | 'summary_marked_dirty' | 'summary_marked_clean' | 'summary_rebuilt' | 'predict_create' | 'predict_close' | 'predict_baserate' | 'recall_autodebias_hint' | 'recall_autodebias_hint_no_class_match' | 'recall_autodebias_hint_tiebreak' | 'recall_anchor_detected_query_repeat' | 'recall_anchor_detected_memory_dominance' | 'recall_anchor_skipped_no_session' | 'recall_availability_detected' | 'decision_create' | 'decision_supersede' | 'decision_close' | 'incident_open' | 'incident_resolve' | 'incident_close' | 'process_create' | 'process_supersede' | 'process_close' | 'policy_create' | 'policy_supersede' | 'policy_close' | 'skill_create' | 'skill_supersede' | 'skill_close' | 'project_brief_create' | 'project_brief_supersede' | 'project_brief_close' | 'customer_note_create' | 'customer_note_supersede' | 'customer_note_close' | 'mv_rescue' | 'reject_value' | 'reject_refusal' | 'unreject_value' | 'half_life_migrate' | 'dormant_restore' | 'conflict_resolve' | 'auth_grant' | 'auth_ungrant';
 export interface AppendAuditOpts {
     tenantId: string;
     actor: string;

package/dist/auth.d.ts

@@ -16,9 +16,17 @@ export interface ValidateResult {
     keyId?: string;
     /** v1.12.0 A5 v2 sub-1: 'admin' | 'member'. Present only when valid=true. */
     role?: 'admin' | 'member';
+    /** EI2: scope grants for this key. Present only when valid=true. */
+    scopes?: string[];
 }
 export declare function validateApiKey(db: DatabaseSyncLike, plaintext: string): ValidateResult;
 export declare function revokeApiKey(db: DatabaseSyncLike, keyId: string): void;
+/** EI2: grant `keyId` read access to one restricted `scope`. Idempotent. */
+export declare function grantScope(db: DatabaseSyncLike, keyId: string, scope: string): void;
+/** EI2: revoke `keyId`'s grant on `scope`. Not an error when no such grant exists. */
+export declare function ungrantScope(db: DatabaseSyncLike, keyId: string, scope: string): void;
+/** EI2: every restricted scope `keyId` may read. */
+export declare function listScopeGrants(db: DatabaseSyncLike, keyId: string): string[];
 export interface ApiKeyListItem {
     keyId: string;
     tenantId: string;
@@ -31,6 +39,8 @@ export interface ApiKeyListItem {
      * Fail-safe-to-member cast: any non-'admin' value reads as 'member'.
      */
     role: 'admin' | 'member';
+    /** EI2: restricted scopes this key may read. */
+    scopes: string[];
 }
 export declare function listApiKeys(db: DatabaseSyncLike, opts: {
     active: boolean;

package/dist/auth.js

@@ -74,12 +74,30 @@ export function validateApiKey(db, plaintext) {
     // 'superuser', or a NULL slipped past the NOT NULL constraint) downgrades to
     // 'member'. The migration constrains to 'admin' DEFAULT, but defense-in-depth.
     const role = row.role === 'admin' ? 'admin' : 'member';
-    return { valid: true, tenantId: row.tenant_id, keyId, role };
+    const scopes = listScopeGrants(db, keyId);
+    return { valid: true, tenantId: row.tenant_id, keyId, role, scopes };
 }
 export function revokeApiKey(db, keyId) {
     db.prepare(`UPDATE api_keys SET revoked_at = ? WHERE key_id = ? AND revoked_at IS NULL`)
         .run(new Date().toISOString(), keyId);
 }
+/** EI2: grant `keyId` read access to one restricted `scope`. Idempotent. */
+export function grantScope(db, keyId, scope) {
+    db.prepare(`INSERT INTO api_key_scope_grants (key_id, scope, granted_at) VALUES (?, ?, ?)
+     ON CONFLICT(key_id, scope) DO NOTHING`).run(keyId, scope, new Date().toISOString());
+}
+/** EI2: revoke `keyId`'s grant on `scope`. Not an error when no such grant exists. */
+export function ungrantScope(db, keyId, scope) {
+    db.prepare(`DELETE FROM api_key_scope_grants WHERE key_id = ? AND scope = ?`).run(keyId, scope);
+}
+/** EI2: every restricted scope `keyId` may read. */
+export function listScopeGrants(db, keyId) {
+    // SAFETY: rows' shape matches the single `scope` column named in the SELECT above.
+    const rows = db
+        .prepare(`SELECT scope FROM api_key_scope_grants WHERE key_id = ? ORDER BY scope`)
+        .all(keyId);
+    return rows.map((r) => r.scope);
+}
 export function listApiKeys(db, opts) {
     const sql = opts.active
         ? `SELECT key_id, tenant_id, label, created_at, revoked_at, role FROM api_keys WHERE revoked_at IS NULL ORDER BY id DESC`
@@ -92,6 +110,7 @@ export function listApiKeys(db, opts) {
         keyId: r.key_id, tenantId: r.tenant_id, label: r.label,
         createdAt: r.created_at, revokedAt: r.revoked_at,
         role: r.role === 'admin' ? 'admin' : 'member',
+        scopes: listScopeGrants(db, r.key_id),
     }));
 }
 //# sourceMappingURL=auth.js.map

package/dist/cli.js

@@ -852,6 +852,7 @@ function cmdSupersede(hippoRoot, oldId, newContent, flags) {
         source: old.source,
         confidence: 'verified',
         tenantId: old.tenantId,
+        scope: old.scope,
     });
     // AT1: write the SUCCESSOR first. The rejection guard fires on the new
     // content — if it refuses, nothing has been mutated yet (the old ordering
@@ -7885,6 +7886,41 @@ function cmdAuthRevoke(hippoRoot, keyId, flags) {
     }
     console.log(`Revoked ${keyId} at ${revokedAt}`);
 }
+/** EI2: `hippo auth grant|ungrant <key_id> <scope>`, routed through api so the tenant, restricted-scope and audit checks live in one place. */
+function cmdAuthScopeGrant(hippoRoot, keyId, scope, grant, flags) {
+    const root = resolveAuthRoot(hippoRoot, flags);
+    // The local CLI owns every tenant (as auth revoke does), so the grant runs in the key's own tenant.
+    const db = openHippoDb(root);
+    let keyTenant;
+    try {
+        // SAFETY: row's shape matches the single tenant_id column in the SELECT.
+        const row = db.prepare(`SELECT tenant_id FROM api_keys WHERE key_id = ?`).get(keyId);
+        keyTenant = row?.tenant_id;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    if (keyTenant === undefined) {
+        console.error(`Unknown key_id: ${keyId}`);
+        process.exit(1);
+    }
+    const ctx = { hippoRoot: root, tenantId: keyTenant, actor: api.adminActor('cli') };
+    try {
+        if (grant)
+            api.authGrant(ctx, keyId, scope);
+        else
+            api.authUngrant(ctx, keyId, scope);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    if (flags['json']) {
+        console.log(JSON.stringify({ keyId, scope, granted: grant }));
+        return;
+    }
+    console.log(grant ? `Granted ${keyId} read access to ${scope}` : `Removed ${keyId}'s grant on ${scope}`);
+}
 // ---------------------------------------------------------------------------
 // Audit log subcommands (A5 stub auth — `hippo audit list`)
 // ---------------------------------------------------------------------------
@@ -7941,6 +7977,8 @@ const VALID_AUDIT_OPS = new Set([
     'conflict_resolve', // AT1 — emitted by resolveConflict on every resolution path; lockstep
     'half_life_migrate', // Decay default change — emitted by migrateDefaultHalfLife; lockstep with AuditOp union
     'dormant_restore', // Dormant memories — emitted by api.restoreDormant; lockstep with AuditOp union + server.ts VALID_AUDIT_OPS
+    'auth_grant', // EI2: emitted by api.authGrant; lockstep with AuditOp union + server.ts VALID_AUDIT_OPS
+    'auth_ungrant', // EI2: emitted by api.authUngrant; lockstep with AuditOp union + server.ts VALID_AUDIT_OPS
 ]);
 function formatAuditRow(ev) {
     const target = ev.targetId ?? '-';
@@ -8264,7 +8302,7 @@ function cmdGoal(hippoRoot, args, flags) {
 function cmdAuth(hippoRoot, args, flags) {
     const sub = args[0];
     if (!sub) {
-        console.error('Usage: hippo auth <create|list|revoke> [options]');
+        console.error('Usage: hippo auth <create|list|revoke|grant|ungrant> [options]');
         process.exit(1);
     }
     const subArgs = args.slice(1);
@@ -8284,8 +8322,18 @@ function cmdAuth(hippoRoot, args, flags) {
             cmdAuthRevoke(hippoRoot, keyId, flags);
             return;
         }
+        case 'grant':
+        case 'ungrant': {
+            const [keyId, scope] = subArgs;
+            if (!keyId || !scope) {
+                console.error(`Usage: hippo auth ${sub} <key_id> <scope>`);
+                process.exit(1);
+            }
+            cmdAuthScopeGrant(hippoRoot, keyId, scope, sub === 'grant', flags);
+            return;
+        }
         default:
-            console.error(`Unknown auth subcommand: ${sub}. Expected: create | list | revoke.`);
+            console.error(`Unknown auth subcommand: ${sub}. Expected: create | list | revoke | grant | ungrant.`);
             process.exit(1);
     }
 }
@@ -8966,6 +9014,12 @@ Commands:
     auth revoke <key_id>   Revoke an API key (subsequent validate fails)
       --json               Output as JSON
       --global             Operate on the global store
+    auth grant <key_id> <scope>    Let a member key read one restricted scope
+      --json               Output as JSON
+      --global             Operate on the global store
+    auth ungrant <key_id> <scope>  Remove a scope grant
+      --json               Output as JSON
+      --global             Operate on the global store
   audit <sub>              Query the append-only audit log (A5 stub auth)
     audit list             List audit events for the active tenant
       --op <op>            Filter by op (remember | recall | promote |

package/dist/consolidate.d.ts

@@ -19,6 +19,8 @@ export interface ConsolidationResult {
     semanticCreated: number;
     replayed: number;
     promotedTraces: number;
+    /** T7: sessions skipped because their events span two derivation scopes. */
+    tracesSkippedMixedScope: number;
     extractionCandidates: number;
     extracted: number;
     dagCandidateClusters: number;

package/dist/consolidate.js

@@ -25,6 +25,7 @@ import { rescueSet, rankNonPinnedByTenant, validateWeights } from './memory-valu
 import { MEMORY_VALUE_WEIGHTS, SOURCE_ARTIFACT_SHA256 } from './memory-value-weights.js';
 import { appendAuditEvent } from './audit.js';
 import { migrateDefaultHalfLife } from './half-life-migration.js';
+import { derivationScope, commonDerivationScope, derivationPartitionKey } from './recall-scope.js';
 const DECAY_THRESHOLD = 0.05;
 const MERGE_OVERLAP_THRESHOLD = 0.35; // Jaccard similarity for "related"
 const MERGE_MIN_CLUSTER = 2; // minimum cluster size to merge
@@ -108,6 +109,7 @@ export async function consolidate(hippoRoot, options = {}) {
         semanticCreated: 0,
         replayed: 0,
         promotedTraces: 0,
+        tracesSkippedMixedScope: 0,
         extractionCandidates: 0,
         extracted: 0,
         dagCandidateClusters: 0,
@@ -368,6 +370,13 @@ export async function consolidate(hippoRoot, options = {}) {
                     session_id: session.session_id,
                     limit: 1000,
                 });
+                // T7: a mixed-scope session would otherwise leak into one trace.
+                const sessionScope = commonDerivationScope(events.map((e) => e.scope));
+                if (!sessionScope.ok) {
+                    result.tracesSkippedMixedScope++;
+                    result.details.push(`  ⏭  skipped session ${session.session_id}: events span mixed scopes`);
+                    continue;
+                }
                 const completeEvent = events.find((e) => e.event_type === 'session_complete');
                 if (!completeEvent)
                     continue; // defence-in-depth; findPromotableSessions filters already.
@@ -391,6 +400,7 @@ export async function consolidate(hippoRoot, options = {}) {
                     source_session_id: session.session_id,
                     tags: ['auto-promoted'],
                     source: 'auto-promote',
+                    scope: sessionScope.scope,
                     // T1 fix (2026-08-15 hardening pass): stamp the trace into the SAME
                     // tenant the traceExistsForSession idempotency check (above) runs
                     // under. Before
@@ -671,11 +681,12 @@ export async function consolidate(hippoRoot, options = {}) {
         // before this fix — byte-identical behavior there.
         const mergeCandidatesByTenant = new Map();
         for (const entry of mergeCandidates) {
-            const bucket = mergeCandidatesByTenant.get(entry.tenantId);
+            const key = derivationPartitionKey(entry.tenantId, entry.scope);
+            const bucket = mergeCandidatesByTenant.get(key);
             if (bucket)
                 bucket.push(entry);
             else
-                mergeCandidatesByTenant.set(entry.tenantId, [entry]);
+                mergeCandidatesByTenant.set(key, [entry]);
         }
         // AT1 consolidation-loop fix (docs/plans/2026-08-15-at1-rejected-value-tombstone.md):
         // reuses the single consolidateDb handle opened once above (before the
@@ -686,7 +697,9 @@ export async function consolidate(hippoRoot, options = {}) {
         // declared up at the try's opening above 1.4, not here — it has to
         // survive the try/finally that now wraps this whole section; see the
         // handle-leak restructure comment there.)
-        for (const [mergeTenant, tenantCandidates] of mergeCandidatesByTenant) {
+        for (const [, tenantCandidates] of mergeCandidatesByTenant) {
+            const mergeTenant = tenantCandidates[0].tenantId;
+            const mergeScope = derivationScope(tenantCandidates[0].scope);
             for (let i = 0; i < tenantCandidates.length; i++) {
                 if (used.has(tenantCandidates[i].id))
                     continue;
@@ -722,6 +735,7 @@ export async function consolidate(hippoRoot, options = {}) {
                         source: 'consolidation',
                         confidence: 'inferred',
                         tenantId: mergeTenant,
+                        scope: mergeScope,
                     });
                 }
                 // mergeContents is DETERMINISTIC CONCATENATION (not an LLM paraphrase)

package/dist/dag.js

@@ -2,6 +2,7 @@ import { createMemory, Layer } from './memory.js';
 import { writeEntry, loadAllDirtySummaries, loadChildrenOfSummary, applyRebuildResult, clearSummaryDirtyAfterBuild, } from './store.js';
 import { RejectedValueError } from './rejection.js';
 import { redactSecrets } from './secret-detect.js';
+import { derivationScope, derivationPartitionKey } from './recall-scope.js';
 export function clusterFacts(facts) {
     if (facts.length === 0)
         return [];
@@ -93,13 +94,16 @@ export async function buildDag(hippoRoot, facts, opts) {
     // behavior there.
     const unparentedByTenant = new Map();
     for (const fact of unparented) {
-        const bucket = unparentedByTenant.get(fact.tenantId);
+        const key = derivationPartitionKey(fact.tenantId, fact.scope);
+        const bucket = unparentedByTenant.get(key);
         if (bucket)
             bucket.push(fact);
         else
-            unparentedByTenant.set(fact.tenantId, [fact]);
+            unparentedByTenant.set(key, [fact]);
     }
-    for (const [factTenant, tenantFacts] of unparentedByTenant) {
+    for (const [, tenantFacts] of unparentedByTenant) {
+        const factTenant = tenantFacts[0].tenantId;
+        const factScope = derivationScope(tenantFacts[0].scope);
         const clusters = clusterFacts(tenantFacts);
         const eligibleClusters = clusters.filter((c) => c.members.length >= 3);
         result.candidateClusters += eligibleClusters.length;
@@ -118,6 +122,7 @@ export async function buildDag(hippoRoot, facts, opts) {
                 confidence: 'inferred',
                 dag_level: 2,
                 tenantId: factTenant,
+                scope: factScope,
             });
             // Schema v25: cache descendant_count + earliest/latest_at on the summary
             // row so DAG-aware recall (docs/plans/2026-05-05-dag-recall.md Task 2)
@@ -299,11 +304,14 @@ export async function buildEntityProfiles(hippoRoot, l2Summaries, opts) {
     const byTenant = new Map();
     for (const l2 of unparented) {
         const tid = l2.tenantId ?? 'default';
-        const list = byTenant.get(tid) ?? [];
+        const key = derivationPartitionKey(tid, l2.scope);
+        const list = byTenant.get(key) ?? [];
         list.push(l2);
-        byTenant.set(tid, list);
+        byTenant.set(key, list);
     }
-    for (const [tenantId, tenantL2s] of byTenant) {
+    for (const [, tenantL2s] of byTenant) {
+        const tenantId = tenantL2s[0].tenantId ?? 'default';
+        const scope = derivationScope(tenantL2s[0].scope);
         const clusters = clusterFacts(tenantL2s);
         const eligible = clusters.filter((c) => c.members.length >= 2);
         result.candidateClusters += eligible.length;
@@ -321,6 +329,7 @@ export async function buildEntityProfiles(hippoRoot, l2Summaries, opts) {
                 confidence: 'inferred',
                 dag_level: 3,
                 tenantId, // HIGH #1 fold: thread tenant explicitly
+                scope,
             });
             profileEntry.descendant_count = cluster.members.length;
             profileEntry.earliest_at = memberCreatedAts[0];

package/dist/db.js

@@ -11,7 +11,7 @@ const require = createRequire(import.meta.url);
 // runtime (Node's built-in synchronous SQLite module); there are no bundled
 // types for it here, so this require + cast is the module's documented boundary.
 const { DatabaseSync } = require('node:sqlite');
-const CURRENT_SCHEMA_VERSION = 46;
+const CURRENT_SCHEMA_VERSION = 47;
 const MIGRATIONS = [
     {
         version: 1,
@@ -2447,6 +2447,22 @@ const MIGRATIONS = [
       `);
         },
     },
+    {
+        version: 47,
+        up: (db) => {
+            // Scope grants (src/auth.ts, ROADMAP EI2): a member key reads a
+            // restricted scope only by an explicit row here. Additive only: no
+            // min_compatible_binary bump.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS api_key_scope_grants (
+          key_id     TEXT NOT NULL,
+          scope      TEXT NOT NULL,
+          granted_at TEXT NOT NULL,
+          PRIMARY KEY(key_id, scope)
+        );
+      `);
+        },
+    },
 ];
 function tableHasColumn(db, tableName, columnName) {
     if (!/^[a-z_]+$/i.test(tableName))

package/dist/dedupe.js

@@ -24,6 +24,7 @@ import { textOverlap } from './search.js';
 import { loadAllEntries, deleteEntry } from './store.js';
 import { compareEntryIdentity } from './compare.js';
 import { canAutoDelete } from './memory.js';
+import { derivationPartitionKey } from './recall-scope.js';
 /** Quantization step for strength-tie comparisons. The historical 0.01
  *  epsilon (see `strengthBucket` below) applied via rounding instead of a
  *  raw abs-diff threshold, so the tiebreak is transitive. */
@@ -76,11 +77,13 @@ export function deduplicateStore(hippoRoot, options = {}) {
     // pre-fix global pass.
     const entriesByTenant = new Map();
     for (const entry of entries) {
-        const bucket = entriesByTenant.get(entry.tenantId);
+        // EI2: also split by restricted scope, else a private copy can delete the readable one.
+        const key = derivationPartitionKey(entry.tenantId, entry.scope);
+        const bucket = entriesByTenant.get(key);
         if (bucket)
             bucket.push(entry);
         else
-            entriesByTenant.set(entry.tenantId, [entry]);
+            entriesByTenant.set(key, [entry]);
     }
     // finiteCount mirrors strengthBucket's non-finite hardening on the
     // retrieval leg: a NaN retrieval_count would make the comparator return

package/dist/extract.js

@@ -92,6 +92,7 @@ export function storeExtractedFacts(hippoRoot, source, facts) {
             confidence: 'inferred',
             source: source.source,
             extracted_from: source.id,
+            scope: source.scope,
             // T1 executor check (2026-08-15 hardening pass): same defect as the
             // consolidate.ts merge/trace passes — createMemory with no tenantId
             // option stamps 'default' (memory.ts:535) regardless of the source

package/dist/mcp/server.d.ts

@@ -48,6 +48,8 @@ export interface McpContext {
      * assuming admin, or a member key over HTTP-MCP would act as admin.
      */
     role?: 'admin' | 'member';
+    /** EI2: scope grants for the HTTP-MCP caller's key. Absent for stdio (admin, needs none). */
+    scopes?: readonly string[];
     /**
      * 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/server.js

@@ -12,7 +12,7 @@ import * as path from 'path';
 import { createMemory, Layer, calculateStrength, } from '../memory.js';
 import { hybridSearch, physicsSearch, estimateTokens } from '../search.js';
 import { evalNow } from '../ablation.js';
-import { loadAllEntries, writeEntry, strengthenRetrieved, readEntry, loadFreshActiveTaskSnapshot, listMemoryConflicts, resolveConflict, RECALL_DEFAULT_DENY_SCOPES, countCreatedSinceLastSleep } from '../store.js';
+import { loadAllEntries, writeEntry, strengthenRetrieved, readEntry, loadFreshActiveTaskSnapshot, listMemoryConflicts, resolveConflict, countCreatedSinceLastSleep } from '../store.js';
 import { shareMemory, listPeers, getGlobalRoot, initGlobal } from '../shared.js';
 import { consolidate } from '../consolidate.js';
 import { execSync } from 'child_process';
@@ -20,7 +20,7 @@ import { fetchGitLog, extractLessons, partitionLessons, deduplicateLesson, isGit
 import { loadConfig } from '../config.js';
 import { confidenceLabel } from '../memory.js';
 import { resolveTenantId } from '../tenant.js';
-import { recall as apiRecall, remember as apiRemember, outcome as apiOutcome, drillDown as apiDrillDown, assemble as apiAssemble, isPrivateScope, passesScopeFilterForRecall, buildSuppressionSummary, ambientSecretAdmit } from '../api.js';
+import { recall as apiRecall, remember as apiRemember, outcome as apiOutcome, drillDown as apiDrillDown, assemble as apiAssemble, passesScopeFilterForRecall, buildSuppressionSummary, ambientSecretAdmit } from '../api.js';
 import { assertScopeRequestAllowed } from '../recall-scope.js';
 import { resolveProjectIdentity, classifyOriginProject, findHippoStoreDir } from '../project-identity.js';
 import { computePredictionBaserate } from '../predictions.js';
@@ -57,7 +57,7 @@ export function findHippoRoot(cwd = process.cwd(), opts) {
  * a member key never acts as admin through MCP.
  */
 function mcpActor(ctx) {
-    return { subject: ctx?.actor ?? 'mcp', role: ctx?.role ?? 'admin' };
+    return { subject: ctx?.actor ?? 'mcp', role: ctx?.role ?? 'admin', scopes: ctx?.scopes };
 }
 // MCP stdio transport spec: messages are newline-delimited JSON-RPC, no embedded newlines.
 // https://modelcontextprotocol.io/specification/.../basic/transports#stdio
@@ -518,7 +518,7 @@ async function executeTool(name, args, ctx) {
             // ordering and the strength bump on retrieval. Apply the same scope
             // rule as api.recall: explicit scope = exact match; no scope =
             // default-deny on ANY `<source>:private:*` AND 'unknown:legacy'.
-            // v1.2.1: generic-private check via api.isPrivateScope.
+            // EI2: one shared predicate (passesScopeFilterForRecall) so MCP never admits what SQL hides.
             const allEntries = loadAllEntries(hippoRoot, tenantId);
             // v1.12.13 / C5 — WYSIATI counters for the MCP physics/hybrid pipeline.
             // Per the plan-eng-critic round 1 CRIT resolution: MCP's user-visible
@@ -530,18 +530,7 @@ async function executeTool(name, args, ctx) {
             const totalCandidatesCountMcp = allEntries.length;
             const entries = explicitScope
                 ? allEntries.filter((e) => e.scope === explicitScope)
-                : allEntries.filter((e) => {
-                    const s = e.scope ?? null;
-                    if (s === null)
-                        return true;
-                    if (isPrivateScope(s))
-                        return false;
-                    // v1.7.2: read from RECALL_DEFAULT_DENY_SCOPES (single source of truth
-                    // shared with SQL clause + passesScopeFilterForRecall).
-                    if (RECALL_DEFAULT_DENY_SCOPES.some((deny) => deny === s))
-                        return false;
-                    return true;
-                });
+                : allEntries.filter((e) => passesScopeFilterForRecall(e.scope ?? null, undefined));
             const droppedPreRankCountMcp = allEntries.length - entries.length;
             const usePhysics = config.physics?.enabled !== false;
             let results = usePhysics
@@ -1012,7 +1001,7 @@ async function executeTool(name, args, ctx) {
             // results and the snapshot. Pre-v1.2 this surface returned all memories
             // and the snapshot unfiltered, which would have leaked private-channel
             // content to no-scope MCP callers once scope writers shipped.
-            assertScopeRequestAllowed(mcpActor(ctx).role, explicitScope);
+            assertScopeRequestAllowed(mcpActor(ctx), explicitScope);
             const allEntries = loadAllEntries(hippoRoot, tenantId);
             // v39 memory scope isolation: this surface reads the LOCAL store only,
             // but synced-down or legacy rows can still carry another project's

package/dist/project-briefs.js

@@ -22,7 +22,7 @@
  * closed (retired).
  */
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry, assertTenantId } from './store.js';
+import { writeEntry, assertTenantId, RECALL_DEFAULT_DENY_SCOPES } from './store.js';
 import { markGraphDirty, removeGraphEntitiesForObject } from './graph.js';
 import { createMemory, Layer, PROJECT_BRIEF_HALF_LIFE_DAYS } from './memory.js';
 import { appendAuditEvent } from './audit.js';
@@ -386,6 +386,7 @@ export function assembleBriefFromReceipts(hippoRoot, tenantId, repo) {
     }
     const tag = `path:${normalizedRepo.toLowerCase()}`;
     const likeParam = `%"${escapeLike(tag)}"%`;
+    const denyPlaceholders = RECALL_DEFAULT_DENY_SCOPES.map(() => '?').join(', ');
     const db = openHippoDb(hippoRoot);
     let receipts;
     try {
@@ -396,9 +397,10 @@ export function assembleBriefFromReceipts(hippoRoot, tenantId, repo) {
       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:%'))
       ORDER BY created DESC, id DESC
       LIMIT ?
-    `).all(tenantId, likeParam, MAX_BRIEF_RECEIPTS);
+    `).all(tenantId, likeParam, ...RECALL_DEFAULT_DENY_SCOPES, MAX_BRIEF_RECEIPTS);
     }
     finally {
         closeHippoDb(db);

package/dist/recall-scope.d.ts

@@ -71,14 +71,26 @@ export declare class ScopeForbiddenError extends Error {
  * is the act that needs authorization.
  */
 export declare function isRestrictedScope(scope: string | null | undefined): boolean;
-/**
- * Authorize an explicitly requested scope before any read honours it.
- *
- * An admin (tenant owner, the local CLI, loopback without a key) may unlock
- * any scope in its tenant. A member key may not unlock a restricted scope by
- * naming it: before this check, any key in a tenant could read every private
- * channel or repo by passing its scope string. Per-scope grants for member
- * keys belong to ROADMAP Part VIII EI2 (permission-aware recall).
- */
-export declare function assertScopeRequestAllowed(role: 'admin' | 'member', requested: string | undefined): void;
+/** The identity a scope check runs against: a role plus any scope grants. */
+export interface ScopeActor {
+    role: 'admin' | 'member';
+    scopes?: readonly string[];
+}
+/** True when `actor` may read `scope`: admin always; member needs an exact grant on a restricted scope. */
+export declare function canReadScope(actor: ScopeActor, scope: string): boolean;
+/** Authorize an explicitly requested scope before any read honours it (ROADMAP Part VIII EI2: member scope grants). */
+export declare function assertScopeRequestAllowed(actor: ScopeActor, requested: string | undefined): void;
+/** Scope a derived row keeps from one source: the restricted scope itself, else null. */
+export declare function derivationScope(scope: string | null | undefined): string | null;
+/** The one derivation scope shared by every source, or `{ ok: false }` when
+ *  two disagree, so the caller skips the derived row instead of under-scoping it. */
+export declare function commonDerivationScope(scopes: readonly (string | null | undefined)[]): {
+    ok: true;
+    scope: string | null;
+} | {
+    ok: false;
+};
+/** Map-partition key for consolidate/dag producers: tenant + derivation scope,
+ *  so a derived row never blends two restricted scopes or a mixed pair. */
+export declare function derivationPartitionKey(tenantId: string, scope: string | null | undefined): string;
 //# sourceMappingURL=recall-scope.d.ts.map

package/dist/recall-scope.js

@@ -50,18 +50,7 @@ export function passesScopeFilterForRecall(scope, requested) {
     if (requested !== undefined && requested !== '') {
         return scope === requested;
     }
-    if (scope === null)
-        return true;
-    if (isPrivateScope(scope))
-        return false;
-    // SAFETY: RECALL_DEFAULT_DENY_SCOPES (v1.7.2, single source of truth
-    // shared with the SQL clause in loadSearchRows) is a readonly tuple of
-    // string literals. Cast the array to readonly string[] so .includes()
-    // accepts arbitrary string scopes without a cast on the input (codex
-    // P0-2: casting `scope` would defeat the constant's safety).
-    if (RECALL_DEFAULT_DENY_SCOPES.includes(scope))
-        return false;
-    return true;
+    return !isRestrictedScope(scope);
 }
 /**
  * v1.25.0 — the CLI `--scope` variant of the recall filter (JS half of the
@@ -108,23 +97,49 @@ export function isRestrictedScope(scope) {
         return false;
     // SAFETY: RECALL_DEFAULT_DENY_SCOPES is a readonly tuple of string
     // literals; widening the array (not the input) lets .includes() take any scope.
-    return isPrivateScope(scope) || RECALL_DEFAULT_DENY_SCOPES.includes(scope);
+    // `:private:` anywhere, any case, matches the store's SQL default-deny (store.ts:894) so JS never admits what SQL hides.
+    return isPrivateScope(scope) || /:private:/i.test(scope) || RECALL_DEFAULT_DENY_SCOPES.includes(scope);
 }
-/**
- * Authorize an explicitly requested scope before any read honours it.
- *
- * An admin (tenant owner, the local CLI, loopback without a key) may unlock
- * any scope in its tenant. A member key may not unlock a restricted scope by
- * naming it: before this check, any key in a tenant could read every private
- * channel or repo by passing its scope string. Per-scope grants for member
- * keys belong to ROADMAP Part VIII EI2 (permission-aware recall).
- */
-export function assertScopeRequestAllowed(role, requested) {
+/** True when `actor` may read `scope`: admin always; member needs an exact grant on a restricted scope. */
+export function canReadScope(actor, scope) {
+    if (actor.role === 'admin')
+        return true;
+    if (!isRestrictedScope(scope))
+        return true;
+    return (actor.scopes ?? []).includes(scope);
+}
+/** Authorize an explicitly requested scope before any read honours it (ROADMAP Part VIII EI2: member scope grants). */
+export function assertScopeRequestAllowed(actor, requested) {
     if (requested === undefined || requested === '')
         return;
-    if (role === 'admin')
+    if (canReadScope(actor, requested))
         return;
-    if (isRestrictedScope(requested))
-        throw new ScopeForbiddenError(requested);
+    throw new ScopeForbiddenError(requested);
+}
+/** Scope a derived row keeps from one source: the restricted scope itself, else null. */
+export function derivationScope(scope) {
+    return isRestrictedScope(scope) ? (scope ?? null) : null;
+}
+/** The one derivation scope shared by every source, or `{ ok: false }` when
+ *  two disagree, so the caller skips the derived row instead of under-scoping it. */
+export function commonDerivationScope(scopes) {
+    let common = null;
+    let seen = false;
+    for (const raw of scopes) {
+        const scope = derivationScope(raw);
+        if (!seen) {
+            common = scope;
+            seen = true;
+        }
+        else if (scope !== common) {
+            return { ok: false };
+        }
+    }
+    return { ok: true, scope: common };
+}
+/** Map-partition key for consolidate/dag producers: tenant + derivation scope,
+ *  so a derived row never blends two restricted scopes or a mixed pair. */
+export function derivationPartitionKey(tenantId, scope) {
+    return `${tenantId}\u0000${derivationScope(scope) ?? ''}`;
 }
 //# sourceMappingURL=recall-scope.js.map

package/dist/secret-detect.js

@@ -50,7 +50,7 @@ const KEYISH_CONTEXT_RE = /key|token|secret|credential|bearer|auth|password/i;
 const CO_OCCURRENCE_GUARDED = new Set(['sk-style-key', 'sk-underscore-key']);
 // redactSecretsStrict-only: too noisy for whole-entry memory scanning, worth hiding once text leaves the machine.
 const STRICT_ONLY_PATTERNS = [
-    /\b[Bb]earer\s+[A-Za-z0-9._~+/-]{16,}=*/g,
+    /\bbearer\s+[A-Za-z0-9._~+/-]{16,}=*/gi,
     /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]*/g,
 ];
 /**

package/dist/server.js

@@ -116,6 +116,8 @@ const VALID_AUDIT_OPS = new Set([
     'conflict_resolve', // AT1 — emitted by resolveConflict on every resolution path; lockstep
     'half_life_migrate', // Decay default change — emitted by migrateDefaultHalfLife; lockstep with AuditOp union
     'dormant_restore', // Dormant memories — emitted by api.restoreDormant; lockstep with AuditOp union + cli.ts VALID_AUDIT_OPS
+    'auth_grant', // EI2: emitted by api.authGrant; lockstep with AuditOp union + cli.ts VALID_AUDIT_OPS
+    'auth_ungrant', // EI2: emitted by api.authUngrant; lockstep with AuditOp union + cli.ts VALID_AUDIT_OPS
 ]);
 // Cap on GET /v1/audit?limit=. Matches docs/api.md (when written) and is large
 // enough to dump a small deployment's full audit log without paginating, but
@@ -469,6 +471,7 @@ function buildContextWithAuth(req, hippoRoot) {
                 actor: {
                     subject: `api_key:${result.keyId}`,
                     role: result.role,
+                    scopes: result.scopes,
                 },
             };
         }
@@ -1191,16 +1194,13 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             limit = parsed;
         }
         const ctx = buildContextWithAuth(req, opts.hippoRoot);
-        // D2 v1.12.10: optional ?tenant=<t> param. Defaults to ctx.tenantId
-        // (caller's own tenant). Lets admins query the '__host__' synthetic
-        // tenant where host-wide ops like 'consolidate' are recorded. Today
-        // the audit route inherits the auth gate on /v1/audit (Bearer auth);
-        // a future per-tenant authz check should ensure non-admin Bearers
-        // can only pass their own tenant_id here.
+        // ?tenant=<t> reads another tenant (e.g. '__host__' for consolidate rows); admin only.
         const tenantOverride = query.get('tenant');
-        const effectiveCtx = tenantOverride !== null && tenantOverride !== ''
-            ? { ...ctx, tenantId: tenantOverride }
-            : ctx;
+        const crossTenant = tenantOverride !== null && tenantOverride !== '' && tenantOverride !== ctx.tenantId;
+        if (crossTenant && ctx.actor.role !== 'admin') {
+            throw new HttpError(403, '/v1/audit?tenant= for another tenant requires admin role');
+        }
+        const effectiveCtx = crossTenant ? { ...ctx, tenantId: tenantOverride } : ctx;
         const result = auditList(effectiveCtx, { op, since, limit });
         sendJson(res, 200, result);
         return;
@@ -3021,6 +3021,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
                 actor: ctx.actor.subject,
                 // The caller's real role: MCP tools must not run a member key as admin.
                 role: ctx.actor.role,
+                scopes: ctx.actor.scopes,
                 clientKey: buildMcpClientKey(req),
             });
         }

package/dist/version.d.ts

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export declare const PACKAGE_VERSION = "1.48.0";
+export declare const PACKAGE_VERSION = "1.49.0";
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export declare function compareSemver(a: string, b: string): number;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export const PACKAGE_VERSION = '1.48.0';
+export const PACKAGE_VERSION = '1.49.0';
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export function compareSemver(a, b) {
     const parse = (v) => {

package/extensions/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Biologically-inspired memory for AI agents. Decay by default, retrieval strengthening, sleep consolidation.",
-  "version": "1.48.0",
+  "version": "1.49.0",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.48.0",
+  "version": "1.49.0",
   "type": "module",
   "description": "Hippo Memory plugin for OpenClaw - biologically-inspired agent memory",
   "main": "index.ts",

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Biologically-inspired memory for AI agents. Decay by default, retrieval strengthening, sleep consolidation.",
-  "version": "1.48.0",
+  "version": "1.49.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.48.0",
+  "version": "1.49.0",
   "description": "Biologically-inspired memory for AI agents. Zero runtime deps, SQLite, MCP server, and an opt-in hosted TypeSafe Jev reranker. Decay, retrieval strengthening, consolidation.",
   "mcpName": "io.github.kitfunso/hippo-memory",
   "type": "module",