Tool Layer

Four Plugin Tools, Their Contracts & the OpenClaw Interaction Protocol

Tool 1: obsidian_rag_search

Primary semantic search tool
PARAMETERS
query (required) string
Natural language question
max_results (opt) int, default 5
Max chunks to return (1-50)
directory_filter (opt) string[]
Limit to subdirs e.g. ["Journal"]
date_range (opt) {from, to}
ISO 8601 dates
tags (opt) string[]
Filter by hashtags
RESPONSE data
results: [{
chunk_text: string
score: number (0-1)
source_file: string
section: string | null
date: string | null
tags: string[]
chunk_index: number
}]
sensitive_detected: boolean
If true, agent should confirm before display

Tool 2: obsidian_rag_index

Trigger indexing from within OpenClaw
PARAMETERS
mode (required) enum
"full" | "sync" | "reindex"
full: initial index of entire vault
sync: incremental (mtime diff only)
reindex: nuke + rebuild from scratch
RESPONSE data
indexed_files: number
total_chunks: number
duration_ms: number
errors: [{file, message}]
Long-running: returns immediately with
job_id, agent polls via status tool

Tool 3: obsidian_rag_status

Index health and sync state
PARAMETERS
(none — always returns current state)
RESPONSE data
plugin_health: "healthy"|"degraded"|"unavailable"
total_docs: number
total_chunks: number
last_sync: string (ISO 8601)
unindexed_files: number
ollama_status: "up" | "down"
active_job: {id, mode, progress} | null

Tool 4: obsidian_rag_memory_store

Commit facts to OpenClaw memory for faster retrieval
PARAMETERS
key (required) string
Identifier for the fact
value (required) string
The fact to remember
source (required) string
Source file path in vault
RESPONSE data
stored: boolean
key: string (echoed back)
Auto-suggest: When search results
match financial/health/commitment
patterns, plugin flags
sensitive_detected=true and includes
memory_suggestion with key/value

OpenClaw Interaction Protocol

How the agent decides which tool to use and when
INTENT → TOOL MAPPING
User Intent Pattern Tool Agent Behavior
"What did I write about X?"
"How was my Y in Z?"		 search Query vault, synthesize answer from chunks
"Index my vault"
"Update the search index"		 index Choose mode (sync default, full on no index), poll status
"Is the index up to date?"
"How many docs are indexed?"		 status Report health, suggest index if stale
"Remember this"
Auto-suggest after search		 memory_store Confirm with user, store key+value+source
PROTOCOL SEQUENCE
1. Agent receives user query with vault-related intent
2. Agent calls obsidian_rag_status (if first interaction or >5min since last check)
→ Skips if status already cached and healthy
3. If unavailable → agent suggests running obsidian_rag_index (mode: "full")
4. If degraded → agent warns user but proceeds with search
5. Agent calls obsidian_rag_search with appropriate filters
6. If sensitive_detected=true → agent confirms before displaying
7. Agent synthesizes answer from chunks + existing knowledge
8. If memory_suggestion present → agent asks if user wants to store
→ User confirms → obsidian_rag_memory_store