Core Concepts

Ariv is built on a few core ideas that shape how the app works. Understanding these concepts will help you get the most out of it.

Vaults

A vault is just a folder on your computer that contains Markdown files. That’s it.

Ariv indexes the contents of your vault to power features like search, lifecycle tracking, and auto-tagging, but your notes are always plain .md files in a regular folder. There is no proprietary format, no database-only storage, and no import/export ceremony.

This means:

• Zero migration. Point Ariv at an existing folder of Markdown files and you’re up and running. Obsidian vaults, a folder of notes from any editor, or a freshly created directory — they all work.
• No lock-in. If you ever stop using Ariv, your notes are right where you left them. Open them in any text editor.
• External edits are fine. Edit files in VS Code, Vim, or another app. Ariv watches for changes and updates its index automatically.

Lifecycle Buckets

Every note in Ariv falls into one of three lifecycle buckets based on when it was last modified. This is the 3-bucket system, and it drives how Ariv surfaces what matters.

Inbox

Quick captures, new ideas, and unprocessed notes. When you create a new note or use Quick Capture, it lands in the Inbox. These are notes that haven’t been developed yet.

The Inbox is your “deal with this soon” zone. The goal is to process Inbox items regularly — flesh them out, tag them, merge them into existing notes, or move on.

Active

Notes you’ve touched recently. By default, any note modified within the last 5 days is considered Active. These are the notes you’re currently working with.

Active notes show up prominently on your dashboard and in the sidebar, making it easy to stay focused on what’s in flight.

Customizing the threshold

The 5-day window is configurable. Go to Settings and adjust files.lifecycleThresholdDays to any value between 1 and 90 days. A shorter threshold keeps Active focused on only the most recent work; a longer one gives you more runway before notes drift to Background.

Background

Notes that haven’t been touched in 5+ days. These aren’t forgotten — they’re candidates for your weekly review.

Background notes are where a lot of your accumulated knowledge lives. Ariv’s lifecycle system makes sure these notes aren’t buried but also aren’t cluttering your active workspace. The weekly review feature helps you periodically revisit Background notes to surface anything that deserves renewed attention.

Tags

Tags are a central organizing concept in Ariv. They help you find related notes, filter your vault, and build a web of connected knowledge — without requiring you to maintain a rigid folder hierarchy.

• Manual tags: Add tags directly in your notes using #tag syntax or through the tag editor in the note footer.
• Auto-tags: Ariv can suggest and apply tags automatically (see Auto-Tagging below).
• Tag filtering: Use tags to filter notes in the sidebar, search results, and dashboard views.

Tags are stored as metadata in Ariv’s index. They don’t modify the contents of your Markdown files unless you explicitly write #tag in the note body.

Auto-Tagging

Manually tagging every note gets tedious fast, especially in large vaults. Ariv’s auto-tagging system handles this for you with a two-tier approach:

Tier 1: Heuristic (Free, Local)

This runs entirely on your machine with no API calls and no cost:

• Vault propagation: If many notes about “machine learning” are tagged #ml, Ariv learns to suggest that tag for similar new notes.
• TF-IDF analysis: Ariv identifies the most distinctive terms in a note relative to your vault and suggests tags based on them.
• Heading extraction: Section headings in your notes are used as signal for relevant tags.

Tier 1 tagging runs automatically as you create and edit notes.

Tier 2: AI Refinement

When AI is configured, Ariv can use a language model to refine and improve tag suggestions:

• Understands context and nuance better than heuristics alone.
• Can suggest tags that capture the meaning of a note, not just its keywords.
• Uses your configured AI provider (Gemini, OpenAI, Anthropic, or Ollama).

Note

Tier 2 AI tagging is optional and requires an API key or local Ollama setup. See AI Setup for configuration details. During the beta period, AI features are free to use.

Auto-generated tags appear in the footer of the editor, where you can accept, reject, or edit them.

Ask Brain

Ask Brain is Ariv’s AI-powered Q&A feature. It lets you ask questions about your own notes in natural language, and Ariv synthesizes an answer from your vault.

How it works:

1. You type a question (e.g., “What were the key decisions from last week’s planning meeting?”).
2. Ariv searches your vault using full-text and semantic search to find the most relevant notes.
3. The relevant context is sent to your configured AI provider.
4. You get a synthesized answer with references back to the source notes.

Ask Brain is a form of RAG (Retrieval-Augmented Generation) — the AI only sees the notes that are relevant to your question, not your entire vault. This keeps responses accurate, grounded, and fast.

Tip

Ask Brain works best when your notes have some substance to them. Even rough bullet points are enough — the AI is good at synthesizing fragmented information across multiple notes.

Local-First

Ariv is local-first by design. This means:

• All data stored on your machine. Your notes, the search index, tags, and settings all live on your local filesystem. Nothing is uploaded to a server.
• No account required. You can use Ariv fully without creating an account, signing in, or providing an email address.
• AI is optional. Every core feature — note editing, search, lifecycle buckets, tags, dashboard — works without any AI provider configured. AI enhances the experience but is never required.
• Works offline. Since everything is local, Ariv functions perfectly without an internet connection. The only features that need connectivity are AI-powered ones (Ask Brain, Tier 2 auto-tagging, semantic search) when using a cloud API provider.

Your notes are your data. Ariv is a tool that works with them, not a service that holds them.

Structure-Agnostic

Ariv follows a philosophy of being “outcome-opinionated, structure-agnostic.”

This means Ariv has opinions about the outcomes it drives (surfacing relevant knowledge, keeping your notes healthy, making sure nothing falls through the cracks) but is deliberately agnostic about how you organize your files.

• PARA method? Works great. Ariv indexes everything regardless of folder structure.
• Zettelkasten? Ariv’s backlinks and auto-tagging complement this perfectly.
• GTD? The lifecycle buckets and action items map naturally to GTD workflows.
• No system at all? That works too. Dump everything in one folder and let Ariv’s search, tagging, and lifecycle tracking bring order to the chaos.

You don’t need to reorganize your notes to fit Ariv. Ariv fits your notes.

---

Next steps:

• Dashboard — learn about your home base in Ariv
• Ask Brain — dive deeper into AI-powered Q&A
• AI Setup — configure an AI provider for enhanced features