Files.md: the local-first, LLM-friendly note-taking app that lives in .md files (2026)

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

The official site provides installation, philosophy, and sync setup.

The problem: when note-taking becomes procrastination

The README quotes I Deleted My Second Brain:

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:

1. Advanced templates, plugins, AI workflows create dopamine from system-building, not thinking.
2. The first brain doesn't improve while the second brain grows.
3. Reading and taking notes fool us into believing we understand—we know, but we don't do.
4. Knowledge barrier: We refuse new experiences because "we already know" from our notes.
5. 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.

Translation:

• Plain .md files survive tool churn—if Files.md disappears, your notes remain readable.
• 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:

1. You're in a meeting. Someone mentions a book.
2. Open the chat, type "Read 'Deep Work' by Cal Newport".
3. Click "To Read" → saved to Read.md checklist.
4. 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:

## 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:

1. A colleague asks for the Q4 report.
2. You're in flow. Drop a message: "Send Q4 report to Sarah."
3. Click "To Later" → saved to Later.md.
4. Later, open Later.md, complete it, check it off.

Task file location: Later.md

Feature 04: Checklists (groceries, reading, watching)

Problem: You need butter. A friend recommends a book. Holding these in your head is taxing.

Solution: Drop them in chat, move to the matching checklist:

• Shop.md — groceries, household items
• Read.md — books, articles
• Watch.md — movies, shows
• MyChecklist_.md — custom checklists (any filename ending with _)

Example:

## Shop.md

- [ ] Butter
- [ ] Buns
- [ ] Coffee

## Read.md

- [ ] "Deep Work" by Cal Newport
- [x] "Atomic Habits" by James Clear

Feature 05: Notes with one idea per file

Problem: Notes become dumping grounds for unrelated thoughts.

Solution: Files.md enforces one idea per note. Each note should be understood without context.

Structure:

• brain/Note.md — default category
• <category>/*.md — custom categories (e.g., dev/React Hooks.md, health/Sleep Hygiene.md)

Linking: Type [ to insert a link to another file. Standard Markdown links: [Note Name](/path/to/note.md).

Philosophy:

1. Start with no structure (0 folders).
2. Add a note when you learn something new.
3. Apply knowledge immediately—don't save for future self.
4. Link related notes (type [).
5. Revisit and think through—this is where the work happens.

Anti-pattern: Don't create a "Second Brain" system that grows while your first brain stays static. Use your brain to think through the notes.

Feature 06: Habits tracking

Problem: Habit trackers are too complex. You just want to mark "Ate consciously today."

Solution: Habit files in habits/*.md. Each habit is a file. Each day you complete it, add a checkmark.

Example (habits/Ate consciously.md):

- [x] 2026.05.21
- [x] 2026.05.20
- [ ] 2026.05.19

Feature 07: LaTeX support (added May 20, 2026)

Why: LaTeX is text-based and LLM-friendly. Text + Math covers almost everything.

Usage: Write LaTeX inline or as blocks in any .md file.

Example:

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.

$$
E = mc^2
$$

Tradeoff: Adds ~20 font files, but the creator decided it's worth it for LLM-friendly math notation.

Feature 08: Telegram bot for on-the-go access

Problem: You're away from your computer. You want to dump a thought without opening the app.

Solution: Telegram bot. Send a message, it's saved to Chat.md. Later, open the app and move it to the right place.

Setup: Follow instructions at files.md (bot link in repo).

Other messengers: "Will follow" (Discord, Slack, etc. not yet available as of 2026-05-21).

Feature 09: Hotkeys for power users

Feature 10: Four sync options

How to use cloud folder sync:

1. Open app.files.md.
2. Click "Open a local folder" → choose your iCloud/Dropbox/Google Drive folder.
3. On other devices, open the same folder.
4. Files sync via the cloud provider.

How to self-host:

1. Clone the repo: git clone https://github.com/zakirullin/files.md.git
2. Run the server: cd files.md && make server (requires Go)
3. Point the app to your server URL in config.

File structure: predefined, LLM-friendly

Files.md uses a predefined structure to eliminate decision paralysis:

Chat.md                       # Chat/inbox for quick thoughts
brain/Note.md                 # Notes (default category)
<category>/*.md               # Notes in custom categories
journal/2024.08 August.md     # Journal entries (one file per month)
Later.md                      # Tasks
habits/Ate consciously.md     # Habit tracking
habits/*.md                   # Other habits
Read.md                       # Books/articles checklist
Watch.md                      # Movies/shows checklist
Shop.md                       # Groceries/items checklist
MyChecklist_.md               # Custom checklists (any filename ending with _)
media/*                       # Images (png, jpg, webp, gif)
archive/*.md                  # Archived notes
config.json                   # App configuration

LLM-friendly: Copy-paste the structure from files.md/llms.txt into your CLAUDE.md or AGENTS.md so AI agents understand the layout.

Example for AI agents:

# Files.md structure

- Chat: Chat.md
- Notes: brain/*.md, <category>/*.md
- Journal: journal/YYYY.MM Month.md
- Tasks: Later.md
- Habits: habits/*.md
- Checklists: Read.md, Watch.md, Shop.md, MyChecklist_.md

How to use Files.md for deep thinking (not collecting)

The README provides a 5-year-tested workflow:

1. Start with no structure (0 folders). Add folders only when needed.
2. One idea per note. Each note should be understood without context.
3. Apply new knowledge immediately. Don't save for future self.
4. Link related notes. Type [ to insert a link.
5. Revisit and think through. This is where understanding happens.

Example (from the creator):

I used app.files.md to grow my knowledge about brain and software development:

• I added new notes to either brain or dev folders. One idea per note.
• I made connections between relevant notes (type [).
• Everything is connected, just as in our brain.
• I spent time traveling through the notes and thinking it through.
• At one point, some brain and dev notes appeared very related.
• This connection between two different domains produced an insight.
• I wrote an article based on that insight: Cognitive Load in Software Development.

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

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.

Example (convert wikilinks):

go run /abs/path/to/files.md/cmd/tomdlinks/tomdlinks.go .

Installation and setup

Configuration:

• Open the app, click settings (⚙️), configure sync, Telegram bot, etc.
• config.json is stored in your files folder.

Contribution guidelines

From the README:

• Junior developers should be able to understand the code.
• Ideally, every PR should remove or simplify code, not add it.
• The less code we have, the more flexible we are.
• All dependencies are our code and responsibility. Avoid dependencies if possible.
• Code should be self-sufficient, so vendor/ and web/lib/ are included in the repository.
• Do we really need this feature? Will it help us do the real job, or does it just give dopamine?

Backend guidelines:

• We write tests.
• No get* prefix for methods.
• No panics; errors are part of business logic.
• Wrap errors with context.
• We prefer real implementations or fakes over mocks.

Frontend guidelines:

• Use PATCHED keyword if you modify web/lib/ in-place.
• No build systems—in 10 years, /web/index.html should just work.
• Avoid flaky E2E tests.
• Most bugs are caused by race conditions (async flows interrupted mid-through).

ADRs (Architecture Decision Records): 5 years of design choices

Selected highlights from the repo's ADR section:

Full ADR log: See README.md in the repo.

Related on ExplainX

• What are agent skills? Complete guide — portable instruction packs for LLMs
• MCP explained — tool protocol for agents
• oh-my-pi: terminal coding agent — LLM-friendly file structures
• Karpathy-inspired Claude Code guidelines — Think Before Coding, Simplicity First
• Agent harness engineering — scaffolding over model swaps

Sources

• Files.md repository: github.com/zakirullin/files.md
• Official site: files.md
• Web app (Beta): app.files.md
• LLMs.txt scheme: files.md/llms.txt
• Creator: Artem Zakirullin
• I Deleted My Second Brain: The Introspective Engineer
• Cognitive Load in Software Development: zakirullin.com

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.