LZ/01

CASE STUDY / LOCAL AI SYSTEM

ObsAgent CLI

Active refactor

An evidence-bounded local AI workflow for Obsidian

ObsAgent CLI is a local-first AI workflow for Obsidian Vaults. It combines safe Markdown parsing, context-aware chunking, rebuildable SQLite indexes and hybrid retrieval with citation-bounded answers and approval-gated file edits protected by optimistic concurrency and recovery transactions.

View code Current boundaries

01 / PRODUCT BRIEF

Why local knowledge AI should be more than a chat box

Plain full-text search is not enough for cross-document questions, while uploading an entire Vault to a remote model creates privacy, cost and context-control risks. ObsAgent CLI is not just another chat box: it turns parsing, indexing, retrieval, evidence-grounded answering and file writes into one local-first, verifiable and recoverable workflow.

  • Keep Obsidian Markdown as the source of truth while making the index fully rebuildable
  • Combine keyword, vector and graph retrieval to reduce the blind spots of any single strategy
  • Bind answers to bounded evidence and abstain when evidence or citations are not reliable
  • Keep Agent steps, tool calls and error loops within explicit limits
  • Require previews, approval, concurrency checks and recoverable transactions for every file write
ObsAgent CLI architecture showing the Obsidian Vault, Python application, SQLite retrieval index, local or remote models and approval-gated write path
The Vault remains the source of truth; retrieval and answering are separated from approval-gated file writes.

02 / SYSTEM FLOW

How a question and a file edit are completed

  1. 01

    Parse

    The scanner reads the Vault without executing Markdown HTML, JavaScript or Dataview, while extracting front matter, headings, paragraphs, code blocks, callouts, WikiLinks and tags.

  2. 02

    Index

    The context-aware chunker preserves heading breadcrumbs and paragraph boundaries, then writes SQLite metadata, FTS5 records and sqlite-vec embeddings. Content hashes drive incremental updates and move detection.

  3. 03

    Retrieve

    A query can use keyword, vector or graph search. Hybrid retrieval fuses rankings with RRF and reports visible degradation when semantic capabilities are unavailable.

  4. 04

    Answer

    ContextBuilder reloads original content from SQLite, bounds evidence, context and output sizes, labels sources such as [S1], then validates and repairs model citations or abstains.

  5. 05

    Approve

    Write tools first produce a ChangeSet and Diff, pause for explicit human approval, then validate paths and original hashes before applying a transactional Vault change.

03 / ENGINEERING DECISIONS

AI engineering decisions visible in the code

  1. 01

    Keep the Vault as the source of truth

    ImplementationMarkdown files are authoritative; SQLite, FTS5 and sqlite-vec are derived indexes that can be deleted and rebuilt. Incremental indexing skips unchanged content and recognizes unique moves or renames through content hashes.

    ValueRecovery is designed around restoring the source files rather than trusting an opaque database, reducing the risk of index corruption and migration lock-in.

  2. 02

    Preserve Markdown semantics during chunking

    ImplementationChunks retain heading breadcrumbs and keep code blocks, callouts and Block ID paragraphs atomic. The chunker splits at paragraph boundaries and produces stable raw_content and embedding_text values.

    ValueCode and explanation are less likely to be separated by arbitrary character limits, while stable content supports embedding reuse, citations and incremental indexing.

  3. 03

    Use hybrid retrieval instead of vector search alone

    ImplementationSQLite FTS5 handles keyword search, sqlite-vec handles semantic search, WikiLink relationships provide graph retrieval, and Hybrid mode fuses the rankings with Reciprocal Rank Fusion.

    ValueExact terminology, natural-language intent and document relationships each have a suitable retrieval path without introducing a separate vector database or search cluster.

  4. 04

    Constrain answers to verifiable evidence

    ImplementationAnswering reloads original content instead of relying on FTS snippets, bounds evidence, context and output, annotates sources and validates citations. It abstains when the evidence is insufficient.

    ValueThe system makes an answer auditable instead of merely plausible, reducing unsupported claims, context contamination and citation hallucinations.

  5. 05

    Make the LangGraph Agent bounded by design

    ImplementationDeterministic intent routing selects direct search or a planning path. Agent limits cover steps, retrieval calls, repeated tools, consecutive errors and no-progress loops, while state stores references and artifact IDs instead of copying large content.

    ValueExecution remains predictable, resumable and reviewable, which is a safer fit for local file operations than letting the model decide when it is finished.

  6. 06

    Treat file writes as approved transactions

    Implementationsafe_write validates Vault-relative paths, reserved directories and symlink traversal. The transaction service stores snapshots and checks original hashes with optimistic concurrency control before replacement, with rollback and recovery records on failure.

    ValueA bad Agent plan cannot silently overwrite a user file; every change has a preview, conflict detection and a recovery path.

04 / CURRENT BOUNDARIES

What the current implementation does and does not claim

The project connects local retrieval, evidence constraints and safe writes into a complete workflow, but it remains a local single-user system rather than a cloud multi-tenant or distributed AI platform.

  1. High priority

    This is local single-user software, not a cloud multi-tenant platform

    The FastAPI adapter, React UI and Agent runtime operate around a local Vault. There is no account system, cross-user isolation, cloud sync or multi-instance task scheduler, so the project should not be presented as an AI SaaS platform.

  2. High priority

    Remote model calls still depend on consent and network conditions

    OpenAI embedding or LLM calls are gated by consent and budgets and send only the selected text required for the operation, but provider availability, network latency and answer quality are outside the local retrieval benchmark.

  3. Medium priority

    The benchmark is synthetic and local, not a production SLA

    The release notes record a local test with 10,000 notes and 100,000 chunks. It excludes remote network time and the distribution of a real Vault, so it cannot be used to claim production QPS or end-to-end latency.

  4. Medium priority

    Reranking and evaluation are still basic

    A reranker interface exists, but the current implementation is primarily NoOpReranker. A real Vault evaluation set is still needed to measure recall, citation correctness and abstention quality rather than retrieval latency alone.

  5. Medium priority

    The local threat model does not isolate a malicious same-user process

    The system focuses on Agent mistakes, path traversal, symlinks and concurrent overwrites. Another local process with the same file permissions can still modify the Vault outside the application threat boundary.

05 / NEXT ITERATION

What to improve next

  1. 01

    Build a real Obsidian Vault evaluation set for retrieval, citation and abstention quality

  2. 02

    Add exact tokenizer accounting and provider latency, cost and budget telemetry

  3. 03

    Implement a stronger reranker and explainable retrieval diagnostics

  4. 04

    Add integration coverage for multi-process locks, recovery and external file changes

  5. 05

    Evaluate a Tauri desktop shell while keeping the local-first boundary instead of adding cloud multi-tenancy prematurely