BrainVaultAI

BrainVaultAI is a personal second-brain system for capturing knowledge from notes, text, links, PDFs, images, and video, then turning that content into searchable, source-backed knowledge.

What It Does

• ingest raw content
• clean and normalize it
• generate summaries and metadata
• store embeddings and relationships
• support retrieval with cited evidence

Current Scope

• FastAPI backend in apps/api
• Next.js frontend in apps/web
• ingestion for notes, text, URLs, PDFs, images, Telegram media, and video URLs
• optional OpenAI enrichment for OCR, summaries, and embeddings
• optional PostgreSQL, Qdrant, and Neo4j adapters for durable storage
• VideoDB-backed video transcript and spoken-word indexing when configured

Knowledge Flow

Raw Input
   |
   v
Ingest
   |
   v
Normalize / Clean
   |
   v
Summarize / Tag / Embed
   |
   v
Store
   |
   +--> Canonical data
   +--> Vector index
   +--> Graph relations
   |
   v
Retrieve / Answer with Sources

Delivery Workflow

Planner --> Tester --> Coder --> Reviewer --> Optimizer

• Planner: lock scope, interfaces, data flow, failure cases, and acceptance criteria
• Tester: write failing tests first
• Coder: implement the smallest correct slice
• Reviewer: check correctness, regressions, security, and coverage gaps
• Optimizer: improve structure without changing behavior

Quick Start

1. Copy .env.example to .env.
2. Set:

BRAINVAULT_USE_IN_MEMORY_STORE=true
BRAINVAULT_USE_QDRANT=false
BRAINVAULT_USE_NEO4J=false
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api

3. Install and run:

pip install -r apps/api/requirements.txt
cd apps/api
uvicorn app.main:app --reload

In another terminal:

npm install
npm run dev

Optional Services

• OPENAI_API_KEY for OCR, summaries, and embeddings
• VIDEODB_API_KEY for live video ingestion and transcript indexing
• TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET for Telegram ingestion
• docker compose up -d postgres qdrant neo4j for durable local infrastructure

API Surface

• POST /api/items
• POST /api/items/upload-pdf
• POST /api/items/upload-image
• POST /api/media/video
• GET /api/items
• GET /api/items/{id}
• GET /api/search?q=...
• GET /api/answer?q=...
• GET /api/related/{id}
• GET /api/relationships/{id}

Docs

• Product and architecture plan: docs/brainvault-plan.md
• Agent operating rules: AGENTS.md