JavaScript / TypeScript SDK

The official JavaScript SDK for Hypersave with full TypeScript support.

Installation

npm install hypersave

Quick Start

import { HypersaveClient } from 'hypersave';
 
const hypersave = new HypersaveClient({
  apiKey: process.env.HYPERSAVE_API_KEY,
});
 
// Save content
const { documentId } = await hypersave.save({
  content: 'Meeting notes: Discussed Q1 roadmap...',
  title: 'Q1 Planning Meeting',
  tags: ['meetings', 'planning'],
});
 
// Ask a question
const { answer } = await hypersave.ask({
  query: 'What was discussed in the Q1 planning meeting?',
});
 
console.log(answer);

Configuration

import { HypersaveClient } from 'hypersave';
 
const hypersave = new HypersaveClient({
  apiKey: 'hs_live_xxxxx',
 
  // Optional configuration
  baseUrl: 'https://api.hypersave.io',  // Custom API endpoint
  timeout: 30000,                        // Request timeout (ms)
  retries: 3,                            // Auto-retry count
  debug: false,                          // Enable debug logging
});

Core Methods

save()

Save content to Hypersave.

interface SaveOptions {
  content?: string;
  url?: string;
  title?: string;
  description?: string;
  tags?: string[];
  metadata?: Record<string, any>;
  spaceId?: string;
  async?: boolean;
}
 
const result = await hypersave.save({
  content: 'Your content here',
  title: 'Document Title',
  tags: ['tag1', 'tag2'],
});
// { success: true, documentId: 'doc_xxx' }

ask()

Ask questions about your memories.

interface AskOptions {
  query: string;
  limit?: number;
  spaceId?: string;
  filters?: {
    tags?: string[];
    after?: string;
    before?: string;
  };
  includeContext?: boolean;
}
 
const result = await hypersave.ask({
  query: 'What is our Q1 budget?',
  includeContext: true,
});
// { success: true, answer: '...', context: [...] }

search()

Semantic search across memories.

interface SearchOptions {
  query: string;
  limit?: number;
  offset?: number;
  threshold?: number;
  tags?: string[];
  hybrid?: boolean;
}
 
const { results } = await hypersave.search({
  query: 'machine learning',
  limit: 10,
  hybrid: true,
});

memories.list()

List all memories.

const { data, pagination } = await hypersave.memories.list({
  limit: 20,
  tags: ['important'],
});

memories.delete()

Delete a memory.

await hypersave.memories.delete('doc_xxx');

Advanced Usage

Streaming Responses

const stream = await hypersave.ask({
  query: 'Summarize the meeting notes',
  stream: true,
});
 
for await (const chunk of stream) {
  process.stdout.write(chunk);
}

Bulk Operations

const { jobId } = await hypersave.ingest({
  items: [
    { content: 'Document 1...', tags: ['batch'] },
    { content: 'Document 2...', tags: ['batch'] },
    { url: 'https://example.com/article' },
  ],
  async: true,
});
 
// Check status
const status = await hypersave.ingest.status(jobId);

Error Handling

import { HypersaveClient, HypersaveError, RateLimitError } from 'hypersave';
 
try {
  await hypersave.save({ content: '...' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof HypersaveError) {
    console.log(`API error: ${error.message}`);
  } else {
    throw error;
  }
}

TypeScript Types

import type {
  SaveOptions,
  SaveResult,
  AskOptions,
  AskResult,
  SearchOptions,
  SearchResult,
  Memory,
  Entity,
  Fact,
} from 'hypersave';
 
const options: SaveOptions = {
  content: 'Hello',
  tags: ['greeting'],
};
 
const result: SaveResult = await hypersave.save(options);

React Hooks (Coming Soon)

import { useHypersave, useSearch, useAsk } from '@hypersave/react';
 
function MyComponent() {
  const { data, isLoading } = useSearch({ query: 'meetings' });
  const { ask, answer, isAsking } = useAsk();
 
  return (
    <div>
      <button onClick={() => ask('What is the status?')}>
        Ask
      </button>
      {answer && <p>{answer}</p>}
    </div>
  );
}

React hooks package coming soon! Star the GitHub repo (opens in a new tab) to be notified.

Examples

Next.js API Route

// pages/api/search.ts
import { HypersaveClient } from 'hypersave';
import type { NextApiRequest, NextApiResponse } from 'next';
 
const hypersave = new HypersaveClient({
  apiKey: process.env.HYPERSAVE_API_KEY!,
});
 
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }
 
  const { query } = req.body;
  const results = await hypersave.search({ query });
 
  res.json(results);
}

Express Middleware

import { HypersaveClient } from 'hypersave';
 
const hypersave = new HypersaveClient({
  apiKey: process.env.HYPERSAVE_API_KEY,
});
 
// Attach to request
app.use((req, res, next) => {
  req.hypersave = hypersave;
  next();
});
 
app.post('/api/save', async (req, res) => {
  const result = await req.hypersave.save(req.body);
  res.json(result);
});

Overview Python