@memorilabs/memori 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,194 @@
+[![Memori Labs](https://s3.us-east-1.amazonaws.com/images.memorilabs.ai/banner.png)](https://memorilabs.ai/)
+
+<p align="center">
+  <strong>The memory fabric for enterprise AI</strong>
+</p>
+
+<p align="center">
+  <i>Memori plugs into the software and infrastructure you already use. It is LLM and framework agnostic and seamlessly integrates into the architecture you've already designed.</i>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@memorilabs/memori">
+    <img src="https://img.shields.io/npm/v/@memorilabs/memori.svg" alt="NPM version">
+  </a>
+  <a href="https://www.npmjs.com/package/@memorilabs/memori">
+    <img src="https://img.shields.io/npm/dm/@memorilabs/memori.svg" alt="NPM Downloads">
+  </a>
+  <a href="https://opensource.org/license/apache-2-0">
+    <img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License">
+  </a>
+  <a href="https://discord.gg/abD4eGym6v">
+    <img src="https://img.shields.io/discord/1042405378304004156?logo=discord" alt="Discord">
+  </a>
+</p>
+
+---
+
+## Getting Started
+
+Install the Memori SDK and your preferred LLM client using your package manager of choice:
+
+```bash
+npm install @memorilabs/memori
+```
+
+_(Note: Memori currently supports `openai` and `@anthropic-ai/sdk` as peer dependencies)._
+
+## Quickstart Example
+
+```typescript
+import 'dotenv/config';
+import { OpenAI } from 'openai';
+import { Memori } from '@memorilabs/memori';
+
+// Environment check
+const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+if (!OPENAI_API_KEY) {
+  console.error('Error: OPENAI_API_KEY must be set in .env');
+  process.exit(1);
+}
+
+// 1. Initialize the LLM Client
+const client = new OpenAI({ apiKey: OPENAI_API_KEY });
+
+// 2. Initialize Memori and Register the Client
+const memori = new Memori().llm
+  .register(client)
+  .attribution('typescript-sdk-test-user', 'test-process-1');
+
+async function main() {
+  console.log('--- Step 1: Teaching the AI ---');
+  const factPrompt = 'My favorite color is blue and I live in Paris.';
+  console.log(`User: ${factPrompt}`);
+
+  // This call automatically triggers Persistence and Augmentation in the background.
+  const response1 = await client.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [{ role: 'user', content: factPrompt }],
+  });
+
+  console.log(`AI:   ${response1.choices[0].message.content}`);
+
+  console.log('\n(Waiting 5 seconds for backend processing...)\n');
+  await new Promise((resolve) => setTimeout(resolve, 5000));
+
+  console.log('--- Step 2: Testing Recall ---');
+  const questionPrompt = 'What is my favorite color?';
+  console.log(`User: ${questionPrompt}`);
+
+  // This call automatically triggers Recall, injecting the Paris/Blue facts into the prompt.
+  const response2 = await client.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [{ role: 'user', content: questionPrompt }],
+  });
+
+  console.log(`AI:   ${response2.choices[0].message.content}`);
+}
+
+main().catch(console.error);
+```
+
+## Key Features
+
+- **Zero-Latency Memory:** Background processing ensures your LLM calls are never slowed down.
+- **Advanced Augmentation:** Automatically extracts and structures facts, preferences, and relationships.
+- **Cloud-Hosted:** Fully managed infrastructure via the Memori Cloud API.
+- **LLM Agnostic:** Native support for the official OpenAI and Anthropic SDKs via interceptors.
+- **Automatic Prompt Injection:** Seamlessly fetches relevant memories and injects them into the system context.
+
+## Attribution
+
+To get the most out of Memori, you want to attribute your LLM interactions to an entity (think person, place or thing; like a user) and a process (think your agent, LLM interaction or program).
+
+If you do not provide any attribution, Memori cannot make memories for you.
+
+```typescript
+memori.attribution('user-123', 'my-app');
+```
+
+## Session Management
+
+Memori uses sessions to group your LLM interactions together. For example, if you have an agent that executes multiple steps you want those to be recorded in a single session.
+
+By default, Memori handles setting the session for you but you can start a new session or override the session by executing the following:
+
+```typescript
+memori.resetSession();
+```
+
+or
+
+```typescript
+const sessionId = memori.session.id;
+
+// ... Later ...
+
+memori.setSession(sessionId);
+```
+
+## Supported LLMs
+
+- Anthropic Claude (`@anthropic-ai/sdk`)
+- OpenAI (`openai`)
+- Gemini (`@google/genai`)
+
+## Memori Advanced Augmentation
+
+Memories are tracked at several different levels:
+
+- **entity**: think person, place, or thing; like a user
+- **process**: think your agent, LLM interaction or program
+- **session**: the current interactions between the entity, process and the LLM
+
+[Memori's Advanced Augmentation](https://github.com/MemoriLabs/Memori/blob/main/docs/advanced-augmentation.md) enhances memories at each of these levels with:
+
+- attributes
+- events
+- facts
+- people
+- preferences
+- relationships
+- rules
+- skills
+
+Memori knows who your user is, what tasks your agent handles and creates unparalleled context between the two. Augmentation occurs asynchronously in the background incurring no latency.
+
+By default, Memori Advanced Augmentation is available without an account but is rate limited. When you need increased limits, [sign up for Memori Advanced Augmentation](https://app.memorilabs.ai/signup).
+
+Memori Advanced Augmentation is always free for developers!
+
+Once you've obtained an API key, simply set the following environment variable:
+
+```bash
+export MEMORI_API_KEY=[api_key]
+```
+
+## Managing Your Quota
+
+You can check your quota and manage your account by logging in at [https://memorilabs.ai/](https://memorilabs.ai/). If you have reached your IP address quota, sign up and get an API key for increased limits.
+
+If your API key exceeds its quota limits we will email you and let you know.
+
+## Contributing
+
+We welcome contributions from the community! Please see our [Contributing Guidelines](https://github.com/MemoriLabs/Memori/blob/main/CONTRIBUTING.md) for details on:
+
+- Setting up your development environment
+- Code style and standards
+- Submitting pull requests
+- Reporting issues
+
+---
+
+## Support
+
+- **Documentation**: [https://memorilabs.ai/docs](https://memorilabs.ai/docs)
+- **Discord**: [https://discord.gg/abD4eGym6v](https://discord.gg/abD4eGym6v)
+- **Issues**: [GitHub Issues](https://github.com/MemoriLabs/Memori/issues)
+
+---
+
+## License
+
+Apache 2.0 - see [LICENSE](https://github.com/MemoriLabs/Memori/blob/main/LICENSE)

package/dist/core/config.d.ts

@@ -0,0 +1,42 @@
+export declare class Config {
+    /**
+     * The API Key used for authentication.
+     * Defaults to `MEMORI_API_KEY` environment variable.
+     */
+    apiKey: string | null;
+    /**
+     * The base URL for the Memori API.
+     * Automatically switches between production and staging based on `testMode`.
+     */
+    baseUrl: string;
+    /**
+     * Whether the SDK is running in test/staging mode.
+     * Defaults to `true` if `MEMORI_TEST_MODE` is set to '1'.
+     */
+    testMode: boolean;
+    /**
+     * The unique identifier for the end-user associated with the current memories.
+     */
+    entityId?: string;
+    /**
+     * The unique identifier for the specific process or workflow.
+     */
+    processId?: string;
+    /**
+     * The current conversation session ID.
+     * Included in all requests to track conversation history.
+     */
+    sessionId: string;
+    /**
+     * The minimum relevance score (0.0 to 1.0) required for a memory to be included in the context.
+     * Defaults to 0.1.
+     */
+    recallRelevanceThreshold: number;
+    /**
+     * Request timeout in milliseconds.
+     * Defaults to 5000ms (5 seconds).
+     */
+    timeout: number;
+    constructor();
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAYA,qBAAa,MAAM;IACjB;;;OAGG;IACI,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B;;;OAGG;IACI,OAAO,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACI,QAAQ,EAAE,OAAO,CAAC;IAEzB;;OAEG;IACI,QAAQ,CAAC,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACI,SAAS,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACI,SAAS,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACI,wBAAwB,EAAE,MAAM,CAAC;IAExC;;;OAGG;IACI,OAAO,EAAE,MAAM,CAAC;;CAuBxB"}

package/dist/core/config.js

@@ -0,0 +1,70 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Utility to safely retrieve environment variables across Node.js and other runtimes.
+ */
+function getEnv(key) {
+    if (typeof process !== 'undefined') {
+        return process.env[key];
+    }
+    return undefined;
+}
+export class Config {
+    /**
+     * The API Key used for authentication.
+     * Defaults to `MEMORI_API_KEY` environment variable.
+     */
+    apiKey;
+    /**
+     * The base URL for the Memori API.
+     * Automatically switches between production and staging based on `testMode`.
+     */
+    baseUrl;
+    /**
+     * Whether the SDK is running in test/staging mode.
+     * Defaults to `true` if `MEMORI_TEST_MODE` is set to '1'.
+     */
+    testMode;
+    /**
+     * The unique identifier for the end-user associated with the current memories.
+     */
+    entityId;
+    /**
+     * The unique identifier for the specific process or workflow.
+     */
+    processId;
+    /**
+     * The current conversation session ID.
+     * Included in all requests to track conversation history.
+     */
+    sessionId;
+    /**
+     * The minimum relevance score (0.0 to 1.0) required for a memory to be included in the context.
+     * Defaults to 0.1.
+     */
+    recallRelevanceThreshold;
+    /**
+     * Request timeout in milliseconds.
+     * Defaults to 5000ms (5 seconds).
+     */
+    timeout;
+    constructor() {
+        // 1. Environment and Base URL Logic
+        this.testMode = getEnv('MEMORI_TEST_MODE') === '1';
+        const envUrl = getEnv('MEMORI_API_URL_BASE');
+        if (envUrl) {
+            this.baseUrl = envUrl;
+        }
+        else {
+            this.baseUrl = this.testMode
+                ? 'https://staging-api.memorilabs.ai'
+                : 'https://api.memorilabs.ai';
+        }
+        // 2. Authentication
+        this.apiKey = getEnv('MEMORI_API_KEY') ?? null;
+        // 3. Session and Defaults
+        this.sessionId = randomUUID();
+        this.recallRelevanceThreshold = 0.1;
+        this.timeout = 5000;
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/core/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;GAEG;AACH,SAAS,MAAM,CAAC,GAAW;IACzB,IAAI,OAAO,OAAO,KAAK,WAAW,EAAE,CAAC;QACnC,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,OAAO,MAAM;IACjB;;;OAGG;IACI,MAAM,CAAgB;IAE7B;;;OAGG;IACI,OAAO,CAAS;IAEvB;;;OAGG;IACI,QAAQ,CAAU;IAEzB;;OAEG;IACI,QAAQ,CAAU;IAEzB;;OAEG;IACI,SAAS,CAAU;IAE1B;;;OAGG;IACI,SAAS,CAAS;IAEzB;;;OAGG;IACI,wBAAwB,CAAS;IAExC;;;OAGG;IACI,OAAO,CAAS;IAEvB;QACE,oCAAoC;QACpC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,kBAAkB,CAAC,KAAK,GAAG,CAAC;QAEnD,MAAM,MAAM,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;QAC7C,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,QAAQ;gBAC1B,CAAC,CAAC,mCAAmC;gBACrC,CAAC,CAAC,2BAA2B,CAAC;QAClC,CAAC;QAED,oBAAoB;QACpB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,gBAAgB,CAAC,IAAI,IAAI,CAAC;QAE/C,0BAA0B;QAC1B,IAAI,CAAC,SAAS,GAAG,UAAU,EAAE,CAAC;QAC9B,IAAI,CAAC,wBAAwB,GAAG,GAAG,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;CACF"}

package/dist/core/errors.d.ts

@@ -0,0 +1,32 @@
+export { UnsupportedLLMProviderError } from '@memorilabs/axon';
+/** Base class for all Memori SDK errors. */
+export declare class MemoriError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the Memori Cloud IP rate limit or account quota is exceeded. */
+export declare class QuotaExceededError extends MemoriError {
+    constructor(message?: string);
+}
+/** Thrown when the Memori Cloud API returns a 4xx or 5xx status code. */
+export declare class MemoriApiClientError extends MemoriError {
+    readonly statusCode: number;
+    readonly details?: unknown;
+    constructor(statusCode: number, message?: string, details?: unknown);
+}
+/** Thrown when the Memori Cloud API rejects a request due to validation errors (422). */
+export declare class MemoriApiValidationError extends MemoriApiClientError {
+    constructor(statusCode: number, message: string, details?: unknown);
+}
+/** Thrown when the Memori Cloud API explicitly rejects a request (433). */
+export declare class MemoriApiRequestRejectedError extends MemoriApiClientError {
+    constructor(statusCode: number, message: string, details?: unknown);
+}
+/** Thrown when a request requires an API key but none was found in the environment or config. */
+export declare class MissingMemoriApiKeyError extends MemoriError {
+    constructor(envVar?: string);
+}
+/** Thrown when a network request to the Memori API exceeds the configured timeout duration. */
+export declare class TimeoutError extends MemoriError {
+    constructor(timeout: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAE/D,4CAA4C;AAC5C,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAK5B;AAED,+EAA+E;AAC/E,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,OAAO,CAAC,EAAE,MAAM;CAO7B;AAED,yEAAyE;AACzE,qBAAa,oBAAqB,SAAQ,WAAW;IACnD,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEtB,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAMpE;AAED,yFAAyF;AACzF,qBAAa,wBAAyB,SAAQ,oBAAoB;gBACpD,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAInE;AAED,2EAA2E;AAC3E,qBAAa,6BAA8B,SAAQ,oBAAoB;gBACzD,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAInE;AAED,iGAAiG;AACjG,qBAAa,wBAAyB,SAAQ,WAAW;gBAC3C,MAAM,SAAmB;CAMtC;AAED,+FAA+F;AAC/F,qBAAa,YAAa,SAAQ,WAAW;gBAC/B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/core/errors.js

@@ -0,0 +1,57 @@
+export { UnsupportedLLMProviderError } from '@memorilabs/axon';
+/** Base class for all Memori SDK errors. */
+export class MemoriError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MemoriError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Thrown when the Memori Cloud IP rate limit or account quota is exceeded. */
+export class QuotaExceededError extends MemoriError {
+    constructor(message) {
+        super(message ||
+            'Your IP address is over quota; register for an API key now: https://app.memorilabs.ai/signup');
+        this.name = 'QuotaExceededError';
+    }
+}
+/** Thrown when the Memori Cloud API returns a 4xx or 5xx status code. */
+export class MemoriApiClientError extends MemoriError {
+    statusCode;
+    details;
+    constructor(statusCode, message, details) {
+        super(message || `Memori API request failed with status ${statusCode}`);
+        this.name = 'MemoriApiClientError';
+        this.statusCode = statusCode;
+        this.details = details;
+    }
+}
+/** Thrown when the Memori Cloud API rejects a request due to validation errors (422). */
+export class MemoriApiValidationError extends MemoriApiClientError {
+    constructor(statusCode, message, details) {
+        super(statusCode, message, details);
+        this.name = 'MemoriApiValidationError';
+    }
+}
+/** Thrown when the Memori Cloud API explicitly rejects a request (433). */
+export class MemoriApiRequestRejectedError extends MemoriApiClientError {
+    constructor(statusCode, message, details) {
+        super(statusCode, message, details);
+        this.name = 'MemoriApiRequestRejectedError';
+    }
+}
+/** Thrown when a request requires an API key but none was found in the environment or config. */
+export class MissingMemoriApiKeyError extends MemoriError {
+    constructor(envVar = 'MEMORI_API_KEY') {
+        super(`A ${envVar} is required to use the Memori cloud API. Sign up at https://app.memorilabs.ai/signup`);
+        this.name = 'MissingMemoriApiKeyError';
+    }
+}
+/** Thrown when a network request to the Memori API exceeds the configured timeout duration. */
+export class TimeoutError extends MemoriError {
+    constructor(timeout) {
+        super(`Request timed out after ${timeout}ms`);
+        this.name = 'TimeoutError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAE/D,4CAA4C;AAC5C,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IACjD,YAAY,OAAgB;QAC1B,KAAK,CACH,OAAO;YACL,8FAA8F,CACjG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,yEAAyE;AACzE,MAAM,OAAO,oBAAqB,SAAQ,WAAW;IACnC,UAAU,CAAS;IACnB,OAAO,CAAW;IAElC,YAAY,UAAkB,EAAE,OAAgB,EAAE,OAAiB;QACjE,KAAK,CAAC,OAAO,IAAI,yCAAyC,UAAU,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,yFAAyF;AACzF,MAAM,OAAO,wBAAyB,SAAQ,oBAAoB;IAChE,YAAY,UAAkB,EAAE,OAAe,EAAE,OAAiB;QAChE,KAAK,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,OAAO,6BAA8B,SAAQ,oBAAoB;IACrE,YAAY,UAAkB,EAAE,OAAe,EAAE,OAAiB;QAChE,KAAK,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED,iGAAiG;AACjG,MAAM,OAAO,wBAAyB,SAAQ,WAAW;IACvD,YAAY,MAAM,GAAG,gBAAgB;QACnC,KAAK,CACH,KAAK,MAAM,uFAAuF,CACnG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,+FAA+F;AAC/F,MAAM,OAAO,YAAa,SAAQ,WAAW;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,2BAA2B,OAAO,IAAI,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF"}

package/dist/core/network.d.ts

@@ -0,0 +1,24 @@
+import { Config } from './config.js';
+export declare enum ApiSubdomain {
+    DEFAULT = "api",
+    COLLECTOR = "collector"
+}
+export declare class Api {
+    private readonly config;
+    private readonly xApiKey;
+    private readonly baseUrl;
+    constructor(config: Config, subdomain?: ApiSubdomain);
+    private getHeaders;
+    /**
+     * Performs a fetch request with exponential backoff and timeout handling.
+     * Retries on network errors, timeouts, and 5xx server errors.
+     */
+    private request;
+    private executeAttempt;
+    private throwOnApiError;
+    get<T>(route: string): Promise<T>;
+    post<T>(route: string, body?: unknown): Promise<T>;
+    patch<T>(route: string, body?: unknown): Promise<T>;
+    delete<T>(route: string): Promise<T>;
+}
+//# sourceMappingURL=network.d.ts.map

package/dist/core/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/core/network.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AASrC,oBAAY,YAAY;IACtB,OAAO,QAAQ;IACf,SAAS,cAAc;CACxB;AAWD,qBAAa,GAAG;IACd,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,MAAM,EAAE,SAAS,GAAE,YAAmC;IAc1E,OAAO,CAAC,UAAU;IAalB;;;OAGG;YACW,OAAO;YA8CP,cAAc;YA4Bd,eAAe;IA8BtB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAIjC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIlD,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAInD,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CAG5C"}

package/dist/core/network.js

@@ -0,0 +1,136 @@
+import { MemoriApiClientError, MemoriApiRequestRejectedError, MemoriApiValidationError, QuotaExceededError, TimeoutError, } from './errors.js';
+export var ApiSubdomain;
+(function (ApiSubdomain) {
+    ApiSubdomain["DEFAULT"] = "api";
+    ApiSubdomain["COLLECTOR"] = "collector";
+})(ApiSubdomain || (ApiSubdomain = {}));
+const PUBLIC_PROD_KEY = '96a7ea3e-11c2-428c-b9ae-5a168363dc80';
+const PUBLIC_STAGING_KEY = 'c18b1022-7fe2-42af-ab01-b1f9139184f0';
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class Api {
+    config;
+    xApiKey;
+    baseUrl;
+    constructor(config, subdomain = ApiSubdomain.DEFAULT) {
+        this.config = config;
+        if (subdomain === ApiSubdomain.COLLECTOR) {
+            this.baseUrl = this.config.baseUrl
+                .replace('://api.', '://collector.')
+                .replace('://staging-api.', '://staging-collector.');
+        }
+        else {
+            this.baseUrl = this.config.baseUrl;
+        }
+        this.xApiKey = this.config.testMode ? PUBLIC_STAGING_KEY : PUBLIC_PROD_KEY;
+    }
+    getHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+            'X-Memori-API-Key': this.xApiKey,
+        };
+        if (this.config.apiKey) {
+            headers['Authorization'] = `Bearer ${this.config.apiKey}`;
+        }
+        return headers;
+    }
+    /**
+     * Performs a fetch request with exponential backoff and timeout handling.
+     * Retries on network errors, timeouts, and 5xx server errors.
+     */
+    async request(method, route, body, options = {}) {
+        const url = `${this.baseUrl}/v1/${route}`;
+        const { maxRetries = 5, ...fetchInit } = options;
+        // Prepare the RequestInit once
+        const init = {
+            method,
+            headers: this.getHeaders(),
+            body: body ? JSON.stringify(body) : undefined,
+            ...fetchInit,
+        };
+        let attempt = 0;
+        let lastError = null;
+        while (attempt <= maxRetries) {
+            try {
+                return await this.executeAttempt(url, init);
+            }
+            catch (err) {
+                lastError = err;
+                // Determine if we should retry
+                const isNetworkError = err instanceof TypeError;
+                const isServer5xx = err instanceof MemoriApiClientError && err.statusCode >= 500 && err.statusCode <= 599;
+                const isTimeout = err instanceof TimeoutError;
+                if ((isNetworkError || isServer5xx || isTimeout) && attempt < maxRetries) {
+                    const backoff = Math.pow(2, attempt) * 1000;
+                    await delay(backoff);
+                    attempt++;
+                    continue;
+                }
+                throw lastError;
+            }
+        }
+        throw lastError || new Error('Unknown network error');
+    }
+    async executeAttempt(url, init) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => {
+            controller.abort();
+        }, this.config.timeout);
+        try {
+            const response = await fetch(url, { ...init, signal: controller.signal });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                if (response.status === 204)
+                    return {};
+                return (await response.json());
+            }
+            await this.throwOnApiError(response);
+            throw new Error('Unreachable');
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            if (err.name === 'AbortError') {
+                throw new TimeoutError(this.config.timeout);
+            }
+            throw err;
+        }
+    }
+    async throwOnApiError(response) {
+        // Try to parse the error details safely
+        let errorData = {};
+        try {
+            errorData = (await response.json());
+        }
+        catch {
+            // ignore parsing error
+        }
+        const message = errorData.message || errorData.detail;
+        const status = response.status;
+        // Map status codes to errors
+        if (status === 429)
+            throw new QuotaExceededError(message);
+        if (status === 422) {
+            throw new MemoriApiValidationError(status, message || 'Memori API rejected the request (422 validation error).');
+        }
+        if (status === 433) {
+            throw new MemoriApiRequestRejectedError(status, message || 'The request was rejected (433).');
+        }
+        if (status >= 500)
+            throw new MemoriApiClientError(status, message);
+        if (status >= 400)
+            throw new MemoriApiClientError(status, message);
+        throw new MemoriApiClientError(status, `Unknown error ${status}`);
+    }
+    get(route) {
+        return this.request('GET', route);
+    }
+    post(route, body) {
+        return this.request('POST', route, body);
+    }
+    patch(route, body) {
+        return this.request('PATCH', route, body);
+    }
+    delete(route) {
+        return this.request('DELETE', route);
+    }
+}
+//# sourceMappingURL=network.js.map

package/dist/core/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../src/core/network.ts"],"names":[],"mappings":"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"}

package/dist/core/session.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Manages the conversation session lifecycle.
+ * Ensures consistent session IDs across requests to maintain conversation history.
+ */
+export declare class SessionManager {
+    private _id;
+    constructor();
+    /**
+     * The current active session UUID.
+     */
+    get id(): string;
+    /**
+     * Generates a brand new random UUID for the session.
+     * Use this to clear context and start fresh.
+     */
+    reset(): this;
+    /**
+     * Manually sets the session ID to a specific value.
+     * Useful for resuming a conversation from a database or frontend client.
+     *
+     * @param id - The UUID to reuse.
+     */
+    set(id: string): this;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/core/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,GAAG,CAAS;;IAMpB;;OAEG;IACH,IAAW,EAAE,IAAI,MAAM,CAEtB;IAED;;;OAGG;IACI,KAAK,IAAI,IAAI;IAKpB;;;;;OAKG;IACI,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CAI7B"}

package/dist/core/session.js

@@ -0,0 +1,36 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Manages the conversation session lifecycle.
+ * Ensures consistent session IDs across requests to maintain conversation history.
+ */
+export class SessionManager {
+    _id;
+    constructor() {
+        this._id = randomUUID();
+    }
+    /**
+     * The current active session UUID.
+     */
+    get id() {
+        return this._id;
+    }
+    /**
+     * Generates a brand new random UUID for the session.
+     * Use this to clear context and start fresh.
+     */
+    reset() {
+        this._id = randomUUID();
+        return this;
+    }
+    /**
+     * Manually sets the session ID to a specific value.
+     * Useful for resuming a conversation from a database or frontend client.
+     *
+     * @param id - The UUID to reuse.
+     */
+    set(id) {
+        this._id = id;
+        return this;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/core/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;GAGG;AACH,MAAM,OAAO,cAAc;IACjB,GAAG,CAAS;IAEpB;QACE,IAAI,CAAC,GAAG,GAAG,UAAU,EAAE,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,IAAW,EAAE;QACX,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED;;;OAGG;IACI,KAAK;QACV,IAAI,CAAC,GAAG,GAAG,UAAU,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACI,GAAG,CAAC,EAAU;QACnB,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}