hebbrix 2.1.0 → 2.2.0

package/dist/index.d.mts

@@ -57,8 +57,27 @@ interface SearchResponse {
     total: number;
     search_type: string;
     processing_time_ms: number;
+    no_match: boolean;
+    abstain_recommended: boolean;
+    query_confidence: number;
+    grounding: GroundingReceipt;
+    evidence_ids: string[];
+    evidence_claims?: EvidenceClaim[];
+    safety_contract_version: string;
+    degraded?: boolean;
+    sdk_safety_reason?: string;
     proof_context?: ProofContext;
 }
+interface GroundingReceipt {
+    status: string;
+    reason?: string;
+    contract_version?: string;
+    [key: string]: unknown;
+}
+interface EvidenceClaim {
+    memory_id: string;
+    claims: Record<string, unknown>;
+}
 interface ProofContext {
     schema_version: "proofloop-context-v1";
     context_id: string;
@@ -88,9 +107,18 @@ interface ReasoningSource {
     score: number;
 }
 interface ReasoningResponse {
-    answer: string;
+    answer: string | null;
     sources: ReasoningSource[];
     metadata: Record<string, any>;
+    no_match: boolean;
+    abstain_recommended: boolean;
+    query_confidence: number;
+    grounding: GroundingReceipt;
+    evidence_ids: string[];
+    evidence_claims?: EvidenceClaim[];
+    safety_contract_version: string;
+    degraded?: boolean;
+    sdk_safety_reason?: string;
     reasoning_context?: Record<string, any>;
 }
 interface CreateCollectionParams {
@@ -104,17 +132,54 @@ interface UpdateCollectionParams {
     metadata?: Record<string, any>;
 }
 interface CreateMemoryParams {
-    collection_id: string;
-    content: string;
+    collection_id?: string;
+    content?: string;
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
     importance?: number;
     source_type?: string;
     source_reference?: string;
     metadata?: Record<string, any>;
+    infer?: boolean;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    app_id?: string;
+    namespace?: string;
+    wait_for_index?: boolean;
+    async_dispatch?: boolean;
+    title?: string;
+    tags?: string[];
+    source?: string;
+    /** Stable retry key sent as the Idempotency-Key transport header. */
+    idempotency_key?: string;
+}
+interface MemoryAddResult {
+    id: string;
+    memory_id?: string;
+    event: "ADD" | "UPDATE" | "NOOP" | string;
+    memory?: string;
+    reason?: string;
+}
+interface MemoryAddResponse {
+    results: MemoryAddResult[];
+    collection_id?: string;
+    processing_status: string;
+    searchable: boolean;
+    outbox_event_id?: string;
+    status_url?: string;
+    job_id?: string;
+    created_count: number;
+    updated_count: number;
+    skipped_count: number;
 }
 interface UpdateMemoryParams {
     content?: string;
     importance?: number;
     metadata?: Record<string, any>;
+    wait_for_index?: boolean;
 }
 interface SearchParams {
     query: string;
@@ -123,17 +188,81 @@ interface SearchParams {
     search_type?: "hybrid" | "vector" | "bm25" | "graph";
     filters?: Record<string, any>;
     user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    fast?: boolean;
+    threshold?: number;
+    include_low_confidence?: boolean;
+    group_by_source?: boolean;
+    debug?: boolean;
 }
 interface ReasonParams {
     query: string;
     collection_id?: string;
     provider?: "gemini" | "openai" | "anthropic";
     include_steps?: boolean;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    facets?: string[];
 }
 interface ListParams {
     skip?: number;
     limit?: number;
 }
+interface MemoryListParams {
+    collection_id?: string;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    scope?: "all";
+    cursor?: string;
+    limit?: number;
+    include_superseded?: boolean;
+}
+interface CursorPage<T> {
+    items: T[];
+    next_cursor?: string | null;
+    has_more: boolean;
+    total_count: number;
+}
+interface MemoryJobReceipt {
+    job_id?: string;
+    status: string;
+    [key: string]: any;
+}
+interface CorrectionCreateParams {
+    corrected_content: string;
+    correction_type?: "preference" | "factual" | "procedural" | string;
+    original_content?: string;
+    context?: string;
+    memory_id?: string;
+    collection_id?: string;
+    user_id?: string;
+    agent_id?: string;
+    confidence?: number;
+    metadata?: Record<string, any>;
+    idempotency_key?: string;
+}
+interface CorrectionSearchParams {
+    query: string;
+    correction_type?: string;
+    collection_id?: string;
+    user_id?: string;
+    agent_id?: string;
+    include_global?: boolean;
+    limit?: number;
+}
+interface ProofLoopMetricParams {
+    policy_key: string;
+    metric_key: string;
+    name: string;
+    min_value: number;
+    max_value: number;
+    collection_id?: string;
+    user_id?: string;
+    [key: string]: any;
+}
 interface APIKeyResponse {
     id: string;
     name: string;
@@ -194,13 +323,13 @@ declare class MemoriesResource extends BaseResource {
     /**
      * Create a new memory
      */
-    create(params: CreateMemoryParams): Promise<Memory>;
+    create(params: CreateMemoryParams): Promise<MemoryAddResponse>;
     /**
      * List memories
      */
-    list(params?: ListParams & {
-        collection_id?: string;
-    }): Promise<Memory[]>;
+    listPage(params?: MemoryListParams): Promise<CursorPage<Memory>>;
+    /** Back-compatible one-page convenience; use listPage for cursor metadata. */
+    list(params?: MemoryListParams): Promise<Memory[]>;
     /**
      * Get a specific memory
      */
@@ -214,6 +343,19 @@ declare class MemoriesResource extends BaseResource {
      */
     delete(memoryId: string): Promise<void>;
 }
+declare class MemoryJobsResource extends BaseResource {
+    get(jobId: string): Promise<MemoryJobReceipt>;
+    wait(jobId: string, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<MemoryJobReceipt>;
+}
+declare class CorrectionsResource extends BaseResource {
+    create(params: CorrectionCreateParams): Promise<Record<string, any>>;
+    relevant(params: CorrectionSearchParams): Promise<Array<Record<string, any>>>;
+    get(correctionId: string): Promise<Record<string, any>>;
+    delete(correctionId: string): Promise<Record<string, any>>;
+}
 declare class SearchResource extends BaseResource {
     /**
      * Search memories
@@ -239,8 +381,26 @@ declare class ProofLoopResource extends BaseResource {
         success?: boolean;
         idempotency_key?: string;
     }): Promise<Record<string, any>>;
+    getDecision(decisionId: string): Promise<Record<string, any>>;
+    defineMetric(params: ProofLoopMetricParams): Promise<Record<string, any>>;
+    listMetrics(params?: {
+        policy_key?: string;
+        collection_id?: string;
+        user_id?: string;
+    }): Promise<Record<string, any>>;
+    policyInsights(policyKey: string, params?: {
+        collection_id?: string;
+        user_id?: string;
+        action_keys?: string[];
+        context?: Record<string, any>;
+    }): Promise<Record<string, any>>;
+    evaluatePolicy(policyKey: string, params?: {
+        collection_id?: string;
+        user_id?: string;
+        limit?: number;
+    }): Promise<Record<string, any>>;
     proof(decisionId: string): Promise<Record<string, any>>;
-    publicKey(): Promise<Record<string, any>>;
+    publicKey(keyId?: string): Promise<Record<string, any>>;
 }
 declare class RLResource extends BaseResource {
     /**
@@ -418,6 +578,8 @@ declare class MemoryClient {
     auth: AuthResource;
     collections: CollectionsResource;
     memories: MemoriesResource;
+    memoryJobs: MemoryJobsResource;
+    corrections: CorrectionsResource;
     private searchResource;
     rl: RLResource;
     procedural: ProceduralResource;
@@ -464,4 +626,24 @@ declare class ServerError extends HebbrixError {
     constructor(message?: string);
 }
 
-export { type APIKeyResponse, AuthResource, type AuthResponse, AuthenticationError, type ClientConfig, type Collection, CollectionsResource, ConsolidationResource, type CreateCollectionParams, type CreateMemoryParams, HebbrixError, type ListParams, MemoriesResource, type Memory, MemoryClient, MemoryToolsResource, type MemoryWithMetadata, NotFoundError, ProceduralResource, type ProofContext, type ProofLoopCandidate, type ProofLoopDecisionParams, ProofLoopResource, RLResource, RateLimitError, type ReasonParams, type ReasoningResponse, type ReasoningSource, type SearchParams, SearchResource, type SearchResponse, type SearchResult, ServerError, TemporalResource, type UpdateCollectionParams, type UpdateMemoryParams, type User, ValidationError, WorkingMemoryResource, WorldModelResource };
+interface SafetyEnvelope {
+    no_match: boolean;
+    abstain_recommended: boolean;
+    query_confidence: number;
+    grounding: GroundingReceipt;
+    evidence_ids: string[];
+    evidence_claims?: unknown[];
+    safety_contract_version: string;
+    degraded?: boolean;
+    sdk_safety_reason?: string;
+    [key: string]: unknown;
+}
+/**
+ * Validate the API-owned grounding receipt before exposing evidence to an agent.
+ * A malformed, degraded, abstaining, or ungrounded response is converted into
+ * one deterministic no-match envelope. This prevents SDK/API contract drift
+ * from turning a nearest neighbour into verified evidence.
+ */
+declare function enforceSearchSafety<T extends object>(response: T, rowsKey?: "results" | "sources"): T & SafetyEnvelope;
+
+export { type APIKeyResponse, AuthResource, type AuthResponse, AuthenticationError, type ClientConfig, type Collection, CollectionsResource, ConsolidationResource, type CorrectionCreateParams, type CorrectionSearchParams, CorrectionsResource, type CreateCollectionParams, type CreateMemoryParams, type CursorPage, type EvidenceClaim, type GroundingReceipt, HebbrixError, type ListParams, MemoriesResource, type Memory, type MemoryAddResponse, type MemoryAddResult, MemoryClient, type MemoryJobReceipt, MemoryJobsResource, type MemoryListParams, MemoryToolsResource, type MemoryWithMetadata, NotFoundError, ProceduralResource, type ProofContext, type ProofLoopCandidate, type ProofLoopDecisionParams, type ProofLoopMetricParams, ProofLoopResource, RLResource, RateLimitError, type ReasonParams, type ReasoningResponse, type ReasoningSource, type SafetyEnvelope, type SearchParams, SearchResource, type SearchResponse, type SearchResult, ServerError, TemporalResource, type UpdateCollectionParams, type UpdateMemoryParams, type User, ValidationError, WorkingMemoryResource, WorldModelResource, enforceSearchSafety };

package/dist/index.d.ts

@@ -57,8 +57,27 @@ interface SearchResponse {
     total: number;
     search_type: string;
     processing_time_ms: number;
+    no_match: boolean;
+    abstain_recommended: boolean;
+    query_confidence: number;
+    grounding: GroundingReceipt;
+    evidence_ids: string[];
+    evidence_claims?: EvidenceClaim[];
+    safety_contract_version: string;
+    degraded?: boolean;
+    sdk_safety_reason?: string;
     proof_context?: ProofContext;
 }
+interface GroundingReceipt {
+    status: string;
+    reason?: string;
+    contract_version?: string;
+    [key: string]: unknown;
+}
+interface EvidenceClaim {
+    memory_id: string;
+    claims: Record<string, unknown>;
+}
 interface ProofContext {
     schema_version: "proofloop-context-v1";
     context_id: string;
@@ -88,9 +107,18 @@ interface ReasoningSource {
     score: number;
 }
 interface ReasoningResponse {
-    answer: string;
+    answer: string | null;
     sources: ReasoningSource[];
     metadata: Record<string, any>;
+    no_match: boolean;
+    abstain_recommended: boolean;
+    query_confidence: number;
+    grounding: GroundingReceipt;
+    evidence_ids: string[];
+    evidence_claims?: EvidenceClaim[];
+    safety_contract_version: string;
+    degraded?: boolean;
+    sdk_safety_reason?: string;
     reasoning_context?: Record<string, any>;
 }
 interface CreateCollectionParams {
@@ -104,17 +132,54 @@ interface UpdateCollectionParams {
     metadata?: Record<string, any>;
 }
 interface CreateMemoryParams {
-    collection_id: string;
-    content: string;
+    collection_id?: string;
+    content?: string;
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
     importance?: number;
     source_type?: string;
     source_reference?: string;
     metadata?: Record<string, any>;
+    infer?: boolean;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    app_id?: string;
+    namespace?: string;
+    wait_for_index?: boolean;
+    async_dispatch?: boolean;
+    title?: string;
+    tags?: string[];
+    source?: string;
+    /** Stable retry key sent as the Idempotency-Key transport header. */
+    idempotency_key?: string;
+}
+interface MemoryAddResult {
+    id: string;
+    memory_id?: string;
+    event: "ADD" | "UPDATE" | "NOOP" | string;
+    memory?: string;
+    reason?: string;
+}
+interface MemoryAddResponse {
+    results: MemoryAddResult[];
+    collection_id?: string;
+    processing_status: string;
+    searchable: boolean;
+    outbox_event_id?: string;
+    status_url?: string;
+    job_id?: string;
+    created_count: number;
+    updated_count: number;
+    skipped_count: number;
 }
 interface UpdateMemoryParams {
     content?: string;
     importance?: number;
     metadata?: Record<string, any>;
+    wait_for_index?: boolean;
 }
 interface SearchParams {
     query: string;
@@ -123,17 +188,81 @@ interface SearchParams {
     search_type?: "hybrid" | "vector" | "bm25" | "graph";
     filters?: Record<string, any>;
     user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    fast?: boolean;
+    threshold?: number;
+    include_low_confidence?: boolean;
+    group_by_source?: boolean;
+    debug?: boolean;
 }
 interface ReasonParams {
     query: string;
     collection_id?: string;
     provider?: "gemini" | "openai" | "anthropic";
     include_steps?: boolean;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    facets?: string[];
 }
 interface ListParams {
     skip?: number;
     limit?: number;
 }
+interface MemoryListParams {
+    collection_id?: string;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    scope?: "all";
+    cursor?: string;
+    limit?: number;
+    include_superseded?: boolean;
+}
+interface CursorPage<T> {
+    items: T[];
+    next_cursor?: string | null;
+    has_more: boolean;
+    total_count: number;
+}
+interface MemoryJobReceipt {
+    job_id?: string;
+    status: string;
+    [key: string]: any;
+}
+interface CorrectionCreateParams {
+    corrected_content: string;
+    correction_type?: "preference" | "factual" | "procedural" | string;
+    original_content?: string;
+    context?: string;
+    memory_id?: string;
+    collection_id?: string;
+    user_id?: string;
+    agent_id?: string;
+    confidence?: number;
+    metadata?: Record<string, any>;
+    idempotency_key?: string;
+}
+interface CorrectionSearchParams {
+    query: string;
+    correction_type?: string;
+    collection_id?: string;
+    user_id?: string;
+    agent_id?: string;
+    include_global?: boolean;
+    limit?: number;
+}
+interface ProofLoopMetricParams {
+    policy_key: string;
+    metric_key: string;
+    name: string;
+    min_value: number;
+    max_value: number;
+    collection_id?: string;
+    user_id?: string;
+    [key: string]: any;
+}
 interface APIKeyResponse {
     id: string;
     name: string;
@@ -194,13 +323,13 @@ declare class MemoriesResource extends BaseResource {
     /**
      * Create a new memory
      */
-    create(params: CreateMemoryParams): Promise<Memory>;
+    create(params: CreateMemoryParams): Promise<MemoryAddResponse>;
     /**
      * List memories
      */
-    list(params?: ListParams & {
-        collection_id?: string;
-    }): Promise<Memory[]>;
+    listPage(params?: MemoryListParams): Promise<CursorPage<Memory>>;
+    /** Back-compatible one-page convenience; use listPage for cursor metadata. */
+    list(params?: MemoryListParams): Promise<Memory[]>;
     /**
      * Get a specific memory
      */
@@ -214,6 +343,19 @@ declare class MemoriesResource extends BaseResource {
      */
     delete(memoryId: string): Promise<void>;
 }
+declare class MemoryJobsResource extends BaseResource {
+    get(jobId: string): Promise<MemoryJobReceipt>;
+    wait(jobId: string, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<MemoryJobReceipt>;
+}
+declare class CorrectionsResource extends BaseResource {
+    create(params: CorrectionCreateParams): Promise<Record<string, any>>;
+    relevant(params: CorrectionSearchParams): Promise<Array<Record<string, any>>>;
+    get(correctionId: string): Promise<Record<string, any>>;
+    delete(correctionId: string): Promise<Record<string, any>>;
+}
 declare class SearchResource extends BaseResource {
     /**
      * Search memories
@@ -239,8 +381,26 @@ declare class ProofLoopResource extends BaseResource {
         success?: boolean;
         idempotency_key?: string;
     }): Promise<Record<string, any>>;
+    getDecision(decisionId: string): Promise<Record<string, any>>;
+    defineMetric(params: ProofLoopMetricParams): Promise<Record<string, any>>;
+    listMetrics(params?: {
+        policy_key?: string;
+        collection_id?: string;
+        user_id?: string;
+    }): Promise<Record<string, any>>;
+    policyInsights(policyKey: string, params?: {
+        collection_id?: string;
+        user_id?: string;
+        action_keys?: string[];
+        context?: Record<string, any>;
+    }): Promise<Record<string, any>>;
+    evaluatePolicy(policyKey: string, params?: {
+        collection_id?: string;
+        user_id?: string;
+        limit?: number;
+    }): Promise<Record<string, any>>;
     proof(decisionId: string): Promise<Record<string, any>>;
-    publicKey(): Promise<Record<string, any>>;
+    publicKey(keyId?: string): Promise<Record<string, any>>;
 }
 declare class RLResource extends BaseResource {
     /**
@@ -418,6 +578,8 @@ declare class MemoryClient {
     auth: AuthResource;
     collections: CollectionsResource;
     memories: MemoriesResource;
+    memoryJobs: MemoryJobsResource;
+    corrections: CorrectionsResource;
     private searchResource;
     rl: RLResource;
     procedural: ProceduralResource;
@@ -464,4 +626,24 @@ declare class ServerError extends HebbrixError {
     constructor(message?: string);
 }
 
-export { type APIKeyResponse, AuthResource, type AuthResponse, AuthenticationError, type ClientConfig, type Collection, CollectionsResource, ConsolidationResource, type CreateCollectionParams, type CreateMemoryParams, HebbrixError, type ListParams, MemoriesResource, type Memory, MemoryClient, MemoryToolsResource, type MemoryWithMetadata, NotFoundError, ProceduralResource, type ProofContext, type ProofLoopCandidate, type ProofLoopDecisionParams, ProofLoopResource, RLResource, RateLimitError, type ReasonParams, type ReasoningResponse, type ReasoningSource, type SearchParams, SearchResource, type SearchResponse, type SearchResult, ServerError, TemporalResource, type UpdateCollectionParams, type UpdateMemoryParams, type User, ValidationError, WorkingMemoryResource, WorldModelResource };
+interface SafetyEnvelope {
+    no_match: boolean;
+    abstain_recommended: boolean;
+    query_confidence: number;
+    grounding: GroundingReceipt;
+    evidence_ids: string[];
+    evidence_claims?: unknown[];
+    safety_contract_version: string;
+    degraded?: boolean;
+    sdk_safety_reason?: string;
+    [key: string]: unknown;
+}
+/**
+ * Validate the API-owned grounding receipt before exposing evidence to an agent.
+ * A malformed, degraded, abstaining, or ungrounded response is converted into
+ * one deterministic no-match envelope. This prevents SDK/API contract drift
+ * from turning a nearest neighbour into verified evidence.
+ */
+declare function enforceSearchSafety<T extends object>(response: T, rowsKey?: "results" | "sources"): T & SafetyEnvelope;
+
+export { type APIKeyResponse, AuthResource, type AuthResponse, AuthenticationError, type ClientConfig, type Collection, CollectionsResource, ConsolidationResource, type CorrectionCreateParams, type CorrectionSearchParams, CorrectionsResource, type CreateCollectionParams, type CreateMemoryParams, type CursorPage, type EvidenceClaim, type GroundingReceipt, HebbrixError, type ListParams, MemoriesResource, type Memory, type MemoryAddResponse, type MemoryAddResult, MemoryClient, type MemoryJobReceipt, MemoryJobsResource, type MemoryListParams, MemoryToolsResource, type MemoryWithMetadata, NotFoundError, ProceduralResource, type ProofContext, type ProofLoopCandidate, type ProofLoopDecisionParams, type ProofLoopMetricParams, ProofLoopResource, RLResource, RateLimitError, type ReasonParams, type ReasoningResponse, type ReasoningSource, type SafetyEnvelope, type SearchParams, SearchResource, type SearchResponse, type SearchResult, ServerError, TemporalResource, type UpdateCollectionParams, type UpdateMemoryParams, type User, ValidationError, WorkingMemoryResource, WorldModelResource, enforceSearchSafety };

package/dist/index.js

@@ -24,9 +24,11 @@ __export(index_exports, {
   AuthenticationError: () => AuthenticationError,
   CollectionsResource: () => CollectionsResource,
   ConsolidationResource: () => ConsolidationResource,
+  CorrectionsResource: () => CorrectionsResource,
   HebbrixError: () => HebbrixError,
   MemoriesResource: () => MemoriesResource,
   MemoryClient: () => MemoryClient,
+  MemoryJobsResource: () => MemoryJobsResource,
   MemoryToolsResource: () => MemoryToolsResource,
   NotFoundError: () => NotFoundError,
   ProceduralResource: () => ProceduralResource,
@@ -38,10 +40,63 @@ __export(index_exports, {
   TemporalResource: () => TemporalResource,
   ValidationError: () => ValidationError,
   WorkingMemoryResource: () => WorkingMemoryResource,
-  WorldModelResource: () => WorldModelResource
+  WorldModelResource: () => WorldModelResource,
+  enforceSearchSafety: () => enforceSearchSafety
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/safety.ts
+var REQUIRED_FIELDS = [
+  "no_match",
+  "abstain_recommended",
+  "query_confidence",
+  "grounding",
+  "evidence_ids",
+  "safety_contract_version"
+];
+function enforceSearchSafety(response, rowsKey = "results") {
+  const data = { ...response };
+  const rawRows = data[rowsKey];
+  const rows = Array.isArray(rawRows) ? rawRows.filter((row) => typeof row === "object" && row !== null) : [];
+  const missing = REQUIRED_FIELDS.filter(
+    (field) => !Object.prototype.hasOwnProperty.call(data, field)
+  );
+  let reason;
+  if (missing.length > 0) {
+    reason = `missing_safety_fields:${missing.join(",")}`;
+  } else if (typeof data.no_match !== "boolean" || typeof data.abstain_recommended !== "boolean") {
+    reason = "invalid_abstention_fields";
+  } else if (typeof data.query_confidence !== "number" || !Number.isFinite(data.query_confidence) || data.query_confidence < 0 || data.query_confidence > 1) {
+    reason = "invalid_query_confidence";
+  } else if (typeof data.grounding !== "object" || data.grounding === null || Array.isArray(data.grounding)) {
+    reason = "invalid_grounding_receipt";
+  } else if (!Array.isArray(data.evidence_ids)) {
+    reason = "invalid_evidence_ids";
+  } else {
+    const evidenceIds = new Set(data.evidence_ids.map(String));
+    const rowIds = rows.map((row) => row.memory_id ?? row.id).filter((value) => typeof value === "string" && value.length > 0);
+    if (rowIds.some((value) => !evidenceIds.has(value))) {
+      reason = "rows_not_bound_to_evidence_ids";
+    } else if (data.no_match && (rowIds.length > 0 || evidenceIds.size > 0)) {
+      reason = "no_match_contains_evidence";
+    }
+  }
+  if (reason || data.degraded === true || data.no_match === true || data.abstain_recommended === true) {
+    data[rowsKey] = [];
+    if (rowsKey === "results") data.total = 0;
+    data.no_match = true;
+    data.abstain_recommended = true;
+    data.query_confidence = 0;
+    data.evidence_ids = [];
+    data.evidence_claims = [];
+    if (reason) {
+      data.sdk_safety_reason = reason;
+      data.grounding = { status: "no_grounded_match", reason };
+    }
+  }
+  return data;
+}
+
 // src/resources.ts
 var BaseResource = class {
   constructor(client) {
@@ -121,14 +176,32 @@ var MemoriesResource = class extends BaseResource {
    * Create a new memory
    */
   async create(params) {
-    return this.client.post("/v1/memories", params);
+    if (!params.content?.trim() && !params.messages?.length) {
+      throw new TypeError("content or messages must be provided");
+    }
+    const { idempotency_key, ...input } = params;
+    return this.client.request("POST", "/v1/memories", {
+      headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
+      body: JSON.stringify({
+        source_type: "text",
+        metadata: {},
+        infer: false,
+        wait_for_index: false,
+        ...input
+      })
+    });
   }
   /**
    * List memories
    */
-  async list(params = {}) {
+  async listPage(params = {}) {
     return this.client.get("/v1/memories", params);
   }
+  /** Back-compatible one-page convenience; use listPage for cursor metadata. */
+  async list(params = {}) {
+    const page = await this.listPage(params);
+    return page.items;
+  }
   /**
    * Get a specific memory
    */
@@ -148,30 +221,79 @@ var MemoriesResource = class extends BaseResource {
     await this.client.delete(`/v1/memories/${memoryId}`);
   }
 };
+var MemoryJobsResource = class extends BaseResource {
+  async get(jobId) {
+    return this.client.get(`/v1/memory-jobs/${jobId}`);
+  }
+  async wait(jobId, options = {}) {
+    const timeoutMs = Math.max(0, options.timeoutMs ?? 6e4);
+    const pollIntervalMs = Math.max(50, options.pollIntervalMs ?? 500);
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const receipt = await this.get(jobId);
+      const status = String(receipt.status || "").toLowerCase();
+      if (["completed", "failed", "cancelled", "canceled"].includes(status)) {
+        return receipt;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`memory job ${jobId} did not finish in ${timeoutMs}ms`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+  }
+};
+var CorrectionsResource = class extends BaseResource {
+  async create(params) {
+    const { idempotency_key, ...body } = params;
+    return this.client.request("POST", "/v1/corrections", {
+      headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
+      body: JSON.stringify({
+        correction_type: "preference",
+        confidence: 1,
+        ...body
+      })
+    });
+  }
+  async relevant(params) {
+    return this.client.get("/v1/corrections/relevant", {
+      include_global: false,
+      limit: 10,
+      ...params
+    });
+  }
+  async get(correctionId) {
+    return this.client.get(`/v1/corrections/${correctionId}`);
+  }
+  async delete(correctionId) {
+    return this.client.delete(`/v1/corrections/${correctionId}`);
+  }
+};
 var SearchResource = class extends BaseResource {
   /**
    * Search memories
    */
   async search(params) {
-    const response = await this.client.post("/v1/search", {
-      query: params.query,
-      collection_id: params.collection_id,
-      limit: params.limit || 10,
-      search_type: params.search_type || "hybrid",
-      filters: params.filters || {}
-    });
+    const response = await this.searchWithProof(params);
     return response.results;
   }
   /** Search while preserving the automatic ProofLoop evidence context. */
   async searchWithProof(params) {
-    return this.client.post("/v1/search", {
+    const response = await this.client.post("/v1/search", {
       query: params.query,
       collection_id: params.collection_id,
       user_id: params.user_id,
+      agent_id: params.agent_id,
+      run_id: params.run_id,
       limit: params.limit || 10,
       search_type: params.search_type || "hybrid",
-      filters: params.filters || {}
+      filters: params.filters || {},
+      fast: params.fast,
+      threshold: params.threshold,
+      include_low_confidence: params.include_low_confidence ?? false,
+      group_by_source: params.group_by_source ?? true,
+      debug: params.debug ?? false
     });
+    return enforceSearchSafety(response);
   }
   /**
    * Find similar memories
@@ -187,12 +309,20 @@ var SearchResource = class extends BaseResource {
    * Perform reasoning over memories
    */
   async reason(params) {
-    return this.client.post("/v1/search/reason", {
-      query: params.query,
-      collection_id: params.collection_id,
-      provider: params.provider,
-      include_steps: params.include_steps || false
-    });
+    const response = await this.client.post(
+      "/v1/search/reason",
+      {
+        query: params.query,
+        collection_id: params.collection_id,
+        provider: params.provider,
+        include_steps: params.include_steps ?? false,
+        user_id: params.user_id,
+        agent_id: params.agent_id,
+        run_id: params.run_id,
+        facets: params.facets ?? []
+      }
+    );
+    return enforceSearchSafety(response, "sources");
   }
 };
 var ProofLoopResource = class extends BaseResource {
@@ -212,11 +342,37 @@ var ProofLoopResource = class extends BaseResource {
       ...body
     });
   }
+  async getDecision(decisionId) {
+    return this.client.get(`/v1/learning/decisions/${decisionId}`);
+  }
+  async defineMetric(params) {
+    return this.client.post("/v1/learning/metrics", params);
+  }
+  async listMetrics(params = {}) {
+    return this.client.get("/v1/learning/metrics", params);
+  }
+  async policyInsights(policyKey, params = {}) {
+    return this.client.get(`/v1/learning/policies/${policyKey}/insights`, {
+      collection_id: params.collection_id,
+      user_id: params.user_id,
+      action_key: params.action_keys,
+      context: params.context ? JSON.stringify(params.context) : void 0
+    });
+  }
+  async evaluatePolicy(policyKey, params = {}) {
+    return this.client.post(`/v1/learning/policies/${policyKey}/evaluate`, {
+      collection_id: params.collection_id,
+      user_id: params.user_id,
+      limit: params.limit ?? 500
+    });
+  }
   async proof(decisionId) {
     return this.client.get(`/v1/learning/decisions/${decisionId}/proof`);
   }
-  async publicKey() {
-    return this.client.get("/v1/learning/proof-key");
+  async publicKey(keyId) {
+    return this.client.get("/v1/learning/proof-key", {
+      key_id: keyId
+    });
   }
 };
 var RLResource = class extends BaseResource {
@@ -513,6 +669,8 @@ var MemoryClient = class {
     this.auth = new AuthResource(this);
     this.collections = new CollectionsResource(this);
     this.memories = new MemoriesResource(this);
+    this.memoryJobs = new MemoryJobsResource(this);
+    this.corrections = new CorrectionsResource(this);
     this.searchResource = new SearchResource(this);
     this.rl = new RLResource(this);
     this.procedural = new ProceduralResource(this);
@@ -526,7 +684,7 @@ var MemoryClient = class {
   getHeaders() {
     const headers = {
       "Content-Type": "application/json",
-      "User-Agent": "hebbrix-typescript/2.1.0"
+      "User-Agent": "hebbrix-typescript/2.2.0"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
@@ -580,7 +738,11 @@ var MemoryClient = class {
       const searchParams = new URLSearchParams();
       Object.entries(params).forEach(([key, value]) => {
         if (value !== void 0 && value !== null) {
-          searchParams.append(key, String(value));
+          if (Array.isArray(value)) {
+            value.forEach((item) => searchParams.append(key, String(item)));
+          } else {
+            searchParams.append(key, String(value));
+          }
         }
       });
       url += `?${searchParams.toString()}`;
@@ -617,9 +779,11 @@ var MemoryClient = class {
   AuthenticationError,
   CollectionsResource,
   ConsolidationResource,
+  CorrectionsResource,
   HebbrixError,
   MemoriesResource,
   MemoryClient,
+  MemoryJobsResource,
   MemoryToolsResource,
   NotFoundError,
   ProceduralResource,
@@ -631,5 +795,6 @@ var MemoryClient = class {
   TemporalResource,
   ValidationError,
   WorkingMemoryResource,
-  WorldModelResource
+  WorldModelResource,
+  enforceSearchSafety
 });

package/dist/index.mjs

@@ -1,3 +1,55 @@
+// src/safety.ts
+var REQUIRED_FIELDS = [
+  "no_match",
+  "abstain_recommended",
+  "query_confidence",
+  "grounding",
+  "evidence_ids",
+  "safety_contract_version"
+];
+function enforceSearchSafety(response, rowsKey = "results") {
+  const data = { ...response };
+  const rawRows = data[rowsKey];
+  const rows = Array.isArray(rawRows) ? rawRows.filter((row) => typeof row === "object" && row !== null) : [];
+  const missing = REQUIRED_FIELDS.filter(
+    (field) => !Object.prototype.hasOwnProperty.call(data, field)
+  );
+  let reason;
+  if (missing.length > 0) {
+    reason = `missing_safety_fields:${missing.join(",")}`;
+  } else if (typeof data.no_match !== "boolean" || typeof data.abstain_recommended !== "boolean") {
+    reason = "invalid_abstention_fields";
+  } else if (typeof data.query_confidence !== "number" || !Number.isFinite(data.query_confidence) || data.query_confidence < 0 || data.query_confidence > 1) {
+    reason = "invalid_query_confidence";
+  } else if (typeof data.grounding !== "object" || data.grounding === null || Array.isArray(data.grounding)) {
+    reason = "invalid_grounding_receipt";
+  } else if (!Array.isArray(data.evidence_ids)) {
+    reason = "invalid_evidence_ids";
+  } else {
+    const evidenceIds = new Set(data.evidence_ids.map(String));
+    const rowIds = rows.map((row) => row.memory_id ?? row.id).filter((value) => typeof value === "string" && value.length > 0);
+    if (rowIds.some((value) => !evidenceIds.has(value))) {
+      reason = "rows_not_bound_to_evidence_ids";
+    } else if (data.no_match && (rowIds.length > 0 || evidenceIds.size > 0)) {
+      reason = "no_match_contains_evidence";
+    }
+  }
+  if (reason || data.degraded === true || data.no_match === true || data.abstain_recommended === true) {
+    data[rowsKey] = [];
+    if (rowsKey === "results") data.total = 0;
+    data.no_match = true;
+    data.abstain_recommended = true;
+    data.query_confidence = 0;
+    data.evidence_ids = [];
+    data.evidence_claims = [];
+    if (reason) {
+      data.sdk_safety_reason = reason;
+      data.grounding = { status: "no_grounded_match", reason };
+    }
+  }
+  return data;
+}
+
 // src/resources.ts
 var BaseResource = class {
   constructor(client) {
@@ -77,14 +129,32 @@ var MemoriesResource = class extends BaseResource {
    * Create a new memory
    */
   async create(params) {
-    return this.client.post("/v1/memories", params);
+    if (!params.content?.trim() && !params.messages?.length) {
+      throw new TypeError("content or messages must be provided");
+    }
+    const { idempotency_key, ...input } = params;
+    return this.client.request("POST", "/v1/memories", {
+      headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
+      body: JSON.stringify({
+        source_type: "text",
+        metadata: {},
+        infer: false,
+        wait_for_index: false,
+        ...input
+      })
+    });
   }
   /**
    * List memories
    */
-  async list(params = {}) {
+  async listPage(params = {}) {
     return this.client.get("/v1/memories", params);
   }
+  /** Back-compatible one-page convenience; use listPage for cursor metadata. */
+  async list(params = {}) {
+    const page = await this.listPage(params);
+    return page.items;
+  }
   /**
    * Get a specific memory
    */
@@ -104,30 +174,79 @@ var MemoriesResource = class extends BaseResource {
     await this.client.delete(`/v1/memories/${memoryId}`);
   }
 };
+var MemoryJobsResource = class extends BaseResource {
+  async get(jobId) {
+    return this.client.get(`/v1/memory-jobs/${jobId}`);
+  }
+  async wait(jobId, options = {}) {
+    const timeoutMs = Math.max(0, options.timeoutMs ?? 6e4);
+    const pollIntervalMs = Math.max(50, options.pollIntervalMs ?? 500);
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const receipt = await this.get(jobId);
+      const status = String(receipt.status || "").toLowerCase();
+      if (["completed", "failed", "cancelled", "canceled"].includes(status)) {
+        return receipt;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`memory job ${jobId} did not finish in ${timeoutMs}ms`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+  }
+};
+var CorrectionsResource = class extends BaseResource {
+  async create(params) {
+    const { idempotency_key, ...body } = params;
+    return this.client.request("POST", "/v1/corrections", {
+      headers: idempotency_key ? { "Idempotency-Key": idempotency_key } : void 0,
+      body: JSON.stringify({
+        correction_type: "preference",
+        confidence: 1,
+        ...body
+      })
+    });
+  }
+  async relevant(params) {
+    return this.client.get("/v1/corrections/relevant", {
+      include_global: false,
+      limit: 10,
+      ...params
+    });
+  }
+  async get(correctionId) {
+    return this.client.get(`/v1/corrections/${correctionId}`);
+  }
+  async delete(correctionId) {
+    return this.client.delete(`/v1/corrections/${correctionId}`);
+  }
+};
 var SearchResource = class extends BaseResource {
   /**
    * Search memories
    */
   async search(params) {
-    const response = await this.client.post("/v1/search", {
-      query: params.query,
-      collection_id: params.collection_id,
-      limit: params.limit || 10,
-      search_type: params.search_type || "hybrid",
-      filters: params.filters || {}
-    });
+    const response = await this.searchWithProof(params);
     return response.results;
   }
   /** Search while preserving the automatic ProofLoop evidence context. */
   async searchWithProof(params) {
-    return this.client.post("/v1/search", {
+    const response = await this.client.post("/v1/search", {
       query: params.query,
       collection_id: params.collection_id,
       user_id: params.user_id,
+      agent_id: params.agent_id,
+      run_id: params.run_id,
       limit: params.limit || 10,
       search_type: params.search_type || "hybrid",
-      filters: params.filters || {}
+      filters: params.filters || {},
+      fast: params.fast,
+      threshold: params.threshold,
+      include_low_confidence: params.include_low_confidence ?? false,
+      group_by_source: params.group_by_source ?? true,
+      debug: params.debug ?? false
     });
+    return enforceSearchSafety(response);
   }
   /**
    * Find similar memories
@@ -143,12 +262,20 @@ var SearchResource = class extends BaseResource {
    * Perform reasoning over memories
    */
   async reason(params) {
-    return this.client.post("/v1/search/reason", {
-      query: params.query,
-      collection_id: params.collection_id,
-      provider: params.provider,
-      include_steps: params.include_steps || false
-    });
+    const response = await this.client.post(
+      "/v1/search/reason",
+      {
+        query: params.query,
+        collection_id: params.collection_id,
+        provider: params.provider,
+        include_steps: params.include_steps ?? false,
+        user_id: params.user_id,
+        agent_id: params.agent_id,
+        run_id: params.run_id,
+        facets: params.facets ?? []
+      }
+    );
+    return enforceSearchSafety(response, "sources");
   }
 };
 var ProofLoopResource = class extends BaseResource {
@@ -168,11 +295,37 @@ var ProofLoopResource = class extends BaseResource {
       ...body
     });
   }
+  async getDecision(decisionId) {
+    return this.client.get(`/v1/learning/decisions/${decisionId}`);
+  }
+  async defineMetric(params) {
+    return this.client.post("/v1/learning/metrics", params);
+  }
+  async listMetrics(params = {}) {
+    return this.client.get("/v1/learning/metrics", params);
+  }
+  async policyInsights(policyKey, params = {}) {
+    return this.client.get(`/v1/learning/policies/${policyKey}/insights`, {
+      collection_id: params.collection_id,
+      user_id: params.user_id,
+      action_key: params.action_keys,
+      context: params.context ? JSON.stringify(params.context) : void 0
+    });
+  }
+  async evaluatePolicy(policyKey, params = {}) {
+    return this.client.post(`/v1/learning/policies/${policyKey}/evaluate`, {
+      collection_id: params.collection_id,
+      user_id: params.user_id,
+      limit: params.limit ?? 500
+    });
+  }
   async proof(decisionId) {
     return this.client.get(`/v1/learning/decisions/${decisionId}/proof`);
   }
-  async publicKey() {
-    return this.client.get("/v1/learning/proof-key");
+  async publicKey(keyId) {
+    return this.client.get("/v1/learning/proof-key", {
+      key_id: keyId
+    });
   }
 };
 var RLResource = class extends BaseResource {
@@ -469,6 +622,8 @@ var MemoryClient = class {
     this.auth = new AuthResource(this);
     this.collections = new CollectionsResource(this);
     this.memories = new MemoriesResource(this);
+    this.memoryJobs = new MemoryJobsResource(this);
+    this.corrections = new CorrectionsResource(this);
     this.searchResource = new SearchResource(this);
     this.rl = new RLResource(this);
     this.procedural = new ProceduralResource(this);
@@ -482,7 +637,7 @@ var MemoryClient = class {
   getHeaders() {
     const headers = {
       "Content-Type": "application/json",
-      "User-Agent": "hebbrix-typescript/2.1.0"
+      "User-Agent": "hebbrix-typescript/2.2.0"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
@@ -536,7 +691,11 @@ var MemoryClient = class {
       const searchParams = new URLSearchParams();
       Object.entries(params).forEach(([key, value]) => {
         if (value !== void 0 && value !== null) {
-          searchParams.append(key, String(value));
+          if (Array.isArray(value)) {
+            value.forEach((item) => searchParams.append(key, String(item)));
+          } else {
+            searchParams.append(key, String(value));
+          }
         }
       });
       url += `?${searchParams.toString()}`;
@@ -572,9 +731,11 @@ export {
   AuthenticationError,
   CollectionsResource,
   ConsolidationResource,
+  CorrectionsResource,
   HebbrixError,
   MemoriesResource,
   MemoryClient,
+  MemoryJobsResource,
   MemoryToolsResource,
   NotFoundError,
   ProceduralResource,
@@ -586,5 +747,6 @@ export {
   TemporalResource,
   ValidationError,
   WorkingMemoryResource,
-  WorldModelResource
+  WorldModelResource,
+  enforceSearchSafety
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hebbrix",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Advanced Memory API for AI Agents with Reinforcement Learning - TypeScript/JavaScript SDK",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -19,7 +19,7 @@
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "test": "jest",
+    "test": "npm run build && node --test tests/*.test.mjs",
     "lint": "eslint src --ext .ts",
     "format": "prettier --write \"src/**/*.ts\"",
     "prepublishOnly": "npm run build"