🗂️ krusch-fs-mcp: OS Filesystem Page Memory, SHA-256 Drift Detection, and Multi-Node Fleet Indexing for AI Agents

1. The OS Filesystem Blind Spot in Agentic Workflows

When an AI coding or SRE agent needs to answer a question about the host operating system or a multi-node cluster—such as "Which drives are protected in /etc/fstab across our production servers?", "Where is that downloaded whitepaper PDF?", or "Which node defines OLLAMA_MODELS in its systemd unit?"—default filesystem tools force the model into three anti-patterns:

• Context Window Incineration: Reading a 60-page PDF or a 2,500-line configuration log dumps tens of thousands of raw tokens into the prompt window, degrading reasoning accuracy.
• Ephemeral Discovery Amnesia: Even when an agent spends 8 tool turns running find, grep, and ssh to discover a subtle caveat on Page 14 of a document or Line 42 of /etc/fstab, that discovery vanishes when the session ends.
• Secret Exposure Hazard: Giving an agent unrestricted raw file-read access across .env files and credential directories risks leaking live API keys, bearer tokens, and database passwords directly into LLM context logs.

2. Architectural Separation of Concerns: Why Opt-In Beats Monoliths

Rather than bloating krusch-context-mcp or krusch-git with OS document parsers and SSH fleet scanners, we designed krusch-fs-mcp as an independent, opt-in MCP server:

3. KruschNexus Library Mode: Every File Is a Page Tree

Instead of slicing files into arbitrary 500-token sliding windows that sever headings from tables, krusch-fs-mcp embeds KruschNexus Library Mode (ingest_document_from_bytes) with a zero-dependency fallback chunker:

• PDFs & DOCX Documents: Parsed with layout-aware page coordinates (pdf_page, printed_page, section headings, and character spans).
• Markdown, Configs & Systemd Units: Segmented along structural Markdown headings (# / ## / ###) or 80-line logical pages with exact [start_line, end_line] coordinates.
• Pointer-Slice Chunk Deduplication (v0.3.1): Because fs_pages.page_text already stores the normalized text for each 1-based page, fs_chunks stores only char_start..char_end offsets (content="") whenever a chunk cleanly slices page_text—reconstructing snippets in memory during search() to eliminate 2x SQLite bloat.
• Incremental SHA-256 Delta Sync: Every file and every logical page is hashed with SHA-256. Unchanged files are skipped in sub-millisecond metadata checks during krusch_fs_sync.

4. Co-Located PageMemory with Automatic SHA-256 Drift Verification

The signature capability of krusch-fs-mcp is Page-Anchored Memory (krusch_fs_remember_on_page). When an agent or operator discovers a critical operational rule inside a file—such as a protected OS drive in /etc/fstab or a key clause on Page 4 of a PDF—it pins that annotation directly to the tuple (node, file_path, page_number, page_hash):

krusch_fs_remember_on_page({
  node: "primary-state-node",
  path: "/etc/fstab",
  page_number: 1,
  category: "warning",
  note: "CRITICAL OS DRIVE PROTECTION: Root partition (/) is the protected boot SSD on this node. All large datasets and vector caches must target dedicated secondary NVMe storage."
})

Whenever any future agent reads that page via krusch_fs_read_page or searches via krusch_fs_search, the co-located PageMemory is returned automatically alongside the page text—with live cryptographic drift verification:

• VALID: The current page's SHA-256 hash matches anchored_page_hash bit-for-bit.
• STALE_DRIFT: If the underlying file section was edited on disk after the memory was recorded, krusch-fs-mcp automatically flags the memory as STALE_DRIFT so the agent knows to re-verify the updated lines.

5. Multi-Layer Privacy & Secret Shield (shield.py)

Indexing an operating system or a multi-node server fleet requires strict, fail-closed security boundaries:

1. Path & Glob Denylist: Hard-blocks ~/.ssh, ~/.gnupg, ~/.aws, browser profiles, *.pem, *.key, id_rsa, id_ed25519, and package lockfiles (package-lock.json, pnpm-lock.yaml, Cargo.lock, poetry.lock, uv.lock).
2. Structural .env Key Indexing with Value Redaction: Agents frequently need to know which service defines an environment variable without seeing the secret itself. When krusch-fs-mcp indexes any .env file, it transforms KEY=secret_value into KEY = [REDACTED BY KRUSCH-FS SHIELD]—making variable names searchable across the fleet while guaranteeing zero secret leakage.
3. Inline Token Scrubbing: Regex sanitizers automatically scrub inline OpenAI/Anthropic keys (sk-...), GitHub PATs (ghp_...), Slack tokens (xoxb-...), AWS access keys (AKIA...), and PEM private key blocks before text ever reaches SQLite or Postgres.

6. Zero-Daemon Multi-Node Fleet Indexing Over Tailscale SSH

To index an entire bare-metal server fleet without maintaining fragile background daemons on every machine, krusch-fs-mcp uses an agentless SSH/Tailscale scanner configured via ~/.krusch-fs/fleet.json:

• A single Python payload streams over SSH to each online node, walks the configured directories (/etc/systemd/system, /etc/fstab, /etc/hosts, project Compose/config files), applies shield.py secret redaction in-flight, and indexes into the central database tagged by node.
• In production dogfooding across our fleet (711 files and 4,477 pages indexed across primary state, compute, and orchestrator nodes), a single krusch_fs_locate({ min_size_bytes: 50000000, node: "all" }) query immediately uncovered an 8.6 GB compressed dataset sitting on a protected production root drive and 29.1 MB of duplicate SHA-256 downloads—reclaimed in seconds.