Architecture Overview

Layered Protocol Model — Obsidian RAG Plugin for OpenClaw

System Boundary Diagram

Architecture: Obsidian RAG Plugin
USER LAYER
Natural Language Query
"How was my mental health in 2024?"
OPENCLAW AGENT
Tool Router
Selects plugin tools based on intent
Session Manager
Tracks plugin health state
↕ Tool Calls & Results
PLUGIN LAYER (TypeScript)
TRANSPORT
Tool Registry
Error Normalizer
SESSION
Vault Watcher
Sync Scheduler
TOOL
search
index / status
memory_store
DATA
LanceDB Client
Indexer Bridge
↕ CLI & Filesystem
DATA LAYER
LanceDB (vectors.lance)
Ollama (localhost:11434)
Obsidian Vault (filesystem)
INDEXER (Python CLI)
obsidian-rag index
obsidian-rag sync
obsidian-rag reindex
obsidian-rag status

Key Design Decisions

Chosen

  • Layered protocol: Transport → Session → Tool → Data
  • Plugin is thin TS wrapper; heavy lifting in Python
  • LanceDB embedded — no server process
  • Vault watcher auto-syncs on file changes
  • Graceful degradation on dependency failures

Rejected

  • Event bus (over-engineered for single plugin)
  • Minimal spec (no protocol contract = ad-hoc)
  • Server-based vector DB (unnecessary complexity)
  • On-demand-only sync (user chose auto-sync)