Structured access
to your markdown vault
TypeScript toolkit that parses frontmatter, resolves wikilinks, extracts tags, and enforces schema across your notes. CLI, REST API, MCP server, native macOS app. Self-hosted, zero lock-in.
What it does
Parses, indexes, validates, and enriches plain markdown files. Every feature works without modifying the file format.
CLI + REST API
20 command groups wrapping a TypeScript core. Express 5 REST API with SSE events. JSON-first output. Docker-ready with multi-stage builds.
AI Enrichment
Auto-generate summaries, suggest wikilinks, detect patterns. Anthropic API with your key on your machine. Opt-in per command.
Health Engine
16 schema-driven validators: 9 note-level (broken links, missing frontmatter, empty bodies, stale dates) and 7 system-level (orphans, tag consistency, folder compliance).
Knowledge Graph
Force-directed graph on SwiftUI Canvas with Verlet physics. Type-based clustering, ego networks (1-3 hops), connectivity-weighted node sizing.
Schema Governance
Declare schema in _meta/schema.yaml. Run schema diff to compare declaration vs reality. Run schema impact to simulate changes before applying.
MCP Server
22 tools, 3 resources, 1 prompt template. Stdio transport. Connect to Claude Code, Claude Desktop, or any MCP client.
Native macOS App
SwiftUI with JavaScriptCore bridge to the TypeScript core. Graph, calendar heatmap, editor, chat, intelligence dashboard. Developer ID signed and notarized.
Activity Tracking
GitHub-style year heatmap. Streak tracking (current, longest, 30-day ratio). Grouped day detail with color-coded sections.
Zero Lock-in
Plain markdown with YAML frontmatter. PARA folders. Compatible with Obsidian. Syncthing for sync. Delete vaultctl and your notes still work.
Architecture
TypeScript monorepo. One core library, multiple interfaces. Core handles parsing, indexing, validation, and intelligence. Everything else is a thin wrapper.
Data Flow
Vault path configured in ~/.vaultctlrc (JSON). All packages read from the same source: markdown files on disk.
Frontmatter parsed by gray-matter with JSON_SCHEMA mode (dates stay as strings). Core builds an in-memory index on startup, serves queries from memory.
Mutations write to the filesystem. Server emits SSE events on the EventBus so connected clients get real-time updates.
Note anatomy
Drives folder placement, health rules, and graph coloring. 15 built-in types: project, concept, tool, resource, area, person, meeting, daily, decision, pattern, inbox, skill, memory, template, archive.
Lifecycle tracking: seed, growing, evergreen, active, paused, completed, archive. Review queue surfaces notes based on status and age.
Flat array for faceted search. Extracted, indexed, validated against schema. CLI lists all tags with counts.
Bidirectional links resolved by core. Creates edges in the knowledge graph. Broken links flagged by health engine.
Own your knowledge
Source available under BSL 1.1. Self-hosted. No subscriptions, no cloud dependency. Plain markdown files and a structured toolkit.