@remnic/hermes-provider 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,188 @@
+/**
+ * @remnic/hermes-provider
+ *
+ * Typed HTTP client for the Remnic memory API.
+ *
+ * Usage:
+ *   const client = new HermesClient({ baseUrl: "http://127.0.0.1:4318", authToken: "secret" });
+ *   const health = await client.health();
+ *   const memories = await client.recall("what did I work on last week?");
+ */
+interface HermesClientOptions {
+    /** Base URL of the Engram HTTP server (e.g. "http://127.0.0.1:4318") */
+    baseUrl: string;
+    /** Bearer token for authentication */
+    authToken: string;
+    /** Default namespace for requests (optional) */
+    namespace?: string;
+    /** Default session key (optional) */
+    sessionKey?: string;
+    /** Max retries for server errors (default: 3) */
+    maxRetries?: number;
+    /** Base delay in ms between retries (default: 100) */
+    retryBaseDelayMs?: number;
+    /** Request timeout in ms (default: 5000) */
+    timeoutMs?: number;
+}
+interface EngramAccessHealthResponse {
+    ok: boolean;
+    memoryDir: string;
+    namespacesEnabled: boolean;
+    defaultNamespace: string;
+    searchBackend: string;
+    qmdEnabled: boolean;
+    nativeKnowledgeEnabled: boolean;
+    projectionAvailable: boolean;
+}
+interface EngramAccessRecallResponse {
+    context?: string;
+    results?: Array<{
+        id: string;
+        content: string;
+        score?: number;
+        category?: string;
+    }>;
+    count?: number;
+    traceId?: string;
+    plannerMode?: string;
+    fallbackUsed?: boolean;
+    sourcesUsed?: string[];
+    budgetsApplied?: Record<string, unknown>;
+    latencyMs?: number;
+}
+interface EngramAccessObserveResponse {
+    accepted: number;
+    sessionKey: string;
+    namespace?: string;
+    lcmArchived?: boolean;
+    extractionQueued?: boolean;
+}
+interface EngramAccessWriteResponse {
+    memoryId?: string;
+    status: string;
+    dryRun?: boolean;
+    idempotencyReplay?: boolean;
+    path?: string;
+    duplicateOf?: string;
+    idempotencyKey?: string;
+}
+interface EngramAccessEntityListResponse {
+    entities: Array<{
+        name: string;
+        type: string;
+        factCount?: number;
+    }>;
+    total: number;
+}
+interface EngramAccessEntityGetResponse {
+    found: boolean;
+    entity?: {
+        name: string;
+        type: string;
+        observations?: string[];
+    };
+}
+interface EngramAccessMemoryBrowseResponse {
+    memories: Array<Record<string, unknown>>;
+    total: number;
+}
+interface EngramAccessMemoryGetResponse {
+    found: boolean;
+    memory?: Record<string, unknown>;
+}
+interface EngramAccessLcmSearchResponse {
+    query: string;
+    namespace?: string;
+    results: Array<{
+        sessionId?: string;
+        content?: string;
+        turnIndex?: number;
+    }>;
+    count: number;
+    lcmEnabled: boolean;
+}
+interface RecallOptions {
+    sessionKey?: string;
+    namespace?: string;
+    topK?: number;
+    mode?: "auto" | "no_recall" | "minimal" | "full" | "graph_mode";
+    includeDebug?: boolean;
+}
+interface ObserveOptions {
+    namespace?: string;
+    skipExtraction?: boolean;
+}
+interface MemoryStoreRequest {
+    content: string;
+    category?: string;
+    confidence?: number;
+    tags?: string[];
+    entityRef?: string;
+    ttl?: string;
+    sourceReason?: string;
+    sessionKey?: string;
+    namespace?: string;
+    idempotencyKey?: string;
+    dryRun?: boolean;
+    schemaVersion?: number;
+}
+declare class HermesError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: Array<{
+        field: string;
+        message: string;
+    }> | undefined;
+    constructor(status: number, code: string, message: string, details?: Array<{
+        field: string;
+        message: string;
+    }> | undefined);
+}
+declare class HermesClient {
+    private readonly baseUrl;
+    private readonly authToken;
+    private readonly defaultNamespace?;
+    private readonly defaultSessionKey?;
+    private readonly maxRetries;
+    private readonly retryBaseDelayMs;
+    private readonly timeoutMs;
+    constructor(options: HermesClientOptions);
+    health(): Promise<EngramAccessHealthResponse>;
+    recall(query: string, options?: RecallOptions): Promise<EngramAccessRecallResponse>;
+    observe(sessionKey: string, messages: Array<{
+        role: "user" | "assistant";
+        content: string;
+    }>, options?: ObserveOptions): Promise<EngramAccessObserveResponse>;
+    store(request: MemoryStoreRequest): Promise<EngramAccessWriteResponse>;
+    submitSuggestion(request: MemoryStoreRequest): Promise<EngramAccessWriteResponse>;
+    getEntities(options?: {
+        namespace?: string;
+        query?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<EngramAccessEntityListResponse>;
+    getEntity(name: string, options?: {
+        namespace?: string;
+    }): Promise<EngramAccessEntityGetResponse>;
+    getMemories(options?: {
+        query?: string;
+        status?: string;
+        category?: string;
+        namespace?: string;
+        sort?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<EngramAccessMemoryBrowseResponse>;
+    getMemory(id: string, options?: {
+        namespace?: string;
+    }): Promise<EngramAccessMemoryGetResponse>;
+    lcmSearch(query: string, options?: {
+        sessionKey?: string;
+        namespace?: string;
+        limit?: number;
+    }): Promise<EngramAccessLcmSearchResponse>;
+    private queryString;
+    private request;
+}
+
+export { type EngramAccessEntityGetResponse, type EngramAccessEntityListResponse, type EngramAccessHealthResponse, type EngramAccessLcmSearchResponse, type EngramAccessMemoryBrowseResponse, type EngramAccessMemoryGetResponse, type EngramAccessObserveResponse, type EngramAccessRecallResponse, type EngramAccessWriteResponse, HermesClient, type HermesClientOptions, HermesError, type MemoryStoreRequest, type ObserveOptions, type RecallOptions };

package/dist/index.js

@@ -0,0 +1,229 @@
+// openclaw-engram: Local-first memory plugin
+
+// src/index.ts
+var HermesError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+  status;
+  code;
+  details;
+};
+var HermesClient = class {
+  baseUrl;
+  authToken;
+  defaultNamespace;
+  defaultSessionKey;
+  maxRetries;
+  retryBaseDelayMs;
+  timeoutMs;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.endsWith("/") ? options.baseUrl.slice(0, -1) : options.baseUrl;
+    this.authToken = options.authToken;
+    this.defaultNamespace = options.namespace;
+    this.defaultSessionKey = options.sessionKey;
+    this.maxRetries = options.maxRetries ?? 3;
+    this.retryBaseDelayMs = options.retryBaseDelayMs ?? 100;
+    this.timeoutMs = options.timeoutMs ?? 5e3;
+  }
+  // -----------------------------------------------------------------------
+  // Core methods
+  // -----------------------------------------------------------------------
+  async health() {
+    return this.request("GET", "/engram/v1/health");
+  }
+  async recall(query, options) {
+    const body = {
+      query
+    };
+    const sk = options?.sessionKey ?? this.defaultSessionKey;
+    if (sk) body.sessionKey = sk;
+    const ns = options?.namespace ?? this.defaultNamespace;
+    if (ns) body.namespace = ns;
+    if (options?.topK !== void 0) body.topK = options.topK;
+    if (options?.mode) body.mode = options.mode;
+    if (options?.includeDebug !== void 0) body.includeDebug = options.includeDebug;
+    return this.request("POST", "/engram/v1/recall", body, { noRetry: true });
+  }
+  async observe(sessionKey, messages, options) {
+    const body = {
+      sessionKey,
+      messages,
+      namespace: options?.namespace ?? this.defaultNamespace,
+      skipExtraction: options?.skipExtraction ?? false
+    };
+    return this.request("POST", "/engram/v1/observe", body, { noRetry: true });
+  }
+  async store(request) {
+    const body = {
+      ...request,
+      namespace: request.namespace ?? this.defaultNamespace,
+      sessionKey: request.sessionKey ?? this.defaultSessionKey
+    };
+    return this.request("POST", "/engram/v1/memories", body, { noRetry: true });
+  }
+  async submitSuggestion(request) {
+    const body = {
+      ...request,
+      namespace: request.namespace ?? this.defaultNamespace,
+      sessionKey: request.sessionKey ?? this.defaultSessionKey
+    };
+    return this.request("POST", "/engram/v1/suggestions", body, { noRetry: true });
+  }
+  // -----------------------------------------------------------------------
+  // Browse / read methods
+  // -----------------------------------------------------------------------
+  async getEntities(options) {
+    const params = {
+      namespace: options?.namespace ?? this.defaultNamespace
+    };
+    if (options?.query) params.q = options.query;
+    if (options?.limit !== void 0) params.limit = options.limit;
+    if (options?.offset !== void 0) params.offset = options.offset;
+    return this.request(
+      "GET",
+      `/engram/v1/entities${this.queryString(params)}`
+    );
+  }
+  async getEntity(name, options) {
+    try {
+      return await this.request(
+        "GET",
+        `/engram/v1/entities/${encodeURIComponent(name)}${this.queryString({ namespace: options?.namespace ?? this.defaultNamespace })}`
+      );
+    } catch (err) {
+      if (err instanceof HermesError && err.status === 404) {
+        return { found: false };
+      }
+      throw err;
+    }
+  }
+  async getMemories(options) {
+    const params = {
+      namespace: options?.namespace ?? this.defaultNamespace
+    };
+    if (options?.query) params.q = options.query;
+    if (options?.status) params.status = options.status;
+    if (options?.category) params.category = options.category;
+    if (options?.sort) params.sort = options.sort;
+    if (options?.limit !== void 0) params.limit = options.limit;
+    if (options?.offset !== void 0) params.offset = options.offset;
+    return this.request(
+      "GET",
+      `/engram/v1/memories${this.queryString(params)}`
+    );
+  }
+  async getMemory(id, options) {
+    try {
+      return await this.request(
+        "GET",
+        `/engram/v1/memories/${encodeURIComponent(id)}${this.queryString({ namespace: options?.namespace ?? this.defaultNamespace })}`
+      );
+    } catch (err) {
+      if (err instanceof HermesError && err.status === 404) {
+        return { found: false };
+      }
+      throw err;
+    }
+  }
+  async lcmSearch(query, options) {
+    const body = {
+      query,
+      sessionKey: options?.sessionKey ?? this.defaultSessionKey,
+      namespace: options?.namespace ?? this.defaultNamespace,
+      ...options?.limit !== void 0 ? { limit: options.limit } : {}
+    };
+    return this.request("POST", "/engram/v1/lcm/search", body);
+  }
+  // -----------------------------------------------------------------------
+  // Internal helpers
+  // -----------------------------------------------------------------------
+  queryString(params) {
+    if (!params) return "";
+    const parts = [];
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0 && value !== null && value !== "") {
+        parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+      }
+    }
+    return parts.length > 0 ? `?${parts.join("&")}` : "";
+  }
+  async request(method, path, body, options) {
+    const isMutating = options?.noRetry === true;
+    const maxAttempts = isMutating ? 1 : this.maxRetries + 1;
+    let lastError = null;
+    let lastRateLimitError = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      if (attempt > 0) {
+        const delay = this.retryBaseDelayMs * Math.pow(2, attempt - 1);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+      let timeout;
+      try {
+        const url = `${this.baseUrl}${path}`;
+        const controller = new AbortController();
+        timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        const headers = {
+          "Authorization": `Bearer ${this.authToken}`,
+          "Content-Type": "application/json"
+        };
+        const response = await fetch(url, {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeout);
+        timeout = void 0;
+        if (response.ok) {
+          if (response.status === 204) return {};
+          return await response.json();
+        }
+        if (response.status === 429) {
+          const retryAfter = response.headers.get("retry-after");
+          let waitMs = this.retryBaseDelayMs * 4;
+          if (retryAfter) {
+            const parsed = parseInt(retryAfter, 10);
+            if (Number.isFinite(parsed) && parsed > 0) {
+              waitMs = parsed * 1e3;
+            }
+          }
+          const errorBody = await response.json().catch(() => ({ error: "rate_limited", code: "rate_limited" }));
+          lastRateLimitError = new HermesError(429, errorBody.code ?? "rate_limited", errorBody.error);
+          await new Promise((resolve) => setTimeout(resolve, waitMs));
+          continue;
+        }
+        if (response.status >= 400 && response.status < 500) {
+          const error = await response.json();
+          throw new HermesError(
+            response.status,
+            error.code ?? `http_${response.status}`,
+            error.error,
+            error.details
+          );
+        }
+        lastError = new Error(`HTTP ${response.status}`);
+        continue;
+      } catch (err) {
+        if (timeout !== void 0) clearTimeout(timeout);
+        if (err instanceof HermesError) throw err;
+        if (err instanceof DOMException && err.name === "AbortError") {
+          lastError = new Error(`request timed out after ${this.timeoutMs}ms`);
+          continue;
+        }
+        lastError = err;
+        continue;
+      }
+    }
+    if (lastRateLimitError) throw lastRateLimitError;
+    throw lastError ?? new Error("request failed after retries");
+  }
+};
+export {
+  HermesClient,
+  HermesError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @remnic/hermes-provider\n *\n * Typed HTTP client for the Remnic memory API.\n *\n * Usage:\n *   const client = new HermesClient({ baseUrl: \"http://127.0.0.1:4318\", authToken: \"secret\" });\n *   const health = await client.health();\n *   const memories = await client.recall(\"what did I work on last week?\");\n */\n\n// ---------------------------------------------------------------------------\n// Configuration\n// ---------------------------------------------------------------------------\n\nexport interface HermesClientOptions {\n  /** Base URL of the Engram HTTP server (e.g. \"http://127.0.0.1:4318\") */\n  baseUrl: string;\n  /** Bearer token for authentication */\n  authToken: string;\n  /** Default namespace for requests (optional) */\n  namespace?: string;\n  /** Default session key (optional) */\n  sessionKey?: string;\n  /** Max retries for server errors (default: 3) */\n  maxRetries?: number;\n  /** Base delay in ms between retries (default: 100) */\n  retryBaseDelayMs?: number;\n  /** Request timeout in ms (default: 5000) */\n  timeoutMs?: number;\n}\n\n// ---------------------------------------------------------------------------\n// Response types\n// ---------------------------------------------------------------------------\n\nexport interface EngramAccessHealthResponse {\n  ok: boolean;\n  memoryDir: string;\n  namespacesEnabled: boolean;\n  defaultNamespace: string;\n  searchBackend: string;\n  qmdEnabled: boolean;\n  nativeKnowledgeEnabled: boolean;\n  projectionAvailable: boolean;\n}\n\nexport interface EngramAccessRecallResponse {\n  context?: string;\n  results?: Array<{ id: string; content: string; score?: number; category?: string }>;\n  count?: number;\n  traceId?: string;\n  plannerMode?: string;\n  fallbackUsed?: boolean;\n  sourcesUsed?: string[];\n  budgetsApplied?: Record<string, unknown>;\n  latencyMs?: number;\n}\n\nexport interface EngramAccessObserveResponse {\n  accepted: number;\n  sessionKey: string;\n  namespace?: string;\n  lcmArchived?: boolean;\n  extractionQueued?: boolean;\n}\n\nexport interface EngramAccessWriteResponse {\n  memoryId?: string;\n  status: string;\n  dryRun?: boolean;\n  idempotencyReplay?: boolean;\n  path?: string;\n  duplicateOf?: string;\n  idempotencyKey?: string;\n}\n\nexport interface EngramAccessEntityListResponse {\n  entities: Array<{ name: string; type: string; factCount?: number }>;\n  total: number;\n}\n\nexport interface EngramAccessEntityGetResponse {\n  found: boolean;\n  entity?: { name: string; type: string; observations?: string[] };\n}\n\nexport interface EngramAccessMemoryBrowseResponse {\n  memories: Array<Record<string, unknown>>;\n  total: number;\n}\n\nexport interface EngramAccessMemoryGetResponse {\n  found: boolean;\n  memory?: Record<string, unknown>;\n}\n\nexport interface EngramAccessLcmSearchResponse {\n  query: string;\n  namespace?: string;\n  results: Array<{ sessionId?: string; content?: string; turnIndex?: number }>;\n  count: number;\n  lcmEnabled: boolean;\n}\n\nexport interface RecallOptions {\n  sessionKey?: string;\n  namespace?: string;\n  topK?: number;\n  mode?: \"auto\" | \"no_recall\" | \"minimal\" | \"full\" | \"graph_mode\";\n  includeDebug?: boolean;\n}\n\nexport interface ObserveOptions {\n  namespace?: string;\n  skipExtraction?: boolean;\n}\n\nexport interface MemoryStoreRequest {\n  content: string;\n  category?: string;\n  confidence?: number;\n  tags?: string[];\n  entityRef?: string;\n  ttl?: string;\n  sourceReason?: string;\n  sessionKey?: string;\n  namespace?: string;\n  idempotencyKey?: string;\n  dryRun?: boolean;\n  schemaVersion?: number;\n}\n\n// ---------------------------------------------------------------------------\n// Error types\n// ---------------------------------------------------------------------------\n\nexport class HermesError extends Error {\n  constructor(\n    readonly status: number,\n    readonly code: string,\n    message: string,\n    readonly details?: Array<{ field: string; message: string }>,\n  ) {\n    super(message);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Client\n// ---------------------------------------------------------------------------\n\nexport class HermesClient {\n  private readonly baseUrl: string;\n  private readonly authToken: string;\n  private readonly defaultNamespace?: string;\n  private readonly defaultSessionKey?: string;\n  private readonly maxRetries: number;\n  private readonly retryBaseDelayMs: number;\n  private readonly timeoutMs: number;\n\n  constructor(options: HermesClientOptions) {\n    this.baseUrl = options.baseUrl.endsWith(\"/\") ? options.baseUrl.slice(0, -1) : options.baseUrl;\n    this.authToken = options.authToken;\n    this.defaultNamespace = options.namespace;\n    this.defaultSessionKey = options.sessionKey;\n    this.maxRetries = options.maxRetries ?? 3;\n    this.retryBaseDelayMs = options.retryBaseDelayMs ?? 100;\n    this.timeoutMs = options.timeoutMs ?? 5000;\n  }\n\n  // -----------------------------------------------------------------------\n  // Core methods\n  // -----------------------------------------------------------------------\n\n  async health(): Promise<EngramAccessHealthResponse> {\n    return this.request<EngramAccessHealthResponse>(\"GET\", \"/engram/v1/health\");\n  }\n\n  async recall(query: string, options?: RecallOptions): Promise<EngramAccessRecallResponse> {\n    const body: Record<string, unknown> = {\n      query,\n    };\n    const sk = options?.sessionKey ?? this.defaultSessionKey;\n    if (sk) body.sessionKey = sk;\n    const ns = options?.namespace ?? this.defaultNamespace;\n    if (ns) body.namespace = ns;\n    if (options?.topK !== undefined) body.topK = options.topK;\n    if (options?.mode) body.mode = options.mode;\n    if (options?.includeDebug !== undefined) body.includeDebug = options.includeDebug;\n    return this.request<EngramAccessRecallResponse>(\"POST\", \"/engram/v1/recall\", body, { noRetry: true });\n  }\n\n  async observe(\n    sessionKey: string,\n    messages: Array<{ role: \"user\" | \"assistant\"; content: string }>,\n    options?: ObserveOptions,\n  ): Promise<EngramAccessObserveResponse> {\n    const body: Record<string, unknown> = {\n      sessionKey,\n      messages,\n      namespace: options?.namespace ?? this.defaultNamespace,\n      skipExtraction: options?.skipExtraction ?? false,\n    };\n    return this.request<EngramAccessObserveResponse>(\"POST\", \"/engram/v1/observe\", body, { noRetry: true });\n  }\n\n  async store(request: MemoryStoreRequest): Promise<EngramAccessWriteResponse> {\n    const body: Record<string, unknown> = {\n      ...request,\n      namespace: request.namespace ?? this.defaultNamespace,\n      sessionKey: request.sessionKey ?? this.defaultSessionKey,\n    };\n    return this.request<EngramAccessWriteResponse>(\"POST\", \"/engram/v1/memories\", body, { noRetry: true });\n  }\n\n  async submitSuggestion(request: MemoryStoreRequest): Promise<EngramAccessWriteResponse> {\n    const body: Record<string, unknown> = {\n      ...request,\n      namespace: request.namespace ?? this.defaultNamespace,\n      sessionKey: request.sessionKey ?? this.defaultSessionKey,\n    };\n    return this.request<EngramAccessWriteResponse>(\"POST\", \"/engram/v1/suggestions\", body, { noRetry: true });\n  }\n\n  // -----------------------------------------------------------------------\n  // Browse / read methods\n  // -----------------------------------------------------------------------\n\n  async getEntities(options?: {\n    namespace?: string;\n    query?: string;\n    limit?: number;\n    offset?: number;\n  }): Promise<EngramAccessEntityListResponse> {\n    const params: Record<string, unknown> = {\n      namespace: options?.namespace ?? this.defaultNamespace,\n    };\n    if (options?.query) params.q = options.query;\n    if (options?.limit !== undefined) params.limit = options.limit;\n    if (options?.offset !== undefined) params.offset = options.offset;\n    return this.request<EngramAccessEntityListResponse>(\n      \"GET\",\n      `/engram/v1/entities${this.queryString(params)}`,\n    );\n  }\n\n  async getEntity(name: string, options?: { namespace?: string }): Promise<EngramAccessEntityGetResponse> {\n    try {\n      return await this.request<EngramAccessEntityGetResponse>(\n        \"GET\",\n        `/engram/v1/entities/${encodeURIComponent(name)}${this.queryString({ namespace: options?.namespace ?? this.defaultNamespace })}`,\n      );\n    } catch (err) {\n      // 404 is a valid \"not found\" response for entity lookups\n      if (err instanceof HermesError && err.status === 404) {\n        return { found: false };\n      }\n      throw err;\n    }\n  }\n\n  async getMemories(options?: {\n    query?: string;\n    status?: string;\n    category?: string;\n    namespace?: string;\n    sort?: string;\n    limit?: number;\n    offset?: number;\n  }): Promise<EngramAccessMemoryBrowseResponse> {\n    const params: Record<string, unknown> = {\n      namespace: options?.namespace ?? this.defaultNamespace,\n    };\n    // The HTTP API uses `q` for the search query parameter\n    if (options?.query) params.q = options.query;\n    if (options?.status) params.status = options.status;\n    if (options?.category) params.category = options.category;\n    if (options?.sort) params.sort = options.sort;\n    if (options?.limit !== undefined) params.limit = options.limit;\n    if (options?.offset !== undefined) params.offset = options.offset;\n    return this.request<EngramAccessMemoryBrowseResponse>(\n      \"GET\",\n      `/engram/v1/memories${this.queryString(params)}`,\n    );\n  }\n\n  async getMemory(id: string, options?: { namespace?: string }): Promise<EngramAccessMemoryGetResponse> {\n    try {\n      return await this.request<EngramAccessMemoryGetResponse>(\n        \"GET\",\n        `/engram/v1/memories/${encodeURIComponent(id)}${this.queryString({ namespace: options?.namespace ?? this.defaultNamespace })}`,\n      );\n    } catch (err) {\n      // 404 is a valid \"not found\" response, not an error\n      if (err instanceof HermesError && err.status === 404) {\n        return { found: false };\n      }\n      throw err;\n    }\n  }\n\n  async lcmSearch(\n    query: string,\n    options?: { sessionKey?: string; namespace?: string; limit?: number },\n  ): Promise<EngramAccessLcmSearchResponse> {\n    const body: Record<string, unknown> = {\n      query,\n      sessionKey: options?.sessionKey ?? this.defaultSessionKey,\n      namespace: options?.namespace ?? this.defaultNamespace,\n      ...(options?.limit !== undefined ? { limit: options.limit } : {}),\n    };\n    return this.request<EngramAccessLcmSearchResponse>(\"POST\", \"/engram/v1/lcm/search\", body);\n  }\n\n  // -----------------------------------------------------------------------\n  // Internal helpers\n  // -----------------------------------------------------------------------\n\n  private queryString(params?: Record<string, unknown>): string {\n    if (!params) return \"\";\n    const parts: string[] = [];\n    for (const [key, value] of Object.entries(params)) {\n      if (value !== undefined && value !== null && value !== \"\") {\n        parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);\n      }\n    }\n    return parts.length > 0 ? `?${parts.join(\"&\")}` : \"\";\n  }\n\n  private async request<T>(method: string, path: string, body?: Record<string, unknown>, options?: { noRetry?: boolean }): Promise<T> {\n    // Skip retries for state-mutating writes to prevent duplicate side effects.\n    // Read-only POST endpoints (recall, lcm/search) are safe to retry.\n    const isMutating = options?.noRetry === true;\n    const maxAttempts = isMutating ? 1 : this.maxRetries + 1;\n    let lastError: Error | null = null;\n    let lastRateLimitError: HermesError | null = null;\n\n    for (let attempt = 0; attempt < maxAttempts; attempt++) {\n      if (attempt > 0) {\n        const delay = this.retryBaseDelayMs * Math.pow(2, attempt - 1);\n        await new Promise((resolve) => setTimeout(resolve, delay));\n      }\n\n      let timeout: ReturnType<typeof setTimeout> | undefined;\n      try {\n        const url = `${this.baseUrl}${path}`;\n        const controller = new AbortController();\n        timeout = setTimeout(() => controller.abort(), this.timeoutMs);\n\n        const headers: Record<string, string> = {\n          \"Authorization\": `Bearer ${this.authToken}`,\n          \"Content-Type\": \"application/json\",\n        };\n\n        const response = await fetch(url, {\n          method,\n          headers,\n          body: body ? JSON.stringify(body) : undefined,\n          signal: controller.signal,\n        });\n\n        clearTimeout(timeout);\n        timeout = undefined;\n\n        // Success responses\n        if (response.ok) {\n          if (response.status === 204) return {} as T;\n          return (await response.json()) as T;\n        }\n\n        // Rate-limited — back off and retry\n        if (response.status === 429) {\n          const retryAfter = response.headers.get(\"retry-after\");\n          let waitMs = this.retryBaseDelayMs * 4;\n          if (retryAfter) {\n            const parsed = parseInt(retryAfter, 10);\n            // Only use numeric seconds form; date-form Retry-After is ignored\n            // (isNaN catches NaN from date-form headers like \"Fri, 04 Apr 2026\")\n            if (Number.isFinite(parsed) && parsed > 0) {\n              waitMs = parsed * 1000;\n            }\n          }\n          const errorBody = await response.json().catch(() => ({ error: \"rate_limited\", code: \"rate_limited\" })) as { error: string; code?: string };\n          lastRateLimitError = new HermesError(429, errorBody.code ?? \"rate_limited\", errorBody.error);\n          await new Promise((resolve) => setTimeout(resolve, waitMs));\n          continue;\n        }\n\n        // Client errors — do not retry\n        if (response.status >= 400 && response.status < 500) {\n          const error = (await response.json()) as {\n            error: string;\n            code?: string;\n            details?: Array<{ field: string; message: string }>;\n          };\n          throw new HermesError(\n            response.status,\n            error.code ?? `http_${response.status}`,\n            error.error,\n            error.details,\n          );\n        }\n\n        // Server error — retry\n        lastError = new Error(`HTTP ${response.status}`);\n        continue;\n      } catch (err) {\n        if (timeout !== undefined) clearTimeout(timeout);\n        if (err instanceof HermesError) throw err;\n        if (err instanceof DOMException && err.name === \"AbortError\") {\n          lastError = new Error(`request timed out after ${this.timeoutMs}ms`);\n          continue;\n        }\n        lastError = err as Error;\n        continue;\n      }\n    }\n\n    // If we exhausted retries due to rate limiting, throw the preserved 429 error\n    if (lastRateLimitError) throw lastRateLimitError;\n    throw lastError ?? new Error(\"request failed after retries\");\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@remnic/hermes-provider",
+  "version": "1.0.0",
+  "description": "Typed HTTP client for the Remnic memory API",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joshuaswarren/remnic.git",
+    "directory": "packages/hermes-provider"
+  },
+  "keywords": ["remnic", "memory", "ai", "agent", "openclaw"]
+}