@lumi0/sdk 0.0.3 → 0.0.4

package/README.md

@@ -1,21 +1,52 @@
 # Lumi0 TypeScript SDK
 
-The official TypeScript SDK for storing, retrieving, and compressing persistent
-AI memory with Lumi0.
+The official TypeScript SDK for [Lumi0](https://lumi0.com), an AI infrastructure platform for persistent memory and context compression.
+
+Use Lumi0 to give AI applications long-term memory: store information about users, retrieve relevant context with semantic search, manage memory versions, batch-write memories, forget stored information, and compress large contexts before sending them to an LLM.
+
+## Features
+
+* Persistent AI memory
+* Semantic memory search
+* Memory versioning
+* Batch memory storage
+* Memory deduplication
+* Context compression
+* Fixed and adaptive compression modes
+* TypeScript-first API
+* Bun and Node.js compatible
+* Configurable API URL and request timeout
 
 ## Installation
 
+### Bun
+
 ```bash
 bun add @lumi0/sdk
 ```
 
+### npm
+
 ```bash
 npm install @lumi0/sdk
 ```
 
-## Quick start
+## Requirements
+
+* Node.js 18+ or Bun
+* A Lumi0 API key
+
+Set your API key as an environment variable:
+
+```bash
+LUMI0_API_KEY=your_api_key
+```
 
-Create a client with a Lumi0 API key:
+Never expose your Lumi0 API key in browser-side code. Keep it on your server or in a trusted backend environment.
+
+## Quick Start
+
+Create a Lumi0 client:
 
 ```ts
 import { Lumi0 } from "@lumi0/sdk";
@@ -25,26 +56,63 @@ const client = new Lumi0({
 });
 ```
 
-Store a memory, then search for relevant context:
+### Store a memory
+
+Store information associated with an identifier:
 
 ```ts
 await client.store({
 	id: "user_123",
 	content: "The user prefers concise TypeScript examples.",
 });
+```
+
+### Search memories
 
+Retrieve memories that are semantically relevant to a query:
+
+```ts
 const memories = await client.search({
 	id: "user_123",
 	query: "What coding examples does the user prefer?",
 	limit: 5,
 });
+
+console.log(memories);
+```
+
+A common AI application flow looks like:
+
+```text
+User
+  ↓
+Your AI Application
+  ↓
+Lumi0 Memory
+  ↓
+Semantic Search
+  ↓
+Relevant Context
+  ↓
+LLM
+  ↓
+Response
 ```
 
-## API
+## API Reference
+
+### `store()`
+
+Stores a single memory for an identifier.
 
-### `store`
+```ts
+await client.store({
+	id: "user_123",
+	content: "The user uses Bun and TypeScript.",
+});
+```
 
-Stores one memory for an identifier.
+You can optionally configure deduplication:
 
 ```ts
 await client.store({
@@ -54,9 +122,11 @@ await client.store({
 });
 ```
 
-### `batch`
+`dedupeThreshold` controls how similar an existing memory can be before Lumi0 considers the new memory a duplicate.
+
+### `batch()`
 
-Stores multiple memories in one request.
+Stores multiple memories in a single request.
 
 ```ts
 await client.batch([
@@ -68,12 +138,37 @@ await client.batch([
 		id: "user_123",
 		content: "The user prefers practical implementation details.",
 	},
+	{
+		id: "user_123",
+		content: "The user uses Bun for backend services.",
+	},
 ]);
 ```
 
-### `search`
+Batching is useful when your application needs to save multiple pieces of context at once.
 
-Searches memories semantically.
+For example, after a conversation:
+
+```ts
+await client.batch([
+	{
+		id: "user_123",
+		content: "The user is building an AI application.",
+	},
+	{
+		id: "user_123",
+		content: "The user prefers TypeScript.",
+	},
+	{
+		id: "user_123",
+		content: "The user uses Bun for backend development.",
+	},
+]);
+```
+
+### `search()`
+
+Searches stored memories semantically.
 
 ```ts
 const memories = await client.search({
@@ -85,9 +180,31 @@ const memories = await client.search({
 });
 ```
 
-### `get`
+You can use `limit` to control the maximum number of memories returned.
 
-Retrieves a memory by identifier. Pass `version` to retrieve a specific version.
+`minSimilarity` can be used to filter out results below a similarity threshold.
+
+You can also specify a memory type:
+
+```ts
+const memories = await client.search({
+	id: "user_123",
+	query: "What does the user know about this project?",
+	memoryType: "semantic",
+});
+```
+
+### `get()`
+
+Retrieves a memory by its identifier.
+
+```ts
+const memory = await client.get({
+	id: "memory_123",
+});
+```
+
+To retrieve a specific version:
 
 ```ts
 const memory = await client.get({
@@ -96,19 +213,24 @@ const memory = await client.get({
 });
 ```
 
-### `forget`
+This is useful when your application needs to inspect a particular historical version of a memory.
+
+### `forget()`
 
-Deletes a memory for a user.
+Deletes a stored memory.
 
 ```ts
 await client.forget({
-	id: "memory_123"
+	id: "memory_123",
 });
 ```
 
-### `compress`
 
-Reduces context while retaining information relevant to a query.
+### `compress()`
+
+Compresses context while attempting to retain information that is relevant to a query.
+
+This is useful before sending large context windows to an LLM.
 
 ```ts
 const result = await client.compress({
@@ -122,12 +244,124 @@ console.log(result.data.compressedText);
 console.log(`${result.data.tokensSaved} tokens saved`);
 ```
 
-Use `"fixed"` mode with `budgetRatio` to target a specific retained-context
-ratio. Use `"adaptive"` mode to let Lumi0 determine the appropriate amount of
-context to retain for the query.
+The returned data can be used as the context for your LLM request:
+
+```ts
+const result = await client.compress({
+	content: JSON.stringify(memories),
+	query: "What is the user's preferred backend stack?",
+	mode: "adaptive",
+	budgetRatio: 0.5,
+});
+
+const context = result.data.compressedText;
+
+// Pass `context` to your LLM.
+```
+
+#### Compression modes
+
+Lumi0 supports two compression modes:
+
+**Adaptive**
+
+```ts
+await client.compress({
+	content,
+	query,
+	mode: "adaptive",
+	budgetRatio: 0.5,
+});
+```
+
+Adaptive compression allows Lumi0 to determine how much context should be retained based on the query and content.
+
+**Fixed**
+
+```ts
+await client.compress({
+	content,
+	query,
+	mode: "fixed",
+	budgetRatio: 0.5,
+});
+```
+
+Fixed compression uses `budgetRatio` to target a specific retained-context ratio.
+
+For example, a `budgetRatio` of `0.5` targets approximately half of the original context budget.
+
+## Building an AI Memory Loop
+
+A typical application can combine `store()` and `search()`:
+
+```ts
+import { Lumi0 } from "@lumi0/sdk";
+
+const client = new Lumi0({
+	apiKey: process.env.LUMI0_API_KEY!,
+});
+
+// Save information learned from the conversation.
+await client.store({
+	id: "user_123",
+	content: "The user prefers concise answers.",
+});
+
+// Retrieve relevant memories before generating a response.
+const memories = await client.search({
+	id: "user_123",
+	query: "How should I respond to this user?",
+	limit: 5,
+});
+```
+
+You can then inject the retrieved memories into your LLM context.
+
+## Memory + Compression
+
+For applications with large memory collections, you can combine semantic retrieval with compression:
+
+```ts
+const memories = await client.search({
+	id: "user_123",
+	query: "What does the user prefer when writing code?",
+	limit: 20,
+	minSimilarity: 0.7,
+});
+
+const compressed = await client.compress({
+	content: JSON.stringify(memories),
+	query: "What does the user prefer when writing code?",
+	mode: "adaptive",
+	budgetRatio: 0.5,
+});
+
+const context = compressed.data.compressedText;
+
+console.log(context);
+```
+
+This creates a pipeline:
+
+```text
+Stored Memories
+      ↓
+Semantic Search
+      ↓
+Relevant Memories
+      ↓
+Context Compression
+      ↓
+Compressed Context
+      ↓
+LLM
+```
 
 ## Configuration
 
+The client accepts configuration options:
+
 ```ts
 const client = new Lumi0({
 	apiKey: process.env.LUMI0_API_KEY!,
@@ -136,11 +370,290 @@ const client = new Lumi0({
 });
 ```
 
-`baseUrl` defaults to `https://api.lumi0.com/api/v1` and `timeout` defaults to
-30 seconds.
+### `apiKey`
+
+Your Lumi0 API key.
+
+```ts
+apiKey: process.env.LUMI0_API_KEY!
+```
+
+### `baseUrl`
+
+The Lumi0 API endpoint.
+
+Default:
+
+```text
+https://api.lumi0.com/api/v1
+```
+
+You can override it:
+
+```ts
+const client = new Lumi0({
+	apiKey: process.env.LUMI0_API_KEY!,
+	baseUrl: "https://api.lumi0.com/api/v1",
+});
+```
+
+This can be useful when working with a different API environment.
+
+### `timeout`
+
+Maximum time, in milliseconds, that the SDK waits for an HTTP request.
+
+Default:
+
+```ts
+30_000
+```
+
+Example:
+
+```ts
+const client = new Lumi0({
+	apiKey: process.env.LUMI0_API_KEY!,
+	timeout: 60_000,
+});
+```
+
+## Environment Variables
+
+A typical `.env` file:
+
+```env
+LUMI0_API_KEY=your_api_key
+```
+
+Then:
+
+```ts
+import { Lumi0 } from "@lumi0/sdk";
+
+const client = new Lumi0({
+	apiKey: process.env.LUMI0_API_KEY!,
+});
+```
+
+Do not commit your `.env` file or API keys to source control.
+
+## Error Handling
+
+SDK requests reject with an `Error` when Lumi0 returns a non-success HTTP status.
+
+Use `try/catch` around SDK operations:
+
+```ts
+try {
+	const memories = await client.search({
+		id: "user_123",
+		query: "What does the user prefer?",
+		limit: 5,
+	});
+
+	console.log(memories);
+} catch (error) {
+	console.error("Lumi0 request failed:", error);
+}
+```
+
+The error message includes the HTTP status and the API-provided error message when available.
+
+For production applications, you should handle failures explicitly rather than assuming every memory operation succeeds.
+
+## Server-Side Usage
+
+The Lumi0 API key should be kept private.
+
+Recommended:
+
+```ts
+// Server-side code
+const client = new Lumi0({
+	apiKey: process.env.LUMI0_API_KEY!,
+});
+```
+
+Avoid putting your API key directly into client-side applications:
+
+```ts
+// Don't expose your secret API key in browser code.
+const client = new Lumi0({
+	apiKey: "your-secret-api-key",
+});
+```
+
+For a Next.js application, use Lumi0 from server-side code such as API routes, Route Handlers, Server Actions, or your backend.
+
+## Example: User Memory
+
+A simple chat application can save user preferences:
+
+```ts
+await client.store({
+	id: "user_123",
+	content: "The user prefers concise responses.",
+});
+
+await client.store({
+	id: "user_123",
+	content: "The user prefers TypeScript examples.",
+});
+
+await client.store({
+	id: "user_123",
+	content: "The user uses Bun.",
+});
+```
+
+Later, retrieve the relevant information:
+
+```ts
+const memories = await client.search({
+	id: "user_123",
+	query: "What should I know about this user's coding preferences?",
+	limit: 10,
+});
+```
+
+## Example: Conversation Memory
+
+You can store useful information extracted from a conversation:
+
+```ts
+await client.batch([
+	{
+		id: "user_123",
+		content: "The user is building a SaaS application.",
+	},
+	{
+		id: "user_123",
+		content: "The user uses TypeScript for backend development.",
+	},
+	{
+		id: "user_123",
+		content: "The user prefers concise technical explanations.",
+	},
+]);
+```
+
+Then retrieve only the information relevant to a new request:
+
+```ts
+const memories = await client.search({
+	id: "user_123",
+	query: "What technical preferences should I consider?",
+	limit: 5,
+});
+```
+
+## TypeScript
+
+The SDK is designed for TypeScript applications and provides typed method interfaces.
+
+```ts
+import { Lumi0 } from "@lumi0/sdk";
+
+const client = new Lumi0({
+	apiKey: process.env.LUMI0_API_KEY!,
+});
+
+const result = await client.search({
+	id: "user_123",
+	query: "What does the user prefer?",
+	limit: 5,
+});
+```
+
+Your editor can provide autocomplete and type checking for Lumi0 client methods and their options.
+
+## Runtime Support
+
+The SDK is designed to work with modern JavaScript runtimes, including:
+
+* Bun
+* Node.js
+
+Bun installation:
+
+```bash
+bun add @lumi0/sdk
+```
+
+npm installation:
+
+```bash
+npm install @lumi0/sdk
+```
+
+## API Summary
+
+| Method       | Purpose                               |
+| ------------ | ------------------------------------- |
+| `store()`    | Store one memory                      |
+| `batch()`    | Store multiple memories               |
+| `search()`   | Semantically search memories          |
+| `get()`      | Retrieve a memory or specific version |
+| `forget()`   | Delete a memory                       |
+| `compress()` | Compress context relevant to a query  |
+
+## Complete Example
+
+```ts
+import { Lumi0 } from "@lumi0/sdk";
+
+const client = new Lumi0({
+	apiKey: process.env.LUMI0_API_KEY!,
+});
+
+async function main() {
+	// Store memories.
+	await client.batch([
+		{
+			id: "user_123",
+			content: "The user prefers concise TypeScript examples.",
+		},
+		{
+			id: "user_123",
+			content: "The user uses Bun for backend development.",
+		},
+		{
+			id: "user_123",
+			content: "The user works with Hono.",
+		},
+	]);
+
+	// Search relevant memories.
+	const memories = await client.search({
+		id: "user_123",
+		query: "What backend technologies does the user use?",
+		limit: 10,
+		minSimilarity: 0.7,
+		memoryType: "semantic",
+	});
+
+	// Compress retrieved context.
+	const compressed = await client.compress({
+		content: JSON.stringify(memories),
+		query: "What backend technologies does the user use?",
+		mode: "adaptive",
+		budgetRatio: 0.5,
+	});
+
+	console.log(compressed.data.compressedText);
+	console.log(`${compressed.data.tokensSaved} tokens saved`);
+}
+
+main().catch(console.error);
+```
+
+## Links
+
+* Website: https://lumi0.com
+* API: https://api.lumi0.com
+* npm: https://www.npmjs.com/package/@lumi0/sdk
 
-## Errors
+## License
 
-SDK requests reject with an `Error` when Lumi0 returns a non-success status.
-The error message includes the HTTP status and the API-provided error message
-when available.
+MIT

package/dist/index.mjs

@@ -36,12 +36,6 @@ var HttpClient = class {
 			body: body ? JSON.stringify(body) : void 0
 		});
 	}
-	list(path, items) {
-		return this.request(path, {
-			method: "POST",
-			body: JSON.stringify(items)
-		});
-	}
 	put(path, body) {
 		return this.request(path, {
 			method: "PUT",

package/package.json

@@ -1,9 +1,11 @@
 {
 	"name": "@lumi0/sdk",
-	"version": "0.0.3",
+	"version": "0.0.4",
 	"description": "Official TypeScript SDK for Lumi0",
 	"type": "module",
 	"license": "MIT",
+	"main": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/lumi0ai/lumi0-ts.git"