@memvault/client

Official TypeScript/JavaScript SDK for MemVault - Long-Term Memory API with GraphRAG.

Installation

npm install @memvault/client

Quick Start

import { MemVault } from '@memvault/client';

// Initialize with your API key
const memvault = new MemVault(process.env.MEMVAULT_API_KEY);

// Add memories
await memvault.addMemory("Met with team about Q4 roadmap. Priority: mobile app redesign");
await memvault.addMemory("Sarah mentioned budget concerns for cloud infrastructure");

// Retrieve memories
const memories = await memvault.retrieve("What did we discuss about Q4?");
console.log(memories.results);

// Ask questions (AI-powered)
const answer = await memvault.ask("What are the budget concerns?");
console.log(answer.answer);
console.log("Sources:", answer.sources);

Authentication

Get your API key from the MemVault Dashboard after completing checkout.

const memvault = new MemVault('sk_your_api_key_here');

Options

const memvault = new MemVault(apiKey, {
  baseUrl: 'https://your-custom-domain.com',  // Optional: custom API endpoint
  timeout: 30000,                              // Optional: request timeout (ms)
  maxRetries: 3                                // Optional: retry attempts
});

API Reference

addMemory(content, metadata?)

Store a new memory in your knowledge graph. Processing happens asynchronously.

const result = await memvault.addMemory(
  "Team decided to migrate to Kubernetes by end of Q2",
  { category: "infrastructure", priority: "high" }
);

console.log(result.jobId); // Track processing status

Parameters:

• content (string, required): Memory content
• metadata (object, optional): Additional structured data

Returns: Promise<AddMemoryResponse>

retrieve(query, options?)

Search your knowledge graph for relevant memories.

const results = await memvault.retrieve("kubernetes migration", {
  limit: 10,
  includeEntities: true,
  includeRelationships: true
});

console.log(results.results);      // Relevant memories
console.log(results.entities);     // Extracted entities (people, projects, etc.)
console.log(results.relationships); // Connections between entities

Parameters:

• query (string, required): Search query
• options (object, optional):
  • limit (number): Max results (default: 10)
  • includeEntities (boolean): Include entity graph (default: true)
  • includeRelationships (boolean): Include relationships (default: true)

Returns: Promise<RetrieveResponse>

ask(question)

Ask a question and get an AI-generated answer based on your knowledge graph.

const answer = await memvault.ask("When is the Kubernetes migration deadline?");

console.log(answer.answer);      // "The migration is scheduled for end of Q2"
console.log(answer.confidence);  // 0.95
console.log(answer.reasoning);   // Explanation of how answer was derived
console.log(answer.sources);     // Memories used to generate answer

Parameters:

• question (string, required): Your question

Returns: Promise<AskResponse>

getUser()

Get current user information and billing status.

const user = await memvault.getUser();

console.log(user.id);
console.log(user.tier);           // "PRO"
console.log(user.creditsBalance); // 1000.50

Returns: Promise<User>

listApiKeys()

List all API keys for your account.

const keys = await memvault.listApiKeys();

keys.forEach(key => {
  console.log(key.name, key.createdAt, key.lastUsed);
});

Returns: Promise<ApiKey[]>

deleteApiKey(keyId)

Delete an API key (note: you cannot delete your last key).

await memvault.deleteApiKey('key_abc123');

Parameters:

• keyId (string, required): ID of key to delete

Returns: Promise<{ success: boolean }>

Use Cases

Personal Knowledge Base

// Store information as you learn
await memvault.addMemory("React 19 introduces automatic batching for better performance");
await memvault.addMemory("Next.js 14 has improved image optimization with 40% faster loads");

// Retrieve when needed
const info = await memvault.ask("What did I learn about React 19?");

Team Meeting Notes

// After meetings, store key decisions
await memvault.addMemory(`
  Design Review - March 15, 2024
  Attendees: Sarah, Mike, Jessica
  Decision: Move forward with dark mode as default
  Action items: Sarah creates mockups, Mike updates design system
`);

// Later, anyone can query
const decisions = await memvault.retrieve("dark mode decision");

Customer Support History

// Store customer interactions
await memvault.addMemory(`
  Customer: Acme Corp
  Issue: API rate limiting causing 429 errors
  Solution: Upgraded to Enterprise tier
  Date: 2024-03-10
`);

// Quick lookup
const history = await memvault.ask("What issues has Acme Corp had?");

Research & Documentation

// Accumulate research findings
await memvault.addMemory("Study by MIT: GraphRAG improves retrieval accuracy by 60%");
await memvault.addMemory("Paper: 'Attention is All You Need' introduced transformers in 2017");

// Synthesize information
const summary = await memvault.ask("What are the key innovations in AI retrieval?");

Error Handling

The SDK throws specific error types for different failure scenarios:

import { 
  MemVault,
  AuthenticationError,
  RateLimitError,
  InsufficientCreditsError,
  ValidationError 
} from '@memvault/client';

try {
  await memvault.addMemory("Some content");
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (error instanceof RateLimitError) {
    console.error("Too many requests, slow down");
  } else if (error instanceof InsufficientCreditsError) {
    console.error("Out of credits, please top up");
  } else if (error instanceof ValidationError) {
    console.error("Invalid input:", error.message);
  } else {
    console.error("Unexpected error:", error);
  }
}

Error Types

• AuthenticationError (401): Invalid API key
• InsufficientCreditsError (402): Not enough credits
• ValidationError (400): Invalid input parameters
• RateLimitError (429): Too many requests
• MemVaultError: Generic error with status code

Automatic Retry

The SDK automatically retries failed requests with exponential backoff:

• Network errors: Retries 3 times (configurable)
• Timeout errors: Retries with backoff
• Authentication errors: No retry (fails immediately)

const memvault = new MemVault(apiKey, {
  maxRetries: 5,  // Increase for unreliable networks
  timeout: 60000  // 60 second timeout
});

Advanced Usage

Custom Base URL

For self-hosted or enterprise deployments:

const memvault = new MemVault(apiKey, {
  baseUrl: 'https://memvault.your-company.com'
});

Batch Operations

const memories = [
  "Employee onboarding checklist updated",
  "New security policy effective April 1",
  "Office relocation scheduled for Q3"
];

// Add multiple memories
const results = await Promise.all(
  memories.map(content => memvault.addMemory(content))
);

console.log(`Added ${results.length} memories`);

TypeScript Support

Full TypeScript definitions included:

import { MemVault, Memory, Entity, AskResponse } from '@memvault/client';

const memvault = new MemVault(apiKey);

const answer: AskResponse = await memvault.ask("What's our Q4 plan?");
const memory: Memory = answer.sources[0];
const entity: Entity = answer.entities[0];

Monitoring & Debugging

Check Credits

const user = await memvault.getUser();
console.log(`Credits remaining: ${user.creditsBalance}`);
console.log(`Tier: ${user.tier}`);

Track Job Status

Memory processing is asynchronous. Track with the job ID:

const result = await memvault.addMemory("Important update");
console.log(`Job queued: ${result.jobId}`);
// Job processing happens in background

Contributing

Issues and PRs welcome at github.com/memvault/memvault-sdk

License

MIT

Links

• Dashboard
• API Documentation
• Pricing
• Support