Markdown笔记管理工具

tnotes

AI-native note-taking for plain Markdown files.

tnotes is a small Go CLI with an MCP server and a Neovim/Telescope plugin. Notes live as regular .md files with YAML frontmatter. The derived search indexes live in a per-machine cache, outside the notes directory.

Features

• plain Markdown notes with YAML frontmatter
• timestamp-based note IDs
• fast indexed search over titles and content
• automatic project:<name> and path:<cwd> tags on note creation
• MCP server for AI assistants
• Neovim plugin with Telescope pickers

Install

CLI

go install github.com/toshism/tnotes@latest

Neovim

Requires:

• tnotes in your $PATH
• telescope.nvim
• plenary.nvim

{
  "toshism/tnotes",
  dependencies = {
    "nvim-telescope/telescope.nvim",
    "nvim-lua/plenary.nvim",
  },
  config = function()
    require("tnotes").setup()
  end,
}

Quick start

# initialize the notes directory (default: ~/tnotes)
tnotes init

# create a note
tnotes add "My first note"

# create a note with tags
tnotes add "Search ideas" --tags search,bleve

# list notes
tnotes list

# search notes
tnotes search "query"
tnotes search --tag meeting
tnotes search --project toshism/tnotes "index rebuild"

# show a note by ID
tnotes show 20260219143022

# force a full rebuild of the indexes
tnotes index

All commands support --json.

Storage and config

By default notes are stored in ~/tnotes.

You can override the notes directory with, in priority order:

1. --dir
2. TNOTES_DIR
3. ~/.config/tnotes/config.toml

Example config:

notes_dir = "~/notes/tnotes"

The notes directory holds only your *.md note files. The indexes for it live in $XDG_CACHE_HOME/tnotes/<notes-dir-path>/ (default ~/.cache/tnotes/):

• index.json metadata index
• bleve/ full-text search index

The indexes hold absolute paths, so each machine keeps its own. This lets you sync the notes directory (for example with Syncthing) to machines that mount it at different paths. search, list and show check the notes on disk before reading, and update the indexes for any note that was added, changed or deleted, including notes edited outside tnotes. A full rebuild (tnotes index) is only needed if the cache gets into a bad state.

Older versions kept the indexes in a .tnotes/ folder inside the notes directory. Current versions ignore it. Once every machine runs a current version, you can delete it.

Project tagging

When creating notes, tnotes resolves the project name in this order:

1. .tnotes-project file found by walking upward
2. git remote origin, normalized to org/repo
3. current directory basename

New notes automatically get:

• project:<resolved-project>
• path:<current-working-directory>

You can also set the project explicitly with tnotes add --project <name>.

Search

tnotes search searches indexed note titles and content.

Examples:

tnotes search "roadmap"
tnotes search --tag meeting
tnotes search --project toshism/tnotes "bleve"
tnotes search --snippet "index"

The Neovim Telescope picker also supports prompt prefixes like:

• tag:meeting
• project:toshism/tnotes
• tag:meeting project:toshism/tnotes roadmap

MCP server

Run the stdio MCP server with:

tnotes mcp

Claude Code / Claude Desktop config:

{
  "mcpServers": {
    "tnotes": {
      "command": "tnotes",
      "args": ["mcp"]
    }
  }
}

Custom notes directory:

{
  "mcpServers": {
    "tnotes": {
      "command": "tnotes",
      "args": ["mcp", "--dir", "/path/to/notes"]
    }
  }
}

Available MCP tools:

• tnotes_init
• tnotes_list
• tnotes_search
• tnotes_show
• tnotes_add
• tnotes_index

Neovim

Default mappings:

User commands:

• :TnotesNew [title]
• :TnotesRefresh
• :Telescope tnotes notes
• :Telescope tnotes notes_all
• :Telescope tnotes tags
• :Telescope tnotes search

Example config:

require("tnotes").setup({
  bin = "tnotes",
  mappings = {
    follow_link = "gf",
    new_note = "<leader>nn",
    search = "<leader>ns",
    tags = "<leader>nt",
  },
  telescope = {
    theme = nil, -- or "dropdown", "ivy", "cursor"
  },
})

CLI reference

License

MIT