VasperaMemory TypeScript SDK

Universal AI memory layer for development tools. Give your AI agents persistent memory across sessions.

Installation

npm install vasperamemory-sdk

Quick Start

import { VasperaMemory } from 'vasperamemory-sdk';

const vm = new VasperaMemory({
  apiKey: 'vm_your_api_key',
  projectId: 'your_project_id'
});

// Capture a decision
await vm.captureDecision({
  category: 'architectural',
  title: 'Use Redis for caching',
  content: 'Chose Redis over Memcached for its data structure support',
  reasoning: 'Need sorted sets for leaderboards'
});

// Search memories
const results = await vm.search('caching strategy', { limit: 5 });
for (const result of results) {
  console.log(`[${result.score.toFixed(2)}] ${result.item.content}`);
}

// Capture an error fix
await vm.captureErrorFix({
  errorMessage: "TypeError: Cannot read property 'map' of undefined",
  rootCause: 'Array was not initialized before use',
  fixDescription: 'Added null check and default empty array',
  preventionRule: 'Always initialize arrays before mapping'
});

// Find fix for an error
const fix = await vm.findErrorFix("TypeError: Cannot read property 'map'");
if (fix) {
  console.log(`Fix: ${fix.fixDescription}`);
}

Vercel AI SDK Integration

import { VasperaMemory } from 'vasperamemory-sdk';
import { createVasperaMemoryTools, VasperaMemoryTool } from 'vasperamemory-sdk/vercel-ai';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const vm = new VasperaMemory({ apiKey: 'vm_xxx', projectId: 'proj_xxx' });

// Use individual tools
const result = await generateText({
  model: openai('gpt-4'),
  prompt: 'What caching patterns do we use?',
  tools: {
    searchMemory: VasperaMemoryTool.search(vm),
    captureDecision: VasperaMemoryTool.captureDecision(vm),
  },
});

// Or use all tools at once
const allTools = createVasperaMemoryTools(vm);

System Prompt Enhancement

import { enhanceSystemPrompt } from 'vasperamemory-sdk/vercel-ai';

const basePrompt = 'You are a helpful coding assistant.';
const enhanced = await enhanceSystemPrompt(vm, basePrompt);
// Adds project context from VasperaMemory

Middleware

import { experimental_wrapLanguageModel } from 'ai';
import { createVasperaMemoryMiddleware } from 'vasperamemory-sdk/vercel-ai';

const enhancedModel = experimental_wrapLanguageModel({
  model: openai('gpt-4'),
  middleware: createVasperaMemoryMiddleware(vm),
});

API Reference

Memory Operations

// Capture a memory
const memory = await vm.captureMemory({
  type: 'pattern',  // pattern, decision, or architectural
  content: 'Always use context managers for file operations',
  reasoning: 'Ensures files are properly closed',
  confidence: 0.9
});

// Search memories
const results = await vm.search('file handling', { limit: 10, threshold: 0.7 });

// Get a specific memory
const memory = await vm.getMemory('mem_xxx');

// Delete a memory
await vm.deleteMemory('mem_xxx');

Decision Operations

// Capture a decision
const decision = await vm.captureDecision({
  category: 'architectural',  // architectural, pattern, convention, fix, rejection, preference
  title: 'Use PostgreSQL',
  content: 'Chose PostgreSQL for the database',
  reasoning: 'Need JSONB support and full-text search',
  relatedFiles: ['database.ts', 'models.ts'],
  confidence: 0.95
});

// Get recent decisions
const decisions = await vm.getRecentDecisions({ category: 'architectural', limit: 5 });

Error Fix Operations

// Capture an error fix
const fix = await vm.captureErrorFix({
  errorMessage: 'ConnectionRefusedError: [Errno 111]',
  rootCause: 'Redis server not running',
  fixDescription: 'Start Redis with: redis-server',
  errorFile: 'cache.ts',
  preventionRule: 'Add Redis health check to startup'
});

// Find a fix for an error
const fix = await vm.findErrorFix('ConnectionRefusedError');

// Get recent fixes
const fixes = await vm.getRecentFixes({ limit: 5, days: 7 });

Preference Operations

// Set a preference
const pref = await vm.setPreference({
  category: 'code_style',  // code_style, communication, workflow, tooling, values
  key: 'indent_style',
  value: 'spaces',
  confidence: 1.0
});

// Get preferences
const prefs = await vm.getPreferences({ category: 'code_style', limit: 10 });

Context Operations

// Get session context
const context = await vm.getSessionContext({
  query: 'How do we handle authentication?',
  openFiles: ['auth.ts', 'middleware.ts']
});

// Get fused context
const fused = await vm.fuseContext({
  sources: ['memories', 'specs', 'history'],
  maxTokens: 4000
});
console.log(fused.content);

Error Handling

import {
  VasperaMemory,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  VasperaMemoryError,
} from 'vasperamemory-sdk';

try {
  const vm = new VasperaMemory({ apiKey: 'vm_xxx', projectId: 'proj_xxx' });
  await vm.search('test');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ValidationError) {
    console.log(`Invalid request: ${error.message}`);
  } else if (error instanceof VasperaMemoryError) {
    console.log(`Server error (${error.statusCode}): ${error.message}`);
  }
}

Configuration

Environment Variables

export VASPERAMEMORY_API_KEY=vm_your_api_key
export VASPERAMEMORY_PROJECT_ID=your_project_id

const vm = new VasperaMemory({
  apiKey: process.env.VASPERAMEMORY_API_KEY!,
  projectId: process.env.VASPERAMEMORY_PROJECT_ID!
});

Custom Base URL

// For self-hosted or staging
const vm = new VasperaMemory({
  apiKey: 'vm_xxx',
  projectId: 'proj_xxx',
  baseUrl: 'https://your-server.com',
  timeout: 60000
});

Links

• Website: https://vasperamemory.com
• Documentation: https://docs.vasperamemory.com
• GitHub: https://github.com/RCOLKITT/VasperaMemory
• npm package: https://www.npmjs.com/package/vasperamemory-sdk

License

MIT