pkmrag 0.9.0__tar.gz

pkmrag-0.9.0/.env.example

@@ -0,0 +1,52 @@
+# ==============================================================================
+# PKMRAG — Environment Configuration
+# Copy this file to .env and adjust variables as needed:
+#   cp .env.example .env
+# ==============================================================================
+
+# LLM Inference (Phase 4 Semantic Gap Detection)
+# ------------------------------------------------------------------------------
+# API key for the inference provider (Groq, OpenAI, OpenRouter, etc.)
+OPENAI_API_KEY=your-api-key-here
+
+# Alternatively, set a PKMRAG-specific API key override (ORBIT_LLM_API_KEY also supported)
+# PKMRAG_LLM_API_KEY=your-pkmrag-api-key
+
+# OpenAI-compatible API base URL
+# Defaults to OpenAI's public API: https://api.openai.com/v1
+# For Groq: https://api.groq.com/openai/v1
+# For local Ollama: http://localhost:11434/v1
+# For local vLLM / LiteLLM: http://localhost:8000/v1
+# For OpenRouter: https://openrouter.ai/api/v1
+OPENAI_BASE_URL=https://api.openai.com/v1
+
+# Model identifier to use for classification
+# Defaults to gpt-4o-mini
+# Groq examples: llama-3.1-8b-instant, llama-3.3-70b-versatile
+# Local examples: llama3.1, mistral-nemo, qwen2.5:7b
+PKMRAG_LLM_MODEL=gpt-4o-mini
+
+# LLM Rate Limiting
+# ------------------------------------------------------------------------------
+# Maximum requests per minute (RPM) to LLM provider (0 for unlimited)
+# Default: 30
+PKMRAG_LLM_RPM=30
+
+# Maximum tokens per minute (TPM) to LLM provider (0 for unlimited)
+# Default: 8000
+PKMRAG_LLM_TPM=8000
+
+# Maximum retries on HTTP 429 rate limit errors
+# PKMRAG_LLM_MAX_RETRIES=3
+
+# Storage & Directory Overrides (Optional)
+# ------------------------------------------------------------------------------
+# Default path to your Obsidian vault (used by `pkmrag install-plugin` and testing)
+# PKMRAG_VAULT_PATH=/path/to/your/vault
+
+# Default LadybugDB storage directory (defaults to <vault>/.pkmrag/graph)
+# PKMRAG_DB_DIR=/custom/path/to/graph
+
+# Default LanceDB vector storage directory (defaults to <vault>/.pkmrag/vectors)
+# PKMRAG_VECTOR_DIR=/custom/path/to/vectors
+

pkmrag-0.9.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run pytest --cov=pkmrag --cov-report=term-missing
+      - name: Run retrieval evaluation quality gates
+        run: uv run pkmrag eval --min-mrr 0.80 --min-recall 0.80
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run mypy src tests

pkmrag-0.9.0/.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environments
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Testing & Linting
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Local databases & storage (PKMRAG data)
+*.kuzu/
+*.lance/
+*.db
+*.sqlite
+*.sqlite3
+.pkmrag/
+.orbit/
+
+# IDE & OS
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Secrets & Environment Variables
+.env
+.env.*
+!.env.example
+
+# Scratch files
+scratch/
+
+# Node & Obsidian Plugin
+node_modules/
+plugins/obsidian/dist/
+

pkmrag-0.9.0/.python-version

@@ -0,0 +1 @@
+3.12

pkmrag-0.9.0/AGENTS.md

@@ -0,0 +1,95 @@
+# AGENTS.md — PKMRAG
+
+## What This Is
+
+A local-first Hybrid GraphRAG engine for linked personal knowledge bases (PKMs).
+Obsidian serves as the primary reference dialect, with a pluggable dialect layer for CommonMark, Logseq, Foam, and other linked systems.
+3-tier architecture: deterministic graph (LadybugDB) → semantic search (LanceDB) → AI gap detection (LLM).
+Exposed as an MCP server — no chat UI.
+
+## Project Layout
+
+```
+src/pkmrag/
+  cli.py          # Typer CLI entry point
+  cli_views.py    # Rich terminal display renderers
+  config.py       # Settings, defaults, env vars
+  models.py       # Pydantic data models (shared across modules)
+  doctor.py       # `pkmrag doctor` health checks
+  dialects/       # Pluggable markdown dialect parsing (obsidian, commonmark)
+  cache/          # SQLite L1 query cache and dependency tracking
+  parser/         # Markdown parsing + vault file indexing
+  graph/          # LadybugDB graph store, schema DDL, and traversal
+  ingest/         # Vault → graph and vector ingestion pipeline & single-note reindexer
+  search/         # Chunking, FastEmbed, LanceDB vector store, RRF fusion, service
+  inference/      # LLM inference client (OpenAI, Ollama) and token-bucket rate limiter
+  discovery/      # Semantic gap discovery and relationship inference engine
+  eval/           # Retrieval evaluation harness and IR metrics (MRR, Recall, MAP)
+  telemetry/      # OpenTelemetry spans, collector, visual tree, tracer lifecycle
+  mcp/            # FastMCP server, tool handlers, and stdio transport
+  vault_config.py # Per-vault configuration reader/writer (<vault>/.pkmrag/config.json)
+  plugin.py       # Obsidian plugin installer & bundler CLI
+  plugin_assets/  # Bundled standalone Obsidian plugin assets (manifest, main.js, styles)
+
+tests/            # Mirrors src/pkmrag/ structure
+benchmarks/       # Ground-truth evaluation benchmarks (golden_10, vault)
+```
+
+
+## Hard Rules
+
+1. **Max 300 lines per file.** If a file approaches this, split it. No exceptions.
+2. **No overengineering.** Solve the problem in front of you. Don't add abstractions for hypothetical future needs.
+3. **Simple > clever.** If a colleague can't understand it in 30 seconds, rewrite it.
+4. **Prefer focused libraries over hand-rolled code.** If a well-maintained library solves the exact problem, use it — don't rewrite what's already battle-tested. But don't pull in a heavy framework for a single utility; the dependency's weight should be proportional to the value it provides.
+5. **Type everything.** `mypy --strict` must pass. No `Any` escapes except for third-party lib boundaries.
+6. **Pydantic for data boundaries.** All structured data crossing module boundaries uses Pydantic models defined in `models.py` (or a module-local `models.py` if domain-specific).
+7. **Tests are mandatory.** Every new module gets a corresponding `tests/test_<module>.py`. Test behavior, not implementation.
+8. **Preserve existing comments and docstrings** unless directly contradicted by the change.
+9. **Keep docs current but minimal.** Update `README.md` and `AGENTS.md` when features or layout change. Don't pad them — if it's obvious from the code, don't document it.
+
+## Style
+
+- **Formatter/linter:** `ruff` (line-length 100). Run `uv run ruff check --fix . && uv run ruff format .`
+- **Type checker:** `uv run mypy src/`
+- **Tests:** `uv run pytest`
+- Docstrings: one-line summary in `"""..."""`. Multi-line only when non-obvious.
+- Imports: `from __future__ import annotations` at top of every module.
+- Use `Path` from `pathlib`, never raw string paths for filesystem ops.
+
+## Architecture Decisions (Don't Undo These)
+
+- **Embedded DBs only.** LadybugDB + LanceDB + SQLite. No servers, no Docker, no network DBs.
+- **Dialect-agnostic core.** The property graph, vector store, and MCP tools operate on abstract knowledge primitives (Note, Tag, Folder, LINKS_TO). All syntax parsing lives in pluggable `dialects/` (Obsidian, CommonMark, Logseq). Never introduce dialect-specific branching into storage, search, or MCP tools.
+- **Incremental sync.** Ingestion compares file hashes; only changed files are reprocessed.
+- **Inferred edges are separate from ground truth.** AI-discovered relationships go in their own table/label, tagged with confidence + model + timestamp. Never pollute human-curated graph data.
+- **MCP over custom UI.** The primary interface is an MCP server (stdio + SSE), not a chat frontend.
+
+## When Adding New Features
+
+1. Ensure new functionality aligns with the architectural design and existing subsystems.
+2. Put code in the right subpackage. Create a new one if needed — flat files over deep nesting.
+3. Add CLI commands in `cli.py` using Typer. Keep handlers thin — delegate to engine modules.
+4. Wire up tests before marking done.
+
+## Common Commands
+
+```bash
+uv run pkmrag doctor                      # Sanity check both DBs
+uv run pkmrag ingest <path>               # Ingest a vault (all, graph, or vector)
+uv run pkmrag search "query" --near <note># Hybrid search with graph boost
+uv run pkmrag search "query" --trace      # Hybrid search with visual execution trace tree
+uv run pkmrag discover <path>             # Discover semantic gaps and infer relationships
+uv run pkmrag discover <path> -p ollama   # Offline semantic discovery via local Ollama
+uv run pkmrag eval                        # Automated IR retrieval evaluation against golden benchmark
+uv run pkmrag serve <path>                # Start stdio MCP server for Claude/Cursor
+uv run pkmrag serve <path> -t http        # Start HTTP/SSE MCP & REST daemon on port 3747
+uv run pkmrag mcp-config <path>           # Output MCP JSON client configuration
+uv run pkmrag install-plugin              # Install Obsidian companion plugin to vault (via PKMRAG_VAULT_PATH)
+uv run pkmrag install-plugin --symlink    # Symlink plugin files for live development
+uv run ruff check --fix .                 # Lint
+
+uv run ruff format .                      # Format
+uv run mypy src tests                     # Type check
+uv run pytest                             # Test
+```

pkmrag-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Project Orbit Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pkmrag-0.9.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.5
+Name: pkmrag
+Version: 0.9.0
+Summary: Local-first Hybrid GraphRAG retrieval engine and MCP server for linked knowledge bases
+Project-URL: Homepage, https://github.com/pkmrag/pkmrag
+Project-URL: Documentation, https://github.com/pkmrag/pkmrag#readme
+Project-URL: Repository, https://github.com/pkmrag/pkmrag
+Project-URL: Issues, https://github.com/pkmrag/pkmrag/issues
+Author: PKMRAG Contributors
+License: MIT
+License-File: LICENSE
+Keywords: graphrag,knowledge-graph,lancedb,mcp,obsidian,pkm,rag,vector-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.12
+Requires-Dist: fastembed>=0.3.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: ladybug>=0.20.0
+Requires-Dist: lancedb>=0.38.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: opentelemetry-api>=1.25.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25.0
+Requires-Dist: opentelemetry-sdk>=1.25.0
+Requires-Dist: pyarrow>=17.0.0
+Requires-Dist: pydantic-settings>=2.15.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: python-dotenv>=1.2.3
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/pkmrag-logo-text-dark.svg">
+    <img alt="PKMRAG" src="assets/pkmrag-logo-text.svg" width="520">
+  </picture>
+</p>
+
+<p align="center">
+  <strong>Embedded, Local-First Hybrid GraphRAG Retrieval Engine & MCP Server</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/dev-hashemi/project-orbit/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/dev-hashemi/project-orbit/ci.yml?branch=main&style=flat&label=CI&logo=githubactions&logoColor=white"></a>
+  <a href="https://github.com/dev-hashemi/project-orbit"><img alt="Coverage" src="https://img.shields.io/badge/coverage-89%25-brightgreen?style=flat&logo=pytest"></a>
+  <a href="https://www.python.org/downloads/"><img alt="Python" src="https://img.shields.io/badge/python-%3E%3D3.12-3776AB?style=flat&logo=python&logoColor=white"></a>
+  <a href="https://github.com/dev-hashemi/project-orbit/releases"><img alt="Version" src="https://img.shields.io/github/v/tag/dev-hashemi/project-orbit?style=flat&label=version&logo=github&logoColor=white"></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-green?style=flat&logo=opensourceinitiative&logoColor=white"></a>
+  <a href="http://mypy-lang.org/"><img alt="Mypy" src="https://img.shields.io/badge/types-mypy_strict-2A6DB5?style=flat&logo=python&logoColor=white"></a>
+</p>
+
+PKMRAG is an open-source, local-first retrieval engine designed for linked personal knowledge bases (PKMs). While Obsidian serves as our primary reference dialect, PKMRAG operates on an abstract knowledge model supporting any linked document system (Logseq, Foam, CommonMark docs) via pluggable dialects. It combines an explicit structural property graph with an Arrow-backed vector and keyword search index, exposing contextual intelligence to frontier AI reasoning tools via the Model Context Protocol (MCP).
+
+📖 **Technical Documentation:** [System Architecture & Subsystems](docs/architecture.md)
+
+---
+
+## 🏛️ Architecture Overview
+
+PKMRAG replaces brute-force triple extraction with a targeted, 3-tier discovery pipeline:
+
+```mermaid
+%%{init: {'theme': 'dark', 'themeVariables': { 'darkMode': true, 'background': 'transparent', 'mainBkg': '#1e293b', 'primaryColor': '#1e293b', 'primaryBorderColor': '#3b82f6', 'primaryTextColor': '#f8fafc', 'lineColor': '#38bdf8', 'edgeLabelBackground': '#1e293b' }}}%%
+flowchart TD
+    Vault["📂 Linked Knowledge Base<br/><i>Obsidian, Logseq, CommonMark</i>"]
+
+    Vault --> T1["🏗️ Tier 1: Deterministic Parser ($0 Cost)"]
+    T1 --> BaseGraph[("LadybugDB Property Graph<br/><i>Wikilinks, Tags, Hierarchy</i>")]
+
+    Vault --> T2["🔍 Tier 2: Hybrid Semantic Index"]
+    T2 --> Lance[("LanceDB Vector & FTS Index<br/><i>Dense Embeddings + BM25</i>")]
+
+    BaseGraph --> T3["🧠 Tier 3: Semantic Gap Detector"]
+    Lance --> T3
+    T3 -->|"High vector similarity + graph distance ≥ 3"| Candidates["Unlinked Candidate Note Pairs"]
+    Candidates -->|"Targeted LLM Inference"| TypedEdges["Typed Relationships<br/><code>[:EXTENDS]</code>, <code>[:CONTRADICTS]</code>, <code>[:PREREQUISITE_FOR]</code>"]
+    TypedEdges --> BaseGraph
+
+    style T1 fill:#0f172a,stroke:#3b82f6,color:#e2e8f0
+    style T2 fill:#0f172a,stroke:#8b5cf6,color:#e2e8f0
+    style T3 fill:#7c2d12,stroke:#f97316,color:#e2e8f0
+    linkStyle default stroke:#38bdf8,stroke-width:2px;
+```
+
+---
+
+## 🚀 Key Architectural Principles
+
+- **Zero-Daemon, Embedded Storage:** Runs entirely in-process using embedded C++ and Apache Arrow engines: **LadybugDB** for property graph traversals, **LanceDB** for hybrid vector/BM25 search, and **SQLite WAL** for sub-0.5ms L1 query caching. No Docker, no network databases.
+- **Dialect-Agnostic Core:** Storage, retrieval, and MCP tools operate on abstract knowledge primitives (`Note`, `Tag`, `Folder`, `LINKS_TO`). Syntax parsing is completely encapsulated in pluggable dialects.
+- **Model Context Protocol (MCP):** Serves as a high-precision retrieval data plane for AI agents (**Claude Code**, **Cursor**, **OpenCode**) without exposing raw filesystem mutation risks.
+- **Scientific Quality Gating:** Retrieval accuracy is benchmarked with zero-cost IR metrics (MRR, Context Recall@5) guarding against semantic regressions.
+
+---
+
+## 🛠️ Quickstart
+
+### 1. Installation
+Install PKMRAG into an isolated global environment using `pipx` or `uv tool`:
+```bash
+# Recommended for end users
+pipx install pkmrag
+# or
+uv tool install pkmrag
+```
+
+For local development or cloning from source:
+```bash
+git clone https://github.com/dev-hashemi/project-orbit.git pkmrag
+cd pkmrag
+uv sync
+```
+
+### 2. Verify Storage & Engine Health
+```bash
+pkmrag doctor
+```
+```text
+╭─────────────────────────────────────────────╮
+│ PKMRAG v0.9.0 — System Health & Diagnostics │
+╰─────────────────────────────────────────────╯
+                       In-Process Data Plane Verification                       
+┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Component              ┃ Status  ┃ Version ┃ Latency ┃ Verification Details  ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
+│ LadybugDB Property     │  PASS   │ 0.20.4  │   0.3ms │ Cypher transactional  │
+│ Graph                  │         │         │         │ read/write verified   │
+│ LanceDB Vector Engine  │  PASS   │ 0.38.0  │   6.3ms │ Arrow-backed vector   │
+│                        │         │         │         │ index verified        │
+│ Ollama Local Engine    │  PASS   │ active  │   1.2ms │ Local daemon detected │
+└────────────────────────┴─────────┴─────────┴─────────┴───────────────────────┘
+All systems operational. Engines ready for PKMRAG.
+```
+
+### 3. Ingest and Search in 30 Seconds
+```bash
+pkmrag ingest /path/to/vault
+pkmrag search "how does cache invalidation work?" --near "Cache Architecture.md"
+```
+
+---
+
+## 🔍 Core Capabilities
+
+### Ingestion & Incremental Synchronization
+Ingest notes, links, tags, and semantic vectors with SHA-256 delta sync:
+```bash
+pkmrag ingest /path/to/vault                           # Ingest graph topology + semantic vectors
+pkmrag ingest /path/to/vault --target vector           # Target specific plane (all, graph, or vector)
+pkmrag ingest /path/to/docs --dialect commonmark       # Explicitly select markdown dialect
+pkmrag ingest /path/to/vault --rebuild                 # Force a clean rebuild
+```
+
+### Hybrid & Graph-Boosted Retrieval
+Combines dense semantic similarity (`BAAI/bge-small-en-v1.5`), Tantivy BM25 keyword matching, Reciprocal Rank Fusion ($k=60$), and graph proximity multipliers:
+```bash
+pkmrag search "distributed consensus"                  # Hybrid search (dense + BM25 via RRF)
+pkmrag search "consensus" --near "Paxos Algorithm.md"  # Boosted by graph proximity to anchor note
+pkmrag search "raft" --mode dense --limit 5            # Explicit retrieval mode (hybrid, dense, sparse)
+pkmrag search "storage" --json                         # Machine-readable JSON output
+```
+
+### 🧠 Semantic Gap Discovery & Inferred Relationships
+Detects unlinked note pairs with high semantic similarity ($\ge 0.80$) but graph distance $\ge 3$, classifying missing edges via local or remote LLMs:
+```bash
+pkmrag discover /path/to/vault --dry-run               # Preview semantic gaps without calling LLM
+pkmrag discover /path/to/vault --provider ollama       # 100% offline local inference (Llama 3.2, Qwen 2.5)
+pkmrag discover /path/to/vault --threshold 0.85        # Custom cosine similarity threshold
+```
+Inferred edges are stored separately in the LadybugDB `[:INFERRED_REL]` table with confidence, model name, and rationale—preserving human-curated wikilinks.
+
+---
+
+## 🔌 Model Context Protocol (MCP) & HTTP Server
+
+PKMRAG exposes a rich tool plane over **stdio** (for CLI/IDE agents) and **HTTP/SSE** (for Obsidian and network clients):
+
+```bash
+# Start stdio MCP server (Claude Code, Cursor, OpenCode)
+pkmrag serve /path/to/vault
+
+# Start HTTP/SSE daemon on port 3747 (dual MCP SSE + REST API plane)
+pkmrag serve /path/to/vault --transport http --port 3747
+
+# One-command registration for Claude Code:
+claude mcp add pkmrag -- uv run pkmrag serve /path/to/vault
+```
+
+### Exposed Tools
+- `query_vault`: Hybrid semantic + BM25 keyword retrieval with graph boost and folder/tag filters.
+- `read_note`: Read note content enriched with graph context (tags, forward links, backlinks).
+- `list_notes`: Browse notes in the vault with optional folder filtering and pattern matching.
+- `list_tags` / `search_by_tag`: Rank and query notes by tag topology.
+- `get_outline`: Extract heading hierarchy and line numbers for large notes.
+- `get_note_context`: Inspect incoming backlinks, outgoing citations, 2-hop clusters, and AI-inferred relationships.
+- `find_bridges`: Discover the shortest link path between two notes across the vault.
+- `discover_gaps`: Uncover unlinked note pairs with high vector similarity for bridging.
+- `vault_overview`: Bird's-eye view of vault notes, wikilinks, tags, and central hub notes.
+- `reindex_note`: Targeted sub-40ms single-note incremental reindexing after external edits.
+- `sync_vault`: Incremental delta scan updating modified notes across the vault.
+
+---
+
+## 💎 Obsidian Desktop Plugin (`pkmrag`)
+
+A native desktop companion plugin (`plugins/obsidian/`) connecting Obsidian to PKMRAG:
+- **Interactive Setup Wizard:** If installed before the Python core engine, the sidebar automatically guides you through a 2-step setup with 1-click command copying and live verification.
+- **Orbit Insights Sidebar:** Real-time semantic gap recommendations, contradiction warnings with LLM citations, and structural graph context.
+- **Zero-Terminal Workflow & Auto-Daemon:** Transparently starts the background engine daemon on launch and shuts down cleanly on exit.
+- **In-App AI Discovery & Indexing:** Trigger deep AI relationship discovery (`⚡ Discover`) and full vault rebuilds directly from Obsidian without opening a shell.
+- **Settings-Driven LLM & Embedding Models:** Swap between Ollama, OpenAI, Groq, or local endpoints and customize models with 1-click latency verification directly inside Obsidian Settings.
+- **CodeMirror 6 Inline Indicators:** Ambient visual widgets on headings (`🔗 N`, `⚠️`) without document clutter; clicking reveals the sidebar panel.
+- **Proximity Concept Explorer:** Context-anchored hybrid retrieval drawer (`--near <note>`) directly within the editor with 1-click reference insertion.
+- **Knowledge Governance:** Persistent negative feedback cache preventing dismissed links from recurring; transparent restoration drawer and global reset.
+- **Zero-Config Token Security:** Automatically discovers `.pkmrag/server_token` (or legacy `.orbit/server_token`) from active vault.
+- **Live Reactive Updates:** Subscribes to Server-Sent Events (`/api/v1/events`) for background indexing updates.
+
+```bash
+# Install companion plugin into your Obsidian vault:
+pkmrag install-plugin /path/to/vault
+
+# Or for plugin developers:
+pkmrag install-plugin /path/to/vault --symlink
+```
+
+See [docs/subsystems/obsidian-plugin.md](docs/subsystems/obsidian-plugin.md) for installation and developer guides.
+
+
+---
+
+## 🎯 Benchmarks & Distributed Tracing
+
+### Information Retrieval Quality Gates
+Evaluated against the in-repo Golden 10 ground truth benchmark dataset (`benchmarks/golden_10.json`):
+- **MRR (Mean Reciprocal Rank):** `0.950` (Target $\ge 0.80$, PASS)
+- **Context Recall@5:** `0.950` (Target $\ge 0.80$, PASS)
+- **Hits@1:** `90.0%` | **Hits@3:** `100.0%` | **Hits@5:** `100.0%`
+- **Mean Average Precision (MAP@5):** `0.925`
+
+```bash
+pkmrag eval --min-mrr 0.85 --min-recall 0.80           # CI regression gate
+```
+
+### OpenTelemetry Distributed Tracing
+Inspect execution timelines and token consumption in real time with in-memory OpenTelemetry spans:
+```bash
+pkmrag search "storage" --near "LadybugDB.md" --trace
+```
+```text
+╭───────── Trace ID: 66d44d13f5b480b5... ─────────╮
+│ 🛰️ Trace: pkmrag.search  18.42ms (HIT, hybrid)  │
+│ ├── cache.lookup    0.15ms (HIT)                │
+│ ├── lancedb.search   8.12ms                     │
+│ ├── ladybug.hops     4.20ms (dist: 1)           │
+│ └── rrf.fuse         0.18ms                     │
+╰─────────────────────────────────────────────────╯
+```
+- **Zero Daemons Required:** Spans are collected in-memory and rendered locally.
+- **LLM Token Auditing:** Tracks prompt and completion tokens per inference call.
+- **Remote OTLP Exporter:** Optional live trace streaming to Langfuse, Jaeger, or Datadog via `.env`.
+
+---
+
+## 🧪 Development & Quality Gates
+
+```bash
+# Unit & integration tests + Golden 10 benchmark
+uv run pytest
+
+# Strict type checking
+uv run mypy src tests
+
+# Linting & code formatting
+uv run ruff check . && uv run ruff format --check .
+
+# Retrieval evaluation against benchmark
+uv run pkmrag eval
+```