Vector Notes

• Vector search your notes for similar headings in org-roam.
  • Embedding Defaults
  • Retrieval Quality Notes
  • Emacs Integration
  • Background Indexer Service (inotify)
    • Config file
    • Run
  • Logging Configuration
    • Environment Variables
    • Command Line Options
    • Configuration File
    • Default Behavior

Vector search your notes for similar headings in org-roam.

Embedding Defaults

• Default model is now all-MiniLM-L6-v2 (SentenceTransformers).

• The embedder applies instruction prefixes by default:

  • nomic-embed* models: search_document: for indexed text and search_query: for queries
  • *e5* models: passage: for indexed text and query: for queries
  • everything else: a retrieval-focused natural-language instruction
• You can override either side with CLI flags:

# custom prefixes
python main.py embed --dir ~/org --ingestion-instructions "passage:"
python main.py search --query "project roadmap" --query-instructions "query:"

# template form using {text}
python main.py embed --dir ~/org \
  --ingestion-instructions "Represent this note for retrieval: {text}"

Retrieval Quality Notes

• Re-embedding now replaces existing entries for each source file, which prevents duplicate chunks from older indexing runs.
• Nodes without explicit Org ID properties receive stable auto-generated storage IDs, so repeated indexing remains consistent.
• Search now applies simple result diversification to avoid over-returning many near-identical chunks from one file.
• Embed now performs incremental sync by file metadata (mtime + size): unchanged files are skipped, changed files are re-indexed, and removed files are deleted from the collection.
• Embedding runs in batches to reduce peak memory usage during indexing.
• update is an alias for embed.
• query is accepted as an alias for search, so both commands work:

python main.py query --query "Python code"
python main.py search --query "Python code"
python main.py update --dir ~/org --path ~/.cache/org-vector/

• Search, emacs, and json output modes accept -k/--results to control the number of results (default: 5):

python main.py search --query "Python code" --results 10

• Ingest now skips path matches like directories that happen to end in .org.

Emacs Integration

lisp/org-vector.el ships with the package (installed to share/emacs/site-lisp by the flake). Core commands:

Command	Description
M-x org-vector-search	Async vector search, results in a side window
M-x org-vector-search-at-point	Search the word/region at point
M-x org-vector-embed	Index org files (incremental)
M-x org-vector-start-service / org-vector-stop-service	Background inotify service
M-x org-vector-gptel-query	Insert search results at point
M-x org-vector-transient	Transient menu for everything above
M-x org-vector-stop-all	Kill all running org-vector processes

Customize org-vector-dir, org-vector-db, org-vector-model, and org-vector-collection-name to match your setup. The gptel tool org_vector_search is registered automatically when gptel is loaded.

Requires Emacs 27.1+; subr-x and transient are required explicitly, so loading the file is self-contained.

Background Indexer Service (inotify)

Run continuous indexing with Linux inotify by using serve mode. The service performs one initial sync, then watches your Org directory and re-runs incremental sync when .org files change.

This mode is Linux-specific and requires the Python package inotify-simple.

Config file

The service reads ~/.config/org-vector/config.toml by default. You can copy and adapt config.toml.example:

mkdir -p ~/.config/org-vector
cp config.toml.example ~/.config/org-vector/config.toml

Minimal config:

[service]
dir = "~/Documents/Notes/"
path = "~/.cache/vector-org/"
model = "all-MiniLM-L6-v2"
collection = "org-roam"

[logging]
level = "INFO"
to_file = false

Run

# use default ~/.config/org-vector/config.toml
python main.py serve

# or provide a custom config path
python main.py serve --config /path/to/config.toml

Optional serve-time overrides are available with normal flags (for example --dir, --path, --model, --collection, --debounce-seconds, --poll-timeout-ms).

When started through nix run .# -- ..., the wrapper now installs a default config at ~/.config/org-vector/config.toml on first run if it does not already exist.

Logging Configuration

The logger is configurable and by default only logs errors. You can configure logging in three ways:

Environment Variables

# Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
export VECTOR_ORG_LOG_LEVEL=INFO

# Enable file logging
export VECTOR_ORG_LOG_TO_FILE=true

# Set custom log directory
export VECTOR_ORG_LOG_DIR=/path/to/logs

Command Line Options

# Set log level
python main.py --log-level INFO embed --dir ~/org

# Enable file logging
python main.py --log-to-file embed --dir ~/org

# Set custom log directory
python main.py --log-dir /path/to/logs embed --dir ~/org

Configuration File

Copy logging.conf.example to logging.conf and set your preferred values, then source it:

source logging.conf
python main.py embed --dir ~/org

Default Behavior

• Log level: ERROR (only errors are logged)
• File logging: Disabled
• Console logging: Always enabled for errors and above