hippo-memory 1.70.0 → 1.71.0

package/README.md

@@ -784,7 +784,7 @@ hippo watch "npm run build"
 | `hippo dashboard` | Open web dashboard at localhost:3333 (memory health by project, and the card board); open the printed URL, which carries a per-start access token |
 | `hippo dashboard --port <n>` | Use custom port |
 | `hippo mcp` | Start MCP server (stdio transport) |
-| `hippo serve` | Start the HTTP API server for this store on `127.0.0.1:6789` (`--port <n>` or `HIPPO_PORT`; `--host <host>`, which off loopback needs `HIPPO_REQUIRE_AUTH=1`) |
+| `hippo serve` | Start the HTTP API server for this store on `127.0.0.1:6789` (`--port <n>` or `HIPPO_PORT`; `--host <host>`, which off loopback needs `HIPPO_REQUIRE_AUTH=1`). Every request needs an API key (`hippo auth create`, then `Authorization: Bearer <key>`; the hippo CLI reads `HIPPO_API_KEY`). `HIPPO_ALLOW_KEYLESS_LOCAL=1` lets requests from this machine in without one, as host admin; `HIPPO_REQUIRE_AUTH=1` wins over it |
 | `hippo serve --tls-cert <file> --tls-key <file>` | Serve HTTPS with that PEM certificate and key (or set `HIPPO_TLS_CERT` and `HIPPO_TLS_KEY`). Without them a network bind still starts, and warns once that API keys and memory text travel in cleartext unless a TLS-terminating proxy sits in front |
 
 On `heartbeat`, `block`, `review` and `complete`, a given `--run` is checked against the card's live run and the command is refused, unchanged, if the two do not match.

package/dist/agent-memories/claude-code.d.ts

@@ -1,12 +1,14 @@
 import { type ProjectIdentity } from '../core/project-identity.js';
 import type { Adapter, AdapterContext, Listing } from './types.js';
-/** Claude Code's rule: a linked worktree shares its main checkout's folder, or the git folder's when that sits outside a checkout (a bare repository, or --separate-git-dir); any other checkout, a submodule included, keeps its own. */
+/** Claude Code's rule: a linked worktree shares its main checkout's folder, or the git folder's when that sits outside
+ * a checkout (a bare repository, or --separate-git-dir); any other checkout, a submodule included, keeps its own. */
 export declare function claudeCheckoutRoot(top: string, gitDir: string, common: string): string;
 /** Claude Code's folder name for a path: non-alphanumerics made '-', and a name over 200 characters cut to 200 plus a base-36 hash of the whole path. */
 export declare function claudeFolderName(root: string): string;
 export declare const claudeCodeAdapter: Adapter;
 /** A session's own notes folder and nothing else, with no git call, so post-compact can read it inside the hook's time limit. */
 export declare function claudeTranscriptListing(ctx: AdapterContext, transcriptPath: string): Listing;
-/** The project a session folder's notes belong to: the one Claude named the folder for, the session's start folder, else cwd or a parent; null when none matches. */
+/** The project a session folder's notes belong to: the one Claude named the folder
+ * for, the session's start folder, else cwd or a parent; null when none matches. */
 export declare function transcriptNotesProject(transcriptPath: string, cwd: string | null, machine: Pick<AdapterContext, 'platform' | 'env'>): ProjectIdentity | null;
 //# sourceMappingURL=claude-code.d.ts.map

package/dist/agent-memories/claude-code.js

@@ -21,7 +21,8 @@ function claudeMemoryFolderNames(projectRoot, platform) {
         roots.push(claudeCheckoutRoot(layout.top, layout.gitDir, layout.common));
     return new Set(roots.map((root) => (platform === 'win32' ? claudeFolderName(root).toLowerCase() : claudeFolderName(root))));
 }
-/** Claude Code's rule: a linked worktree shares its main checkout's folder, or the git folder's when that sits outside a checkout (a bare repository, or --separate-git-dir); any other checkout, a submodule included, keeps its own. */
+/** Claude Code's rule: a linked worktree shares its main checkout's folder, or the git folder's when that sits outside
+ * a checkout (a bare repository, or --separate-git-dir); any other checkout, a submodule included, keeps its own. */
 export function claudeCheckoutRoot(top, gitDir, common) {
     if (gitDir === common)
         return top;
@@ -55,7 +56,8 @@ export function claudeTranscriptListing(ctx, transcriptPath) {
     const folder = path.join(path.dirname(transcriptPath), 'memory');
     return { tool: 'claude-code', home: config, containers: readFolders([folder], 'project', ctx.platform), warnings: [] };
 }
-/** The project a session folder's notes belong to: the one Claude named the folder for, the session's start folder, else cwd or a parent; null when none matches. */
+/** The project a session folder's notes belong to: the one Claude named the folder
+ * for, the session's start folder, else cwd or a parent; null when none matches. */
 export function transcriptNotesProject(transcriptPath, cwd, machine) {
     const fold = (name) => (machine.platform === 'win32' ? name.toLowerCase() : name);
     const folder = fold(path.basename(path.dirname(transcriptPath)));
@@ -79,9 +81,16 @@ export function transcriptNotesProject(transcriptPath, cwd, machine) {
 const START_SCAN_BYTES = 64 * 1024;
 /** The cwd on the transcript's first line that has one: the folder Claude named the session folder for, which a folder name alone cannot give back. */
 function transcriptStartCwd(transcriptPath) {
-    if (!fs.existsSync(transcriptPath))
-        return null;
-    const fd = fs.openSync(transcriptPath, 'r');
+    let fd;
+    try {
+        fd = fs.openSync(transcriptPath, 'r');
+    }
+    catch (err) {
+        // A transcript that is not there names no start folder; any other failure is the caller's to see.
+        if (err instanceof Error && 'code' in err && (err.code === 'ENOENT' || err.code === 'ENOTDIR'))
+            return null;
+        throw err;
+    }
     try {
         const buf = Buffer.alloc(START_SCAN_BYTES);
         const lines = buf.subarray(0, fs.readSync(fd, buf, 0, buf.length, 0)).toString('utf8').split('\n');

package/dist/agent-memories/files.js

@@ -7,23 +7,34 @@ const MAX_DEPTH = 8;
 /** A file's text, or why it was skipped: empty, too big, holds a NUL byte (not text), or unreadable. */
 export function readTextFile(file) {
     try {
-        const stat = fs.statSync(file);
-        if (!stat.isFile())
-            return { ok: false, reason: `${file}: not a file` };
-        // A tool rewriting a file truncates it first; read as holding no notes, every row would be set aside.
-        if (stat.size === 0)
-            return { ok: false, reason: `${file}: empty` };
-        if (stat.size > MAX_ITEM_BYTES)
-            return { ok: false, reason: `${file}: over ${MAX_ITEM_BYTES} bytes` };
-        const buf = fs.readFileSync(file);
-        if (buf.includes(0))
-            return { ok: false, reason: `${file}: not text` };
-        return { ok: true, text: buf.toString('utf8'), mtimeMs: stat.mtimeMs };
+        // O_NONBLOCK opens a FIFO at once, for the file check to turn away; Windows has no such flag and the OR adds nothing.
+        const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+        try {
+            return readOpenTextFile(file, fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
     }
     catch (err) {
         return { ok: false, reason: `${file}: ${errorMessage(err)}` };
     }
 }
+/** The checks and the read on one descriptor, so the file measured is the file read. */
+function readOpenTextFile(file, fd) {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile())
+        return { ok: false, reason: `${file}: not a file` };
+    // A tool rewriting a file truncates it first; read as holding no notes, every row would be set aside.
+    if (stat.size === 0)
+        return { ok: false, reason: `${file}: empty` };
+    if (stat.size > MAX_ITEM_BYTES)
+        return { ok: false, reason: `${file}: over ${MAX_ITEM_BYTES} bytes` };
+    const buf = fs.readFileSync(fd);
+    if (buf.includes(0))
+        return { ok: false, reason: `${file}: not text` };
+    return { ok: true, text: buf.toString('utf8'), mtimeMs: stat.mtimeMs };
+}
 /** Files in a folder as '/'-separated relative paths, sorted; dot entries skipped, symlinked folders not followed. */
 export function listFiles(dir, opts) {
     if (!fs.existsSync(dir))

package/dist/agent-memories/markdown.d.ts

@@ -1,6 +1,4 @@
-/**
- * Splits one markdown memory file into items (a top-level bullet or a paragraph), each tagged with its heading. Pure.
- */
+/** Splits one markdown memory file into items (a top-level bullet or a paragraph), each tagged with its heading. Pure. */
 export interface MarkdownItem {
     readonly heading: string;
     readonly headingSlug: string;

package/dist/agent-memories/markdown.js

@@ -1,6 +1,4 @@
-/**
- * Splits one markdown memory file into items (a top-level bullet or a paragraph), each tagged with its heading. Pure.
- */
+/** Splits one markdown memory file into items (a top-level bullet or a paragraph), each tagged with its heading. Pure. */
 const HEADING = /^#{1,6}\s+/;
 // Column 0 only: an indented marker is a sub-bullet and stays inside its item.
 const BULLET = /^(?:[-*+]|\d+[.)]) /;

package/dist/agent-memories/report.js

@@ -47,7 +47,8 @@ export function totalTally(report) {
 const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
 const TALLY_WORDS = {
     imported: 'new', replaced: 'replaced', restored: 'brought back', setAside: 'set aside', untagged: 'pinned and kept',
-    unchanged: 'unchanged', adopted: 'taken over from the old Claude import', renamed: 'moved to the project id', collapsed: 'duplicates folded', retagged: 'retagged',
+    unchanged: 'unchanged', adopted: 'taken over from the old Claude import', renamed: 'moved to the project id', collapsed: 'duplicates folded',
+    retagged: 'retagged',
     handedOver: 'handed over from the global store', duplicate: 'already stored', secret: 'skipped for a secret', short: 'too short',
     rejected: 'skipped as rejected', unread: 'files skipped', unreadable: 'unreadable folders', busy: 'busy folders',
 };

package/dist/agent-memories/sync.d.ts

@@ -24,9 +24,11 @@ export declare function importForStore(hippoRoot: string, opts: SyncOptions): Im
 export declare function importProjectMemories(hippoRoot: string, opts: SyncOptions): ImportReport;
 /** Every tool's user-level memory into the global store, created on demand, with no origin. */
 export declare function importUserMemories(invokingRoot: string, opts: SyncOptions): ImportReport;
-/** Session end in a folder with no store of its own: the session's project into the global store with its origin, the session folder's notes, then the user pass. */
+/** Session end in a folder with no store of its own: the session's project into the
+ * global store with its origin, the session folder's notes, then the user pass. */
 export declare function importAtSessionEnd(cwd: string, transcriptPath: string | undefined, opts: SyncOptions): ImportReport;
-/** The session folder's notes under the project Claude filed them for, never cwd's: a session begun at home keeps its home notes user-global wherever it ends. No git call, so post-compact can run it. */
+/** The session folder's notes under the project Claude filed them for, never cwd's: a session begun at
+ * home keeps its home notes user-global wherever it ends. No git call, so post-compact can run it. */
 export declare function importSessionFolder(hippoRoot: string, transcriptPath: string, cwd: string | null, opts: SyncOptions): ImportReport;
 /** The variable when set (empty or `none` is off); else the tools both the invoking and the target store's config allow. */
 export declare function allowedTools(env: Machine['env'], invoking: string, target: string, warnings: string[]): Set<ToolId>;

package/dist/agent-memories/sync.js

@@ -44,29 +44,34 @@ export function importForStore(hippoRoot, opts) {
 export function importProjectMemories(hippoRoot, opts) {
     const ctx = context(opts.machine, { projectRoot: path.dirname(hippoRoot) });
     return runPass({
-        scope: 'project', target: hippoRoot, invoking: hippoRoot, list: (a) => a.list(ctx, 'project'), legacy: true, originProject: undefined, legacyOrigins: [], handover: true,
+        scope: 'project', target: hippoRoot, invoking: hippoRoot, list: (a) => a.list(ctx, 'project'), legacy: true, originProject: undefined,
+        legacyOrigins: [], handover: true,
     }, opts);
 }
 /** Every tool's user-level memory into the global store, created on demand, with no origin. */
 export function importUserMemories(invokingRoot, opts) {
     const ctx = context(opts.machine, {});
     return runPass({
-        scope: 'user', target: resolveGlobalRootDir(), invoking: invokingRoot, list: (a) => a.list(ctx, 'user'), legacy: false, originProject: '', legacyOrigins: [], handover: false,
+        scope: 'user', target: resolveGlobalRootDir(), invoking: invokingRoot, list: (a) => a.list(ctx, 'user'), legacy: false, originProject: '',
+        legacyOrigins: [], handover: false,
     }, opts);
 }
-/** Session end in a folder with no store of its own: the session's project into the global store with its origin, the session folder's notes, then the user pass. */
+/** Session end in a folder with no store of its own: the session's project into the
+ * global store with its origin, the session folder's notes, then the user pass. */
 export function importAtSessionEnd(cwd, transcriptPath, opts) {
     const globalRoot = resolveGlobalRootDir();
     const ctx = context(opts.machine, { projectRoot: cwd });
     const report = runPass({
-        scope: 'project', target: globalRoot, invoking: globalRoot, list: (a) => a.list(ctx, 'project'), legacy: false, ...projectOrigins(resolveProjectIdentity(cwd)), handover: false,
+        scope: 'project', target: globalRoot, invoking: globalRoot, list: (a) => a.list(ctx, 'project'), legacy: false,
+        ...projectOrigins(resolveProjectIdentity(cwd)), handover: false,
     }, opts);
     if (transcriptPath !== undefined)
         mergeReports(report, importSessionFolder(globalRoot, transcriptPath, cwd, opts));
     mergeReports(report, importUserMemories(globalRoot, opts));
     return report;
 }
-/** The session folder's notes under the project Claude filed them for, never cwd's: a session begun at home keeps its home notes user-global wherever it ends. No git call, so post-compact can run it. */
+/** The session folder's notes under the project Claude filed them for, never cwd's: a session begun at
+ * home keeps its home notes user-global wherever it ends. No git call, so post-compact can run it. */
 export function importSessionFolder(hippoRoot, transcriptPath, cwd, opts) {
     const project = transcriptNotesProject(transcriptPath, cwd, opts.machine);
     if (project === null)

package/dist/api/assemble.d.ts

@@ -9,19 +9,10 @@ export interface AssembleOpts {
     /** Substitute parent summaries for older raws when ≥2 share a level-2
      *  ancestor. Default true. */
     summarizeOlder?: boolean;
-    /**
-     * Restrict to a specific scope, same rule as
-     * `recall`: when set, exact match required (so an authorised caller can
-     * assemble a `slack:private:CSEC` session by passing scope explicitly).
-     * When undefined, default-deny applies to ANY `<source>:private:*` and
-     * `unknown:legacy` rows.
-     */
+    /** Exact scope match when set, so an authorised caller can assemble a private session.
+     * When undefined, default-deny applies to every `<source>:private:*` and `unknown:legacy` row. */
     scope?: string;
-    /**
-     * Hard row cap on the SELECT that loads session raws. Default 5000 to
-     * protect against degenerate sessions. When the cap is hit, `truncated`
-     * is set on the result so the caller knows to widen.
-     */
+    /** Hard row cap on the SELECT that loads session raws (default 5000); `truncated` is set when it is hit. */
     rowCap?: number;
     cost?: AssembleCost;
     project?: CallerProject;
@@ -51,42 +42,14 @@ export interface AssembleResult {
     sessionId: string;
     items: AssembledContextItem[];
     tokens: number;
-    /**
-     * Tenant + scope-filtered raw row count for the session, uncapped by `rowCap`, so
-     * "session has N msgs" stays accurate when items[] is the windowed view.
-     */
+    /** Tenant + scope-filtered raw row count, uncapped by `rowCap`, so "session has N msgs" stays accurate for a windowed items[]. */
     totalRaw: number;
     summarized: number;
     evicted: number;
-    /**
-     * True when `rowCap` truncated the loaded window. The cap keeps the NEWEST
-     * rows, so the items[] array represents the freshest tail of the session;
-     * older rows beyond the cap are silently absent. Use `totalRaw - items.length
-     * - summarized + ...` to estimate how much you didn't see, or widen `rowCap`.
-     */
+    /** True when `rowCap` truncated the window; the cap keeps the NEWEST rows, so older rows beyond it are absent. */
     truncated: boolean;
 }
-/**
- * Build a chronologically-ordered context window for a session. Adapts the
- * lossless-claw context-engine pattern to Hippo's score-ranked memory store.
- *
- * Algorithm:
- *   1. Load all kind='raw' rows for the session, tenant + scope filtered.
- *   2. Split: newest `freshTailCount` are protected (fresh tail).
- *   3. For older rows, when ≥2 share a level-2 parent, substitute the
- *      summary; everything else passes through as raw.
- *   4. Hippo-additive eviction: when over-budget, drop the lowest-strength
- *      non-fresh-tail item first. Fresh-tail rows are never evicted.
- *
- * Strength-weighted eviction is the differentiator from lossless-claw,
- * which evicts oldest-first. A high-strength older row (high retrieval
- * count, slow decay) survives; a low-strength recent row (newer but
- * unimportant) goes first.
- *
- * Returns `items: []` cleanly when:
- *   - sessionId is empty
- *   - no raws exist for the session
- *   - all rows fail the scope/tenant filter
- */
+/** Chronological context window for a session; over budget, evicts the lowest-strength non-fresh-tail item first (fresh tail is never evicted).
+ * Returns `items: []` for an empty sessionId, no raws, or when every row fails the scope/tenant filter. */
 export declare function assemble(ctx: Context, sessionId: string, opts?: AssembleOpts): Promise<AssembleResult>;
 //# sourceMappingURL=assemble.d.ts.map

package/dist/api/assemble.js

@@ -6,28 +6,8 @@ import { classifyOriginProject, projectNames } from '../core/project-identity.js
 const DEFAULT_FRESH_TAIL_COUNT = 10;
 const DEFAULT_ROW_CAP = 5000;
 export const DEFAULT_ASSEMBLE_BUDGET = 4000;
-/**
- * Build a chronologically-ordered context window for a session. Adapts the
- * lossless-claw context-engine pattern to Hippo's score-ranked memory store.
- *
- * Algorithm:
- *   1. Load all kind='raw' rows for the session, tenant + scope filtered.
- *   2. Split: newest `freshTailCount` are protected (fresh tail).
- *   3. For older rows, when ≥2 share a level-2 parent, substitute the
- *      summary; everything else passes through as raw.
- *   4. Hippo-additive eviction: when over-budget, drop the lowest-strength
- *      non-fresh-tail item first. Fresh-tail rows are never evicted.
- *
- * Strength-weighted eviction is the differentiator from lossless-claw,
- * which evicts oldest-first. A high-strength older row (high retrieval
- * count, slow decay) survives; a low-strength recent row (newer but
- * unimportant) goes first.
- *
- * Returns `items: []` cleanly when:
- *   - sessionId is empty
- *   - no raws exist for the session
- *   - all rows fail the scope/tenant filter
- */
+/** Chronological context window for a session; over budget, evicts the lowest-strength non-fresh-tail item first (fresh tail is never evicted).
+ * Returns `items: []` for an empty sessionId, no raws, or when every row fails the scope/tenant filter. */
 export async function assemble(ctx, sessionId, opts = {}) {
     assertScopeRequestAllowed(ctx.actor, opts.scope);
     const budget = opts.budget ?? DEFAULT_ASSEMBLE_BUDGET;

package/dist/api/audit.d.ts

@@ -1,4 +1,4 @@
-import type { AuditEvent, AuditOp } from '../store/audit.js';
+import type { AuditEvent, AuditIssue, AuditOp } from '../store/audit.js';
 import type { KeysetPosition } from '../util/keyset.js';
 import type { Context } from './types.js';
 export interface AuditListOpts {
@@ -11,4 +11,8 @@ export interface AuditListOpts {
 }
 /** Read audit events scoped to `ctx.tenantId` on the store the request runs on. Read-only, no audit emit. */
 export declare function auditList(ctx: Context, opts: AuditListOpts): Promise<AuditEvent[]>;
+/** The pass that removes audit errors; it leads the reason on each forget row. */
+export type AuditPass = 'audit --fix' | 'sleep-audit';
+/** Delete the memories an audit marked as errors, each with its own forget row, and answer the ids that went: a pinned or raw row stays. */
+export declare function removeAuditErrors(ctx: Context, pass: AuditPass, issues: readonly AuditIssue[]): string[];
 //# sourceMappingURL=audit.d.ts.map

package/dist/api/audit.js

@@ -1,4 +1,5 @@
-// Audit log queries.
+// Audit log queries, and the removal of the memories a quality audit marks as errors.
+import { deleteEntry } from '../store/delete-and-batch.js';
 import { requireGroup, storeFor } from '../store/index.js';
 /** Read audit events scoped to `ctx.tenantId` on the store the request runs on. Read-only, no audit emit. */
 export async function auditList(ctx, opts) {
@@ -6,4 +7,11 @@ export async function auditList(ctx, opts) {
         tenantId: ctx.tenantId, op: opts.op, since: opts.since, limit: opts.limit, after: opts.after,
     });
 }
+/** Delete the memories an audit marked as errors, each with its own forget row, and answer the ids that went: a pinned or raw row stays. */
+export function removeAuditErrors(ctx, pass, issues) {
+    return issues
+        .filter((issue) => issue.severity === 'error')
+        .filter((issue) => deleteEntry(ctx.hippoRoot, issue.memoryId, { actor: ctx.actor.subject, reason: `${pass}: ${issue.reason}`, automatic: true }))
+        .map((issue) => issue.memoryId);
+}
 //# sourceMappingURL=audit.js.map

package/dist/api/auth.d.ts

@@ -3,13 +3,12 @@ import type { KeysetPosition } from '../util/keyset.js';
 import type { Context, StoreReply } from './types.js';
 export interface AuthCreateOpts {
     label?: string;
-    /**
-     * Authorization role for the new key. Defaults to `'admin'` for
-     * back-compat with keys minted before roles existed (the api_keys.role column DEFAULT also
-     * resolves to 'admin' if omitted from the INSERT). Member keys are
-     * 403-blocked from admin-gated routes (e.g. `POST /v1/sleep`).
-     */
+    /** Defaults to `'member'`, which admin-gated routes such as `POST /v1/sleep` refuse; an admin key has to be asked for by name. */
     role?: 'admin' | 'member';
+    /** Days until the key expires: above 0 and at most 3650. Defaults to 90. */
+    ttlDays?: number;
+    /** True mints a key that never expires, which has to be asked for by name; refused together with `ttlDays`. */
+    noExpiry?: boolean;
 }
 export interface AuthCreateResult {
     keyId: string;
@@ -17,18 +16,11 @@ export interface AuthCreateResult {
     tenantId: string;
     /** The role bound to the new key (admin | member). */
     role: 'admin' | 'member';
+    /** ISO time the key stops working; null for a key that never expires. */
+    expiresAt: string | null;
 }
-/**
- * Mint a new API key. The new key is ALWAYS bound to `ctx.tenantId`. Callers
- * cannot override the tenant via the opts bag — a previous `tenantId` field
- * was removed because the HTTP layer would happily forward `body.tenantId`,
- * letting tenant A mint a key for tenant B. The HTTP route handler at
- * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
- * `tenantId` and uses the resolved Bearer's tenant exclusively.
- *
- * Only an admin actor can mint (ForbiddenError otherwise), and a key never
- * outranks its minter: a resolver admin is tenant-only, so it mints members.
- */
+/** Mints a key always bound to `ctx.tenantId`; opts cannot override the tenant, or tenant A could mint a key for tenant B.
+ * Admin only (ForbiddenError otherwise), and a key never outranks its minter: a resolver admin is tenant-only, so it mints members. */
 export declare function authCreate<C extends Context>(ctx: C, opts: AuthCreateOpts): StoreReply<C, AuthCreateResult>;
 export interface AuthCreateSelfOpts {
     label?: string;
@@ -41,7 +33,8 @@ export interface AuthCreateSelfResult extends AuthCreateResult {
     /** ISO time the key stops working. */
     expiresAt: string;
 }
-/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the binary floor, the cap's revokes, the mint and its audit rows commit or fail together. */
+/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the
+ * binary floor, the cap's revokes, the mint and its audit rows commit or fail together. */
 export declare function authCreateSelf<C extends Context>(ctx: C, opts: AuthCreateSelfOpts): StoreReply<C, AuthCreateSelfResult>;
 type KeyListOpts = {
     active: boolean;
@@ -58,10 +51,8 @@ export type AuthRevokeReply<C extends Context> = StoreReply<C, AuthRevokeResult>
 /** Revoke a key in the caller's tenant: a member API key may revoke only itself, a resolver member only the keys it minted.
  *  The revoke and its auth_revoke row commit together on either store, so a failed audit write leaves the key live. */
 export declare function authRevoke<C extends Context>(ctx: C, keyId: string): AuthRevokeReply<C>;
-/**
- * The tenant that owns `keyId`, or undefined for an unknown key. Host admin only: it reads across tenants,
- * so the local CLI can run revoke and grant in the key's own tenant.
- */
+/** The tenant that owns `keyId`, or undefined for an unknown key. Host admin only: it reads across tenants,
+ * so the local CLI can run revoke and grant in the key's own tenant. */
 export declare function authKeyTenant(ctx: Context, keyId: string): string | undefined;
 /** Shared result shape for authGrant/authUngrant, named per the file's oxlint anti-slop rule. */
 export interface AuthGrantResult {

package/dist/api/auth.js

@@ -1,5 +1,5 @@
 // API key management: create, list, revoke, and grant or ungrant restricted scopes.
-import { ForbiddenError, NotFoundError } from '../core/api-errors.js';
+import { BadRequestError, ForbiddenError, NotFoundError } from '../core/api-errors.js';
 import { mintApiKey, } from '../store/auth.js';
 import { changeScopeGrant } from '../store/sqlite/local.js';
 import { sqliteSyncStore } from '../store/sqlite/store.js';
@@ -10,17 +10,8 @@ const API_KEY_SUBJECT = 'api_key:';
 function keyIdOfSubject(subject) {
     return subject.startsWith(API_KEY_SUBJECT) ? subject.slice(API_KEY_SUBJECT.length) : null;
 }
-/**
- * Mint a new API key. The new key is ALWAYS bound to `ctx.tenantId`. Callers
- * cannot override the tenant via the opts bag — a previous `tenantId` field
- * was removed because the HTTP layer would happily forward `body.tenantId`,
- * letting tenant A mint a key for tenant B. The HTTP route handler at
- * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
- * `tenantId` and uses the resolved Bearer's tenant exclusively.
- *
- * Only an admin actor can mint (ForbiddenError otherwise), and a key never
- * outranks its minter: a resolver admin is tenant-only, so it mints members.
- */
+/** Mints a key always bound to `ctx.tenantId`; opts cannot override the tenant, or tenant A could mint a key for tenant B.
+ * Admin only (ForbiddenError otherwise), and a key never outranks its minter: a resolver admin is tenant-only, so it mints members. */
 export function authCreate(ctx, opts) {
     // The key and its auth_create row commit together on either store, so a failed audit write leaves no key.
     return onStore(ctx, (port) => {
@@ -34,6 +25,23 @@ function newKey(ctx, fields) {
     const { keyId, plaintext, keyHash } = mintApiKey();
     return { plaintext, key: { ...fields, keyId, keyHash, tenantId: ctx.tenantId, createdAt: new Date().toISOString() } };
 }
+/** Days a key lives when its mint names no expiry, so a key nobody remembers stops working by itself. */
+const DEFAULT_KEY_TTL_DAYS = 90;
+// The ceiling keeps toISOString in range.
+const MAX_TTL_DAYS = 3650;
+/** A 400, not a RangeError, since the caller of the mint chose these. */
+function mintExpiry({ ttlDays, noExpiry }) {
+    if (noExpiry && ttlDays !== undefined) {
+        throw new BadRequestError('send ttlDays or noExpiry, not both');
+    }
+    if (noExpiry)
+        return null;
+    const days = ttlDays ?? DEFAULT_KEY_TTL_DAYS;
+    if (!Number.isFinite(days) || days <= 0 || days > MAX_TTL_DAYS) {
+        throw new BadRequestError(`ttlDays must be above 0 and at most ${MAX_TTL_DAYS}`);
+    }
+    return new Date(Date.now() + days * DAY_MS).toISOString();
+}
 function adminKeyMint(ctx, opts) {
     if (ctx.actor.role !== 'admin') {
         throw new ForbiddenError('Only an admin key can create API keys');
@@ -41,16 +49,16 @@ function adminKeyMint(ctx, opts) {
     if (ctx.actor.viaAuthResolver && opts.role === 'admin') {
         throw new ForbiddenError('A key minted through the auth resolver can only be a member key');
     }
-    const role = opts.role ?? (ctx.actor.viaAuthResolver ? 'member' : 'admin');
+    const role = opts.role ?? 'member';
     const label = opts.label ?? null;
-    const { plaintext, key } = newKey(ctx, { label, role, ownerSubject: null, expiresAt: null });
-    // The plaintext is NEVER logged; metadata carries label + role, keyId is non-secret.
-    return { plaintext, mint: { key, actor: ctx.actor.subject, metadata: { label, role } } };
+    const expiresAt = mintExpiry(opts);
+    const { plaintext, key } = newKey(ctx, { label, role, ownerSubject: null, expiresAt });
+    // The plaintext is NEVER logged; the audit row carries what the key can do and for how long, keyId is non-secret.
+    return { plaintext, mint: { key, actor: ctx.actor.subject, metadata: { label, role, expiresAt } } };
 }
 function createResult({ key }, plaintext) {
-    return { keyId: key.keyId, plaintext, tenantId: key.tenantId, role: key.role };
+    return { keyId: key.keyId, plaintext, tenantId: key.tenantId, role: key.role, expiresAt: key.expiresAt };
 }
-const MAX_TTL_DAYS = 3650;
 /** A RangeError, not a 4xx, since the operator's config sets these; the ttl ceiling keeps toISOString in range and a departed user's key short-lived. */
 function assertSelfMintOpts({ ttlDays, perSubject }) {
     if (!Number.isFinite(ttlDays) || ttlDays <= 0 || ttlDays > MAX_TTL_DAYS) {
@@ -60,7 +68,8 @@ function assertSelfMintOpts({ ttlDays, perSubject }) {
         throw new RangeError(`authCreateSelf: perSubject must be a whole number of at least 1, got ${String(perSubject)}`);
     }
 }
-/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the binary floor, the cap's revokes, the mint and its audit rows commit or fail together. */
+/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the
+ * binary floor, the cap's revokes, the mint and its audit rows commit or fail together. */
 export function authCreateSelf(ctx, opts) {
     return onStore(ctx, (port) => {
         const keyWrites = port.keyWrites ?? notPorted(port, 'keyWrites');
@@ -79,7 +88,10 @@ function selfKeyMint(ctx, opts) {
     // Not destructured: a binding pattern makes TypeScript infer F as KeyFields and lose ownerSubject's string type.
     const made = newKey(ctx, { label, role: 'member', ownerSubject: subject, expiresAt });
     // Same op and actor as an admin mint, so a lookup by audit row finds this key too.
-    return { plaintext: made.plaintext, mint: { key: made.key, actor: subject, metadata: { label, role: 'member', self: true, expiresAt }, perSubject: opts.perSubject } };
+    return {
+        plaintext: made.plaintext,
+        mint: { key: made.key, actor: subject, metadata: { label, role: 'member', self: true, expiresAt }, perSubject: opts.perSubject }
+    };
 }
 function selfResult({ key }, plaintext) {
     return { keyId: key.keyId, plaintext, tenantId: key.tenantId, role: 'member', expiresAt: key.expiresAt };
@@ -146,10 +158,8 @@ function assertMemberKeyRevokesSelf(ctx, keyId) {
 function keyOwnerOf(record) {
     return record ? { tenantId: record.tenantId, revokedAt: record.revokedAt, role: record.role, ownerSubject: record.ownerSubject ?? null } : undefined;
 }
-/**
- * The tenant that owns `keyId`, or undefined for an unknown key. Host admin only: it reads across tenants,
- * so the local CLI can run revoke and grant in the key's own tenant.
- */
+/** The tenant that owns `keyId`, or undefined for an unknown key. Host admin only: it reads across tenants,
+ * so the local CLI can run revoke and grant in the key's own tenant. */
 export function authKeyTenant(ctx, keyId) {
     if (!ctx.actor.hostAdmin) {
         throw new ForbiddenError('Only the host admin can look up a key across tenants');

package/dist/api/auto-sleep.js

@@ -1,5 +1,5 @@
 // When a write starts a background sleep; the MCP remember tool and the session-close hook share it.
-import { errorMessage, log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { countCreatedSinceLastSleep } from '../store/index-and-stats.js';
 import { consolidate } from '../consolidate/sleep.js';
 import { outsideRequestStores, runWithRequestStores, scopedBusyWait } from '../db/index.js';
@@ -25,7 +25,7 @@ export function startAutoSleepIfDue(hippoRoot, tenantId, config, allowed) {
     const busyWaitMs = scopedBusyWait();
     outsideRequestStores(() => runWithRequestStores(() => consolidate(hippoRoot), { busyWaitMs }))
         .catch((err) => {
-        log.error(`auto-sleep consolidate failed (tenant ${tenantId}): ${errorMessage(err)}`);
+        log.error(`auto-sleep consolidate failed (tenant ${tenantId}): ${errorMessage(err)}`, errorFields(err));
     })
         .finally(() => autoSleepInFlight.delete(hippoRoot));
 }

package/dist/api/availability.d.ts

@@ -46,20 +46,7 @@ export declare const DEFAULT_RECENT_FRACTION_THRESHOLD = 0.7;
 export declare const DEFAULT_MIN_RETURNED = 3;
 export declare const DEFAULT_MIN_POOL = 10;
 export declare const DEFAULT_MIN_OLDER_PASSED_OVER = 3;
-/**
- * Detect availability/recency bias in a recall result.
- *
- * Returns an AvailabilityHint when ALL of the following hold:
- *   1. topK.length >= minReturned AND pool.length >= minPool (enough signal);
- *   2. recentFraction > recentFractionThreshold (returned slice is recency-dominated);
- *   3. poolMedianAgeDays > topKMedianAgeDays (the pool genuinely skews older,
- *      so recency is not just the corpus being young);
- *   4. olderCandidatesPassedOver >= minOlderPassedOver (older matched memories
- *      actually existed and were not returned).
- * Otherwise returns null.
- *
- * Entries with an unparseable `created` are dropped defensively so a malformed
- * row cannot poison the medians with NaN.
- */
+/** Returns an AvailabilityHint when the returned slice is recency-dominated, the pool skews older and older matches were passed over; else null.
+ * Entries with an unparseable `created` are dropped so a malformed row cannot poison the medians with NaN. */
 export declare function detectAvailabilityBias(opts: DetectAvailabilityBiasOpts): AvailabilityHint | null;
 //# sourceMappingURL=availability.d.ts.map

package/dist/api/availability.js

@@ -17,21 +17,8 @@ function parseTimestamps(refs) {
         .map((e) => ({ id: e.id, ts: Date.parse(e.created) }))
         .filter((e) => Number.isFinite(e.ts));
 }
-/**
- * Detect availability/recency bias in a recall result.
- *
- * Returns an AvailabilityHint when ALL of the following hold:
- *   1. topK.length >= minReturned AND pool.length >= minPool (enough signal);
- *   2. recentFraction > recentFractionThreshold (returned slice is recency-dominated);
- *   3. poolMedianAgeDays > topKMedianAgeDays (the pool genuinely skews older,
- *      so recency is not just the corpus being young);
- *   4. olderCandidatesPassedOver >= minOlderPassedOver (older matched memories
- *      actually existed and were not returned).
- * Otherwise returns null.
- *
- * Entries with an unparseable `created` are dropped defensively so a malformed
- * row cannot poison the medians with NaN.
- */
+/** Returns an AvailabilityHint when the returned slice is recency-dominated, the pool skews older and older matches were passed over; else null.
+ * Entries with an unparseable `created` are dropped so a malformed row cannot poison the medians with NaN. */
 export function detectAvailabilityBias(opts) {
     const now = opts.now ?? Date.now();
     const recencyWindowMs = opts.recencyWindowMs ?? DEFAULT_RECENCY_WINDOW_MS;

package/dist/api/context-select.js

@@ -4,7 +4,7 @@ import { heldIdLookup } from '../store/entry-reads.js';
 import { calculateStrength } from '../core/memory.js';
 import { auditQueryFields, recordAuditEvent } from '../store/audit.js';
 import { isWorthSurfacing } from '../core/memory-quality.js';
-import { rankBothStores } from '../sharing/shared.js';
+import { rankBothStores } from '../sharing/search-both.js';
 import { evalNow } from '../core/ablation.js';
 import { hybridSearch } from '../search/hybrid.js';
 import { physicsSearch } from '../search/physics-search.js';
@@ -51,9 +51,8 @@ export function selectPinned(opts, plan, left, pools, admission) {
     const [localPool, globalPool] = oneCopyPerMemory(localEntries, globalEntries, nowP);
     obs?.dropMissing([...localEntries, ...globalEntries], [...localPool, ...globalPool], 'load', 'duplicate');
     const picked = { items: [], ids: new Set(), used: 0 };
-    // Pinned entries are explicit user intent, the recent-N list an automatic
-    // backfill. Both loops share ONE budget and the recent loop runs first, so
-    // pins are ranked here and reserve their share before it can spend.
+    // Pinned entries are explicit intent, the recent-N list an automatic backfill; both share ONE budget and the recent loop runs first,
+    // so pins are ranked here and reserve their share before it can spend.
     const pinnedLocal = localPool.filter((e) => e.pinned);
     const pinnedGlobal = globalPool.filter((e) => e.pinned);
     const rankedPinned = rankPinned(plan, pinnedLocal, pinnedGlobal, nowP);