---

Run Locally in 60 Seconds

Requires Python 3.10+

# 1. Clone and install
git clone https://github.com/labrat-0/RatVault.git
cd RatVault
pip install -r requirements.txt

# 2. Start the dashboard
python ingest.py --serve

Open http://localhost:8055 — that's it.

Want to chat with your notes using an LLM?

# Option A — Local (no API key needed, free):
#   Install Ollama from https://ollama.ai, then:
ollama pull mistral
python ingest.py --setup   # choose: ollama → mistral:7b-instruct

# Option B — OpenAI / Anthropic / OpenRouter:
python ingest.py --setup   # follow the wizard

Add your first note:

# Drop any .md or .pdf file into inbox/, then:
python ingest.py           # process → saves to Notes/
python ingest.py --dry-run # preview without writing

See QUICKSTART.md for a walkthrough and SETUP.md for all options.

---

RatVault is a flexible, open-source knowledge management system that ingests raw notes, processes them with any LLM provider, and organizes them into a beautiful Obsidian-native vault.

✨ Features

• 🤖 Multi-LLM Support — Works with OpenAI, Anthropic (Claude), Ollama (local), OpenRouter, and more
• 📝 Raw → Structured — Auto-generates summaries, tags, and cross-references from raw markdown
• 🖼️ Media Preservation — Automatically handles images, videos, and media files
• 🌐 PWA Dashboard — Web interface that works offline (no build step required)
• 🔭 Obsidian Native — Vault structure works directly in Obsidian with Dataview support
• ⚡ Zero Setup — One command to start: python ingest.py --setup

---

📖 Configuration

Provider Setup

Choose one of these methods:

Option A: .env file

cp .env.example .env
# Edit .env with your settings

OpenAI:

RATVAULT_PROVIDER=openai
RATVAULT_MODEL=gpt-4o-mini
OPENAI_API_KEY=sk-...

Anthropic (Claude):

RATVAULT_PROVIDER=anthropic
RATVAULT_MODEL=claude-3-haiku-20240307
ANTHROPIC_API_KEY=sk-ant-...

Ollama (Local):

RATVAULT_PROVIDER=ollama
RATVAULT_MODEL=llama3.2
OLLAMA_BASE_URL=http://localhost:11434

OpenRouter:

RATVAULT_PROVIDER=openrouter
RATVAULT_MODEL=anthropic/claude-3-haiku
OPENROUTER_API_KEY=sk-or-...

Option B: config.yaml

cp config.yaml.example config.yaml
# Edit config.yaml

Option C: Interactive Wizard

python ingest.py --setup

---

💻 Usage

Basic Ingest

# Preview changes without writing
python ingest.py --dry-run

# Process files from inbox/ folder
python ingest.py

# Force re-process even if already ingested
python ingest.py --force

# Specify custom input directory
python ingest.py /path/to/files

# Switch provider temporarily
python ingest.py --provider anthropic --model claude-3-haiku

Vault Structure

RatVault/
├── inbox/              # Drop raw files here (.md, .txt, .pdf)
├── Notes/              # Processed entries (Obsidian vault)
│   ├── entry1.md
│   └── entry2.md
├── assets/
│   ├── images/         # Extracted images
│   └── videos/         # Extracted videos
├── Templates/          # Obsidian templates
├── .obsidian/          # Obsidian configuration
├── dashboard/          # Web dashboard (PWA)
├── pipeline/           # Ingest pipeline (config, providers, parser, writer)
├── serve.py            # FastAPI backend
└── ingest.py           # CLI entry point

Entry Format

Each processed entry is Markdown with YAML frontmatter:

---
title: "My Research Note"
slug: "my-research-note"
created: "2026-04-25"
ingested_at: "2026-04-25T14:32:11Z"
summary: "3-sentence summary auto-generated by LLM"
tags: [research, ml, notes]
category: research
difficulty: intermediate
key_concepts: [concept1, concept2]
questions_answered: [question1, question2]
source_file: "inbox/raw-note.md"
provider: claude
model: "claude-3-haiku-20240307"
cross_refs: ["[[Related Note]]"]
assets:
  - {type: image, path: "assets/images/slug/diagram.png"}
status: active
type: note
---

# My Research Note

Content here...

🌐 Web Dashboard

Run python ingest.py --serve and open http://localhost:8055

Features:

• 🔍 Search — Full-text search over entries and tags
• 📅 Timeline — Browse entries by date (newest first)
• 🖼️ Gallery — View all extracted images and videos
• 📊 Analytics — Charts: entries per day, tags cloud, provider usage
• ⚙️ Settings — Change provider, model, and API key
• 📲 Installable — Add to home screen as PWA (offline support)

---

🏗️ How It Works

The Ingest Pipeline

1. Discover — Scan inbox/ for .md, .txt, .pdf files
2. Parse — Extract title, strip existing frontmatter
3. Media Extraction — Copy images/videos to assets/, rewrite links
   • Local images: ![alt](path) → copied to assets/images/{slug}/
   • YouTube/Vimeo URLs: wrapped in > [!video] callout
   • Video files: copied to assets/videos/{slug}/
4. LLM Enrichment — Call your configured LLM to generate:
   • Auto-title (if not detected)
   • Summary (2-3 sentences)
   • Tags (5-10 kebab-case)
   • Category (security|development|research|personal|reference|workflow)
   • Key concepts and questions answered
5. Write — Save as Markdown with YAML frontmatter to Notes/
6. State Tracking — Remember processed files to avoid re-processing

All files are skipped if already processed (unless --force is used).

Multi-LLM Abstraction

providers.py supports 4 LLM providers with a unified interface:

response = call_llm(prompt, system_message, config)
# Returns: LLMResponse(content, model, provider, tokens, duration)

Retry logic: 3 attempts with exponential backoff (1s → 2s → 4s)

---

📚 Obsidian Integration

The vault root is a valid Obsidian vault. Just open it:

File → Open folder as vault → Select repo root

Recommended Plugins

Already configured:

• Dataview — Query entries as tables/lists
• Templater — Template system for new notes
• Obsidian Git — Auto-commit changes
• Calendar — Browse by date
• QuickAdd — Shortcuts for common actions

Dataview Examples

List all entries from Claude:

TABLE summary, tags
FROM "Notes"
WHERE provider = "anthropic"
SORT ingested_at DESC

Find draft entries:

LIST
FROM "Notes"
WHERE status = "draft"
SORT created DESC

---

🔒 API Key Safety

• API keys are stored in .env or config.yaml
• Both files are in .gitignore — they won't commit to git
• The web dashboard (serve.py) masks API key inputs
• Local Ollama doesn't require an API key

---

❓ Troubleshooting

Q: Ingest hangs or is slow
A: Check that your LLM provider is running. For Ollama: ollama serve. For OpenAI/Claude: check your internet connection.

Q: "No files found in inbox"
A: Make sure .md, .txt, or .pdf files exist in the inbox/ folder. Files are case-sensitive.

Q: Images don't show in Obsidian
A: Make sure relative paths are correct. Images should be in assets/images/{slug}/. Check > [!video] callouts.

Q: Web dashboard won't start
A: Make sure fastapi and uvicorn are installed: pip install fastapi uvicorn. Port 8055 might be in use; check with lsof -i :8055.

---

🤝 Contributing

PRs welcome! Areas for contribution:

• Support for more file formats (docx, odt, etc.)
• Additional LLM providers
• Enhanced media handling
• Dashboard improvements
• Documentation

---

📜 Credits

🙏 Andrej Karpathy for the "recipes" concept that inspired this entire system. His insights about structured, reproducible workflows shaped RatVault's design.

---

📄 License

MIT

---

❔ FAQ

Can I use this without an API key?
Yes! Use Ollama (local LLM). Download from ollama.ai.

Can I import existing notes?
Yes. Drop them in inbox/ and run python ingest.py.

Can I switch LLM providers?
Yes, anytime. Just change .env or config.yaml and re-run ingest.py --force.

Is the vault data portable?
Yes. The vault is just Markdown files. Open in any text editor, move to another Obsidian vault, or use elsewhere.

Can I use this for production?
RatVault is designed for personal knowledge management. For production use, consider self-hosting a backend or using an external service.

---

🚀 Getting Help

• Browse Notes/ for example processed entries
• Review config.yaml.example for all configuration options
• Run python ingest.py --help for all CLI flags
• Open an issue on GitHub

---

Made with 🖤 by labrat
Inspired by Andrej Karpathy's recipes for training neural networks.