Files.md: A Minimalist, Local-First Approach to Knowledge Management

In the crowded landscape of Personal Knowledge Management (PKM) tools, the trend has largely moved toward "Second Brains"—complex systems of nested folders, intricate plugins, and automated workflows designed to capture every scrap of information from the internet. While these systems offer a sense of omnipotence, they often introduce a new problem: the deferral of actual thought. We spend more time curating the system than synthesizing the knowledge.

Files.md emerges as a deliberate counter-movement. It is an open-source, local-first application designed to manage plain .md files with a focus on simplicity and ownership. Rather than offering a feature-rich suite that mimics a database, Files.md provides a lightweight interface that encourages the user to do the hard work of thinking.

The Philosophy: Strengthening the First Brain

At the core of Files.md is a critical perspective on the "Second Brain" movement. The author argues that while a digital system can grow indefinitely, the "first brain" (the human mind) does not automatically get smarter just because its digital counterpart is well-organized.

"The more my system grew, the more I deferred the work of thought to some future self who would sort, tag, distill, and extract the gold. That self never arrived."

Files.md is built on the belief that restrictions foster creativity. By stripping away advanced templates and AI-driven automation, the tool forces the user to engage deeply with their notes. The goal is not to "remember nothing" by relying on a search engine, but to use the act of note-taking to develop a structured, internal understanding of a subject.

Key Technical Features

Files.md is designed to be portable, transparent, and LLM-friendly. Its architecture reflects a commitment to long-term data survival:

Local-First and Browser-Based

Unlike many modern note apps that require heavy Electron installations, Files.md is a PWA (Progressive Web App). It can be run simply by opening an index.html file in a browser. It leverages the Local FileSystem API and OPFS (Origin Private File System) to ensure that users own their files directly on their hard drive.

The "Chat" Workflow

One of the most distinct features of Files.md is its integration of a chat-like interface. Users can "dump" thoughts quickly via a chat dialog or a Telegram chatbot, which then synchronizes these entries into a Chat.md file. This reduces the friction of capturing ideas on the go without requiring the user to decide on a folder or category immediately.

Interoperability and Simplicity

To ensure the knowledge base remains cross-platform and future-proof, Files.md adheres to strict standards:

• Plain Markdown: No proprietary formats or complex wikilinks; it uses standard Markdown links to ensure compatibility with GitHub and other editors.
• Flat-ish Structure: While it supports categories, it encourages a simple structure (one idea per note) to avoid the "knowledge barrier" where one feels they understand a topic simply because they have a note about it.
• Minimal Dependencies: The project is written in Go (backend) and vanilla JS (frontend), avoiding complex build systems so that the code remains understandable for a single person or an LLM.

Technical Implementation and Architecture

For those interested in the engineering behind the project, Files.md employs several interesting strategies to handle synchronization and performance:

• Sync Mechanism: The server is a single Go binary. It uses a combination of mtime (modification time) for content-based sync and an append-only log to track renames and deletions, avoiding the need to send all files in every request.
• Performance: The author emphasizes the efficiency of Go, noting that mutex locks and SSD reads are negligible compared to the overall user experience, resulting in a "blazing fast" feel.
• Development Guidelines: The project follows a strict "less is more" contribution policy. PRs that simplify or remove code are preferred over those that add features, specifically to avoid "dopamine-driven development" where adding a feature is mistaken for adding value.

Community Perspectives and Alternatives

The release of Files.md sparked a broader discussion among the Hacker News community regarding the trade-offs between native apps, web apps, and terminal-based workflows.

The Native vs. Web Debate

Some users expressed a preference for native applications, citing the "heavy Electron vibes" of Obsidian and the perceived limitations of PWAs. One contributor highlighted a highly optimized terminal-based setup using Helix, LSP (markdown-oxide), and ripgrep, arguing that the terminal remains the most powerful interface for text manipulation.

The Plugin Ecosystem

A common point of contention is the lack of a plugin system in Files.md. While Obsidian's power comes from its community-driven plugins, the author of Files.md views this as a potential trap that leads to "curating metadata" rather than thinking. However, some users argue that for a tool to truly disrupt the market, it must either be interoperable with existing plugin ecosystems or provide a compelling reason to abandon them.

Alternative Tools

The discussion surfaced several other minimalist or open-source alternatives for those seeking different balances of power and simplicity:

• Logseq: A privacy-first, open-source knowledge base.
• Joplin: A robust open-source alternative with strong sync options (S3, Dropbox).
• TiddlyWiki: A non-linear personal web notebook.
• SmallDocs: A CLI-to-browser rendering tool that keeps content entirely local via URL fragments.

Conclusion

Files.md is more than just a note-taking app; it is a statement on the nature of digital cognition. By prioritizing the "first brain" and embracing the constraints of plain text and local storage, it offers a sanctuary for those exhausted by the complexity of modern PKM tools. It reminds us that the ultimate goal of taking notes is not to build a perfect archive, but to facilitate a deeper way of thinking.