Node.js SDK Implementation Summary

Overview

This implementation adds a Node.js SDK and HTTP server for Memvid, enabling integration with serverless platforms (Vercel, AWS Lambda) and voice agents (Grok Voice Agent).

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Serverless Environment                     │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Grok Voice Agent + Node.js SDK (Vercel/Lambda)     │  │
│  │  • Function calling pattern                          │  │
│  │  • WebSocket for real-time audio                    │  │
│  │  • @memvid/sdk for memory access                    │  │
│  └────────────────────┬─────────────────────────────────┘  │
│                       │ HTTP/JSON                           │
│                       ▼                                     │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Memvid Server (Rust - Axum)                         │  │
│  │  • Session management                                │  │
│  │  • REST API (JSON)                                   │  │
│  │  • Multi-tenant architecture                          │  │
│  └────────────────────┬─────────────────────────────────┘  │
│                       │                                    │
│                       ▼                                    │
│              ┌────────────────┐                             │
│              │  .mv2 Files   │                             │
│              │  (Storage)    │                             │
│              └────────────────┘                             │
└─────────────────────────────────────────────────────────────┘

What Was Created

1. Rust HTTP Server (`crates/memvid-server/`)

Purpose: Expose Memvid functionality via HTTP/JSON API

Files:

crates/memvid-server/Cargo.toml - Dependencies and configuration
crates/memvid-server/src/lib.rs - HTTP API implementation
crates/memvid-server/src/bin/memvid-server.rs - Server binary

Features:

✅ Session-based multi-tenancy
✅ RESTful API design
✅ JSON request/response
✅ Error handling with proper HTTP status codes
✅ CORS support
✅ Tracing and logging

API Endpoints:

POST   /api/v1/sessions              Create session
GET    /api/v1/sessions/:id          Get session info
DELETE /api/v1/sessions/:id          Close session
POST   /api/v1/sessions/:id/store    Store data
POST   /api/v1/sessions/:id/search   Search memory
POST   /api/v1/sessions/:id/ask      RAG query
GET    /api/v1/sessions/:id/timeline Get timeline
POST   /api/v1/sessions/:id/commit   Commit changes
GET    /health                       Health check

2. Node.js SDK (`packages/memvid-js/`)

Purpose: TypeScript client for the Memvid HTTP server

Files:

packages/memvid-js/package.json - Package configuration
packages/memvid-js/tsconfig.json - TypeScript configuration
packages/memvid-js/src/index.ts - Main exports
packages/memvid-js/src/types.ts - Type definitions
packages/memvid-js/src/client.ts - Client implementation
packages/memvid-js/test/client.test.ts - Unit tests
packages/memvid-js/vitest.config.ts - Test configuration

Features:

✅ Full TypeScript support with type safety
✅ Async/await API
✅ Error handling with custom MemvidError class
✅ Timeout support
✅ Custom fetch implementation (for edge environments)
✅ Session management
✅ Comprehensive test suite

Usage Example:

import { MemvidClient } from '@memvid/sdk';

const client = new MemvidClient({
  serverUrl: 'http://localhost:8080',
});

const session = await client.createSession({
  storagePath: './memory.mv2',
  createIfNotExists: true,
});

await session.store('Hello, world!', {
  tags: ['greeting'],
  labels: ['user'],
});

const results = await session.search({ query: 'hello', top_k: 5 });
console.log(results);

await session.close();

3. Grok Voice Agent Integration (`examples/vercel-grok/`)

Purpose: Vercel Edge Function for Grok Voice Agent integration

Files:

examples/vercel-grok/index.ts - Main webhook handler
examples/vercel-grok/grok-tools.ts - Tool definitions
examples/vercel-grok/README.md - Setup guide
examples/vercel-grok/package.json - Dependencies

Features:

✅ WebSocket event handling
✅ Function call routing
✅ Auto-transcription storage
✅ Context retrieval
✅ RAG question answering
✅ Deployment ready

Available Tools:

search_memory - Search conversation history
get_context - Get recent messages
ask_question - RAG-based question answering
store_conversation - Store important information

Integration Flow:

Grok Voice Agent                    Vercel Function              Memvid Server
     │                                  │                            │
     │ WebSocket Event                  │                            │
     ├─────────────────────────────────>│                            │
     │  (function call)                 │ HTTP Request               │
     │                                  ├───────────────────────────>│
     │                                  │                            │ Search
     │                                  │                            │ Query
     │                                  │ HTTP Response              │ Result
     │                                  │<───────────────────────────┤
     │ Function Result                  │                            │
     │<─────────────────────────────────┤                            │
     │                                  │                            │

Quick Start Guide

1. Start Memvid Server

# Build and run the server
cargo run --bin memvid-server

# Server will start on http://localhost:8080

2. Create Node.js SDK Session

cd packages/memvid-js

# Install dependencies
npm install

# Build TypeScript
npm run build

# Test
npm test

3. Create a Session

node -e "
const { MemvidClient } = require('./dist/index.js');

async function main() {
  const client = new MemvidClient({
    serverUrl: 'http://localhost:8080',
  });

  const session = await client.createSession({
    storagePath: './conversation.mv2',
    createIfNotExists: true,
  });

  console.log('Session ID:', session.sessionId);

  await session.store('Hello, my name is Alice', {
    labels: ['user'],
    tags: ['introduction'],
  });

  const results = await session.search({ query: 'Alice' });
  console.log('Search results:', results);

  await session.close();
}

main();
"

4. Deploy Grok Integration

cd examples/vercel-grok

# Install dependencies
npm install

# Set environment variables
export MEMVID_SERVER_URL=http://localhost:8080
export MEMVID_SESSION_ID=<your-session-id>

# Deploy to Vercel
vercel deploy

Testing

Server Tests

# Test health endpoint
curl http://localhost:8080/health

# Create session
curl -X POST http://localhost:8080/api/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"storage_path": "./test.mv2", "create_if_not_exists": true}'

# Store data
curl -X POST http://localhost:8080/api/v1/sessions/{session_id}/store \
  -H "Content-Type: application/json" \
  -d '{"content": "SGVsbG8gd29ybGQ=", "options": {"tags": ["test"]}}'

# Search
curl -X POST http://localhost:8080/api/v1/sessions/{session_id}/search \
  -H "Content-Type: application/json" \
  -d '{"query": "hello", "top_k": 5}'

SDK Tests

cd packages/memvid-js
npm test

Integration Tests

# Test webhook
curl -X POST http://localhost:3000/api/grok-webhook \
  -H "Content-Type: application/json" \
  -d '{
    "type": "response.function_call_arguments.done",
    "call_id": "test_123",
    "name": "search_memory",
    "arguments": "{\"query\": \"hello\"}"
  }'

File Structure

memvid/
├── Cargo.toml                          # Workspace root
├── crates/
│   ├── memvid-core/                    # Core Memvid library
│   ├── memvid-adapter/                 # Async adapter (existing)
│   └── memvid-server/                  # HTTP server (NEW)
│       ├── Cargo.toml
│       ├── src/
│       │   ├── lib.rs                  # API implementation
│       │   └── bin/
│       │       └── memvid-server.rs    # Server binary
├── packages/
│   └── memvid-js/                      # Node.js SDK (NEW)
│       ├── package.json
│       ├── tsconfig.json
│       ├── vitest.config.ts
│       ├── src/
│       │   ├── index.ts                # Main exports
│       │   ├── types.ts                # Type definitions
│       │   └── client.ts               # Client implementation
│       ├── test/
│       │   └── client.test.ts          # Unit tests
│       └── examples/                    # Example usage
├── examples/
│   └── vercel-grok/                    # Grok integration (NEW)
│       ├── index.ts                    # Webhook handler
│       ├── grok-tools.ts               # Tool definitions
│       ├── README.md                   # Setup guide
│       └── package.json
└── IMPLEMENTATION_SUMMARY.md           # This file

Key Design Decisions

1. Server Process Architecture

Why: Serverless platforms don't support native Rust bindings

✅ Works with Vercel, AWS Lambda, Cloudflare Workers
✅ No native compilation per platform
✅ Easy to deploy and scale
✅ Clean separation of concerns

2. Session-Based API

Why: Support multiple users and isolate data

Each session has its own .mv2 file
Session IDs for easy management
Multi-tenant architecture
Per-session isolation

3. HTTP/JSON Protocol

Why: Maximum compatibility

Works with any language
Standard HTTP infrastructure
Easy to debug and test
WebSocket compatible for real-time

4. TypeScript for SDK

Why: Type safety and DX

Full IntelliSense support
Compile-time error checking
Easy integration with modern frameworks
Good documentation through types

5. Function Calling Pattern

Why: Matches voice agent API design

Native integration with Grok
Easy to extend
Standard pattern for AI agents
WebSocket-friendly

Environment Variables

Server

MEMVID_BIND_ADDRESS - Bind address (default: 0.0.0.0:8080)

Node.js SDK

MEMVID_SERVER_URL - Server URL
MEMVID_API_KEY - Optional API key
MEMVID_SESSION_ID - Session ID (for webhook)

Vercel Deployment

Set in Vercel dashboard or vercel env CLI

Production Considerations

Security

Add API key authentication
Implement rate limiting
Add request validation
Enable CORS for specific origins only

Performance

Add connection pooling
Implement caching layer
Optimize for low latency
Add compression

Monitoring

Add health checks
Implement metrics
Add request logging
Track error rates

Scalability

Horizontal scaling with load balancer
Session distribution
Shared storage backend
Multi-region deployment

Next Steps

Add Authentication: Implement API key or JWT auth
Add Rate Limiting: Prevent abuse with token bucket
Add Caching: Cache search results and sessions
Add Metrics: Track usage and performance
Add WebSocket Support: For real-time updates
Add Load Testing: Verify performance under load
Add CI/CD: Automated testing and deployment
Documentation: API reference and guides

Resources

Memvid Core: https://github.com/memvid/memvid
Grok Voice Agent: https://x.ai/news/grok-voice-agent-api
Vercel Edge Functions: https://vercel.com/docs/edge-functions
Axum Framework: https://github.com/tokio-rs/axum
TypeScript: https://www.typescriptlang.org/

License

Apache-2.0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Node.js SDK Implementation Summary

Overview

Architecture

What Was Created

1. Rust HTTP Server (`crates/memvid-server/`)

2. Node.js SDK (`packages/memvid-js/`)

3. Grok Voice Agent Integration (`examples/vercel-grok/`)

Quick Start Guide

1. Start Memvid Server

2. Create Node.js SDK Session

3. Create a Session

4. Deploy Grok Integration

Testing

Server Tests

SDK Tests

Integration Tests

File Structure

Key Design Decisions

1. Server Process Architecture

2. Session-Based API

3. HTTP/JSON Protocol

4. TypeScript for SDK

5. Function Calling Pattern

Environment Variables

Server

Node.js SDK

Vercel Deployment

Production Considerations

Security

Performance

Monitoring

Scalability

Next Steps

Resources

License

FilesExpand file tree

IMPLEMENTATION_SUMMARY.md

Latest commit

History

IMPLEMENTATION_SUMMARY.md

File metadata and controls

Node.js SDK Implementation Summary

Overview

Architecture

What Was Created

1. Rust HTTP Server (crates/memvid-server/)

2. Node.js SDK (packages/memvid-js/)

3. Grok Voice Agent Integration (examples/vercel-grok/)

Quick Start Guide

1. Start Memvid Server

2. Create Node.js SDK Session

3. Create a Session

4. Deploy Grok Integration

Testing

Server Tests

SDK Tests

Integration Tests

File Structure

Key Design Decisions

1. Server Process Architecture

2. Session-Based API

3. HTTP/JSON Protocol

4. TypeScript for SDK

5. Function Calling Pattern

Environment Variables

Server

Node.js SDK

Vercel Deployment

Production Considerations

Security

Performance

Monitoring

Scalability

Next Steps

Resources

License

1. Rust HTTP Server (`crates/memvid-server/`)

2. Node.js SDK (`packages/memvid-js/`)

3. Grok Voice Agent Integration (`examples/vercel-grok/`)