korely-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Korely
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# korely-memory
+
+The JavaScript / TypeScript SDK for [Korely Agents](https://korely.ai/agents) —
+memory for AI agents, with a typed bi-temporal knowledge graph behind every
+write. A thin, **zero-dependency** client over the Korely REST API (uses the
+native `fetch`). Same package name as the Python twin on
+[PyPI](https://pypi.org/project/korely-memory/).
+
+```bash
+npm install korely-memory
+```
+
+## Quickstart
+
+```ts
+import { Korely } from "korely-memory";
+
+const korely = new Korely({ apiKey: "kor_live_..." }); // or set KORELY_API_KEY
+
+// Remember something your agent learned about an end user
+await korely.add("Maria prefers email over Slack, and her renewal is in October.", {
+  user_id: "customer-4812",
+});
+
+// Later — even in a new session — pull a prompt-ready block back
+const ctx = await korely.getContext({
+  query: "how does Maria like to be contacted?",
+  user_id: "customer-4812",
+});
+console.log(ctx.context); // drop straight into your system prompt
+```
+
+That's the whole loop: `add` to remember, `getContext` (or `search`) to recall.
+Behind `add`, Korely extracts typed, bi-temporal facts and builds a graph — you
+just hand it text.
+
+## Methods
+
+Every method maps to one REST endpoint.
+
+| Method | Endpoint | |
+|---|---|---|
+| `add(content, opts?)` | `POST /v1/memories` | Write. `content` is a string or a list of chat messages. |
+| `search(query, opts?)` | `POST /v1/memories/search` | Hybrid search over memories. |
+| `getAll(opts?)` | `GET /v1/memories` | List a scope, newest first. |
+| `get(id)` | `GET /v1/memories/:id` | One memory, with its facts. |
+| `update(id, { content })` | `PATCH /v1/memories/:id` | Re-runs extraction. |
+| `delete(id)` | `DELETE /v1/memories/:id` | Forget one (audited). |
+| `deleteAll({ user_id })` | `DELETE /v1/users/:user_id/memories` | Forget everything for a user (GDPR). |
+| `history(id)` | `GET /v1/memories/:id/history` | A memory's timeline + the facts it produced. |
+| `users(opts?)` | `GET /v1/users` | Your end users, with counts. |
+| `getFacts(opts?)` | `GET /v1/facts` | Typed facts; `as_of` for point-in-time. |
+| `addFactTriple(s, p, o, opts?)` | `POST /v1/facts` | Write a fact directly (bi-temporal). |
+| `getProfile({ user_id, as_of? })` | `GET /v1/profile` | The assembled profile of one end user. |
+| `getContext({ query, user_id? })` | `GET /v1/context` | One call → a prompt-ready context block. |
+| `batch(memories)` | `POST /v1/batch` | Bulk import, for migrations. |
+| `batchStatus(jobId)` | `GET /v1/batch/:id` | Poll an import job. |
+
+## Bi-temporal facts (the moat)
+
+Every write extracts typed `(subject, predicate, object)` facts with validity in
+time. Ask what was true on a past date:
+
+```ts
+// What did we know about this user on March 1st?
+const past = await korely.getProfile({ user_id: "customer-4812", as_of: "2026-03-01" });
+
+// Write a fact directly, dated in the past
+await korely.addFactTriple("Marco", "works_at", "Acme GmbH", {
+  user_id: "customer-4812",
+  valid_from: "2026-06-01",
+});
+```
+
+## Errors
+
+Every error subclasses `KorelyError`, so one `catch` covers them all:
+
+```ts
+import { Korely, QuotaExceededError, AuthenticationError } from "korely-memory";
+
+try {
+  await korely.add("...", { user_id: "u" });
+} catch (e) {
+  if (e instanceof QuotaExceededError) {
+    console.log(`Rate limited — retry after ${e.retryAfter}s`);
+  } else if (e instanceof AuthenticationError) {
+    console.log("Bad or missing API key");
+  } else {
+    throw e;
+  }
+}
+```
+
+`AuthenticationError` (401) · `NamespaceForbiddenError` (403) · `NotFoundError`
+(404) · `StaleWriteError` (409) · `QuotaExceededError` (429, carries
+`retryAfter`) · `APIError` (everything else).
+
+## Configuration
+
+```ts
+new Korely({
+  apiKey: "kor_live_...",  // or the KORELY_API_KEY env var
+  region: "eu",             // EU only — data stored and processed in the EU
+  timeoutMs: 30000,
+});
+```
+
+Requires Node 18+ (native `fetch`), or any runtime with a global `fetch`. On
+older runtimes, pass one via `{ fetch }`.
+
+## Docs
+
+- [SDK reference](https://korely.ai/agents/docs/surfaces/sdk)
+- [REST API reference](https://korely.ai/agents/docs/api-reference)
+
+MIT © Korely

package/dist/index.cjs

@@ -0,0 +1,389 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APIError: () => APIError,
+  AuthenticationError: () => AuthenticationError,
+  Korely: () => Korely,
+  KorelyError: () => KorelyError,
+  NamespaceForbiddenError: () => NamespaceForbiddenError,
+  NotFoundError: () => NotFoundError,
+  QuotaExceededError: () => QuotaExceededError,
+  StaleWriteError: () => StaleWriteError,
+  VERSION: () => VERSION
+});
+module.exports = __toCommonJS(index_exports);
+
+// 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}`);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APIError,
+  AuthenticationError,
+  Korely,
+  KorelyError,
+  NamespaceForbiddenError,
+  NotFoundError,
+  QuotaExceededError,
+  StaleWriteError,
+  VERSION
+});