hebbrix 2.1.0 → 2.2.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 2.2.1 — 2026-08-26
+
+- Preserve bearer authentication, content type, user agent, idempotency, and
+  caller-supplied headers on every request.
+- Handle `204`, empty, and non-JSON successful responses without attempting an
+  unconditional JSON parse.
+- Preserve valid evidence-bound search rows during a degraded or abstaining
+  server response while retaining the safety metadata; malformed and explicit
+  no-match envelopes still fail closed.
+- Preserve caller-provided abort signals while retaining the default timeout.
+- Add `temporal.deleteFact(factId)` for tenant-scoped, idempotent cleanup of
+  facts created through the temporal API.
+- Align procedure create/list/get/update/execute/delete with the canonical
+  `/v1/procedures` REST and OpenAPI contract, including empty `204` deletion.
+- Add explicit synchronous/asynchronous batch readiness receipts and
+  `waitForBatchSearchable`, which polls every accepted memory, propagates
+  terminal failures, respects deadlines, and supports cancellation.
+
+The supported server/SDK release pair is published by the server OpenAPI
+document in `info.x-hebbrix-sdk-compatibility`. Patch releases preserve the
+public API within the same major version.
+
+## 2.2.0
+
+- Added the GA scoped memory, corrections, search proof, and ProofLoop surface.

package/README.md

@@ -50,8 +50,22 @@ const main = async () => {
     collection_id: collection.id,
     content: 'User prefers dark mode and loves TypeScript',
     importance: 0.9,
+    wait_for_index: true,
   });
 
+  // Batch writes have an explicit two-mode contract. With wait_for_index=true,
+  // success means every item is searchable; a server deadline rejects with a
+  // retryable error instead of returning a misleading successful 202.
+  const batch = await client.memories.createBatch({
+    memories: [{ content: 'First fact' }, { content: 'Second fact' }],
+    collection_id: collection.id,
+    wait_for_index: true,
+    idempotency_key: 'import-42',
+  });
+
+  // For fire-and-forget batches, poll every item (with timeout/cancellation):
+  // await client.memories.waitForBatchSearchable(batch, { signal });
+
   // Search memories
   const results = await client.search({
     query: 'What programming language does user like?',
@@ -322,6 +336,8 @@ const updated = await client.procedural.update(procedure.id, {
 
 // Delete procedure
 await client.procedural.delete(procedure.id);
+// DELETE is tenant-scoped and idempotent: deleted, absent, and foreign IDs all
+// return 204 without revealing whether another tenant owns the identifier.
 ```
 
 ### 8. Temporal Knowledge Graphs

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,93 @@ 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 BatchMemoryItemParams {
+    content: string;
+    collection_id?: string;
+    importance?: number;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    tags?: string[];
+    metadata?: Record<string, any>;
+}
+interface BatchMemoryCreateParams {
+    memories: BatchMemoryItemParams[];
+    collection_id?: string;
+    user_id?: string;
+    agent_id?: string;
+    run_id?: string;
+    app_id?: string;
+    namespace?: string;
+    wait_for_index?: boolean;
+    /** Stable retry key sent as the Idempotency-Key transport header. */
+    idempotency_key?: string;
+    /** Optional caller cancellation signal; it is never serialized. */
+    signal?: AbortSignal;
+}
+interface BatchMemoryResponse {
+    created: number;
+    failed: number;
+    memory_ids: string[];
+    errors: string[];
+    results: Array<{
+        id: string;
+        memory_id?: string;
+        processing_status: string;
+    }>;
+    processing_status: string;
+    searchable: boolean;
+    outbox_event_id?: string;
+    status_url?: string;
 }
 interface UpdateMemoryParams {
     content?: string;
     importance?: number;
     metadata?: Record<string, any>;
+    wait_for_index?: boolean;
 }
 interface SearchParams {
     query: string;
@@ -123,17 +227,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 +362,26 @@ declare class MemoriesResource extends BaseResource {
     /**
      * Create a new memory
      */
-    create(params: CreateMemoryParams): Promise<Memory>;
+    create(params: CreateMemoryParams): Promise<MemoryAddResponse>;
+    /**
+     * Create up to 100 memories with one unambiguous readiness contract.
+     * `wait_for_index=true` resolves only for a fully searchable batch; a server
+     * deadline or indexing failure rejects the request instead of returning a
+     * successful processing receipt.
+     */
+    createBatch(params: BatchMemoryCreateParams): Promise<BatchMemoryResponse>;
+    /** Poll every item in an asynchronous batch receipt until it is searchable. */
+    waitForBatchSearchable(receipt: BatchMemoryResponse, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+        signal?: AbortSignal;
+    }): Promise<BatchMemoryResponse>;
     /**
      * 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 +395,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 +433,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 {
     /**
@@ -269,6 +481,7 @@ declare class RLResource extends BaseResource {
     evaluate(agentType: string, collectionId?: string): Promise<any>;
 }
 declare class ProceduralResource extends BaseResource {
+    private unwrapProcedure;
     /**
      * Create a new procedure
      */
@@ -340,6 +553,8 @@ declare class TemporalResource extends BaseResource {
      * Query knowledge state at a specific point in time
      */
     pointInTime(timestamp: string, entity?: string): Promise<any>;
+    /** Permanently delete a tenant-scoped temporal fact by stable ID. */
+    deleteFact(factId: string): Promise<any>;
 }
 declare class WorkingMemoryResource extends BaseResource {
     /**
@@ -418,6 +633,8 @@ declare class MemoryClient {
     auth: AuthResource;
     collections: CollectionsResource;
     memories: MemoriesResource;
+    memoryJobs: MemoryJobsResource;
+    corrections: CorrectionsResource;
     private searchResource;
     rl: RLResource;
     procedural: ProceduralResource;
@@ -464,4 +681,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 or explicit no-match response is converted into one deterministic
+ * no-match envelope. Degraded, evidence-bound rows remain visible together with
+ * the API's abstention signal so the SDK cannot introduce a false negative.
+ */
+declare function enforceSearchSafety<T extends object>(response: T, rowsKey?: "results" | "sources"): T & SafetyEnvelope;
+
+export { type APIKeyResponse, AuthResource, type AuthResponse, AuthenticationError, type BatchMemoryCreateParams, type BatchMemoryItemParams, type BatchMemoryResponse, 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 };