@memonest/sdk 0.0.12

package/README.md

@@ -0,0 +1,86 @@
+## @memonest/sdk
+
+A tiny TypeScript/JavaScript client for the Memonest API.
+It makes it easy to **store, search, and auto-extract memories about your users** with just a few lines of code.
+
+### Installation
+
+```bash
+npm install @memonest/sdk
+# or
+yarn add @memonest/sdk
+# or
+pnpm add @memonest/sdk
+```
+
+### Quick start
+
+```ts
+import MemoryClient from "@memonest/sdk";
+
+const client = new MemoryClient({
+  // If omitted, the client will fall back to process.env.MEMONEST_API_KEY (in Node)
+  apiKey: process.env.MEMONEST_API_KEY,
+});
+
+// Add a memory
+await client.add({
+  userId: "user_123",
+  content: "Meeting notes from Q1 planning",
+});
+
+// Find memories
+const result = await client.find({
+  userId: "user_123",
+  query: "planning notes",
+  // optional:
+  // limit: 10,
+  // relevanceThreshold: 0.7,
+});
+
+console.log(result); // { memories: [...] }
+```
+
+### API Overview
+
+The client exposes a **small, ergonomic surface** on top of the HTTP API:
+
+- **`new MemoryClient(options)`**
+  - `apiKey?: string` – Your Memonest API key. If omitted (Node), falls back to `process.env.MEMONEST_API_KEY` (and also supports `process.env.YOURAIMEMORY_API_KEY` for backward compatibility).
+  - `baseUrl?: string` – Override the API base URL (defaults to `https://api.getmemonest.xyz`).
+  - `fetchFn?: typeof fetch` – Custom fetch implementation (for tests, Node polyfills, etc.).
+
+- **High-level helpers**
+  - `client.add({ userId, content, metadata? })`
+    Store a single memory for a user.
+  - `client.find({ userId, query, limit?, relevanceThreshold? })`
+    Search for the most relevant memories for a user.
+  - `client.auto({ userId, messages, maxMemories?, importanceThreshold? })`
+    Send a conversation transcript and let the API extract and store memories automatically.
+  - `client.list({ userId, limit?, offset? })`
+    List recent memories for a user.
+  - `client.deleteMemory(memoryId)`
+    Delete a memory by its ID.
+
+- **Low-level access**
+  - `client.memories.auto(...)`
+  - `client.memories.search(...)`
+  - `client.memories.store(...)`
+  - `client.memories.list(...)`
+  - `client.memories.delete(...)`
+
+These map 1:1 to the underlying `/v1/memories` HTTP endpoints and accept the full typed request payloads from `@aimemory/shared`.
+
+### Why use Memonest?
+
+- **Long‑term memory for your AI apps**
+  Store user profile details, preferences, tasks, and episodic events so your AI can stay consistent over time.
+
+- **Smart retrieval**
+  Hybrid search (vectors + keywords), recency, importance, usage frequency, and memory type signals are combined to surface the most relevant memories.
+
+- **Automatic extraction**
+  Send raw conversation logs and let the API extract structured memories for you.
+
+- **Simple integration**
+  Just a few lines of code with `client.add` and `client.find` – no need to manage embeddings, indexes, or ranking logic yourself.

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+import { AutoMemorySchema, ListMemoriesSchema, SearchMemorySchema, StoreMemorySchema } from "@memonest/shared";
+import type { z } from "zod";
+export type AutoMemoryRequest = z.infer<typeof AutoMemorySchema>;
+export type SearchMemoryRequest = z.infer<typeof SearchMemorySchema>;
+export type StoreMemoryRequest = z.infer<typeof StoreMemorySchema>;
+export type ListMemoriesRequest = z.infer<typeof ListMemoriesSchema>;
+export interface MemoryClientOptions {
+    apiKey?: string;
+    /**
+     * Base URL of the Memonest API (no trailing slash).
+     * Defaults to https://api.getmemonest.xyz
+     */
+    baseUrl?: string;
+    /**
+     * Optional custom fetch implementation (for testing or environments without global fetch).
+     */
+    fetchFn?: typeof fetch;
+}
+export interface MemoryClientResponseError extends Error {
+    status: number;
+    body: unknown;
+}
+export interface AddMemoryParams {
+    userId: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AutoMemoryParams {
+    userId: string;
+    messages: {
+        role: "user" | "assistant" | "system";
+        content: string;
+    }[];
+    maxMemories?: number;
+    importanceThreshold?: number;
+}
+export interface FindMemoriesParams {
+    userId: string;
+    query: string;
+    limit?: number;
+    relevanceThreshold?: number;
+}
+export interface ListSimpleParams {
+    userId: string;
+    limit?: number;
+    offset?: number;
+}
+export declare class MemoryClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchFn;
+    constructor(options: MemoryClientOptions);
+    /**
+     * Access to memories-related operations.
+     */
+    readonly memories: {
+        auto: (req: AutoMemoryRequest) => Promise<any>;
+        search: (req: SearchMemoryRequest) => Promise<any>;
+        store: (req: StoreMemoryRequest) => Promise<any>;
+        list: (req: ListMemoriesRequest) => Promise<any>;
+        delete: (memoryId: string) => Promise<any>;
+    };
+    /**
+     * High-level convenience methods
+     */
+    /**
+     * Store a single memory for a user.
+     */
+    add(params: AddMemoryParams): Promise<any>;
+    /**
+     * Automatically extract and store memories from a conversation.
+     */
+    auto(params: AutoMemoryParams): Promise<any>;
+    /**
+     * Find relevant memories for a user.
+     */
+    find(params: FindMemoriesParams): Promise<any>;
+    /**
+     * List recent memories for a user.
+     */
+    list(params: ListSimpleParams): Promise<any>;
+    /**
+     * Delete a memory by id.
+     */
+    deleteMemory(memoryId: string): Promise<any>;
+    private postJson;
+    private getJson;
+    private delete;
+    private handleResponse;
+}
+export default MemoryClient;

package/dist/index.js

@@ -0,0 +1,130 @@
+export class MemoryClient {
+    constructor(options) {
+        /**
+         * Access to memories-related operations.
+         */
+        this.memories = {
+            auto: (req) => this.postJson("/v1/memories/auto", req),
+            search: (req) => this.postJson("/v1/memories/search", req),
+            store: (req) => this.postJson("/v1/memories", req),
+            list: (req) => this.getJson("/v1/memories", {
+                user_id: req.user_id,
+                limit: req.limit ?? 20,
+                offset: req.offset ?? 0,
+            }),
+            delete: (memoryId) => this.delete(`/v1/memories/${encodeURIComponent(memoryId)}`),
+        };
+        const processEnv = typeof globalThis !== "undefined" && globalThis.process?.env
+            ? globalThis.process.env
+            : undefined;
+        const envApiKey = processEnv?.MEMONEST_API_KEY ?? processEnv?.YOURAIMEMORY_API_KEY;
+        const apiKey = options.apiKey ?? envApiKey;
+        if (!apiKey) {
+            throw new Error("MemoryClient: apiKey is required (or set MEMONEST_API_KEY / YOURAIMEMORY_API_KEY)");
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = (options.baseUrl ?? "https://api.getmemonest.xyz").replace(/\/+$/, "");
+        this.fetchFn = options.fetchFn ?? fetch;
+    }
+    /**
+     * High-level convenience methods
+     */
+    /**
+     * Store a single memory for a user.
+     */
+    async add(params) {
+        const body = {
+            user_id: params.userId,
+            content: params.content,
+            metadata: params.metadata,
+        };
+        return this.memories.store(body);
+    }
+    /**
+     * Automatically extract and store memories from a conversation.
+     */
+    async auto(params) {
+        const body = {
+            user_id: params.userId,
+            messages: params.messages,
+            max_memories: params.maxMemories ?? 5,
+            importance_threshold: params.importanceThreshold ?? 0.5,
+        };
+        return this.memories.auto(body);
+    }
+    /**
+     * Find relevant memories for a user.
+     */
+    async find(params) {
+        const body = {
+            user_id: params.userId,
+            query: params.query,
+            limit: params.limit ?? 10,
+            relevance_threshold: params.relevanceThreshold ?? 0.7,
+        };
+        return this.memories.search(body);
+    }
+    /**
+     * List recent memories for a user.
+     */
+    async list(params) {
+        const req = {
+            user_id: params.userId,
+            limit: params.limit ?? 20,
+            offset: params.offset ?? 0,
+        };
+        return this.memories.list(req);
+    }
+    /**
+     * Delete a memory by id.
+     */
+    async deleteMemory(memoryId) {
+        return this.memories.delete(memoryId);
+    }
+    async postJson(path, body) {
+        const res = await this.fetchFn(this.baseUrl + path, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+        return this.handleResponse(res);
+    }
+    async getJson(path, query) {
+        const url = new URL(this.baseUrl + path);
+        for (const [key, value] of Object.entries(query)) {
+            url.searchParams.set(key, String(value));
+        }
+        const res = await this.fetchFn(url.toString(), {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+        });
+        return this.handleResponse(res);
+    }
+    async delete(path) {
+        const res = await this.fetchFn(this.baseUrl + path, {
+            method: "DELETE",
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+        });
+        return this.handleResponse(res);
+    }
+    async handleResponse(res) {
+        const contentType = res.headers.get("content-type") ?? "";
+        const isJson = contentType.includes("application/json");
+        const body = isJson ? await res.json().catch(() => undefined) : await res.text().catch(() => undefined);
+        if (!res.ok) {
+            const err = Object.assign(new Error(`Memonest API request failed with status ${res.status}${body && typeof body === "object" && "error" in body
+                ? `: ${body.error}`
+                : ""}`), { status: res.status, body });
+            throw err;
+        }
+        return body;
+    }
+}
+export default MemoryClient;

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@memonest/sdk",
+  "version": "0.0.12",
+  "private": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@memonest/shared": "file:../shared",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,211 @@
+import {
+    AutoMemorySchema,
+    ListMemoriesSchema,
+    SearchMemorySchema,
+    StoreMemorySchema,
+} from "@memonest/shared";
+import type { z } from "zod";
+
+export type AutoMemoryRequest = z.infer<typeof AutoMemorySchema>;
+export type SearchMemoryRequest = z.infer<typeof SearchMemorySchema>;
+export type StoreMemoryRequest = z.infer<typeof StoreMemorySchema>;
+export type ListMemoriesRequest = z.infer<typeof ListMemoriesSchema>;
+
+export interface MemoryClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  fetchFn?: typeof fetch;
+}
+
+export interface MemoryClientResponseError extends Error {
+  status: number;
+  body: unknown;
+}
+
+export interface AddMemoryParams {
+  userId: string;
+  content: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AutoMemoryParams {
+  userId: string;
+  messages: { role: "user" | "assistant" | "system"; content: string }[];
+  maxMemories?: number;
+  importanceThreshold?: number;
+}
+
+export interface FindMemoriesParams {
+  userId: string;
+  query: string;
+  limit?: number;
+  relevanceThreshold?: number;
+}
+
+export interface ListSimpleParams {
+  userId: string;
+  limit?: number;
+  offset?: number;
+}
+
+export class MemoryClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly fetchFn: typeof fetch;
+
+  constructor(options: MemoryClientOptions) {
+    const processEnv =
+      typeof globalThis !== "undefined" && (globalThis as any).process?.env
+        ? ((globalThis as any).process.env as Record<string, string | undefined>)
+        : undefined;
+
+    const envApiKey =
+      processEnv?.MEMONEST_API_KEY ?? processEnv?.YOURAIMEMORY_API_KEY;
+    const apiKey = options.apiKey ?? envApiKey;
+    if (!apiKey) {
+      throw new Error(
+        "MemoryClient: apiKey is required (or set MEMONEST_API_KEY / YOURAIMEMORY_API_KEY)"
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl ?? "https://api.getmemonest.xyz").replace(/\/+$/, "");
+    this.fetchFn = options.fetchFn ?? fetch;
+  }
+
+  /**
+   * Access to memories-related operations.
+   */
+  public readonly memories = {
+    auto: (req: AutoMemoryRequest) => this.postJson("/v1/memories/auto", req),
+    search: (req: SearchMemoryRequest) => this.postJson("/v1/memories/search", req),
+    store: (req: StoreMemoryRequest) => this.postJson("/v1/memories", req),
+    list: (req: ListMemoriesRequest) =>
+      this.getJson("/v1/memories", {
+        user_id: req.user_id,
+        limit: req.limit ?? 20,
+        offset: req.offset ?? 0,
+      }),
+    delete: (memoryId: string) => this.delete(`/v1/memories/${encodeURIComponent(memoryId)}`),
+  };
+
+  /**
+   * High-level convenience methods
+   */
+
+  /**
+   * Store a single memory for a user.
+   */
+  async add(params: AddMemoryParams): Promise<any> {
+    const body: StoreMemoryRequest = {
+      user_id: params.userId,
+      content: params.content,
+      metadata: params.metadata,
+    };
+    return this.memories.store(body);
+  }
+
+  /**
+   * Automatically extract and store memories from a conversation.
+   */
+  async auto(params: AutoMemoryParams): Promise<any> {
+    const body: AutoMemoryRequest = {
+      user_id: params.userId,
+      messages: params.messages,
+      max_memories: params.maxMemories ?? 5,
+      importance_threshold: params.importanceThreshold ?? 0.5,
+    };
+    return this.memories.auto(body);
+  }
+
+  /**
+   * Find relevant memories for a user.
+   */
+  async find(params: FindMemoriesParams): Promise<any> {
+    const body: SearchMemoryRequest = {
+      user_id: params.userId,
+      query: params.query,
+      limit: params.limit ?? 10,
+      relevance_threshold: params.relevanceThreshold ?? 0.7,
+    };
+    return this.memories.search(body);
+  }
+
+  /**
+   * List recent memories for a user.
+   */
+  async list(params: ListSimpleParams): Promise<any> {
+    const req: ListMemoriesRequest = {
+      user_id: params.userId,
+      limit: params.limit ?? 20,
+      offset: params.offset ?? 0,
+    };
+    return this.memories.list(req);
+  }
+
+  /**
+   * Delete a memory by id.
+   */
+  async deleteMemory(memoryId: string): Promise<any> {
+    return this.memories.delete(memoryId);
+  }
+
+  private async postJson(path: string, body: unknown): Promise<any> {
+    const res = await this.fetchFn(this.baseUrl + path, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify(body),
+    });
+    return this.handleResponse(res);
+  }
+
+  private async getJson(path: string, query: Record<string, string | number>): Promise<any> {
+    const url = new URL(this.baseUrl + path);
+    for (const [key, value] of Object.entries(query)) {
+      url.searchParams.set(key, String(value));
+    }
+    const res = await this.fetchFn(url.toString(), {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+    });
+    return this.handleResponse(res);
+  }
+
+  private async delete(path: string): Promise<any> {
+    const res = await this.fetchFn(this.baseUrl + path, {
+      method: "DELETE",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+    });
+    return this.handleResponse(res);
+  }
+
+  private async handleResponse(res: Response): Promise<any> {
+    const contentType = res.headers.get("content-type") ?? "";
+    const isJson = contentType.includes("application/json");
+    const body = isJson ? await res.json().catch(() => undefined) : await res.text().catch(() => undefined);
+
+    if (!res.ok) {
+      const err: MemoryClientResponseError = Object.assign(
+        new Error(
+          `Memonest API request failed with status ${res.status}${
+            body && typeof body === "object" && "error" in (body as any)
+              ? `: ${(body as any).error}`
+              : ""
+          }`
+        ),
+        { status: res.status, body }
+      );
+      throw err;
+    }
+
+    return body;
+  }
+}
+
+export default MemoryClient;

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": false,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"]
+}