MDRack

MDRack 1.3.0 is a local Python 3.11+ command-line and embedded retrieval rack for Markdown, typed metadata, timed transcripts, frame-caption text, and explicitly supplied images. Its primary operational user is an agent working under a human operator's explicit authority over locally held data.

The application depends on standalone mdrack-core and mdrack-sqlite distributions. The first is the stdlib-only provider/persistence-neutral kernel; the second is the stdlib-plus-core generic resource catalog/search adapter. The mdrack distribution owns Markdown/image ingestion, app migration generations, LM Studio integration, Click JSON commands, and MDRackEngine; it vendors neither package.

Quick start

uv sync --all-extras
uv run mdrack --help
uv run mdrack guide
mkdir -p ./notes
uv run mdrack --root ./notes init
uv run mdrack --root ./notes scan --provider fake
uv run mdrack --root ./notes search "architecture" --mode text

This is an offline installation smoke: fake embeddings are deterministic test data, not semantic-quality evidence. Configure LM Studio before ordinary semantic or hybrid use; see Getting started and the CLI guide.

Agent-first work with human data

For a real task, an agent first identifies whether it is using the source-checkout command (uv run mdrack) or an already installed mdrack command, then asks for an explicit data root and the exact operation to perform. Keep private sources outside this repository and out of shell history, reports, and commits. The static guide and --help are read-only discovery steps; init, scan, explicit ingest, rebuild, delete, and provider/model actions change derived local state and must be named and authorized before the agent runs them.

An authorized workflow can scan Markdown in the chosen root or ingest one selected raw text/Markdown file, image with caller-supplied text, WAVE file, or ISO-BMFF video. The WAVE and ISO-BMFF paths require the caller to opt in to a selected local adapter executable; MDRack does not provide built-in transcription, decoding, or visual analysis. Search by text and optional scope, retain only returned logical IDs and portable locators or time/line evidence, then use a new CLI process with the same root to run status against the same derived store. Source files remain unchanged. The complete safe sequence and its evidence boundary are in Getting started, operations, and the shipped MDRack agent skill.

A real acceptance claim is stronger than this quick start: it requires an agent to exercise the installed public surface with separately authorized human-like private data while checking source immutability and privacy. Synthetic/offline checks are supporting evidence only; they do not substitute for that run.

The CLI also provides read, files, status, doctor, rebuild, eval, and LM Studio model-management commands. Host applications can use MDRackEngine without importing Click.

How it works

1. The default markdown-it adapter parses UTF-8 Markdown into source blocks with H1–H6 heading paths and exact line/character provenance.
2. Markdown image syntax contributes only safe textual alt/alias prose; paths and referenced files are never inspected or indexed as assets.
3. The app projects documents into typed core resources and writes a complete graph atomically to the fixed SQLite catalog at <store>/catalog.sqlite3.
4. Core retrieval accepts ready lexical/vector branches, applies scope filters before limits, groups resource evidence, and performs deterministic weighted RRF.
5. Explicit image ingestion stores derived caption/OCR text and ready vectors, never source bytes; duplicate and whole-resource similarity use logical IDs.

Documentation

• Getting started: installation, configuration, CLI, and engine
• MDRack agent skill — self-contained terminal workflow
• Operations, diagnostics, privacy, and troubleshooting
• Development guide for humans and coding agents
• Current architecture index
• System overview
• Indexing and structural chunking
• SQLite persistence and current schema
• Text, semantic, and hybrid retrieval
• Asset handling
• CLI and embedded interfaces
• Current limitations
• Completed MDRack 1.3 compact-storage plan (historical)
• MDRack 1.3.0 release notes and source-publication status
• MDRack 1.1 local release
• CLI contracts
• v0.3 compatibility registry
• Recovery procedures
• ADR-0001: reranking deferred
• ADR-0002: provider/storage-neutral core
• ADR-0004: SQLite operating envelope
• Offline release verification — supported distribution cells, matrix evidence, and strict no-live gates
• Licensing and commercial use — MIT policy, commercial-use boundary, and Windows bundle gate
• Third-party runtime notices — exact locked resolver graph and upstream-license obligations
• v0.4 W5-CI contract
• v0.4 offline release-candidate packet — exact stage/release/DoD evidence and non-claims
• v0.4 public-surface compatibility ledger
• v0.3 release evidence

Files under docs/plans/ and the legacy architecture/design documents are historical unless explicitly marked as an active plan. They are not the current product contract.

Images

Markdown image syntax never starts image ingestion. It preserves eligible alt or textual alias once as ordinary prose and discards target/path/title/dimensions. mdrack image ingest is a separate explicit local-file operation. Caption/OCR text is caller-supplied or produced by an injected extractor; live LM Studio use requires an explicit provider choice. Source bytes remain outside SQLite and are never modified.

Known limitations

• SQLite is the only persistent database. Fresh compact generations use canonical float32 vectors and the builtin exact Python scan; there is no ANN/vector extension dependency in the base distribution.
• Structural overlap_chars is currently not consumed, so structural chunks do not overlap.
• Production reranking is disabled. rerank_rank and rerank_score remain null; non-null reranker injection fails closed.
• MDRack indexes supplied transcripts and frame-caption text; it does not transcribe raw audio or perform pixel/visual or acoustic search.
• The CLI also accepts explicitly authorized local raw-media adapters: ingest audio SOURCE_PATH --source-ref REF --allow-external-stt --stt-command COMMAND for RIFF/WAVE input and ingest raw-video SOURCE_PATH --source-ref REF --allow-external-video-extractor --video-extractor-command COMMAND for ISO-BMFF input. These shell-free stdin adapters are caller-selected; they are not built-in transcription, decoding, pixel/acoustic search, or provider quality evidence.
• Provider-free and real-source checks prove retrieval behavior and source integrity, not universal semantic quality from a live embedding model.
• Legacy files and sections inspection commands still expose internal record IDs; new resource/image/search contracts expose logical IDs only.
• The resource-core schema lives in one fixed catalog.sqlite3. There is no candidate-generation cutover or runtime rollback; destructive recreation is separately authorized.

See the complete limitations ledger.

Verification and recovery

Run the complete offline verification suite with scripts/verify.sh on Linux or scripts/verify.ps1 on Windows. The release-specific cells and strict gates are documented in offline release verification: they cover mdrack, mdrack-core, mdrack-media, and mdrack-sqlite as wheel and sdist, Linux/Windows × Python 3.11/3.12 evidence, offline E2E/privacy lanes, and installed smoke. Provider calls, network fallback, and remote execution are not part of the default path. Fixed-catalog recovery and destructive recreation boundaries are documented in recovery.

For a reproducible Windows executable build, see Windows EXE build.

License and commercial use

MDRack is standard MIT software. Commercial use, modification, redistribution, sublicensing, and sale are allowed, provided that the exact copyright and permission notice — Copyright (c) 2026 VladimirMonin — stays with copies or substantial portions. MDRack is provided without warranty. This is a project license summary, not legal advice or clearance for a particular distribution.

The policy for the four Python distributions and future Windows bundle is in licensing and commercial use. The exact locked resolver dependency graph, including the Windows-only colorama branch and certifi/MPL-2.0, is recorded in THIRD_PARTY_NOTICES.md. Resolver-installed dependencies are not relicensed by MDRack and are not bundled in the four base Python wheel/sdist artifacts.