memoryos-api 0.1.0

package/BUILD_AND_PUBLISH.md

@@ -0,0 +1,115 @@
+# Building and Publishing the MemoryOS Node.js SDK
+
+## Prerequisites
+
+1. Node.js 16+ and npm
+2. npm account (https://www.npmjs.com)
+3. Logged in to npm: `npm login`
+
+## Installation of Build Tools
+
+```bash
+npm install -g npm
+```
+
+## Building the Package
+
+From the `sdk-node` directory:
+
+```bash
+npm run build
+```
+
+This compiles TypeScript to JavaScript in the `dist/` directory and generates type definitions.
+
+## Publishing to npm
+
+### Option 1: Using npm CLI (Recommended)
+
+First, ensure you're logged in:
+
+```bash
+npm login
+```
+
+Then publish:
+
+```bash
+npm publish
+```
+
+### Option 2: Using npm Token
+
+Create or use an existing npm access token from https://www.npmjs.com/settings/tokens
+
+Set the token:
+```bash
+npm config set //registry.npmjs.org/:_authToken=your-npm-token
+```
+
+Then publish:
+```bash
+npm publish
+```
+
+## Verifying the Upload
+
+After publishing, verify your package is available:
+
+```bash
+npm install memoryos
+node -e "const MemoryOS = require('memoryos'); console.log('Success!');"
+```
+
+Or with TypeScript:
+```bash
+npm install memoryos
+npx ts-node -e "import MemoryOS from 'memoryos'; console.log('Success!');"
+```
+
+## Version Updates
+
+To release a new version:
+
+1. Update version in `package.json`
+2. Run `npm run build`
+3. Run `npm publish`
+
+## Testing Before Publishing
+
+Test the package locally:
+
+```bash
+# Install in development mode
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+
+# Test the built package
+npm pack
+npm install ./memoryos-0.1.0.tgz
+```
+
+## Scoped Packages (Optional)
+
+If you want to publish under a scope (e.g., `@memoryos/sdk`):
+
+1. Update `name` in `package.json`: `"@memoryos/sdk"`
+2. Run `npm publish --access public`
+
+## Troubleshooting
+
+- **"You must be logged in"**: Run `npm login` first
+- **"Package name already exists"**: Use a different name or scope
+- **"Version already exists"**: Update the version in package.json
+- **"Invalid package"**: Check that all required fields are in package.json
+
+## Resources
+
+- npm Documentation: https://docs.npmjs.com/
+- npm Publishing Guide: https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry
+- TypeScript Publishing: https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MemoryOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# MemoryOS Node.js SDK
+
+Persistent memory for AI agents. Store, search, and retrieve memories with semantic understanding.
+
+## Installation
+
+```bash
+npm install memoryos
+# or
+yarn add memoryos
+```
+
+## Quick Start
+
+```typescript
+import MemoryOS from 'memoryos';
+
+// Initialize client
+const client = new MemoryOS('your-api-key');
+
+// Store a memory
+const memoryId = await client.store(
+  'User prefers concise responses',
+  { user_id: '123' }
+);
+
+// Search memories (semantic search)
+const results = await client.search('user preferences', 5);
+results.forEach(memory => {
+  console.log(`Similarity: ${memory.similarity}`);
+  console.log(`Content: ${memory.content}`);
+});
+
+// List all memories
+const allMemories = await client.list({ limit: 20 });
+
+// Get a specific memory
+const memory = await client.get(memoryId);
+
+// Delete a memory
+await client.delete(memoryId);
+
+// Get statistics
+const stats = await client.stats();
+console.log(`Total memories: ${stats.totalMemories}`);
+```
+
+## Integration with LangChain
+
+```typescript
+import MemoryOS from 'memoryos';
+
+const client = new MemoryOS('your-api-key');
+
+// Store conversation context
+async function rememberConversation(userInput: string, response: string) {
+  await client.store(
+    `User: ${userInput}\nAssistant: ${response}`,
+    { type: 'conversation' }
+  );
+}
+
+// Retrieve relevant context
+async function getContext(query: string) {
+  const results = await client.search(query, 5);
+  return results.map(m => m.content);
+}
+```
+
+## Integration with AutoGPT
+
+```typescript
+import MemoryOS from 'memoryos';
+
+class MemoryManager {
+  private client: MemoryOS;
+
+  constructor(apiKey: string) {
+    this.client = new MemoryOS(apiKey);
+  }
+
+  async remember(fact: string, category: string) {
+    await this.client.store(fact, { category });
+  }
+
+  async recall(query: string, limit = 5) {
+    return this.client.search(query, limit);
+  }
+
+  async forget(memoryId: number) {
+    return this.client.delete(memoryId);
+  }
+}
+
+// Usage
+const manager = new MemoryManager('your-api-key');
+await manager.remember('User is in New York', 'location');
+const memories = await manager.recall('where is the user');
+```
+
+## API Reference
+
+### MemoryOS(apiKey, baseUrl?)
+
+Initialize the MemoryOS client.
+
+**Parameters:**
+- `apiKey` (string): Your MemoryOS API key
+- `baseUrl` (string, optional): Base URL of the MemoryOS API
+
+### store(content, metadata?)
+
+Store a new memory.
+
+**Parameters:**
+- `content` (string): Memory content (max 10,000 characters)
+- `metadata` (object, optional): Custom metadata
+
+**Returns:** Promise<number> - Memory ID
+
+### search(query, limit?)
+
+Search memories using semantic search.
+
+**Parameters:**
+- `query` (string): Search query
+- `limit` (number, optional): Max results (default: 10, max: 100)
+
+**Returns:** Promise<Memory[]> - List of matching memories
+
+### list(options?)
+
+List all memories with pagination.
+
+**Parameters:**
+- `options.limit` (number, optional): Results per page (default: 20, max: 100)
+- `options.offset` (number, optional): Number to skip (default: 0)
+
+**Returns:** Promise<Memory[]> - List of memories
+
+### get(memoryId)
+
+Get a specific memory by ID.
+
+**Parameters:**
+- `memoryId` (number): Memory ID
+
+**Returns:** Promise<Memory> - Memory object
+
+### delete(memoryId)
+
+Delete a memory.
+
+**Parameters:**
+- `memoryId` (number): Memory ID
+
+**Returns:** Promise<boolean> - True if successful
+
+### stats()
+
+Get memory statistics.
+
+**Returns:** Promise<MemoryStats> - Statistics object
+
+## Error Handling
+
+```typescript
+import { MemoryOSError } from 'memoryos';
+
+try {
+  await client.store('Some memory');
+} catch (error) {
+  if (error instanceof MemoryOSError) {
+    console.error(`Error: ${error.message}`);
+    console.error(`Status: ${error.statusCode}`);
+  }
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support included. Type definitions are automatically available:
+
+```typescript
+import MemoryOS, { Memory, MemoryStats } from 'memoryos';
+
+const client = new MemoryOS('your-api-key');
+const memories: Memory[] = await client.list();
+const stats: MemoryStats = await client.stats();
+```
+
+## Getting Your API Key
+
+1. Sign up at https://billiondna-vaiyukai.manus.space
+2. Go to your dashboard
+3. Create a new API key in the "API Keys" section
+4. Use it in your code
+
+## Support
+
+For issues and questions, visit https://billiondna-vaiyukai.manus.space/docs
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * MemoryOS Node.js/TypeScript SDK
+ * Persistent memory for AI agents
+ */
+export interface Memory {
+    id: number;
+    content: string;
+    metadata?: Record<string, any>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface MemoryStats {
+    totalMemories: number;
+    oldestMemory?: string;
+    newestMemory?: string;
+}
+export declare class MemoryOSError extends Error {
+    statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+export declare class MemoryOS {
+    private apiKey;
+    private baseUrl;
+    private headers;
+    /**
+     * Initialize MemoryOS client
+     * @param apiKey Your MemoryOS API key
+     * @param baseUrl Base URL of the MemoryOS API (default: production)
+     */
+    constructor(apiKey: string, baseUrl?: string);
+    /**
+     * Store a new memory
+     * @param content The memory content (up to 10,000 characters)
+     * @param metadata Optional metadata object
+     * @returns Memory ID of the stored memory
+     */
+    store(content: string, metadata?: Record<string, any>): Promise<number>;
+    /**
+     * Search for memories
+     * @param query Search query (semantic search)
+     * @param limit Maximum number of results (default: 10, max: 100)
+     * @returns List of matching memories
+     */
+    search(query: string, limit?: number): Promise<Memory[]>;
+    /**
+     * List all memories with pagination
+     * @param limit Number of memories to return (default: 20, max: 100)
+     * @param offset Number of memories to skip (default: 0)
+     * @returns List of memories
+     */
+    list(limit?: number, offset?: number): Promise<Memory[]>;
+    /**
+     * Get a specific memory by ID
+     * @param memoryId ID of the memory to retrieve
+     * @returns The memory object
+     */
+    get(memoryId: number): Promise<Memory>;
+    /**
+     * Delete a memory
+     * @param memoryId ID of the memory to delete
+     * @returns True if deletion was successful
+     */
+    delete(memoryId: number): Promise<boolean>;
+    /**
+     * Get memory statistics
+     * @returns Memory statistics
+     */
+    stats(): Promise<MemoryStats>;
+    private request;
+}
+export default MemoryOS;

package/dist/index.js

@@ -0,0 +1,122 @@
+/**
+ * MemoryOS Node.js/TypeScript SDK
+ * Persistent memory for AI agents
+ */
+export class MemoryOSError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = "MemoryOSError";
+    }
+}
+export class MemoryOS {
+    /**
+     * Initialize MemoryOS client
+     * @param apiKey Your MemoryOS API key
+     * @param baseUrl Base URL of the MemoryOS API (default: production)
+     */
+    constructor(apiKey, baseUrl = "https://billiondna-vaiyukai.manus.space") {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.headers = {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        };
+    }
+    /**
+     * Store a new memory
+     * @param content The memory content (up to 10,000 characters)
+     * @param metadata Optional metadata object
+     * @returns Memory ID of the stored memory
+     */
+    async store(content, metadata) {
+        const response = await this.request("POST", "/api/memories/store", {
+            content,
+            metadata,
+        });
+        return response.id;
+    }
+    /**
+     * Search for memories
+     * @param query Search query (semantic search)
+     * @param limit Maximum number of results (default: 10, max: 100)
+     * @returns List of matching memories
+     */
+    async search(query, limit = 10) {
+        const params = new URLSearchParams({
+            query,
+            limit: Math.min(limit, 100).toString(),
+        });
+        return this.request("GET", `/api/memories/search?${params}`);
+    }
+    /**
+     * List all memories with pagination
+     * @param limit Number of memories to return (default: 20, max: 100)
+     * @param offset Number of memories to skip (default: 0)
+     * @returns List of memories
+     */
+    async list(limit = 20, offset = 0) {
+        const params = new URLSearchParams({
+            limit: Math.min(limit, 100).toString(),
+            offset: offset.toString(),
+        });
+        return this.request("GET", `/api/memories/list?${params}`);
+    }
+    /**
+     * Get a specific memory by ID
+     * @param memoryId ID of the memory to retrieve
+     * @returns The memory object
+     */
+    async get(memoryId) {
+        return this.request("GET", `/api/memories/${memoryId}`);
+    }
+    /**
+     * Delete a memory
+     * @param memoryId ID of the memory to delete
+     * @returns True if deletion was successful
+     */
+    async delete(memoryId) {
+        await this.request("DELETE", `/api/memories/${memoryId}`);
+        return true;
+    }
+    /**
+     * Get memory statistics
+     * @returns Memory statistics
+     */
+    async stats() {
+        return this.request("GET", "/api/memories/stats");
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const options = {
+            method,
+            headers: this.headers,
+        };
+        if (body) {
+            options.body = JSON.stringify(body);
+        }
+        try {
+            const response = await fetch(url, options);
+            if (!response.ok) {
+                let message = response.statusText;
+                try {
+                    const errorData = await response.json();
+                    message = errorData.message || message;
+                }
+                catch {
+                    // Use statusText if JSON parsing fails
+                }
+                throw new MemoryOSError(`API Error (${response.status}): ${message}`, response.status);
+            }
+            return response.json();
+        }
+        catch (error) {
+            if (error instanceof MemoryOSError) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new MemoryOSError(`Request failed: ${message}`);
+        }
+    }
+}
+export default MemoryOS;

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "memoryos-api",
+  "version": "0.1.0",
+  "description": "Node.js/TypeScript SDK for MemoryOS - Persistent memory for AI agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "jest"
+  },
+  "keywords": [
+    "memory",
+    "ai",
+    "agents",
+    "persistent",
+    "storage",
+    "api"
+  ],
+  "author": "MemoryOS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/memoryos/sdk-node"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,171 @@
+/**
+ * MemoryOS Node.js/TypeScript SDK
+ * Persistent memory for AI agents
+ */
+
+export interface Memory {
+  id: number;
+  content: string;
+  metadata?: Record<string, any>;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface MemoryStats {
+  totalMemories: number;
+  oldestMemory?: string;
+  newestMemory?: string;
+}
+
+export class MemoryOSError extends Error {
+  constructor(
+    message: string,
+    public statusCode?: number
+  ) {
+    super(message);
+    this.name = "MemoryOSError";
+  }
+}
+
+export class MemoryOS {
+  private apiKey: string;
+  private baseUrl: string;
+  private headers: Record<string, string>;
+
+  /**
+   * Initialize MemoryOS client
+   * @param apiKey Your MemoryOS API key
+   * @param baseUrl Base URL of the MemoryOS API (default: production)
+   */
+  constructor(
+    apiKey: string,
+    baseUrl: string = "https://billiondna-vaiyukai.manus.space"
+  ) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.headers = {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    };
+  }
+
+  /**
+   * Store a new memory
+   * @param content The memory content (up to 10,000 characters)
+   * @param metadata Optional metadata object
+   * @returns Memory ID of the stored memory
+   */
+  async store(
+    content: string,
+    metadata?: Record<string, any>
+  ): Promise<number> {
+    const response = await this.request("POST", "/api/memories/store", {
+      content,
+      metadata,
+    });
+    return response.id;
+  }
+
+  /**
+   * Search for memories
+   * @param query Search query (semantic search)
+   * @param limit Maximum number of results (default: 10, max: 100)
+   * @returns List of matching memories
+   */
+  async search(query: string, limit: number = 10): Promise<Memory[]> {
+    const params = new URLSearchParams({
+      query,
+      limit: Math.min(limit, 100).toString(),
+    });
+
+    return this.request("GET", `/api/memories/search?${params}`);
+  }
+
+  /**
+   * List all memories with pagination
+   * @param limit Number of memories to return (default: 20, max: 100)
+   * @param offset Number of memories to skip (default: 0)
+   * @returns List of memories
+   */
+  async list(limit: number = 20, offset: number = 0): Promise<Memory[]> {
+    const params = new URLSearchParams({
+      limit: Math.min(limit, 100).toString(),
+      offset: offset.toString(),
+    });
+
+    return this.request("GET", `/api/memories/list?${params}`);
+  }
+
+  /**
+   * Get a specific memory by ID
+   * @param memoryId ID of the memory to retrieve
+   * @returns The memory object
+   */
+  async get(memoryId: number): Promise<Memory> {
+    return this.request("GET", `/api/memories/${memoryId}`);
+  }
+
+  /**
+   * Delete a memory
+   * @param memoryId ID of the memory to delete
+   * @returns True if deletion was successful
+   */
+  async delete(memoryId: number): Promise<boolean> {
+    await this.request("DELETE", `/api/memories/${memoryId}`);
+    return true;
+  }
+
+  /**
+   * Get memory statistics
+   * @returns Memory statistics
+   */
+  async stats(): Promise<MemoryStats> {
+    return this.request("GET", "/api/memories/stats");
+  }
+
+  private async request(
+    method: string,
+    path: string,
+    body?: any
+  ): Promise<any> {
+    const url = `${this.baseUrl}${path}`;
+
+    const options: RequestInit = {
+      method,
+      headers: this.headers,
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    try {
+      const response = await fetch(url, options);
+
+      if (!response.ok) {
+        let message = response.statusText;
+        try {
+          const errorData = await response.json();
+          message = (errorData as any).message || message;
+        } catch {
+          // Use statusText if JSON parsing fails
+        }
+
+        throw new MemoryOSError(
+          `API Error (${response.status}): ${message}`,
+          response.status
+        );
+      }
+
+      return response.json();
+    } catch (error) {
+      if (error instanceof MemoryOSError) {
+        throw error;
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      throw new MemoryOSError(`Request failed: ${message}`);
+    }
+  }
+}
+
+export default MemoryOS;

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}