Architecture

Relevant source files

• .devin/wiki.json
• AGENTS.md
• ARCHITECTURE.md
• README.md
• src/utils/__tests__/describe-error.test.ts
• src/utils/describe-error.ts
• src/vault-mcp/__tests__/server.test.ts
• src/vault-mcp/server.ts
• src/vault-mcp/vault-operations/daily-notes.ts
• tsconfig.json

Vault Cortex is a remote MCP server that exposes an Obsidian vault over HTTPS. Unlike typical integrations that proxy requests to a running Obsidian desktop instance via a plugin, Vault Cortex interacts directly with the .md files on disk using a headless architecture optimized for Docker environments and remote access ARCHITECTURE.md3-6 ARCHITECTURE.md23-29

Four-Layer Architecture

The internal logic is organized into four distinct layers, moving from pure data parsing to filesystem I/O and finally to the MCP protocol surface.

Layer	Directory	Responsibility
Obsidian Markdown	src/vault-mcp/obsidian-markdown/	Pure parsers for Obsidian's link formats, frontmatter, callouts, and tasks. No I/O. AGENTS.md95-106
Vault Operations	src/vault-mcp/vault-operations/	Filesystem I/O for reading, writing, and surgical patching of notes with safety guards. AGENTS.md112-120
Search and Indexing	src/vault-mcp/search/	SQLite FTS5 + sqlite-vec index and chokidar file watcher for real-time indexing. AGENTS.md121-135
MCP Core	src/vault-mcp/mcp-core/	MCP protocol wiring, tool registrations, and prompt definitions. AGENTS.md136-146

For a deep dive into each layer, see:

• Server and Transport — How the Express server bootstraps (server.ts) and the MCP streamable-http transport lifecycle.
• Authentication and Security — The two-layer auth model (Lambda authorizer and OAuth 2.1) and runtime hardening.
• Obsidian Markdown Parsing — Domain knowledge of Obsidian syntax including links, tasks, and canvas.
• Vault Operations — Atomic filesystem I/O, path safety, and surgical note patching.
• Search and Indexing — Hybrid search (FTS5 + vector), RRF fusion, and the embedding pipeline.
• Memory Layer — The "About Me/" structured memory system and daily note integration.

Sources: AGENTS.md95-146 ARCHITECTURE.md43-49

Component Diagram

The following diagram illustrates how the MCP server interacts with the vault filesystem, the SQLite index, and the optional Obsidian Sync service in a remote deployment.

System Components and Code Entities

Sources: ARCHITECTURE.md61-108 AGENTS.md7-17 src/vault-mcp/server.ts70-140

Data Flow: Request to Disk

The system follows a strict request-response lifecycle managed by an Express server and the MCP streamable-http transport src/vault-mcp/server.ts114-140

1. Transport: The createMcpRouter in mcp-router.ts handles incoming HTTP POST requests to /mcp. It manages sessions and provides the transport layer for the MCP SDK src/vault-mcp/server.ts134-140
2. Authentication: Requests are dual-validated. First by a path-aware AWS Lambda authorizer (in AWS mode) and then by the application-level requireBearerAuth middleware using JWTs from the OAuthServerProvider ARCHITECTURE.md74-78 AGENTS.md15-17
3. Tool Execution: The tool-definitions.ts orchestrator dispatches the request to a specific tool handler grouped by domain modules (e.g., vault-crud-tools.ts, search-tools.ts) AGENTS.md136-141
4. Data Layer:
   • Reads: Tools query search-queries.ts for metadata/hybrid results or vault-filesystem.ts for raw content src/vault-mcp/server.ts90-93
   • Writes: Surgical edits are handled by vault-patcher.ts, while renames with full link rewriting are managed by note-mover.ts AGENTS.md112-120
5. Synchronization: The chokidar watcher in file-watcher.ts detects filesystem changes (from the server or Obsidian Sync) and incrementally updates the SQLite index src/vault-mcp/server.ts103-105 ARCHITECTURE.md116-117

Sources: src/vault-mcp/server.ts101-140 ARCHITECTURE.md110-121

Bridging Natural Language to Code

The following table maps conceptual system operations to the specific code entities that implement them.

Concept	Code Entity	File Path
Surgical Edits	patchNote	src/vault-mcp/vault-operations/vault-patcher.ts38
Link Resolution	resolveObsidianLink	src/vault-mcp/obsidian-markdown/links.ts251
Hybrid Search	hybridSearch	src/vault-mcp/search/search-queries.ts88
RRF Fusion	computeRrfScores	src/vault-mcp/search/rrf.ts15
Daily Note Path	getDailyNotePath	src/vault-mcp/vault-operations/daily-notes.ts119
Memory Recall	memoryRecall	src/vault-mcp/search/search-queries.ts120
Task Parsing	parseTaskLine	src/vault-mcp/obsidian-markdown/tasks.ts101
Tool Registry	registerAllTools	src/vault-mcp/mcp-core/tool-definitions.ts37
Atomic Writes	atomicWriteFile	src/vault-mcp/vault-operations/vault-filesystem.ts178
Shutdown Handler	createShutdownHandler	src/vault-mcp/server.ts44

Sources: AGENTS.md73-106 src/vault-mcp/server.ts7-16 src/vault-mcp/vault-operations/daily-notes.ts119-141