korely-memory 0.1.0

package/dist/index.js

@@ -0,0 +1,354 @@
+// src/errors.ts
+var KorelyError = class extends Error {
+  constructor(message = "", opts = {}) {
+    super(message || opts.code || "Korely error");
+    this.name = "KorelyError";
+    this.status = opts.status;
+    this.code = opts.code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class _AuthenticationError extends KorelyError {
+  constructor(message = "", opts = {}) {
+    super(message, opts);
+    this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, _AuthenticationError.prototype);
+  }
+};
+var NamespaceForbiddenError = class _NamespaceForbiddenError extends KorelyError {
+  constructor(message = "", opts = {}) {
+    super(message, opts);
+    this.name = "NamespaceForbiddenError";
+    Object.setPrototypeOf(this, _NamespaceForbiddenError.prototype);
+  }
+};
+var NotFoundError = class _NotFoundError extends KorelyError {
+  constructor(message = "", opts = {}) {
+    super(message, opts);
+    this.name = "NotFoundError";
+    Object.setPrototypeOf(this, _NotFoundError.prototype);
+  }
+};
+var StaleWriteError = class _StaleWriteError extends KorelyError {
+  constructor(message = "", opts = {}) {
+    super(message, opts);
+    this.name = "StaleWriteError";
+    Object.setPrototypeOf(this, _StaleWriteError.prototype);
+  }
+};
+var QuotaExceededError = class _QuotaExceededError extends KorelyError {
+  constructor(message = "", opts = {}) {
+    super(message, opts);
+    this.name = "QuotaExceededError";
+    this.retryAfter = opts.retryAfter;
+    Object.setPrototypeOf(this, _QuotaExceededError.prototype);
+  }
+};
+var APIError = class _APIError extends KorelyError {
+  constructor(message = "", opts = {}) {
+    super(message, opts);
+    this.name = "APIError";
+    Object.setPrototypeOf(this, _APIError.prototype);
+  }
+};
+
+// src/client.ts
+var VERSION = "0.1.0";
+var REGIONS = { eu: "https://api.korely.ai" };
+function coerceContent(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    const parts = [];
+    for (const m of content) {
+      if (m && typeof m === "object") {
+        const role = String(m.role ?? "").trim();
+        const raw = m.content;
+        const body = raw == null ? "" : String(raw).trim();
+        if (role && body) parts.push(`${role}: ${body}`);
+        else if (body) parts.push(body);
+      } else {
+        const s = String(m).trim();
+        if (s) parts.push(s);
+      }
+    }
+    return parts.join("\n");
+  }
+  return String(content);
+}
+var Korely = class {
+  constructor(opts = {}) {
+    const envKey = typeof process !== "undefined" ? process.env?.KORELY_API_KEY : void 0;
+    const key = opts.apiKey ?? envKey;
+    if (!key) {
+      throw new KorelyError(
+        "No API key. Pass { apiKey: 'kor_live_...' } or set KORELY_API_KEY."
+      );
+    }
+    this.apiKey = key;
+    this.baseUrl = (opts.baseUrl ?? REGIONS[opts.region ?? "eu"] ?? REGIONS.eu).replace(/\/+$/, "");
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+    const f = opts.fetch ?? globalThis.fetch;
+    if (!f) {
+      throw new KorelyError(
+        "No fetch available. On Node < 18 pass a fetch implementation via { fetch }."
+      );
+    }
+    this.fetchImpl = f;
+  }
+  // ── transport ─────────────────────────────────────────────────────────────
+  async request(method, path, opts = {}) {
+    let url = this.baseUrl + path;
+    if (opts.params) {
+      const qs = new URLSearchParams();
+      for (const [k, v] of Object.entries(opts.params)) {
+        if (v !== void 0 && v !== null) qs.append(k, String(v));
+      }
+      const s = qs.toString();
+      if (s) url += "?" + s;
+    }
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: "application/json",
+      "X-Korely-Client": `korely-js/${VERSION}`
+    };
+    let body;
+    if (opts.body !== void 0) {
+      body = JSON.stringify(opts.body);
+      headers["Content-Type"] = "application/json";
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let resp;
+    try {
+      resp = await this.fetchImpl(url, {
+        method,
+        headers,
+        body,
+        signal: controller.signal
+      });
+    } catch (e) {
+      throw new KorelyError(`Connection error: ${e?.message ?? String(e)}`);
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await resp.text();
+    let parsed = {};
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = { message: text };
+      }
+    }
+    if (!resp.ok) {
+      this.raise(resp.status, parsed, resp.headers.get("retry-after"));
+    }
+    return parsed && typeof parsed === "object" ? parsed : {};
+  }
+  raise(status, body, retryAfter) {
+    const code = body?.code;
+    const msg = body?.message || code || `HTTP ${status}`;
+    if (status === 401) throw new AuthenticationError(msg, { status, code });
+    if (status === 403) throw new NamespaceForbiddenError(msg, { status, code });
+    if (status === 404) throw new NotFoundError(msg, { status, code });
+    if (status === 409) throw new StaleWriteError(msg, { status, code });
+    if (status === 429) {
+      const raw = retryAfter ?? body?.retry_after ?? body?._retry_after;
+      let ra;
+      if (raw != null) {
+        const n = parseInt(String(raw), 10);
+        ra = Number.isNaN(n) ? void 0 : n;
+      }
+      throw new QuotaExceededError(msg, { status, code, retryAfter: ra });
+    }
+    throw new APIError(msg, { status, code });
+  }
+  // ── memories ────────────────────────────────────────────────────────────
+  /**
+   * POST /v1/memories — store a memory; resolves to it with extracted facts.
+   * `content` is a string, or a list of chat messages (role/content), joined
+   * into one block before sending.
+   */
+  async add(content, opts = {}) {
+    const text = coerceContent(content);
+    if (!text.trim()) {
+      throw new KorelyError(
+        "content is empty \u2014 pass a non-blank string or messages with content."
+      );
+    }
+    return this.request("POST", "/v1/memories", {
+      body: {
+        content: text,
+        agent_id: opts.agent_id,
+        user_id: opts.user_id,
+        run_id: opts.run_id,
+        metadata: opts.metadata
+      }
+    });
+  }
+  /** POST /v1/memories/search — hybrid retrieval, ranked by score. */
+  async search(query, opts = {}) {
+    const body = await this.request("POST", "/v1/memories/search", {
+      body: {
+        query,
+        user_id: opts.user_id,
+        agent_id: opts.agent_id,
+        limit: opts.limit ?? 10
+      }
+    });
+    return body.results ?? [];
+  }
+  /** GET /v1/memories — list a scope, newest first. */
+  async getAll(opts = {}) {
+    return this.request("GET", "/v1/memories", {
+      params: {
+        user_id: opts.user_id,
+        agent_id: opts.agent_id,
+        limit: opts.limit ?? 50,
+        offset: opts.offset ?? 0
+      }
+    });
+  }
+  /** GET /v1/memories/:id — full content, metadata, extracted facts. */
+  async get(memoryId) {
+    return this.request("GET", `/v1/memories/${memoryId}`);
+  }
+  /**
+   * PATCH /v1/memories/:id — re-runs extraction. Pass `expected_updated_at`
+   * for optimistic concurrency (throws StaleWriteError instead of clobbering).
+   */
+  async update(memoryId, opts) {
+    return this.request("PATCH", `/v1/memories/${memoryId}`, {
+      body: {
+        content: opts.content,
+        expected_updated_at: opts.expected_updated_at
+      }
+    });
+  }
+  /** DELETE /v1/memories/:id — forget one memory (audited invalidation). */
+  async delete(memoryId) {
+    return this.request("DELETE", `/v1/memories/${memoryId}`);
+  }
+  /**
+   * DELETE /v1/users/:user_id/memories — forget every memory + fact for one
+   * end user in a single call.
+   */
+  async deleteAll(opts) {
+    return this.request(
+      "DELETE",
+      `/v1/users/${opts.user_id}/memories`
+    );
+  }
+  /**
+   * GET /v1/memories/:id/history — the lifecycle timeline of a memory:
+   * created / updated / deleted, plus every typed fact it produced.
+   */
+  async history(memoryId) {
+    return this.request("GET", `/v1/memories/${memoryId}/history`);
+  }
+  /**
+   * GET /v1/users — the end users you've stored data for (distinct user_id
+   * namespaces), each with active memory + fact counts and last-active time.
+   */
+  async users(opts = {}) {
+    return this.request("GET", "/v1/users", {
+      params: {
+        agent_id: opts.agent_id,
+        limit: opts.limit ?? 50,
+        offset: opts.offset ?? 0
+      }
+    });
+  }
+  // ── facts ─────────────────────────────────────────────────────────────────
+  /**
+   * GET /v1/facts — typed (subject, predicate, object) triples with bi-temporal
+   * validity. Pass `as_of` (ISO date) for a point-in-time query.
+   */
+  async getFacts(opts = {}) {
+    const params = {
+      subject: opts.subject,
+      entity: opts.entity,
+      predicate: opts.predicate,
+      predicate_family: opts.predicate_family,
+      as_of: opts.as_of,
+      user_id: opts.user_id,
+      agent_id: opts.agent_id,
+      limit: opts.limit ?? 50,
+      offset: opts.offset ?? 0
+    };
+    if (opts.include_invalidated) params.include_invalidated = "true";
+    const body = await this.request("GET", "/v1/facts", { params });
+    return body.facts ?? [];
+  }
+  /**
+   * POST /v1/facts — write a typed (subject, predicate, object) triple directly,
+   * skipping extraction. The server runs the contradiction check; the fact is
+   * bi-temporal (pass `valid_from` for a historical fact). Resolves to the
+   * written Fact, with `invalidated` listing any fact ids it superseded.
+   */
+  async addFactTriple(subject, predicate, object, opts = {}) {
+    return this.request("POST", "/v1/facts", {
+      body: {
+        subject,
+        predicate,
+        object,
+        user_id: opts.user_id,
+        agent_id: opts.agent_id,
+        run_id: opts.run_id,
+        subject_type: opts.subject_type ?? "unknown",
+        object_is_literal: opts.object_is_literal ?? false,
+        confidence: opts.confidence ?? 0.9,
+        valid_from: opts.valid_from
+      }
+    });
+  }
+  /**
+   * GET /v1/profile — the assembled profile of one end user: the active typed
+   * facts known about them, the end user's own facts first, grouped by family.
+   * Pass `as_of` (ISO date) for the point-in-time profile.
+   */
+  async getProfile(opts) {
+    return this.request("GET", "/v1/profile", {
+      params: {
+        user_id: opts.user_id,
+        agent_id: opts.agent_id,
+        as_of: opts.as_of
+      }
+    });
+  }
+  // ── context ─────────────────────────────────────────────────────────────
+  /**
+   * GET /v1/context — one call that assembles a prompt-ready context block
+   * (profile + relevant facts + memories) within a token budget.
+   */
+  async getContext(opts) {
+    return this.request("GET", "/v1/context", {
+      params: {
+        query: opts.query,
+        user_id: opts.user_id,
+        agent_id: opts.agent_id,
+        token_budget: opts.token_budget ?? 800
+      }
+    });
+  }
+  // ── batch ─────────────────────────────────────────────────────────────────
+  /** POST /v1/batch — bulk import (up to 500 memory objects), async. */
+  async batch(memories) {
+    return this.request("POST", "/v1/batch", { body: { memories } });
+  }
+  /** GET /v1/batch/:id — poll an import job. */
+  async batchStatus(jobId) {
+    return this.request("GET", `/v1/batch/${jobId}`);
+  }
+};
+export {
+  APIError,
+  AuthenticationError,
+  Korely,
+  KorelyError,
+  NamespaceForbiddenError,
+  NotFoundError,
+  QuotaExceededError,
+  StaleWriteError,
+  VERSION
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "korely-memory",
+  "version": "0.1.0",
+  "description": "JavaScript / TypeScript SDK for Korely Agents — memory for AI agents with bi-temporal typed facts.",
+  "keywords": [
+    "ai",
+    "agents",
+    "memory",
+    "llm",
+    "rag",
+    "knowledge-graph",
+    "typescript"
+  ],
+  "homepage": "https://korely.ai/agents",
+  "license": "MIT",
+  "author": "Korely <hello@korely.ai>",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "node --test",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  }
+}