[Feature]: JavaScript/TypeScript SDK Implementation

[Teingi]

Describe your use case

Modern web applications, Node.js backends, and full-stack JavaScript/TypeScript applications are increasingly adopting AI capabilities. Developers working in JavaScript/TypeScript ecosystems need a native PowerMem SDK to integrate intelligent memory capabilities into their applications without requiring Python runtime or complex HTTP API wrappers. This would enable:

• Seamless integration with Node.js, Express, Next.js, React, and other JavaScript frameworks
• Type-safe memory operations with TypeScript's strong typing system
• Better performance for JavaScript/TypeScript applications (no Python interop overhead)
• Integration with existing JavaScript tooling and build systems (npm, yarn, pnpm, webpack, Vite)
• Browser and server-side support (universal/isomorphic SDK)
• Modern JavaScript features (async/await, Promises, ES modules)
• Enterprise JavaScript/TypeScript applications requiring memory management for AI features

Describe the solution you'd like

Implement a complete JavaScript/TypeScript SDK for PowerMem that:

1. Core functionality:

   • Memory CRUD operations (add, search, update, delete)
   • User and agent memory management
   • Configuration management (environment variables, config objects)
   • Async operations support (Promises, async/await)
   • Support for both CommonJS and ES modules
   • Proper handling of 64-bit integer IDs (memory_id as string to avoid precision loss)

2. SDK structure:

   • npm package distribution (@powermem/sdk or powermem-js)
   • Package structure: @powermem/sdk.* or powermem.*
   • Builder pattern for configuration
   • Exception handling with custom error classes
   • TypeScript definitions included
   • Support for both browser and Node.js environments

3. Features:

   • Full feature parity with Python SDK
   • Support for all memory types (short-term, long-term, private, shared)
   • Multi-agent support
   • User profile management
   • Ebbinghaus forgetting curve integration
   • Hybrid retrieval (vector, full-text, graph)
   • Streaming support for large responses
   • Request/response interceptors for customization

4. Quality requirements:

   • Comprehensive unit tests (Jest, Vitest, or Mocha)
   • Integration tests
   • TypeScript documentation (TSDoc)
   • Example projects and tutorials
   • Performance benchmarks
   • Browser compatibility testing
   • Bundle size optimization

5. Additional considerations:

   • Handle 64-bit integer precision issues (treat memory_id as string in JSON)
   • Support for both REST API and potential future WebSocket connections
   • Retry logic and error handling
   • Request timeout configuration
   • Support for custom HTTP clients (fetch, axios, etc.)
   • Tree-shaking support for smaller bundle sizes
   • Source maps for debugging

The solution should:

• Follow JavaScript/TypeScript best practices and conventions
• Support Node.js 18+ (LTS versions) and modern browsers
• Be thread-safe for concurrent operations (where applicable)
• Include proper error handling and logging
• Provide npm distribution
• Support both ESM and CommonJS module formats
• Include comprehensive TypeScript type definitions

Describe alternatives you've considered

• Using the HTTP API Server directly with fetch/axios - but this requires manual implementation of all endpoints, error handling, and lacks type safety
• Creating a thin wrapper around the HTTP API - but this doesn't provide the developer experience and type safety of a native SDK

Additional context

• The HTTP API Server is already available and can serve as the backend for the JavaScript SDK
• There's a known issue with 64-bit integer precision in JavaScript (memory_id should be handled as string) - see docs/guides/1000-other_notes.md
• The SDK should work seamlessly with existing PowerMem HTTP API Server infrastructure
• Consider supporting both browser and Node.js environments for maximum flexibility