Files.md: the local-first, LLM-friendly note-taking app that lives in .md files (2026)
Files.md is a private, quiet note-taking app built on plain .md files—local-first, offline-capable, LLM-friendly, with optional sync, Telegram bot, and a 5-year philosophy of simplicity over templates. By Artem Zakirullin.
Files.md is the note-taking app that answers a quiet question: what if the tool disappeared and only the files remained? Built by Artem Zakirullin over 5 years, Files.md is a local-first, privacy-first, browser-based app that stores your notes, journal, tasks, and checklists as plain .md files in a local folder. No data leaves your device unless you opt into sync. No plugins, no templates, no graph view—just a predefined structure that works, and a philosophy that restrictions foster creativity. The repository has 2.3k+ stars, a 50-fork ecosystem, and a Telegram bot for on-the-go note capture. It's a direct challenge to the "Second Brain" movement, arguing that your first brain should improve, not your system.
This article is a field guide: what problem it solves, the core philosophy, feature overview, sync options, file structure, and when to choose Files.md over Obsidian, Notion, or Roam.
TL;DR
Question
Short answer
What is it?
A browser-based, local-first note-taking app that stores everything as plain .md files—works offline, optionally syncs, includes Telegram bot.
Obsidian is a brilliant piece of software. I love it, dearly. But like anything, without restraint, it can also be a trap. Markdown files in nested folders. Plugins that track your productivity. Graph views that suggest omniscience. There's an illusion of mastery in watching your notes web into constellations. But constellations are projections. They tell stories. They do not guarantee understanding.
When I first started using PKM tools, I believed I was solving a problem of forgetting. Later, I believed I was solving a problem of integration.
Eventually, I realized I had created a new problem: deferral. 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.
The Second Brain trap:
Advanced templates, plugins, AI workflows create dopamine from system-building, not thinking.
The first brain doesn't improve while the second brain grows.
Reading and taking notes fool us into believing we understand—we know, but we don't do.
Knowledge barrier: We refuse new experiences because "we already know" from our notes.
Self-help through notes doesn't work—harm at the emotional level must be healed at the emotional level (therapy, meditation, feeling), not intellectual work.
Files.md's answer:
Predefined structure (no endless folder debates)
No plugins (no system-building dopamine)
No templates (no deferral to future self)
One idea per note (forces clarity)
Apply knowledge immediately (don't save for later)
Think through, don't collect (your brain improves, not your archive)
Core philosophy: own your data, own the software, use your brain
The README opens with a manifesto:
Own your data as plain local files.Own the software that opens those files.Grow your knowledge with files and your own brain.Grow the software around it with an LLM.Plain files and self-owned software can last through the ages.
Local-first means you control the storage, backups, and privacy.
LLM-friendly structure means AI agents can read, write, and organize your notes without vendor lock-in.
5 years of refinement proves the approach works—not a trendy hack.
Feature 01: Chat interface for dumping thoughts
Problem: Holding things in your head drains energy. You're in flow, a colleague asks for a report—where do you drop it?
Solution: The Chat.md interface. Send a message, then decide where it goes:
To Journal (or add jj / жж at the end)
To Later (task)
To a specific file (note, checklist)
Example flow:
You're in a meeting. Someone mentions a book.
Open the chat, type "Read 'Deep Work' by Cal Newport".
Click "To Read" → saved to Read.md checklist.
Later, open Read.md, check it off when done.
Philosophy: The chat is a write-only entrance to your knowledge base. No friction, no decisions in the moment—just dump it.
Feature 02: Journal with timestamps
Problem: Journaling apps are too heavy. You just want to record "Felt good about the presentation."
Solution: Send a message in chat, click "To Journal" (or add jj / жж). It's saved to journal/YYYY.MM Month.md with a timestamp.
Example:
markdown
## 2026.05.21 Tuesday
14:23 Felt good about the presentation. Team appreciated the clarity.
16:45 Realized I need to follow up with the client by Friday.
Automatic structure: One file per month. Entries are appended with timestamps. No manual file creation.
Feature 03: Tasks with zero guilt
Problem: Task lists become guilt-inducing backlogs.
Solution: Files.md pushes you to add only small, actionable items. Not "Plan a vacation" (too vague), but "Book flight to Berlin" (first tiny step).
Rule: Add what should be done anyway, not what you wish to be done but lack motivation for.
Example:
A colleague asks for the Q4 report.
You're in flow. Drop a message: "Send Q4 report to Sarah."
Key takeaway: The tool is not important. Your thinking is.
When to take notes (and when not to)
Take notes when:
Your goal is to develop a deeper, structured understanding of something.
You're doing research.
You're writing an article or book.
Don't take notes when:
You're reading for entertainment or procrastination.
You're trying to heal emotional wounds (therapy and meditation work; notes don't).
You're accumulating knowledge without applying it (knowledge barrier—you refuse new experiences because "you already know").
Quote from the README:
Reading without action is entertainment. A form of procrastination.
No amount of self-help books can heal emotional wounds.
What can help is psychotherapy, rescripting and chair work. Meditation.
Healing happens by feeling.
Files.md vs Obsidian / Notion / Roam
Factor
Files.md
Obsidian
Notion
Roam Research
Philosophy
Use your brain, not systems. Simplicity over features.
Extensibility, plugins, graph view.
Team collaboration, databases, all-in-one workspace.
Focus on thinking, not building systems. Maximum privacy.
Power users who love customization and plugins.
Teams needing collaboration and databases.
Networked thought, daily journaling.
Bottom line: Use Obsidian if you want extensibility and plugins. Use Notion if you need team collaboration and databases. Use Roam if you want daily notes and graph view. Use Files.md if you want simplicity, privacy, and to focus on thinking over system-building.
Architecture: Go backend + vanilla JS frontend
Backend (Go):
cmd/server — sync API server
server/bot.go — Telegram bot
server/sync/ — sync logic
Tests — E2E tests for both web app and server
Frontend (vanilla JS):
web/index.html — entrypoint (no build system required)
web/lib — frontend libraries (vendored for portability)
PWA — Progressive Web App (offline-capable, installable)
Philosophy:
No build systems. In 10 years, open web/index.html and it should just work.
Junior developers should understand the code.
All dependencies are our code and responsibility. Avoid external deps.
Portable. Everything is vendored (vendor/ and web/lib/ in repo).
Performance:
Blazing fast. Mutex lock/unlock = 25 ns, Read 4K from SSD = 150,000 ns.
Granular locks (per-user, per-resource) to avoid bottlenecks.
Useful scripts for your files (Go utilities)
All scripts are in cmd/ and can be run inside your files directory. Install Go first.
Script
What it does
whoop
Add Whoop metrics to journal
tomdlinks
Convert [[wikilinks]] to standard [Name](/path.md) (supports --dry-run)
backlink
Insert backlinks (adds links back to referencing files; supports --dry-run)
shifttime
Shift timestamps in journal files by N hours (useful after timezone change)
Example (convert wikilinks):
bash
go run /abs/path/to/files.md/cmd/tomdlinks/tomdlinks.go .
Repository stats, feature additions, and sync options change over time. Treat this as May 21, 2026 context—verify installation steps and sync setup before committing to a workflow. Files.md is MIT-licensed; contributions welcome. The creator accepts sponsorship on GitHub.
