hippo-memory 1.72.0 → 2.1.0

package/dist/api/recall-request.js

@@ -1,121 +0,0 @@
-// The recall and context input rules in one copy, so MCP and HTTP reject the same inputs with the same messages.
-import { BadRequestError } from '../core/api-errors.js';
-import { MAX_ID_LEN } from '../util/limits.js';
-import { isJsonString } from '../util/json.js';
-const MAX_RECALL_LIMIT = 1000;
-// recall() owns the shape rule for scorer_window (invalid_scorer_window); this cap bounds remote cost.
-const MAX_SCORER_WINDOW = 1000;
-// Bounds BM25 tokenisation cost while covering pasted error messages.
-const MAX_CONTEXT_QUERY_LEN = 1024;
-const RECALL_MODES = ['bm25', 'hybrid', 'physics'];
-/** A recall or context input the caller must fix; MCP answers it with an isError result, HTTP with a 400. */
-export class RecallRequestError extends BadRequestError {
-    constructor(message) {
-        super(message);
-        this.name = 'RecallRequestError';
-    }
-}
-export function httpParams(query) {
-    return { get: (name) => query.get(name) ?? undefined, queryName: 'q' };
-}
-export function toolParams(args) {
-    return { get: (name) => args[name], queryName: 'query' };
-}
-function numberParam(params, name) {
-    const value = params.get(name);
-    return value === undefined || value === null ? undefined : Number(value);
-}
-function nonNegativeParam(params, name) {
-    const n = numberParam(params, name);
-    if (n !== undefined && (!Number.isFinite(n) || n < 0))
-        throw new RecallRequestError(`${name} must be a non-negative number`);
-    return n;
-}
-// Only `true`, "1" and "true" turn a flag on, so `?summarize_overflow=banana` or an empty value stays off.
-function flagParam(params, name) {
-    const value = params.get(name);
-    return value === true || value === '1' || value === 'true';
-}
-function optionalFlagParam(params, name) {
-    const value = params.get(name);
-    return value === undefined || value === null ? undefined : flagParam(params, name);
-}
-function stringParam(params, name) {
-    const value = params.get(name);
-    return isJsonString(value) && value.length > 0 ? value : undefined;
-}
-/** An id-shaped string capped at MAX_ID_LEN; empty reads as absent. */
-function idParam(params, name) {
-    const value = params.get(name);
-    if (isJsonString(value) && value.length > MAX_ID_LEN)
-        throw new RecallRequestError(`${name} exceeds ${MAX_ID_LEN}-character cap`);
-    return stringParam(params, name);
-}
-function limitParam(params) {
-    const limit = numberParam(params, 'limit');
-    if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0 || limit > MAX_RECALL_LIMIT)) {
-        throw new RecallRequestError(`limit must be a positive integer <= ${MAX_RECALL_LIMIT}`);
-    }
-    return limit;
-}
-function modeParam(params) {
-    const value = params.get('mode');
-    if (value === undefined || value === null)
-        return undefined;
-    const mode = RECALL_MODES.find((m) => m === value);
-    if (!mode)
-        throw new RecallRequestError("mode must be 'bm25', 'hybrid', or 'physics'");
-    return mode;
-}
-function scorerWindowParam(params) {
-    const scorerWindow = numberParam(params, 'scorer_window');
-    if (scorerWindow !== undefined && scorerWindow > MAX_SCORER_WINDOW) {
-        throw new RecallRequestError(`scorer_window must be <= ${MAX_SCORER_WINDOW}`);
-    }
-    return scorerWindow;
-}
-/** Trimmed, and absent when blank, so a whitespace id never keys a goal stack or a session ring. */
-function sessionIdParam(params) {
-    const value = idParam(params, 'session_id');
-    const trimmed = value?.trim() ?? '';
-    return trimmed.length > 0 ? trimmed : undefined;
-}
-/** Checks in a fixed order, so the first bad input is the one reported. */
-export function parseRecallRequest(params) {
-    const query = params.get(params.queryName);
-    if (!isJsonString(query) || query.length === 0)
-        throw new RecallRequestError(`${params.queryName} is required`);
-    const limit = limitParam(params);
-    const mode = modeParam(params);
-    const scope = stringParam(params, 'scope');
-    const includeContinuity = flagParam(params, 'include_continuity');
-    const freshTailCount = nonNegativeParam(params, 'fresh_tail_count');
-    const freshTailSessionId = idParam(params, 'fresh_tail_session_id');
-    const summarizeOverflow = optionalFlagParam(params, 'summarize_overflow');
-    const scorerWindow = scorerWindowParam(params);
-    const sessionId = sessionIdParam(params);
-    const explain = flagParam(params, 'explain');
-    return {
-        opts: { query, scope, includeContinuity, freshTailCount, freshTailSessionId, summarizeOverflow, scorerWindow, sessionId },
-        limit,
-        mode,
-        explain,
-    };
-}
-export function parseContextRequest(params) {
-    const qValue = params.get(params.queryName);
-    const q = isJsonString(qValue) ? qValue : undefined;
-    if (q !== undefined && q.length > MAX_CONTEXT_QUERY_LEN) {
-        throw new RecallRequestError(`${params.queryName} exceeds ${MAX_CONTEXT_QUERY_LEN}-character cap`);
-    }
-    const budget = nonNegativeParam(params, 'budget');
-    const limit = numberParam(params, 'limit');
-    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0))
-        throw new RecallRequestError('limit must be a positive number');
-    const pinnedOnly = flagParam(params, 'pinned_only');
-    const scope = idParam(params, 'scope');
-    const includeRecent = nonNegativeParam(params, 'include_recent');
-    const crossProject = flagParam(params, 'cross_project');
-    return { q, budget, limit, pinnedOnly, scope, includeRecent, crossProject };
-}
-//# sourceMappingURL=recall-request.js.map

package/dist/api/recall.d.ts

@@ -1,6 +0,0 @@
-import type { RecallOpts, RecallResult } from './recall-types.js';
-import { type Context } from './types.js';
-/** The one recall entry: ranks with the ranker `opts` names, then writes the recall, and records it in full for a surface that sets `recordAs`.
- *  Only the CLI core ranker writes last_retrieval_ids (contract lock). */
-export declare function retrieve(ctx: Context, opts: RecallOpts): Promise<RecallResult>;
-//# sourceMappingURL=recall.d.ts.map

package/dist/api/refine.d.ts

@@ -1,7 +0,0 @@
-import type { MemoryEntry } from '../core/memory.js';
-import type { Context } from './types.js';
-/** Marks a merged memory a model has rewritten, so a later pass skips it. */
-export declare const REFINED_TAG = "llm-refined";
-/** Store a model's rewrite of a merged memory: the new text replaces the old one, and the row gains the refined tag once. */
-export declare function storeRefinement(ctx: Context, entry: MemoryEntry, refined: string): void;
-//# sourceMappingURL=refine.d.ts.map

package/dist/api/refine.js

@@ -1,10 +0,0 @@
-// The write half of `hippo refine`: the model call stays with the caller, the rewritten row is stored here.
-import { writeEntry } from '../store/entry-writes.js';
-/** Marks a merged memory a model has rewritten, so a later pass skips it. */
-export const REFINED_TAG = 'llm-refined';
-/** Store a model's rewrite of a merged memory: the new text replaces the old one, and the row gains the refined tag once. */
-export function storeRefinement(ctx, entry, refined) {
-    const tags = entry.tags.includes(REFINED_TAG) ? entry.tags : [...entry.tags, REFINED_TAG];
-    writeEntry(ctx.hippoRoot, { ...entry, content: refined, tags }, { actor: ctx.actor.subject });
-}
-//# sourceMappingURL=refine.js.map

package/dist/api/session-owners.d.ts

@@ -1,4 +0,0 @@
-import { type Context } from './types.js';
-/** Binds `sessionId` to the caller's owner on first use; a session another owner holds is a 409, so the client can set it aside. */
-export declare function bindSessionOwner(ctx: Context, sessionId: string): void;
-//# sourceMappingURL=session-owners.d.ts.map

package/dist/api/session-owners.js

@@ -1,17 +0,0 @@
-// A session id belongs to the first owner that binds it, so one developer's client cannot write into another's session.
-import { ConflictError } from '../core/api-errors.js';
-import { ownerOrSubject } from './types.js';
-import { sessionOwnerOrBind } from '../store/sessions.js';
-import { assertTenantId } from '../store/tenant.js';
-import { DAY_MS } from '../util/time.js';
-/** Bindings older than this are pruned when a new session binds. */
-const BINDING_RETENTION_DAYS = 90;
-/** Binds `sessionId` to the caller's owner on first use; a session another owner holds is a 409, so the client can set it aside. */
-export function bindSessionOwner(ctx, sessionId) {
-    assertTenantId('bindSessionOwner', ctx.tenantId);
-    const owner = ownerOrSubject(ctx.actor);
-    const bound = sessionOwnerOrBind(ctx.hippoRoot, { tenantId: ctx.tenantId, sessionId, owner, retentionMs: BINDING_RETENTION_DAYS * DAY_MS });
-    if (bound !== owner)
-        throw new ConflictError('session id belongs to another caller');
-}
-//# sourceMappingURL=session-owners.js.map

package/dist/api/sleep-run.d.ts

@@ -1,26 +0,0 @@
-import { loadAllEntries } from '../store/entry-reads.js';
-import { auditMemories } from '../core/memory-audit.js';
-import { autoShare } from '../sharing/share.js';
-import { consolidate } from '../consolidate/sleep.js';
-import { loadConfig } from '../core/config.js';
-import { deduplicateStore } from '../consolidate/dedupe.js';
-import { computeAmbientState } from '../core/ambient.js';
-import { loadPendingExtractionTenants } from '../store/graph-queue.js';
-import { type ExtractResult } from '../graph/extract.js';
-import type { Context } from './types.js';
-import type { SleepOpts, SleepResult } from './sleep.js';
-/** Test-only seam: `runSleep` overrides force a phase to throw into emitSleepAudit's `partial: true` row; production never sets them. */
-export interface SleepPhases {
-    consolidate: typeof consolidate;
-    deduplicateStore: typeof deduplicateStore;
-    auditMemories: typeof auditMemories;
-    autoShare: typeof autoShare;
-    loadAllEntries: typeof loadAllEntries;
-    computeAmbientState: typeof computeAmbientState;
-    loadConfig: typeof loadConfig;
-    loadPendingExtractionTenants: typeof loadPendingExtractionTenants;
-    extractGraph: (hippoRoot: string, tenantId: string) => ExtractResult | Promise<ExtractResult>;
-}
-/** `sleep` with its phase dependencies overridable; tests pass stubs here, so the seam never touches the public `SleepOpts`. */
-export declare function runSleep(ctx: Context, opts: SleepOpts, overrides?: Partial<SleepPhases>): Promise<SleepResult>;
-//# sourceMappingURL=sleep-run.d.ts.map

package/dist/api/sleep.js

@@ -1,10 +0,0 @@
-// The sleep cycle: decay, consolidation, dedupe, graph extraction and the other maintenance passes.
-import { runSleep } from './sleep-run.js';
-/** Sleeps the WHOLE hippoRoot, every tenant, so /v1/sleep stays loopback-only; SQLite only; never auto-deletes pinned, raw, kept or object-backing rows. */
-export async function sleep(ctx, opts = {}) {
-    if (ctx.store && ctx.store.kind !== 'sqlite') {
-        throw new Error(`sleep supports only the sqlite store, not '${ctx.store.kind}'`);
-    }
-    return runSleep(ctx, opts);
-}
-//# sourceMappingURL=sleep.js.map

package/dist/cli/lenient-id.d.ts

@@ -1,2 +0,0 @@
-export declare function parseObjectId(idRaw: string, noun: string): number;
-//# sourceMappingURL=lenient-id.d.ts.map

package/dist/cli/lenient-id.js

@@ -1,13 +0,0 @@
-// The id parser the predict and decide verbs share.
-import { printError } from './output.js';
-import { CliExit } from './exit.js';
-// Lenient on purpose (parseInt reads "1abc" as 1) until the next major version; the other object verbs use the strict parser.
-export function parseObjectId(idRaw, noun) {
-    const id = parseInt(String(idRaw), 10);
-    if (!Number.isFinite(id) || id <= 0) {
-        printError(`Invalid ${noun} id: "${idRaw}"`);
-        throw new CliExit(1);
-    }
-    return id;
-}
-//# sourceMappingURL=lenient-id.js.map

package/dist/graph/write.d.ts

@@ -1,14 +0,0 @@
-import type { DatabaseSyncLike } from '../db/index.js';
-import type { GraphOp } from './delta.js';
-export interface ApplyGraphOpsResult {
-    readonly next: number;
-    readonly skipped: number;
-}
-/** Applies `ops` from index `opts.from` on the caller's open transaction and stops at the first op boundary past `opts.holdMs`.
- *  Returns where the next chunk starts and how many ops were skipped as stale. */
-export declare function applyGraphOps(db: DatabaseSyncLike, tenantId: string, ops: readonly GraphOp[], opts: {
-    readonly from: number;
-    readonly holdMs: number;
-    readonly clock?: () => number;
-}): ApplyGraphOpsResult;
-//# sourceMappingURL=write.d.ts.map

package/dist/store/sqlite/busy.d.ts

@@ -1,3 +0,0 @@
-/** A held lock in any store: SQLite's busy codes or a port's StoreBusyError. */
-export declare function isStoreBusy<E>(error: E): boolean;
-//# sourceMappingURL=busy.d.ts.map

package/dist/store/sqlite/busy.js

@@ -1,8 +0,0 @@
-// Busy detection lives with the adapter, so the port names no SQLite error code.
-import { isSqliteBusy } from '../../db/busy.js';
-import { StoreBusyError } from '../port.js';
-/** A held lock in any store: SQLite's busy codes or a port's StoreBusyError. */
-export function isStoreBusy(error) {
-    return error instanceof StoreBusyError || isSqliteBusy(error);
-}
-//# sourceMappingURL=busy.js.map

package/dist/store/sqlite/local.d.ts

@@ -1,21 +0,0 @@
-import { type ScopeGrantChange } from '../key-writes.js';
-import type { EntryTarget, OutcomeWrite, RecallWrites } from '../port.js';
-/** A recall's writes when hippo.db keeps it as its last one: `strengthen.ids` are the ids it returned. */
-type LastRecallWrites = RecallWrites & Required<Pick<RecallWrites, 'strengthen'>>;
-/** The port's writes with a part that needs hippo.db's own handle or its meta table, which no other store has. */
-export interface SqliteLocal {
-    /** entryWrites.applyOutcome, then a link from the recall trace to the ids applied, on the same handle after the commit. */
-    applyOutcome(outcome: OutcomeWrite, traceId: number): string[];
-    /** applyOutcome on the ids of the last recall, which hippo.db's meta table holds with that recall's trace; answers the ids applied. */
-    applyOutcomeToLastRecall(target: EntryTarget, good: boolean): string[];
-    /** finishRecall, then the ids this root lacks strengthened under `globalRoot`, then the ids and their trace saved as the last recall;
-     *  answers the trace id. A store of another kind keeps no last recall, so its stand-in is its own finishRecall, answering null. */
-    finishLastRecall(writes: LastRecallWrites, globalRoot: string | undefined): number | null | Promise<number | null>;
-}
-export declare function sqliteLocal(hippoRoot: string): SqliteLocal;
-/** What a served store answers for each write that needs hippo.db's own handle: a refusal. */
-export declare const REFUSED_ON_A_STORE: Pick<SqliteLocal, 'applyOutcome'>;
-/** Off the port: only the local CLI changes grants, through synchronous published functions a store's Promise cannot answer. */
-export declare function changeScopeGrant(hippoRoot: string, change: ScopeGrantChange): void;
-export {};
-//# sourceMappingURL=local.d.ts.map

package/dist/store/sqlite/local.js

@@ -1,39 +0,0 @@
-// What only hippo.db does: operations no port method covers, so they never run on another store.
-import { strengthenRetrieved } from '../entry-writes.js';
-import { loadLastRecall, saveIndex } from '../index-and-stats.js';
-import { changeScopeGrantAt } from '../key-writes.js';
-import { onHandle } from '../open.js';
-import { applyOutcomeAt } from './entry-writes-group.js';
-import { finishRecallAt } from './store.js';
-export function sqliteLocal(hippoRoot) {
-    return {
-        applyOutcome: (outcome, traceId) => applyOutcomeAt(hippoRoot, outcome, traceId),
-        // The ids and the trace come from one statement, so the outcome is linked to the recall that returned those ids.
-        applyOutcomeToLastRecall(target, good) {
-            const { last_retrieval_ids: ids, last_trace_id: trace } = loadLastRecall(hippoRoot);
-            if (ids.length === 0)
-                return [];
-            return applyOutcomeAt(hippoRoot, { ...target, ids, good }, trace === null ? undefined : Number(trace));
-        },
-        finishLastRecall(writes, globalRoot) {
-            const { ids, opts } = writes.strengthen;
-            const { traceId, strengthened } = finishRecallAt(hippoRoot, writes);
-            if (globalRoot !== undefined)
-                strengthenRetrieved(globalRoot, ids.filter((id) => !strengthened.has(id)), opts);
-            // One write for both keys, so an outcome never pairs these ids with an older trace; a lost trace saves null.
-            saveIndex(hippoRoot, { last_retrieval_ids: [...ids], last_trace_id: traceId === null ? null : String(traceId) });
-            return traceId;
-        },
-    };
-}
-/** What a served store answers for each write that needs hippo.db's own handle: a refusal. */
-export const REFUSED_ON_A_STORE = {
-    applyOutcome() {
-        throw new Error('an outcome links its recall trace on hippo.db only, never through a store');
-    },
-};
-/** Off the port: only the local CLI changes grants, through synchronous published functions a store's Promise cannot answer. */
-export function changeScopeGrant(hippoRoot, change) {
-    onHandle(hippoRoot, (db) => changeScopeGrantAt(db, change));
-}
-//# sourceMappingURL=local.js.map