vektori 0.1.0

package/README.md

@@ -0,0 +1,162 @@
+# Vektori TypeScript SDK
+
+> AI Memory that Actually Works — Graph-based memory for LLM applications.
+
+## Installation
+
+```bash
+npm install vektori
+# or
+yarn add vektori
+# or
+pnpm add vektori
+```
+
+## Quick Start
+
+```typescript
+import { Vektori } from 'vektori';
+
+// Initialize with your API key
+const memory = new Vektori({ apiKey: 'vk_your_key_here' });
+
+// Store conversation messages
+await memory.ingest({
+  userId: 'user_123',
+  messages: [
+    { role: 'user', content: "I'm allergic to peanuts" },
+    { role: 'assistant', content: 'I\'ll remember that!' },
+    { role: 'user', content: 'I also love Italian food' }
+  ]
+});
+
+// Retrieve relevant context
+const result = await memory.retrieve({
+  userId: 'user_123',
+  query: 'What are this user\'s dietary restrictions?'
+});
+
+console.log(result.context);
+// Output: "User is allergic to peanuts. User loves Italian food."
+```
+
+## Self-Hosted
+
+```typescript
+const memory = new Vektori({ url: 'http://localhost:8080' });
+```
+
+## API Reference
+
+### `new Vektori(options)`
+
+Create a new client instance.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | string | * | API key for Vektori Cloud |
+| `url` | string | * | URL for self-hosted instance |
+| `timeout` | number | No | Request timeout in ms (default: 30000) |
+
+\* Either `apiKey` or `url` must be provided.
+
+### `memory.ingest(options)`
+
+Store conversation messages.
+
+```typescript
+const result = await memory.ingest({
+  userId: 'user_123',
+  messages: [
+    { role: 'user', content: 'Hello!' },
+    { role: 'assistant', content: 'Hi there!' }
+  ],
+  sessionId: 'optional-session-id' // auto-generated if not provided
+});
+
+console.log(result.processed.facts); // Number of facts extracted
+```
+
+### `memory.retrieve(options)`
+
+Retrieve relevant context.
+
+```typescript
+const result = await memory.retrieve({
+  userId: 'user_123',
+  query: 'What does the user like?',
+  topK: 10,          // Max results (1-50)
+  includeRaw: false  // Include raw facts/insights
+});
+
+console.log(result.context);  // Synthesized context string
+console.log(result.latencyMs); // Request latency
+```
+
+### `memory.health()`
+
+Check API health.
+
+```typescript
+const status = await memory.health();
+console.log(status.version); // "1.0.0"
+```
+
+## Error Handling
+
+```typescript
+import { Vektori, VektoriError, AuthenticationError, ValidationError } from 'vektori';
+
+try {
+  const result = await memory.retrieve({ userId: 'u1', query: 'test' });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API key');
+  } else if (error instanceof ValidationError) {
+    console.error('Bad request:', error.details);
+  } else if (error instanceof VektoriError) {
+    console.error('API error:', error.message);
+  }
+}
+```
+
+## With OpenAI
+
+```typescript
+import { Vektori } from 'vektori';
+import OpenAI from 'openai';
+
+const memory = new Vektori({ apiKey: 'vk_...' });
+const openai = new OpenAI();
+
+async function chatWithMemory(userId: string, userMessage: string) {
+  // Get relevant context
+  const context = await memory.retrieve({ userId, query: userMessage });
+
+  // Generate response with context
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [
+      { role: 'system', content: `User context:\n${context.context}` },
+      { role: 'user', content: userMessage }
+    ]
+  });
+
+  const assistantMessage = response.choices[0].message.content!;
+
+  // Store for future context
+  await memory.ingest({
+    userId,
+    messages: [
+      { role: 'user', content: userMessage },
+      { role: 'assistant', content: assistantMessage }
+    ]
+  });
+
+  return assistantMessage;
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,189 @@
+/**
+ * Vektori TypeScript SDK Types
+ */
+interface Message {
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp?: string;
+}
+interface IngestOptions {
+    userId: string;
+    messages: Message[];
+    sessionId?: string;
+}
+interface RetrieveOptions {
+    userId: string;
+    query: string;
+    topK?: number;
+    includeRaw?: boolean;
+}
+interface ProcessedCounts {
+    messages: number;
+    sentences: number;
+    facts: number;
+    insights: number;
+    summary: boolean;
+}
+interface IngestResponse {
+    success: boolean;
+    sessionId: string;
+    processed: ProcessedCounts;
+    latencyMs: number;
+    errors?: string[];
+}
+interface RawItem {
+    id: string;
+    score: number;
+    text?: string;
+}
+interface RawResults {
+    facts: RawItem[];
+    insights: RawItem[];
+    sentences: RawItem[];
+}
+interface SourceMetadata {
+    sentences: number;
+    facts: number;
+    insights: number;
+    summaries: number;
+}
+interface RetrieveMetadata {
+    sources: SourceMetadata;
+    vectorLatencyMs?: number;
+    pprLatencyMs?: number;
+    synthesisUsed?: boolean;
+}
+interface RetrieveResponse {
+    context: string;
+    latencyMs: number;
+    metadata: RetrieveMetadata;
+    raw?: RawResults;
+}
+interface HealthResponse {
+    status: string;
+    version: string;
+    timestamp: string;
+}
+interface VektoriOptions {
+    apiKey?: string;
+    url?: string;
+    timeout?: number;
+}
+
+/**
+ * Vektori TypeScript SDK
+ *
+ * AI Memory that Actually Works — Graph-based memory for LLM applications.
+ *
+ * @example
+ * ```typescript
+ * import { Vektori } from 'vektori';
+ *
+ * const memory = new Vektori({ apiKey: 'vk_...' });
+ *
+ * // Store memories
+ * await memory.ingest({
+ *   userId: 'user_123',
+ *   messages: [
+ *     { role: 'user', content: 'I love pizza' },
+ *     { role: 'assistant', content: 'Noted!' }
+ *   ]
+ * });
+ *
+ * // Retrieve context
+ * const result = await memory.retrieve({
+ *   userId: 'user_123',
+ *   query: 'What food does this user like?'
+ * });
+ *
+ * console.log(result.context); // "User loves pizza"
+ * ```
+ */
+
+declare class VektoriError extends Error {
+    constructor(message: string);
+}
+declare class AuthenticationError extends VektoriError {
+    constructor(message: string);
+}
+declare class ValidationError extends VektoriError {
+    details?: {
+        path: string;
+        message: string;
+    }[];
+    constructor(message: string, details?: {
+        path: string;
+        message: string;
+    }[]);
+}
+declare class Vektori {
+    private apiKey?;
+    private baseUrl;
+    private timeout;
+    /**
+     * Create a new Vektori client.
+     *
+     * @param options - Client configuration
+     * @param options.apiKey - API key for Vektori Cloud
+     * @param options.url - URL for self-hosted instance
+     * @param options.timeout - Request timeout in milliseconds (default: 30000)
+     *
+     * @example
+     * // Cloud
+     * const memory = new Vektori({ apiKey: 'vk_...' });
+     *
+     * // Self-hosted
+     * const memory = new Vektori({ url: 'http://localhost:8080' });
+     */
+    constructor(options: VektoriOptions);
+    /**
+     * Store conversation messages in memory.
+     *
+     * @param options - Ingest options
+     * @param options.userId - Unique identifier for the user
+     * @param options.messages - Array of messages to ingest
+     * @param options.sessionId - Optional session ID (auto-generated if not provided)
+     * @returns Ingest response with processing stats
+     *
+     * @example
+     * const result = await memory.ingest({
+     *   userId: 'user_123',
+     *   messages: [
+     *     { role: 'user', content: "I'm allergic to peanuts" },
+     *     { role: 'assistant', content: 'Noted!' }
+     *   ]
+     * });
+     * console.log(`Extracted ${result.processed.facts} facts`);
+     */
+    ingest(options: IngestOptions): Promise<IngestResponse>;
+    /**
+     * Retrieve relevant context from memory.
+     *
+     * @param options - Retrieve options
+     * @param options.userId - User to retrieve memories for
+     * @param options.query - Search query
+     * @param options.topK - Max results (1-50, default: 10)
+     * @param options.includeRaw - Include raw facts/insights (default: false)
+     * @returns Retrieve response with synthesized context
+     *
+     * @example
+     * const result = await memory.retrieve({
+     *   userId: 'user_123',
+     *   query: 'What are the user allergies?'
+     * });
+     * console.log(result.context); // "User is allergic to peanuts"
+     */
+    retrieve(options: RetrieveOptions): Promise<RetrieveResponse>;
+    /**
+     * Check the health of the Vektori API.
+     *
+     * @returns Health status
+     */
+    health(): Promise<HealthResponse>;
+    /**
+     * Make an HTTP request to the API.
+     */
+    private request;
+}
+
+export { AuthenticationError, type HealthResponse, type IngestOptions, type IngestResponse, type Message, type ProcessedCounts, type RawItem, type RawResults, type RetrieveMetadata, type RetrieveOptions, type RetrieveResponse, type SourceMetadata, ValidationError, Vektori, VektoriError, type VektoriOptions };

package/dist/index.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Vektori TypeScript SDK Types
+ */
+interface Message {
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp?: string;
+}
+interface IngestOptions {
+    userId: string;
+    messages: Message[];
+    sessionId?: string;
+}
+interface RetrieveOptions {
+    userId: string;
+    query: string;
+    topK?: number;
+    includeRaw?: boolean;
+}
+interface ProcessedCounts {
+    messages: number;
+    sentences: number;
+    facts: number;
+    insights: number;
+    summary: boolean;
+}
+interface IngestResponse {
+    success: boolean;
+    sessionId: string;
+    processed: ProcessedCounts;
+    latencyMs: number;
+    errors?: string[];
+}
+interface RawItem {
+    id: string;
+    score: number;
+    text?: string;
+}
+interface RawResults {
+    facts: RawItem[];
+    insights: RawItem[];
+    sentences: RawItem[];
+}
+interface SourceMetadata {
+    sentences: number;
+    facts: number;
+    insights: number;
+    summaries: number;
+}
+interface RetrieveMetadata {
+    sources: SourceMetadata;
+    vectorLatencyMs?: number;
+    pprLatencyMs?: number;
+    synthesisUsed?: boolean;
+}
+interface RetrieveResponse {
+    context: string;
+    latencyMs: number;
+    metadata: RetrieveMetadata;
+    raw?: RawResults;
+}
+interface HealthResponse {
+    status: string;
+    version: string;
+    timestamp: string;
+}
+interface VektoriOptions {
+    apiKey?: string;
+    url?: string;
+    timeout?: number;
+}
+
+/**
+ * Vektori TypeScript SDK
+ *
+ * AI Memory that Actually Works — Graph-based memory for LLM applications.
+ *
+ * @example
+ * ```typescript
+ * import { Vektori } from 'vektori';
+ *
+ * const memory = new Vektori({ apiKey: 'vk_...' });
+ *
+ * // Store memories
+ * await memory.ingest({
+ *   userId: 'user_123',
+ *   messages: [
+ *     { role: 'user', content: 'I love pizza' },
+ *     { role: 'assistant', content: 'Noted!' }
+ *   ]
+ * });
+ *
+ * // Retrieve context
+ * const result = await memory.retrieve({
+ *   userId: 'user_123',
+ *   query: 'What food does this user like?'
+ * });
+ *
+ * console.log(result.context); // "User loves pizza"
+ * ```
+ */
+
+declare class VektoriError extends Error {
+    constructor(message: string);
+}
+declare class AuthenticationError extends VektoriError {
+    constructor(message: string);
+}
+declare class ValidationError extends VektoriError {
+    details?: {
+        path: string;
+        message: string;
+    }[];
+    constructor(message: string, details?: {
+        path: string;
+        message: string;
+    }[]);
+}
+declare class Vektori {
+    private apiKey?;
+    private baseUrl;
+    private timeout;
+    /**
+     * Create a new Vektori client.
+     *
+     * @param options - Client configuration
+     * @param options.apiKey - API key for Vektori Cloud
+     * @param options.url - URL for self-hosted instance
+     * @param options.timeout - Request timeout in milliseconds (default: 30000)
+     *
+     * @example
+     * // Cloud
+     * const memory = new Vektori({ apiKey: 'vk_...' });
+     *
+     * // Self-hosted
+     * const memory = new Vektori({ url: 'http://localhost:8080' });
+     */
+    constructor(options: VektoriOptions);
+    /**
+     * Store conversation messages in memory.
+     *
+     * @param options - Ingest options
+     * @param options.userId - Unique identifier for the user
+     * @param options.messages - Array of messages to ingest
+     * @param options.sessionId - Optional session ID (auto-generated if not provided)
+     * @returns Ingest response with processing stats
+     *
+     * @example
+     * const result = await memory.ingest({
+     *   userId: 'user_123',
+     *   messages: [
+     *     { role: 'user', content: "I'm allergic to peanuts" },
+     *     { role: 'assistant', content: 'Noted!' }
+     *   ]
+     * });
+     * console.log(`Extracted ${result.processed.facts} facts`);
+     */
+    ingest(options: IngestOptions): Promise<IngestResponse>;
+    /**
+     * Retrieve relevant context from memory.
+     *
+     * @param options - Retrieve options
+     * @param options.userId - User to retrieve memories for
+     * @param options.query - Search query
+     * @param options.topK - Max results (1-50, default: 10)
+     * @param options.includeRaw - Include raw facts/insights (default: false)
+     * @returns Retrieve response with synthesized context
+     *
+     * @example
+     * const result = await memory.retrieve({
+     *   userId: 'user_123',
+     *   query: 'What are the user allergies?'
+     * });
+     * console.log(result.context); // "User is allergic to peanuts"
+     */
+    retrieve(options: RetrieveOptions): Promise<RetrieveResponse>;
+    /**
+     * Check the health of the Vektori API.
+     *
+     * @returns Health status
+     */
+    health(): Promise<HealthResponse>;
+    /**
+     * Make an HTTP request to the API.
+     */
+    private request;
+}
+
+export { AuthenticationError, type HealthResponse, type IngestOptions, type IngestResponse, type Message, type ProcessedCounts, type RawItem, type RawResults, type RetrieveMetadata, type RetrieveOptions, type RetrieveResponse, type SourceMetadata, ValidationError, Vektori, VektoriError, type VektoriOptions };

package/dist/index.js

@@ -0,0 +1,226 @@
+"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, {
+  AuthenticationError: () => AuthenticationError,
+  ValidationError: () => ValidationError,
+  Vektori: () => Vektori,
+  VektoriError: () => VektoriError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var VektoriError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VektoriError";
+  }
+};
+var AuthenticationError = class extends VektoriError {
+  constructor(message) {
+    super(message);
+    this.name = "AuthenticationError";
+  }
+};
+var ValidationError = class extends VektoriError {
+  constructor(message, details) {
+    super(message);
+    this.name = "ValidationError";
+    this.details = details;
+  }
+};
+var DEFAULT_CLOUD_URL = "https://api.vektori.cloud";
+var DEFAULT_TIMEOUT = 3e4;
+var Vektori = class {
+  /**
+   * Create a new Vektori client.
+   *
+   * @param options - Client configuration
+   * @param options.apiKey - API key for Vektori Cloud
+   * @param options.url - URL for self-hosted instance
+   * @param options.timeout - Request timeout in milliseconds (default: 30000)
+   *
+   * @example
+   * // Cloud
+   * const memory = new Vektori({ apiKey: 'vk_...' });
+   *
+   * // Self-hosted
+   * const memory = new Vektori({ url: 'http://localhost:8080' });
+   */
+  constructor(options) {
+    if (!options.apiKey && !options.url) {
+      throw new VektoriError(
+        "Must provide either 'apiKey' (for Cloud) or 'url' (for self-hosted)"
+      );
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.url || DEFAULT_CLOUD_URL).replace(/\/$/, "");
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+  }
+  /**
+   * Store conversation messages in memory.
+   *
+   * @param options - Ingest options
+   * @param options.userId - Unique identifier for the user
+   * @param options.messages - Array of messages to ingest
+   * @param options.sessionId - Optional session ID (auto-generated if not provided)
+   * @returns Ingest response with processing stats
+   *
+   * @example
+   * const result = await memory.ingest({
+   *   userId: 'user_123',
+   *   messages: [
+   *     { role: 'user', content: "I'm allergic to peanuts" },
+   *     { role: 'assistant', content: 'Noted!' }
+   *   ]
+   * });
+   * console.log(`Extracted ${result.processed.facts} facts`);
+   */
+  async ingest(options) {
+    const payload = {
+      user_id: options.userId,
+      messages: options.messages,
+      session_id: options.sessionId
+    };
+    const response = await this.request("POST", "/v1/ingest", payload);
+    return {
+      success: response.success,
+      sessionId: response.session_id,
+      processed: {
+        messages: response.processed.messages,
+        sentences: response.processed.sentences,
+        facts: response.processed.facts,
+        insights: response.processed.insights,
+        summary: response.processed.summary
+      },
+      latencyMs: response.latency_ms,
+      errors: response.errors
+    };
+  }
+  /**
+   * Retrieve relevant context from memory.
+   *
+   * @param options - Retrieve options
+   * @param options.userId - User to retrieve memories for
+   * @param options.query - Search query
+   * @param options.topK - Max results (1-50, default: 10)
+   * @param options.includeRaw - Include raw facts/insights (default: false)
+   * @returns Retrieve response with synthesized context
+   *
+   * @example
+   * const result = await memory.retrieve({
+   *   userId: 'user_123',
+   *   query: 'What are the user allergies?'
+   * });
+   * console.log(result.context); // "User is allergic to peanuts"
+   */
+  async retrieve(options) {
+    const payload = {
+      user_id: options.userId,
+      query: options.query,
+      top_k: options.topK ?? 10,
+      include_raw: options.includeRaw ?? false
+    };
+    const response = await this.request("POST", "/v1/retrieve", payload);
+    const result = {
+      context: response.context,
+      latencyMs: response.latency_ms,
+      metadata: {
+        sources: response.metadata.sources,
+        vectorLatencyMs: response.metadata.vector_latency_ms,
+        pprLatencyMs: response.metadata.ppr_latency_ms,
+        synthesisUsed: response.metadata.synthesis_used
+      }
+    };
+    if (response.raw) {
+      result.raw = {
+        facts: response.raw.facts || [],
+        insights: response.raw.insights || [],
+        sentences: response.raw.sentences || []
+      };
+    }
+    return result;
+  }
+  /**
+   * Check the health of the Vektori API.
+   *
+   * @returns Health status
+   */
+  async health() {
+    return this.request("GET", "/v1/health");
+  }
+  /**
+   * Make an HTTP request to the API.
+   */
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorBody = await response.json();
+        if (response.status === 401) {
+          throw new AuthenticationError(errorBody.error || "Invalid API key");
+        }
+        if (response.status === 400) {
+          throw new ValidationError(
+            errorBody.error || "Validation error",
+            errorBody.details
+          );
+        }
+        throw new VektoriError(errorBody.error || `HTTP ${response.status}`);
+      }
+      return response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof VektoriError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new VektoriError(`Request timeout after ${this.timeout}ms`);
+        }
+        throw new VektoriError(`Request failed: ${error.message}`);
+      }
+      throw new VektoriError("Unknown error occurred");
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  ValidationError,
+  Vektori,
+  VektoriError
+});

package/dist/index.mjs

@@ -0,0 +1,196 @@
+// src/client.ts
+var VektoriError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VektoriError";
+  }
+};
+var AuthenticationError = class extends VektoriError {
+  constructor(message) {
+    super(message);
+    this.name = "AuthenticationError";
+  }
+};
+var ValidationError = class extends VektoriError {
+  constructor(message, details) {
+    super(message);
+    this.name = "ValidationError";
+    this.details = details;
+  }
+};
+var DEFAULT_CLOUD_URL = "https://api.vektori.cloud";
+var DEFAULT_TIMEOUT = 3e4;
+var Vektori = class {
+  /**
+   * Create a new Vektori client.
+   *
+   * @param options - Client configuration
+   * @param options.apiKey - API key for Vektori Cloud
+   * @param options.url - URL for self-hosted instance
+   * @param options.timeout - Request timeout in milliseconds (default: 30000)
+   *
+   * @example
+   * // Cloud
+   * const memory = new Vektori({ apiKey: 'vk_...' });
+   *
+   * // Self-hosted
+   * const memory = new Vektori({ url: 'http://localhost:8080' });
+   */
+  constructor(options) {
+    if (!options.apiKey && !options.url) {
+      throw new VektoriError(
+        "Must provide either 'apiKey' (for Cloud) or 'url' (for self-hosted)"
+      );
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.url || DEFAULT_CLOUD_URL).replace(/\/$/, "");
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+  }
+  /**
+   * Store conversation messages in memory.
+   *
+   * @param options - Ingest options
+   * @param options.userId - Unique identifier for the user
+   * @param options.messages - Array of messages to ingest
+   * @param options.sessionId - Optional session ID (auto-generated if not provided)
+   * @returns Ingest response with processing stats
+   *
+   * @example
+   * const result = await memory.ingest({
+   *   userId: 'user_123',
+   *   messages: [
+   *     { role: 'user', content: "I'm allergic to peanuts" },
+   *     { role: 'assistant', content: 'Noted!' }
+   *   ]
+   * });
+   * console.log(`Extracted ${result.processed.facts} facts`);
+   */
+  async ingest(options) {
+    const payload = {
+      user_id: options.userId,
+      messages: options.messages,
+      session_id: options.sessionId
+    };
+    const response = await this.request("POST", "/v1/ingest", payload);
+    return {
+      success: response.success,
+      sessionId: response.session_id,
+      processed: {
+        messages: response.processed.messages,
+        sentences: response.processed.sentences,
+        facts: response.processed.facts,
+        insights: response.processed.insights,
+        summary: response.processed.summary
+      },
+      latencyMs: response.latency_ms,
+      errors: response.errors
+    };
+  }
+  /**
+   * Retrieve relevant context from memory.
+   *
+   * @param options - Retrieve options
+   * @param options.userId - User to retrieve memories for
+   * @param options.query - Search query
+   * @param options.topK - Max results (1-50, default: 10)
+   * @param options.includeRaw - Include raw facts/insights (default: false)
+   * @returns Retrieve response with synthesized context
+   *
+   * @example
+   * const result = await memory.retrieve({
+   *   userId: 'user_123',
+   *   query: 'What are the user allergies?'
+   * });
+   * console.log(result.context); // "User is allergic to peanuts"
+   */
+  async retrieve(options) {
+    const payload = {
+      user_id: options.userId,
+      query: options.query,
+      top_k: options.topK ?? 10,
+      include_raw: options.includeRaw ?? false
+    };
+    const response = await this.request("POST", "/v1/retrieve", payload);
+    const result = {
+      context: response.context,
+      latencyMs: response.latency_ms,
+      metadata: {
+        sources: response.metadata.sources,
+        vectorLatencyMs: response.metadata.vector_latency_ms,
+        pprLatencyMs: response.metadata.ppr_latency_ms,
+        synthesisUsed: response.metadata.synthesis_used
+      }
+    };
+    if (response.raw) {
+      result.raw = {
+        facts: response.raw.facts || [],
+        insights: response.raw.insights || [],
+        sentences: response.raw.sentences || []
+      };
+    }
+    return result;
+  }
+  /**
+   * Check the health of the Vektori API.
+   *
+   * @returns Health status
+   */
+  async health() {
+    return this.request("GET", "/v1/health");
+  }
+  /**
+   * Make an HTTP request to the API.
+   */
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorBody = await response.json();
+        if (response.status === 401) {
+          throw new AuthenticationError(errorBody.error || "Invalid API key");
+        }
+        if (response.status === 400) {
+          throw new ValidationError(
+            errorBody.error || "Validation error",
+            errorBody.details
+          );
+        }
+        throw new VektoriError(errorBody.error || `HTTP ${response.status}`);
+      }
+      return response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof VektoriError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new VektoriError(`Request timeout after ${this.timeout}ms`);
+        }
+        throw new VektoriError(`Request failed: ${error.message}`);
+      }
+      throw new VektoriError("Unknown error occurred");
+    }
+  }
+};
+export {
+  AuthenticationError,
+  ValidationError,
+  Vektori,
+  VektoriError
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "vektori",
+    "version": "0.1.0",
+    "description": "AI Memory that Actually Works — TypeScript SDK for Vektori",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsup src/index.ts --format cjs,esm --dts",
+        "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+        "lint": "eslint src/",
+        "test": "vitest run",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "ai",
+        "memory",
+        "llm",
+        "rag",
+        "vector",
+        "graph",
+        "context",
+        "personalization"
+    ],
+    "author": "Vektori AI <hello@vektori.cloud>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/vektori-ai/vektori.git"
+    },
+    "homepage": "https://vektori.cloud",
+    "bugs": {
+        "url": "https://github.com/vektori-ai/vektori/issues"
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "tsup": "^8.0.0",
+        "typescript": "^5.0.0",
+        "vitest": "^1.0.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}