hypersave-api

v1.0.0

Published

a month ago

Universal document analysis API - analyze URLs, PDFs, videos, images, and more

Downloads

0High
0Medium
0Low

akhilponnada

document-analysis ai nlp content-extraction

Hypersave: Your AI-Powered Second Brain

A cognitive architecture for human memory - built on neuroscience principles.

Documentation | Platform | API Reference

What is Hypersave?

Hypersave isn't just another document storage system—it's a cognitive architecture that works like your actual brain:

5 Memory Sectors (Episodic, Semantic, Procedural, Emotional, Reflective)
Realistic Decay (memories fade at different rates, just like real memories)
Auto-Learning (synapses inferred from behavior, not manual tags)
Associative Spreading (neural network-like activation)
Working Memory (session-based, ~7±2 items like human cognition)
Context-Aware (time, topics, mood influence retrieval)

Quick Start

Installation

npm install
npm run build
npm start

Environment Variables

GEMINI_API_KEY=your_key_here
SUPABASE_URL=your_url
SUPABASE_SERVICE_ROLE_KEY=your_key
PORT=3005

Your First Save

curl -X POST http://localhost:3005/v1/save \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_key" \
  -d '{
    "content": "I graduated with a CS degree from Stanford in 2020",
    "type": "text",
    "userId": "user-123"
  }'

Your First Query

curl -X POST http://localhost:3005/v1/ask \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_key" \
  -d '{
    "query": "What degree did I get?",
    "userId": "user-123"
  }'

# Response:
{
  "answer": "You graduated with a Computer Science degree from Stanford in 2020.",
  "confidence": "high",
  "verification": {
    "crossCheckPassed": true,
    "groundingScore": 0.95
  }
}

Key Features

🧠 Brain-Like Memory

5 Cognitive Sectors with realistic decay:

Semantic (139 days to 50%) - Facts, knowledge
Episodic (46 days to 50%) - Events, experiences
Procedural (87 days to 50%) - How-to guides
Emotional (35 days to 50%) - Feelings, reactions
Reflective (693 days to 50%) - Insights, wisdom

🔍 Smart Search

3 Tiers (Progressive Disclosure):

Fast (0-100ms) - Core memory + facts cache
Balanced (100-500ms) - Vector + keyword hybrid
Deep (500ms-2s) - Multi-query + RAG synthesis

8+ Search Types:

Semantic, Hybrid, Progressive, Brain, Temporal, Entity, Factual, Context-aware

🎯 Auto-Learning

Synapses - System learns from your behavior:

Interests (topics you save about)
Expertise (knowledge domains)
Goals (active projects)
Preferences (consumption style)
Relationships (people/entities)
Behaviors (patterns)

✅ Verified Answers

Hybrid Verification:

Query cloud RAG
Cross-check with facts
AI verification
Confidence scoring
Auto-fallback if low confidence

📊 Knowledge Graph

Visualize Your Mind:

Documents + Facts connected
Entity relationships
Sector-based coloring
Salience-based sizing
Associative spreading

💾 Universal Ingestion

Save Anything:

Web pages (auto-scraped)
YouTube videos (transcript + analysis)
PDFs, Word docs
Images (OCR + vision)
Raw text, code, conversations

Architecture

┌─────────────────────────────────────────────────────┐
│                   API Layer                         │
│         (Hono REST API - 160+ endpoints)            │
└─────────────┬───────────────────────────────────────┘
              │
┌─────────────┴───────────────────────────────────────┐
│              Service Layer                          │
│  (50+ specialized services)                         │
│  - Brain Features    - Memory Consolidation         │
│  - Search Variants   - Knowledge Graph              │
│  - Fact Extraction   - Synapses Learning            │
│  - Compression       - Working Memory               │
└─────────────┬───────────────────────────────────────┘
              │
┌─────────────┴───────────────────────────────────────┐
│         Memory & Cognition Layer                    │
│  - Sector Classification  - Salience Management     │
│  - Decay Algorithms      - Associative Spreading    │
└─────────────┬───────────────────────────────────────┘
              │
┌─────────────┴───────────────────────────────────────┐
│         Search & Retrieval Layer                    │
│  - Vector Search (pgvector)                         │
│  - Hybrid Search (vector + keyword)                 │
│  - Cloud RAG (FREE storage)                         │
└─────────────┬───────────────────────────────────────┘
              │
┌─────────────┴───────────────────────────────────────┐
│              Storage Layer                          │
│  - Supabase PostgreSQL (primary)                    │
│  - pgvector (embeddings)                            │
│  - Cloud RAG (FREE backup)                          │
└─────────────────────────────────────────────────────┘

API Overview

Consumer API (`/v1/*`) - 12 Endpoints

POST /v1/save         # Save anything
POST /v1/ask          # Verified answers
POST /v1/query        # Multi-strategy search
POST /v1/search       # Document + fact search
POST /v1/remind       # Context reminders
GET  /v1/profile      # User profile
GET  /v1/memories     # List all
GET  /v1/graph        # Knowledge graph
GET  /v1/usage        # Analytics
DELETE /v1/memory/:id # Remove

Advanced API (`/api/*`) - 146+ Endpoints

Categories:

Document Management (11)
Search Variations (15+)
Brain Features (40+)
Chat & RAG (7)
User Facts (8)
Synapses (4)
Knowledge Graph (4)
Memory Blocks (8)
Consolidation (5)
Compression (5)
HSG (6)
Sector Intelligence (5)
Analytics (5)
Cloud RAG (5)
And more...

Full Documentation: COMPLETE_API_REFERENCE.md

Technology Stack

Runtime: Node.js + TypeScript Framework: Hono (fast web framework) Database: Supabase (PostgreSQL + pgvector) AI/ML: Google Gemini (LLM + embeddings) Vector: pgvector (768D embeddings) Search: Hybrid (vector + keyword + reranking) Storage: Cloud RAG (FREE) + Supabase (backup)

Use Cases

For Individuals

Personal Knowledge Management

// Save articles, papers, notes
await hs.save({ content: url, type: 'url' });

// Find anything with natural language
const results = await hs.search('machine learning papers');

// Get your profile
const profile = await hs.getProfile();

Life Logging

// Track experiences
await hs.save({ content: 'Great conversation with Sarah about AI', type: 'text' });

// Remember context
const { answer } = await hs.ask('What did Sarah say about AI?');

For Developers

AI Assistant with Memory

import Hypersave from '@hypersave/client';

const hs = new Hypersave({ apiKey: 'your_key' });

// User saves context
await hs.save({ content: userMessage, userId: user.id });

// AI queries memory
const { answer, confidence } = await hs.ask({
  query: 'What are my current projects?',
  userId: user.id,
  verify: true  // Cross-check for accuracy
});

// Use verified answer
if (confidence === 'high') {
  return answer;
}

Context-Aware Application

// Get user context
const context = await hs.getContext(userId);

// Context-boosted search
const results = await hs.contextualSearch({
  query: 'relevant docs',
  userId
});
// → Returns results boosted by time, recent topics, mood

Performance

Search Latency:

Fast tier: 0-100ms
Balanced tier: 100-500ms
Deep tier: 500ms-2s

Accuracy:

Hybrid search: +10-15% vs vector alone
With reranking: +5-10% additional
Verified mode: Near-perfect (cross-checked)

Cost Efficiency:

FREE storage (Cloud RAG)
FREE query embeddings
Only pay: Initial indexing + LLM tokens

Deployment

Local Development

npm install
npm run build
npm start

Production

# Docker
docker build -t hypersave .
docker run -p 3005:3005 hypersave

# Or deploy to:
# - Vercel, Railway, Fly.io
# - AWS Lambda, Google Cloud Run
# - Cloudflare Workers

Environment Setup

Get API Keys:
- Gemini API: https://ai.google.dev/
- Supabase: https://supabase.com/

Configure .env:

GEMINI_API_KEY=your_key
SUPABASE_URL=your_url
SUPABASE_SERVICE_ROLE_KEY=your_key

Run Migrations:

psql $DATABASE_URL -f supabase/schema.sql

Documentation

Complete API Reference - All 158 endpoints
Capabilities Guide - Features & use cases
Obfuscation Notes - Architecture details

Roadmap

Coming Soon:

[ ] Multi-modal support (audio, video)
[ ] Real-time collaboration
[ ] Mobile apps (iOS/Android)
[ ] Browser extensions
[ ] Notion/Obsidian integrations
[ ] API webhooks
[ ] Custom memory blocks
[ ] Advanced visualizations

Contributing

We welcome contributions! Please see CONTRIBUTING.md.

# Fork the repo
git clone https://github.com/yourusername/hypersave.git

# Create a branch
git checkout -b feature/my-feature

# Make changes and commit
git commit -m "Add my feature"

# Push and create PR
git push origin feature/my-feature

License

MIT License - see LICENSE

Support

Documentation: https://docs.hypersave.ai
GitHub Issues: https://github.com/yourusername/hypersave/issues
Discord: https://discord.gg/hypersave
Email: [email protected]

Citation

If you use Hypersave in your research, please cite:

@software{hypersave2024,
  title = {Hypersave: A Cognitive Architecture for Human Memory},
  author = {Your Name},
  year = {2024},
  url = {https://github.com/yourusername/hypersave}
}

Built on neuroscience. Designed for humans. Enterprise ready.