🧠 VectorMind — Local-First AI Study Assistant

Write notes. VectorMind watches you, understands what you wrote, compares it against everything you've studied, and tells you instantly — what's right, what's wrong, and what's missing.

---

✨ Features

🔴 Live Study Agent (flagship feature)

The most powerful feature — a real-time AI tutor that watches your notes folder and gives you structured feedback every time you save a .txt file.

What it does	How it helps you
Already-studied detector	"You covered this in ML/week2.txt — don't re-learn it, connect it!"
Correctness check	Flags factual errors or vague definitions you wrote
Incompleteness detector	Points out what's missing from your notes
Smart suggestions	Tells you what to study next based on your vault
Encouragement	A short motivational message after every save

The Live Agent tab auto-refreshes every 5 seconds — just write in any editor (VS Code, Notepad, Obsidian…) and watch the feedback appear.

---

📚 Knowledge Vault

• Semantic search across all your notes using local embeddings (no API key needed)
• Notes are embedded automatically into LanceDB on every file save
• Near-duplicate detection prevents redundant indexing

🕸️ Knowledge Graph

• Interactive force-directed graph of your entire vault
• Nodes = notes, edges = semantic similarity
• Color-coded by top-level topic folder
• Drag, zoom, hover — powered by PyVis

📖 Study Room

On-demand AI actions (button-click, no background processing):

• Summarize — 3-5 sentence summary + key terms
• Generate quiz — 4 Q&A pairs grounded in your notes
• Explain simply — beginner-friendly re-explanation
• Flashcards — JSON export for Anki/other tools
• Structured notes — full standalone HTML page with sections, quizzes, and toggles
• Reactive notes lab — AI generates typed blocks (text, list, quiz, image, reference) you can iteratively refine

✍️ Writer

Built-in note editor that saves directly into the notes/ hierarchy and triggers the watcher immediately.

📊 Insights

Stats about your vault: indexed count, most recent saves, topics by frequency.

🌳 Library

Notion-style sidebar view of your notes/ folder tree.

---

🏗️ Architecture

┌─────────────────────────────────────────────┐
│                 notes/*.txt                  │  ← You write here (any editor)
└──────────────────────┬──────────────────────┘
                       │ file save
                       ▼
┌─────────────────────────────────────────────┐
│           watcher.py  (watchdog)             │  ← Detects every .txt save
└──────┬───────────────────────────┬──────────┘
       │ index (no LLM)            │ analyze (background)
       ▼                           ▼
┌────────────┐             ┌──────────────────┐
│  ingest.py  │             │  live_agent.py   │
│ embed+store │             │ diff + vault RAG │
└─────┬──────┘             │ → Ollama (llama)  │
      │                    └────────┬─────────┘
      ▼                             │ review JSON
┌────────────┐             ┌────────▼─────────┐
│  LanceDB   │◄────────────│  event queue     │
│  (vector   │             │  (deque, max 50) │
│   store)   │             └────────┬─────────┘
└────────────┘                      │ poll every 5s
                           ┌────────▼─────────┐
                           │    ui.py (Gradio) │  ← You see feedback here
                           │  🔴 Live Agent tab│
                           └──────────────────┘

All AI runs locally — Ollama serves the llama3.2:1b model, BGE-small embeddings run via sentence-transformers. No data leaves your machine.

---

⚡ Quick Start

1. Prerequisites

• Python 3.12+
• Ollama installed and running
• uv package manager (recommended) or pip

2. Install Ollama and pull the model

# Install Ollama from https://ollama.com/download (Windows/Mac/Linux)
ollama serve                    # start the Ollama server (leave running)
ollama pull llama3.2:1b         # download the model (~1 GB)

You can use a larger model (e.g. llama3.2:3b, mistral) by changing OLLAMA_MODEL in ai_engine.py and live_agent.py.

3. Clone and install dependencies

git clone <your-repo-url>
cd study-assistant

# Option A: uv (fast, recommended)
pip install uv
uv sync

# Option B: plain pip
pip install -r requirements.txt   # or: pip install gradio lancedb sentence-transformers watchdog requests pyvis pandas

4. Run

# With uv
uv run python main.py

# With plain Python
python main.py

The app will open at http://localhost:7860 in your browser.

---

📂 Project Structure

study-assistant/
├── main.py              # Entry point — starts watcher thread + Gradio UI
├── watcher.py           # Watchdog observer — detects .txt saves, triggers indexing + live agent
├── live_agent.py        # 🔴 Live Study Agent — diff, vault RAG, Ollama review, event queue
├── ai_engine.py         # On-demand RAG functions (summarize, quiz, explain, flashcards, …)
├── prompts.py           # Prompt templates for all LLM calls
├── ingest.py            # Clean → embed → LanceDB (no LLM)
├── processor.py         # Text cleaning utilities
├── ui.py                # Gradio dashboard (all 7 tabs)
├── graph_viz.py         # Knowledge graph builder (PyVis)
├── library_tree.py      # Folder tree renderer
├── memory/
│   ├── embedding.py     # BGE-small sentence-transformers wrapper
│   └── vector_store.py  # LanceDB CRUD + search + insights
├── notes/               # ← Write your .txt notes HERE (auto-created)
│   └── Topic/
│       └── Chapter/
│           └── page.txt
├── db/                  # LanceDB vector database (auto-created)
├── output/              # Exported files (graph.html, flashcards.json, …)
└── pyproject.toml       # Dependencies

---

🔴 Using the Live Agent

1. Start the app (python main.py) — the watcher starts automatically.
2. Open the 🔴 Live Agent tab in the Gradio UI.
3. Edit any .txt file in the notes/ folder using your favourite editor.
4. Save the file (Ctrl+S).
5. Within ~10–30 seconds, the Live Agent tab will show a review card:

📄 `my_note.txt` · 14:32:07 · ✏️ +42 chars
🔗 Related vault notes: `ML/week2.txt`, `CS101/arrays.txt`

#### 📚 You've already studied this!
- Binary Search Trees (from `CS101/trees.txt`) — you covered AVL rotations here

#### ✅ What looks correct
- The definition of a node is accurate
- Time complexity of search is correctly stated as O(log n)

#### ⚠️ Wrong or incomplete
- ❌ Insertion complexity stated as O(1)
  - 💬 Fix: Insertion in a BST is O(log n) average, O(n) worst case

#### 💡 Next steps
- Add a comparison with AVL trees and Red-Black trees
- Cover the deletion algorithm with all 3 cases

> 🌟 Great progress — your understanding of tree fundamentals is solid!

The feed auto-refreshes every 5 seconds. Use Refresh now for instant update.

---

⚙️ Configuration

Setting	File	Default	Description
LLM model	ai_engine.py, live_agent.py	llama3.2:1b	Any Ollama-served model
Ollama URL	ai_engine.py, live_agent.py	http://localhost:11434	Change if Ollama runs remotely
Embedding model	memory/embedding.py	BAAI/bge-small-en-v1.5	Any sentence-transformers model
Notes directory	ingest.py	notes/	Relative to project root
Debounce delay	watcher.py	2.5s	Wait time after last file write
Agent feed size	live_agent.py	50 events	Max events kept in memory
UI refresh rate	ui.py	5s	gr.Timer interval

---

🧑‍💻 Development

# Run just the watcher (no UI)
python watcher.py

# Run just the UI (no live-agent)
python -c "from ui import launch_ui; launch_ui()"

# Manually trigger the live agent on a file
python -c "
from live_agent import analyze_note_change
r = analyze_note_change('notes/test.txt', open('notes/test.txt').read())
import json; print(json.dumps(r, indent=2))
"

---

📋 Dependencies

Package	Purpose
gradio	Web UI
watchdog	File system monitoring
lancedb	Local vector database
sentence-transformers	BGE-small embeddings (local)
requests	Ollama HTTP API
pyvis	Knowledge graph visualization
pandas	Data manipulation for LanceDB

---

🚀 Roadmap

• Multi-file diff view in Live Agent
• Spaced repetition scheduler based on vault history
• Export vault to Anki deck (.apkg)
• Support for .md and .pdf notes
• Live Agent webhook / desktop notification

---

📄 License

MIT — use it, fork it, learn from it.

---

Built with ❤️ for learners who take notes. Powered by local AI — your data never leaves your machine.