@eight-atulya/atulya-ai-sdk 0.8.0

package/README.md

@@ -0,0 +1,79 @@
+# Atulya Memory Integration for Vercel AI SDK
+
+Give your AI agents persistent, human-like memory using [Atulya](https://github.com/eight-atulya/atulya) with the [Vercel AI SDK](https://ai-sdk.dev).
+
+## Quick Start
+
+```bash
+npm install @eight-atulya/atulya-ai-sdk @eight-atulya/atulya-client ai zod
+```
+
+```typescript
+import { AtulyaClient } from '@eight-atulya/atulya-client';
+import { createAtulyaTools } from '@eight-atulya/atulya-ai-sdk';
+import { generateText } from 'ai';
+import { anthropic } from '@ai-sdk/anthropic';
+
+// 1. Initialize Atulya client
+const atulyaClient = new AtulyaClient({
+  apiUrl: 'http://localhost:8000',
+});
+
+// 2. Create memory tools
+const tools = createAtulyaTools({ client: atulyaClient });
+
+// 3. Use with AI SDK
+const result = await generateText({
+  model: anthropic('claude-sonnet-4-20250514'),
+  tools,
+  system: `You have long-term memory. Use:
+  - 'recall' to search past conversations
+  - 'retain' to remember important information
+  - 'reflect' to synthesize insights from memories`,
+  prompt: 'Remember that Alice loves hiking and prefers spicy food',
+});
+
+console.log(result.text);
+```
+
+## Features
+
+✅ **Three Memory Tools**: `retain` (store), `recall` (retrieve), and `reflect` (reason over memories)
+✅ **AI SDK 6 Native**: Works with `generateText`, `streamText`, and `ToolLoopAgent`
+✅ **Multi-User Support**: Dynamic bank IDs per call for multi-user scenarios
+✅ **Type-Safe**: Full TypeScript support with Zod schemas
+✅ **Flexible Client**: Works with the official TypeScript client or custom HTTP clients
+
+## Documentation
+
+📖 **[Full Documentation](https://github.com/eight-atulya/atulya/blob/main/atulya-docs/docs/sdks/integrations/ai-sdk.mdx)**
+
+The complete documentation includes:
+- Detailed tool descriptions and parameters
+- Advanced usage patterns (streaming, multi-user, ToolLoopAgent)
+- HTTP client example (no dependencies)
+- TypeScript types and API reference
+- Best practices and system prompt examples
+
+## Running Atulya Locally
+
+```bash
+# Install and run with embedded mode (no setup required)
+uvx atulya-embed@latest -p myapp daemon start
+
+# The API will be available at http://localhost:8000
+```
+
+## Examples
+
+Full examples are available in the [GitHub repository](https://github.com/eight-atulya/atulya/tree/main/examples/ai-sdk).
+
+## Support
+
+- [Documentation](https://github.com/eight-atulya/atulya/tree/main/atulya-docs)
+- [GitHub Issues](https://github.com/eight-atulya/atulya/issues)
+- Email: support@eightengine.com
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { createAtulyaTools, BudgetSchema, type Budget, type AtulyaClient, type AtulyaTools, type AtulyaToolsOptions, type RecallResult, type RecallResponse, type ReflectFact, type ReflectResponse, type RetainResponse, type EntityState, type ChunkData, } from './tools';

package/dist/index.js

@@ -0,0 +1 @@
+export { createAtulyaTools, BudgetSchema, } from './tools';

package/dist/tools/index.d.ts

@@ -0,0 +1,270 @@
+import { z } from 'zod';
+/**
+ * Budget levels for recall/reflect operations.
+ */
+export declare const BudgetSchema: z.ZodEnum<{
+    low: "low";
+    mid: "mid";
+    high: "high";
+}>;
+export type Budget = z.infer<typeof BudgetSchema>;
+/**
+ * Fact types for filtering recall results.
+ */
+export declare const FactTypeSchema: z.ZodEnum<{
+    world: "world";
+    experience: "experience";
+    observation: "observation";
+}>;
+export type FactType = z.infer<typeof FactTypeSchema>;
+/**
+ * Recall result item from Atulya
+ */
+export interface RecallResult {
+    id: string;
+    text: string;
+    type?: string | null;
+    entities?: string[] | null;
+    context?: string | null;
+    occurred_start?: string | null;
+    occurred_end?: string | null;
+    mentioned_at?: string | null;
+    document_id?: string | null;
+    metadata?: Record<string, string> | null;
+    chunk_id?: string | null;
+}
+/**
+ * Entity state with observations
+ */
+export interface EntityState {
+    entity_id: string;
+    canonical_name: string;
+    observations: Array<{
+        text: string;
+        mentioned_at?: string | null;
+    }>;
+}
+/**
+ * Chunk data
+ */
+export interface ChunkData {
+    id: string;
+    text: string;
+    chunk_index: number;
+    truncated?: boolean;
+}
+/**
+ * Recall response from Atulya
+ */
+export interface RecallResponse {
+    results: RecallResult[];
+    trace?: Record<string, unknown> | null;
+    entities?: Record<string, EntityState> | null;
+    chunks?: Record<string, ChunkData> | null;
+}
+/**
+ * Reflect fact
+ */
+export interface ReflectFact {
+    id?: string | null;
+    text: string;
+    type?: string | null;
+    context?: string | null;
+    occurred_start?: string | null;
+    occurred_end?: string | null;
+}
+/**
+ * Reflect response from Atulya
+ */
+export interface ReflectResponse {
+    text: string;
+    based_on?: ReflectFact[];
+}
+/**
+ * Retain response from Atulya
+ */
+export interface RetainResponse {
+    success: boolean;
+    bank_id: string;
+    items_count: number;
+    async: boolean;
+}
+/**
+ * Mental model trigger configuration
+ */
+export interface MentalModelTrigger {
+    refresh_after_consolidation?: boolean;
+}
+/**
+ * Mental model response from Atulya
+ */
+export interface MentalModelResponse {
+    mental_model_id: string;
+    bank_id: string;
+    name?: string;
+    content?: string;
+    source_query?: string;
+    tags?: string[];
+    created_at: string;
+    updated_at: string;
+    trigger?: MentalModelTrigger;
+}
+/**
+ * Document response from Atulya
+ */
+export interface DocumentResponse {
+    id: string;
+    bank_id: string;
+    original_text: string;
+    content_hash: string | null;
+    created_at: string;
+    updated_at: string;
+    memory_unit_count: number;
+    tags?: string[];
+}
+/**
+ * Atulya client interface - matches @eight-atulya/atulya-client
+ */
+export interface AtulyaClient {
+    retain(bankId: string, content: string, options?: {
+        timestamp?: Date | string;
+        context?: string;
+        metadata?: Record<string, string>;
+        documentId?: string;
+        tags?: string[];
+        async?: boolean;
+    }): Promise<RetainResponse>;
+    recall(bankId: string, query: string, options?: {
+        types?: FactType[];
+        maxTokens?: number;
+        budget?: Budget;
+        trace?: boolean;
+        queryTimestamp?: string;
+        includeEntities?: boolean;
+        maxEntityTokens?: number;
+        includeChunks?: boolean;
+        maxChunkTokens?: number;
+    }): Promise<RecallResponse>;
+    reflect(bankId: string, query: string, options?: {
+        context?: string;
+        budget?: Budget;
+        maxTokens?: number;
+    }): Promise<ReflectResponse>;
+    getMentalModel(bankId: string, mentalModelId: string): Promise<MentalModelResponse>;
+    getDocument(bankId: string, documentId: string): Promise<DocumentResponse | null>;
+}
+export interface AtulyaToolsOptions {
+    /** Atulya client instance */
+    client: AtulyaClient;
+    /** Memory bank ID to use for all tool calls (e.g. the user ID) */
+    bankId: string;
+    /** Options for the retain tool */
+    retain?: {
+        /** Fire-and-forget retain without waiting for completion (default: false) */
+        async?: boolean;
+        /** Tags always attached to every retained memory (default: undefined) */
+        tags?: string[];
+        /** Metadata always attached to every retained memory (default: undefined) */
+        metadata?: Record<string, string>;
+        /** Custom tool description */
+        description?: string;
+    };
+    /** Options for the recall tool */
+    recall?: {
+        /** Restrict results to these fact types: 'world', 'experience', 'observation' (default: undefined = all types) */
+        types?: FactType[];
+        /** Maximum tokens to return (default: undefined = API default) */
+        maxTokens?: number;
+        /** Processing budget controlling latency vs. depth (default: 'mid') */
+        budget?: Budget;
+        /** Include entity observations in results (default: false) */
+        includeEntities?: boolean;
+        /** Include raw source chunks in results (default: false) */
+        includeChunks?: boolean;
+        /** Custom tool description */
+        description?: string;
+    };
+    /** Options for the reflect tool */
+    reflect?: {
+        /** Processing budget controlling latency vs. depth (default: 'mid') */
+        budget?: Budget;
+        /** Maximum tokens for the response (default: undefined = API default) */
+        maxTokens?: number;
+        /** Custom tool description */
+        description?: string;
+    };
+    /** Options for the getMentalModel tool */
+    getMentalModel?: {
+        /** Custom tool description */
+        description?: string;
+    };
+    /** Options for the getDocument tool */
+    getDocument?: {
+        /** Custom tool description */
+        description?: string;
+    };
+}
+/**
+ * Creates AI SDK tools for Atulya memory operations.
+ *
+ * The bank ID and all infrastructure concerns (budget, tags, async mode, etc.)
+ * are fixed at creation time. The agent only controls semantic inputs:
+ * content, queries, names, and timestamps.
+ *
+ * @example
+ * ```ts
+ * const tools = createAtulyaTools({
+ *   client: atulyaClient,
+ *   bankId: userId,
+ *   recall: { budget: 'high', includeEntities: true },
+ *   retain: { async: true, tags: ['env:prod'] },
+ * });
+ *
+ * const result = await generateText({
+ *   model: openai('gpt-4o'),
+ *   tools,
+ *   messages,
+ * });
+ * ```
+ */
+export declare function createAtulyaTools({ client, bankId, retain: retainOpts, recall: recallOpts, reflect: reflectOpts, getMentalModel: getMentalModelOpts, getDocument: getDocumentOpts, }: AtulyaToolsOptions): {
+    retain: import("ai").Tool<{
+        content: string;
+        documentId?: string | undefined;
+        timestamp?: string | undefined;
+        context?: string | undefined;
+    }, {
+        success: boolean;
+        itemsCount: number;
+    }>;
+    recall: import("ai").Tool<{
+        query: string;
+        queryTimestamp?: string | undefined;
+    }, {
+        results: RecallResult[];
+        entities?: Record<string, EntityState> | null;
+    }>;
+    reflect: import("ai").Tool<{
+        query: string;
+        context?: string | undefined;
+    }, {
+        text: string;
+        basedOn?: ReflectFact[];
+    }>;
+    getMentalModel: import("ai").Tool<{
+        mentalModelId: string;
+    }, {
+        content: string;
+        name?: string;
+        updatedAt: string;
+    }>;
+    getDocument: import("ai").Tool<{
+        documentId: string;
+    }, {
+        originalText: string;
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+    } | null>;
+};
+export type AtulyaTools = ReturnType<typeof createAtulyaTools>;

package/dist/tools/index.js

@@ -0,0 +1,146 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+/**
+ * Budget levels for recall/reflect operations.
+ */
+export const BudgetSchema = z.enum(['low', 'mid', 'high']);
+/**
+ * Fact types for filtering recall results.
+ */
+export const FactTypeSchema = z.enum(['world', 'experience', 'observation']);
+/**
+ * Creates AI SDK tools for Atulya memory operations.
+ *
+ * The bank ID and all infrastructure concerns (budget, tags, async mode, etc.)
+ * are fixed at creation time. The agent only controls semantic inputs:
+ * content, queries, names, and timestamps.
+ *
+ * @example
+ * ```ts
+ * const tools = createAtulyaTools({
+ *   client: atulyaClient,
+ *   bankId: userId,
+ *   recall: { budget: 'high', includeEntities: true },
+ *   retain: { async: true, tags: ['env:prod'] },
+ * });
+ *
+ * const result = await generateText({
+ *   model: openai('gpt-4o'),
+ *   tools,
+ *   messages,
+ * });
+ * ```
+ */
+export function createAtulyaTools({ client, bankId, retain: retainOpts = {}, recall: recallOpts = {}, reflect: reflectOpts = {}, getMentalModel: getMentalModelOpts = {}, getDocument: getDocumentOpts = {}, }) {
+    // Agent-controlled params only: content, timestamp, documentId, context
+    const retainParams = z.object({
+        content: z.string().describe('Content to store in memory'),
+        documentId: z.string().optional().describe('Optional document ID for grouping/upserting content'),
+        timestamp: z.string().optional().describe('Optional ISO timestamp for when the memory occurred'),
+        context: z.string().optional().describe('Optional context about the memory'),
+    });
+    // Agent-controlled params only: query, queryTimestamp
+    const recallParams = z.object({
+        query: z.string().describe('What to search for in memory'),
+        queryTimestamp: z.string().optional().describe('Query from a specific point in time (ISO format)'),
+    });
+    // Agent-controlled params only: query, context
+    const reflectParams = z.object({
+        query: z.string().describe('Question to reflect on based on memories'),
+        context: z.string().optional().describe('Additional context for the reflection'),
+    });
+    const getMentalModelParams = z.object({
+        mentalModelId: z.string().describe('ID of the mental model to retrieve'),
+    });
+    const getDocumentParams = z.object({
+        documentId: z.string().describe('ID of the document to retrieve'),
+    });
+    return {
+        retain: tool({
+            description: retainOpts.description ??
+                `Store information in long-term memory. Use this when information should be remembered for future interactions, such as user preferences, facts, experiences, or important context.`,
+            inputSchema: retainParams,
+            execute: async (input) => {
+                console.log('[AI SDK Tool] Retain input:', {
+                    bankId,
+                    documentId: input.documentId,
+                    hasContent: !!input.content,
+                });
+                const result = await client.retain(bankId, input.content, {
+                    documentId: input.documentId,
+                    timestamp: input.timestamp,
+                    context: input.context,
+                    tags: retainOpts.tags,
+                    metadata: retainOpts.metadata,
+                    async: retainOpts.async ?? false,
+                });
+                return { success: result.success, itemsCount: result.items_count };
+            },
+        }),
+        recall: tool({
+            description: recallOpts.description ??
+                `Search memory for relevant information. Use this to find previously stored information that can help personalize responses or provide context.`,
+            inputSchema: recallParams,
+            execute: async (input) => {
+                const result = await client.recall(bankId, input.query, {
+                    types: recallOpts.types,
+                    maxTokens: recallOpts.maxTokens,
+                    budget: recallOpts.budget ?? 'mid',
+                    queryTimestamp: input.queryTimestamp,
+                    includeEntities: recallOpts.includeEntities ?? false,
+                    includeChunks: recallOpts.includeChunks ?? false,
+                });
+                return {
+                    results: result.results ?? [],
+                    entities: result.entities,
+                };
+            },
+        }),
+        reflect: tool({
+            description: reflectOpts.description ??
+                `Analyze memories to form insights and generate contextual answers. Use this to understand patterns, synthesize information, or answer questions that require reasoning over stored memories.`,
+            inputSchema: reflectParams,
+            execute: async (input) => {
+                const result = await client.reflect(bankId, input.query, {
+                    context: input.context,
+                    budget: reflectOpts.budget ?? 'mid',
+                    maxTokens: reflectOpts.maxTokens,
+                });
+                return {
+                    text: result.text ?? 'No insights available yet.',
+                    basedOn: result.based_on,
+                };
+            },
+        }),
+        getMentalModel: tool({
+            description: getMentalModelOpts.description ??
+                `Retrieve a mental model to get consolidated knowledge synthesized from memories. Mental models provide synthesized insights that are faster and more efficient to retrieve than searching through raw memories.`,
+            inputSchema: getMentalModelParams,
+            execute: async (input) => {
+                const result = await client.getMentalModel(bankId, input.mentalModelId);
+                return {
+                    content: result.content ?? 'No content available yet.',
+                    name: result.name,
+                    updatedAt: result.updated_at,
+                };
+            },
+        }),
+        getDocument: tool({
+            description: getDocumentOpts.description ??
+                `Retrieve a stored document by its ID. Documents are used to store structured data like application state, user profiles, or any data that needs exact retrieval.`,
+            inputSchema: getDocumentParams,
+            execute: async (input) => {
+                const result = await client.getDocument(bankId, input.documentId);
+                if (!result) {
+                    return null;
+                }
+                return {
+                    originalText: result.original_text,
+                    id: result.id,
+                    createdAt: result.created_at,
+                    updatedAt: result.updated_at,
+                };
+            },
+        }),
+    };
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@eight-atulya/atulya-ai-sdk",
+  "version": "0.8.0",
+  "description": "Atulya memory integration for Vercel AI SDK - Give your AI agents persistent, human-like memory",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "vercel",
+    "memory",
+    "atulya",
+    "agents",
+    "llm",
+    "long-term-memory"
+  ],
+  "author": "Anurag Atulya <support@eightengine.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eight-atulya/atulya.git",
+    "directory": "atulya-integrations/ai-sdk"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "peerDependencies": {
+    "ai": "^6.0.0",
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/ui": "^4.0.18",
+    "ai": "^6.0.2",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18",
+    "zod": "^4.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "overrides": {
+    "rollup": "^4.59.0"
+  }
+}