engraph: Instructions file for Claude Code

engraph

Local knowledge graph + intelligence layer for Obsidian vaults. Rust CLI + MCP server. llama.cpp inference with Metal GPU. MIT licensed.

Architecture

Single binary with 26 modules behind a lib crate:

• config.rs — loads ~/.engraph/config.toml and vault.toml, merges CLI args, provides data_dir(). Includes intelligence: Option<bool>, [models] section for model overrides, [obsidian] section (CLI path, enabled flag), and [agents] section (registered AI agent names). Config::save() writes back to disk.
• chunker.rs — smart chunking with break-point scoring algorithm. Finds optimal split points considering headings, code fences, blank lines, and thematic breaks. split_oversized_chunks() handles token-aware secondary splitting with overlap
• docid.rs — deterministic 6-char hex IDs for files (SHA-256 of path, truncated). Shown in search results for quick reference
• llm.rs — ML inference via llama.cpp (Rust bindings: llama-cpp-2). Three traits: EmbedModel (embeddings), RerankModel (cross-encoder scoring), OrchestratorModel (query intent + expansion). Three llama.cpp implementations: LlamaEmbed (embeddinggemma-300M GGUF on Metal GPU), LlamaOrchestrator (Qwen3-0.6B for query analysis + expansion), LlamaRerank (Qwen3-Reranker-0.6B for relevance scoring). Global LlamaBackend via OnceLock. Also: MockLlm for testing, HfModelUri for model download, FlexTokenizer (HuggingFace tokenizers + shimmytok GGUF fallback), PromptFormat for model-family prompt templates, heuristic_orchestrate() fast path, LaneWeights per query intent
• fts.rs — FTS5 full-text search support. Re-exports FtsResult from store. BM25-ranked keyword search
• fusion.rs — Reciprocal Rank Fusion (RRF) engine. Merges semantic + FTS5 + graph + reranker results. Supports per-lane weighting, --explain output with intent + per-lane detail
• markdown.rs — section parser. Heading detection (ATX # headings with level tracking), section extraction by heading text, frontmatter splitting (YAML block between --- fences). Powers section-level reading and editing
• migrate.rs — PARA migration engine. Heuristic classification of vault notes into Projects/Areas/Resources/Archive using priority-ordered rules (tasks, active status, recurring topics, people, reference, done/inactive). Preview-then-apply workflow generates markdown + JSON preview for review before moving files. Rollback support via engraph migrate para --undo reverses the last migration using SQLite migration log. Three MCP tools (migrate_preview, migrate_apply, migrate_undo) and three HTTP endpoints (POST /api/migrate/preview, /apply, /undo)
• obsidian.rs — Obsidian CLI wrapper. Process detection (checks if Obsidian is running), circuit breaker state machine (Closed/Degraded/Open) for resilient CLI delegation, async subprocess execution with timeout. Falls back gracefully when Obsidian is unavailable
• health.rs — vault health diagnostics. Orphan detection (notes with no incoming or outgoing wikilinks), broken link detection (wikilinks pointing to nonexistent notes), stale note detection (notes not modified within configurable threshold), tag hygiene (unused/rare tags). Returns structured health report
• context.rs — context engine. Seven functions: read (full note content + metadata), read_section (targeted section extraction by heading), list (filtered note listing with created_by filter), vault_map (structure overview), who (person context bundle), project (project context bundle), context_topic (rich topic context with budget trimming). Pure functions taking ContextParams — no model loading except context_topic which reuses search_internal
• vecstore.rs — sqlite-vec virtual table integration. Manages the vec_chunks vec0 table for vector storage and KNN search. Handles insert, delete, and search operations against the virtual table
• tags.rs — tag registry module. Maintains a tag_registry table tracking known tags with source attribution. Supports fuzzy matching for tag suggestions during note creation
• links.rs — link discovery module. Three match types: exact basename, fuzzy (sliding window Levenshtein, 0.92 threshold), and first-name (People folder, suggestion-only at 650bp). Overlap resolution via type priority (exact > alias > fuzzy > first-name)
• placement.rs — folder placement engine. Uses folder centroids (online mean of embeddings per folder) to suggest the best folder for new notes. Falls back to inbox when confidence is low. Includes placement correction detection (detect_correction_from_frontmatter) and frontmatter stripping for moved files
• writer.rs — write pipeline orchestrator. 5-step pipeline: resolve tags (fuzzy match + register new), discover links (exact + fuzzy), place in folder, atomic file write (temp + rename), and index update. Supports create, append, update_metadata, move_note, archive, unarchive, edit (section-level replace/prepend/append), rewrite (full content with frontmatter preservation), edit_frontmatter (granular set/remove/add_tag/remove_tag/add_alias/remove_alias ops), and delete (soft archive or hard permanent) operations with mtime-based conflict detection and crash recovery via temp file cleanup
• watcher.rs — file watcher for engraph serve. OS thread producer (notify-debouncer-full, 2s debounce) sends Vec<WatchEvent> over tokio::mpsc to async consumer task. Two-pass batch processing: mutations (index_file/remove_file/rename_file) then edge rebuild. Move detection via content hash matching. Placement correction on file moves. Centroid adjustment on file add/remove. Startup reconciliation via run_index_shared. recent_writes map coordination with MCP server to prevent double re-indexing of files written through the write pipeline
• serve.rs — MCP stdio server via rmcp SDK. Exposes 22 tools: 8 read (search, read, read_section, list, vault_map, who, project, context) + 10 write (create, append, update_metadata, move_note, archive, unarchive, edit, rewrite, edit_frontmatter, delete) + 1 diagnostic (health) + 3 migrate (migrate_preview, migrate_apply, migrate_undo). edit_frontmatter replaces update_metadata for granular frontmatter mutations. EngraphServer struct with Arc+Mutex wrapping for async handlers. Loads intelligence models (orchestrator + reranker) when enabled, wires into search_with_intelligence. Spawns file watcher on startup. CLI events table provides audit log for write operations. recent_writes map prevents double re-indexing of MCP-written files. HTTP mode also serves openapi.rs routes (/openapi.json, /.well-known/ai-plugin.json) with no auth required
• http.rs — axum-based HTTP REST API server, enabled via engraph serve --http. 23 REST endpoints mirroring all 22 MCP tools + update-metadata. API key authentication with eg_ prefixed keys and read/write permission levels. Per-key token bucket rate limiting (configurable requests/minute). CORS with configurable allowed origins for web-based agents. --no-auth mode for local development (127.0.0.1 only). Graceful shutdown via CancellationToken coordinating MCP + HTTP + watcher exit
• openapi.rs — OpenAPI 3.1.0 spec builder and ChatGPT plugin manifest. Hand-written spec for all 23 HTTP endpoints, served at GET /openapi.json. Plugin manifest served at GET /.well-known/ai-plugin.json. Both routes require no authentication. [http.plugin] config section for name, description, contact_email, and public_url. Used by engraph configure --setup-chatgpt for interactive ChatGPT Actions setup
• graph.rs — vault graph agent. Extracts wikilink targets, expands search results by following graph connections 1-2 hops. Relevance filtering via FTS5 term check and shared tags
• profile.rs — vault profile detection. Auto-detects PARA/Folders/Flat structure, vault type (Obsidian/Logseq/Plain), wikilinks, frontmatter, tags. Content-based role detection for people/daily/archive folders by content patterns (not just names). Writes/loads vault.toml
• store.rs — SQLite persistence. Tables: meta, files (with docid, created_by), chunks (with vector BLOBs), chunks_fts (FTS5), edges (vault graph), tombstones, tag_registry, folder_centroids, placement_corrections, link_skiplist (reserved), llm_cache (orchestrator result cache), cli_events (audit log for CLI operations). vec_chunks virtual table (sqlite-vec) for KNN search. Dynamic embedding dimension stored in meta. has_dimension_mismatch() and reset_for_reindex() for migration. Enhanced resolve_file() with fuzzy Levenshtein matching as final fallback
• indexer.rs — orchestrates vault walking (via ignore crate for .gitignore support), diffing, chunking, embedding, writes to store + sqlite-vec + FTS5, vault graph edge building (wikilinks + people detection), and folder centroid computation. Exposes index_file, remove_file, rename_file as public per-file functions. run_index_shared accepts external store/embedder for watcher FullRescan. Dimension migration on model change.
• temporal.rs — temporal search lane. Extracts note dates from frontmatter date: field or YYYY-MM-DD filename patterns. Heuristic date parsing for natural language ("today", "yesterday", "last week", "this month", "recent", month names, ISO dates, date ranges). Smooth decay scoring for files near but outside target date range. Provides extract_note_date() for indexing and score_temporal() + parse_date_range_heuristic() for search
• search.rs — hybrid search orchestrator. search_with_intelligence() runs the full pipeline: orchestrate (intent + expansions) → 5-lane RRF retrieval (semantic + FTS5 + graph + reranker + temporal) per expansion → two-pass RRF fusion. search_internal() is a thin wrapper without intelligence models. Adaptive lane weights per query intent including temporal (1.5 weight for time-aware queries). Results display normalized confidence percentages (0-100%) instead of raw RRF scores.
• identity.rs — L1 extraction engine: active projects, key people, current focus, OOO, blocking. format_identity_block() for compact session context. extract_l1_facts() called after indexing.
• onboarding.rs — Interactive CLI UX: welcome banner, vault scan, identity prompts (dialoguer), agent mode (--detect --json, --json). run_interactive(), run_detect_json(), run_apply_json().