expo-ai-kit 0.1.17 → 0.1.19

package/README.md

@@ -31,6 +31,7 @@ On-device AI for Expo apps. Run language models locally—no API keys, no cloud,
 - **Streaming support** — Progressive token streaming for responsive UIs
 - **Simple API** — Core functions plus prompt helpers for common tasks
 - **Prompt helpers** — Built-in `summarize()`, `translate()`, `rewrite()`, and more
+- **Chat memory** — Built-in `ChatMemoryManager` for managing conversation history
 
 ## Requirements
 
@@ -126,7 +127,38 @@ console.log(response.text);
 
 ### Multi-turn Conversations
 
-For conversations with context, pass the full conversation history:
+For conversations with context, use `ChatMemoryManager` to manage history:
+
+```tsx
+import { ChatMemoryManager, streamMessage } from 'expo-ai-kit';
+
+// Create a memory manager (handles history automatically)
+const memory = new ChatMemoryManager({
+  maxTurns: 10,
+  systemPrompt: 'You are a helpful assistant.',
+});
+
+// Add user message and get response
+memory.addUserMessage('My name is Alice.');
+const { promise } = streamMessage(
+  memory.getAllMessages(),
+  (event) => console.log(event.accumulatedText)
+);
+const response = await promise;
+
+// Store assistant response in memory
+memory.addAssistantMessage(response.text);
+
+// Continue the conversation (memory includes full history)
+memory.addUserMessage('What is my name?');
+const { promise: p2 } = streamMessage(
+  memory.getAllMessages(),
+  (event) => console.log(event.accumulatedText)
+);
+// Response: "Your name is Alice."
+```
+
+Or manually manage the conversation array:
 
 ```tsx
 import { sendMessage, type LLMMessage } from 'expo-ai-kit';
@@ -505,6 +537,99 @@ function answerQuestion(question: string, context: string, options?: LLMAnswerQu
 
 ---
 
+### `ChatMemoryManager`
+
+Manages conversation history for stateless on-device AI models. Automatically handles turn limits and provides the full message array for each request.
+
+```typescript
+class ChatMemoryManager {
+  constructor(options?: ChatMemoryOptions);
+
+  addUserMessage(content: string): void;
+  addAssistantMessage(content: string): void;
+  addMessage(message: LLMMessage): void;
+
+  getAllMessages(): LLMMessage[];
+  getMessages(): LLMMessage[];
+  getPrompt(): string;
+  getSnapshot(): ChatMemorySnapshot;
+  getTurnCount(): number;
+
+  setSystemPrompt(prompt: string | undefined): void;
+  getSystemPrompt(): string | undefined;
+  setMaxTurns(maxTurns: number): void;
+
+  clear(): void;
+  reset(): void;
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `maxTurns` | `number` | Maximum conversation turns to keep (default: `10`) |
+| `systemPrompt` | `string` | System prompt to include in every request |
+
+**Why use ChatMemoryManager?**
+
+On-device models are stateless — they have no built-in memory. Each request must include the full conversation history. `ChatMemoryManager` handles this automatically:
+
+- Stores messages client-side
+- Automatically trims old messages when limit is reached
+- Preserves the system prompt (never trimmed)
+- Provides `getAllMessages()` for API calls
+
+**Example with React:**
+
+```tsx
+import { useRef } from 'react';
+import { ChatMemoryManager, streamMessage } from 'expo-ai-kit';
+
+function Chat() {
+  const memoryRef = useRef(new ChatMemoryManager({
+    maxTurns: 10,
+    systemPrompt: 'You are a helpful assistant.',
+  }));
+
+  const sendMessage = async (text: string) => {
+    memoryRef.current.addUserMessage(text);
+
+    const { promise } = streamMessage(
+      memoryRef.current.getAllMessages(),
+      (event) => setResponse(event.accumulatedText)
+    );
+
+    const response = await promise;
+    memoryRef.current.addAssistantMessage(response.text);
+  };
+
+  const clearChat = () => memoryRef.current.clear();
+}
+```
+
+---
+
+### `buildPrompt(messages)`
+
+Converts a message array to a single prompt string. Useful for debugging or custom implementations.
+
+```typescript
+function buildPrompt(messages: LLMMessage[]): string
+```
+
+**Example:**
+```tsx
+import { buildPrompt } from 'expo-ai-kit';
+
+const prompt = buildPrompt([
+  { role: 'system', content: 'You are helpful.' },
+  { role: 'user', content: 'Hi!' },
+  { role: 'assistant', content: 'Hello!' },
+]);
+// "SYSTEM: You are helpful.\nUSER: Hi!\nASSISTANT: Hello!"
+```
+
+---
+
 ### Types
 
 ```typescript
@@ -566,6 +691,21 @@ type LLMExtractKeyPointsOptions = {
 type LLMAnswerQuestionOptions = {
   detail?: 'brief' | 'medium' | 'detailed';
 };
+
+// Chat Memory Types
+type ChatMemoryOptions = {
+  /** Maximum conversation turns to keep (default: 10) */
+  maxTurns?: number;
+  /** System prompt to include in every request */
+  systemPrompt?: string;
+};
+
+type ChatMemorySnapshot = {
+  messages: LLMMessage[];
+  systemPrompt: string | undefined;
+  turnCount: number;
+  maxTurns: number;
+};
 ```
 
 ## Feature Comparison
@@ -576,6 +716,7 @@ type LLMAnswerQuestionOptions = {
 | `sendMessage()` | ✅ | ✅ |
 | `streamMessage()` | ✅ | ✅ |
 | Prompt helpers | ✅ | ✅ |
+| `ChatMemoryManager` | ✅ | ✅ |
 | System prompts | ✅ Native | ✅ Prepended |
 | Multi-turn context | ✅ | ✅ |
 | Cancel streaming | ✅ | ✅ |
@@ -627,7 +768,7 @@ const { text } = await sendMessage(messages, { systemPrompt: '...' });
 |---------|--------|----------|
 | ✅ Streaming responses | Done | - |
 | ✅ Prompt helpers (summarize, translate, etc.) | Done | - |
-| Conversation memory (useChat hook) | Planned | High |
+| ✅ Chat memory management | Done | - |
 | Web/generic fallback | Idea | Medium |
 | Configurable hyperparameters (temperature, etc.) | Idea | Low |
 

package/android/build/kotlin/compileDebugKotlin/cacheable/caches-jvm/lookups/counters.tab

@@ -1,2 +1,2 @@
-2
+3
 0

package/android/src/main/java/expo/modules/aikit/ExpoAiKitModule.kt

@@ -32,13 +32,17 @@ class ExpoAiKitModule : Module() {
         ?.get("content") as? String
         ?: fallbackSystemPrompt.ifBlank { "You are a helpful, friendly assistant." }
 
-      // Get the last user message as the prompt
-      val userPrompt = messages
-        .lastOrNull { it["role"] == "user" }
-        ?.get("content") as? String
-        ?: ""
+      // Build conversation history prompt from all non-system messages
+      // On-device models are stateless, so we must include full history in each request
+      val conversationPrompt = messages
+        .filter { it["role"] != "system" }
+        .joinToString("\n") { msg ->
+          val role = (msg["role"] as? String ?: "user").uppercase()
+          val content = msg["content"] as? String ?: ""
+          "$role: $content"
+        } + "\nASSISTANT:"
 
-      val text = promptClient.generateText(userPrompt, systemPrompt)
+      val text = promptClient.generateText(conversationPrompt, systemPrompt)
       mapOf("text" to text)
     }
 
@@ -49,15 +53,19 @@ class ExpoAiKitModule : Module() {
         ?.get("content") as? String
         ?: fallbackSystemPrompt.ifBlank { "You are a helpful, friendly assistant." }
 
-      // Get the last user message as the prompt
-      val userPrompt = messages
-        .lastOrNull { it["role"] == "user" }
-        ?.get("content") as? String
-        ?: ""
+      // Build conversation history prompt from all non-system messages
+      // On-device models are stateless, so we must include full history in each request
+      val conversationPrompt = messages
+        .filter { it["role"] != "system" }
+        .joinToString("\n") { msg ->
+          val role = (msg["role"] as? String ?: "user").uppercase()
+          val content = msg["content"] as? String ?: ""
+          "$role: $content"
+        } + "\nASSISTANT:"
 
       // Launch streaming in a coroutine that can be cancelled
       val job = streamScope.launch {
-        promptClient.generateTextStream(userPrompt, systemPrompt) { token, accumulatedText, isDone ->
+        promptClient.generateTextStream(conversationPrompt, systemPrompt) { token, accumulatedText, isDone ->
           sendEvent("onStreamToken", mapOf(
             "sessionId" to sessionId,
             "token" to token,

package/build/index.d.ts

@@ -1,5 +1,6 @@
 import { LLMMessage, LLMSendOptions, LLMResponse, LLMStreamOptions, LLMStreamCallback, LLMSummarizeOptions, LLMTranslateOptions, LLMRewriteOptions, LLMExtractKeyPointsOptions, LLMAnswerQuestionOptions } from './types';
 export * from './types';
+export * from './memory';
 /**
  * Check if on-device AI is available on the current device.
  * Returns false on unsupported platforms (web, etc.).

package/build/index.d.ts.map

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

package/build/index.js

@@ -1,6 +1,7 @@
 import ExpoAiKitModule from './ExpoAiKitModule';
 import { Platform } from 'react-native';
 export * from './types';
+export * from './memory';
 const DEFAULT_SYSTEM_PROMPT = 'You are a helpful, friendly assistant. Answer the user directly and concisely.';
 let streamIdCounter = 0;
 function generateSessionId() {