doc-obsidian

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Obsidian Vault Management

Obsidian库管理

Unified vault operations using two CLI tools. No Obsidian app required.

Tool	Role	Install
doc-qmd	Search (keyword, semantic, hybrid)	`npm i -g @anthropic/qmd` or check `which qmd`
doc-notesmd	CRUD, move, frontmatter, daily notes, backlinks	`brew install yakitrak/yakitrak/notesmd-cli`

使用两款CLI工具实现统一的库操作，无需Obsidian应用。

工具	作用	安装方式
doc-qmd	搜索（关键词、语义、混合搜索）	`npm i -g @anthropic/qmd` 或执行 `which qmd` 检查
doc-notesmd	增删改查、移动、前置元数据、日常笔记、反向链接	`brew install yakitrak/yakitrak/notesmd-cli`

Setup

设置

First-Time Setup

首次设置

bash

undefined

bash

undefined

1. Set default vault for notesmd-cli

1. 为notesmd-cli设置默认库

notesmd-cli set-default "VaultName"

2. Index vault in qmd

2. 在qmd中索引库

qmd collection add ~/path/to/vault --name vault --mask "**/*.md" qmd embed # generate vector embeddings for semantic search

undefined

qmd collection add ~/path/to/vault --name vault --mask "**/*.md" qmd embed # 生成向量嵌入以支持语义搜索

undefined

Verify

验证

bash

notesmd-cli print-default    # shows vault name + path
qmd status                   # shows indexed docs + embedding status

bash

notesmd-cli print-default    # 显示库名称及路径
qmd status                   # 显示已索引文档及嵌入状态

Keep Index Fresh

保持索引更新

bash

qmd update       # re-index changed files
qmd embed        # embed new/changed docs

bash

qmd update       # 重新索引已修改文件
qmd embed        # 为新增/修改的文档生成嵌入向量

Tool Selection

工具选择

Task	Tool	Command
Search by keyword	qmd	`qmd search "term"`
Search by meaning	qmd	`qmd vsearch "conceptual question"`
Best search quality	qmd	`qmd query "complex question"`
Create note	notesmd-cli	`notesmd-cli create "name" --content "text"`
Append to note	notesmd-cli	`notesmd-cli create "name" --content "text" --append`
Read note	notesmd-cli	`notesmd-cli print "name"`
Partial edit	notesmd-cli + Edit	Read with `print` , edit via vault path + `Edit` tool
Move/rename	notesmd-cli	`notesmd-cli move "old" "new"` (updates all links)
Delete note	notesmd-cli	`notesmd-cli delete "name"` (permanent, no trash)
Daily note	notesmd-cli	`notesmd-cli daily`
Frontmatter	notesmd-cli	`notesmd-cli fm "name" --print / --edit / --delete`
Backlinks	notesmd-cli	`notesmd-cli print "name" --mentions`
List files	notesmd-cli	`notesmd-cli list [path]`
Recently modified	qmd	`qmd ls vault` (sorted by date, includes size)
Get document	qmd	`qmd get vault/note.md`
Batch retrieve	qmd	`qmd multi-get "folder/*.md" --json`

任务	工具	命令
关键词搜索	qmd	`qmd search "term"`
概念搜索（语义）	qmd	`qmd vsearch "conceptual question"`
高质量搜索	qmd	`qmd query "complex question"`
创建笔记	notesmd-cli	`notesmd-cli create "name" --content "text"`
追加笔记内容	notesmd-cli	`notesmd-cli create "name" --content "text" --append`
读取笔记	notesmd-cli	`notesmd-cli print "name"`
部分编辑	notesmd-cli + 编辑工具	用 `print` 读取，通过库路径+编辑工具进行编辑
移动/重命名	notesmd-cli	`notesmd-cli move "old" "new"` （自动更新所有链接）
删除笔记	notesmd-cli	`notesmd-cli delete "name"` （永久删除，无回收站）
日常笔记	notesmd-cli	`notesmd-cli daily`
前置元数据管理	notesmd-cli	`notesmd-cli fm "name" --print / --edit / --delete`
查看反向链接	notesmd-cli	`notesmd-cli print "name" --mentions`
列出文件	notesmd-cli	`notesmd-cli list [path]`
最近修改文件	qmd	`qmd ls vault` （按日期排序，包含文件大小）
获取文档	qmd	`qmd get vault/note.md`
批量获取文档	qmd	`qmd multi-get "folder/*.md" --json`

Search Workflows

搜索工作流

Quick Lookup (keyword)

快速查询（关键词）

bash

qmd search "authentication" -n 10
qmd search "authentication" --json      # structured output
qmd search "authentication" --md        # markdown for LLM context

bash

qmd search "authentication" -n 10
qmd search "authentication" --json      # 结构化输出
qmd search "authentication" --md        # 生成Markdown格式用于LLM上下文

Conceptual Search (semantic)

概念搜索（语义）

bash

qmd vsearch "how do we handle user sessions"
qmd vsearch "error recovery patterns" --json -n 5

bash

qmd vsearch "how do we handle user sessions"
qmd vsearch "error recovery patterns" --json -n 5

Deep Search (hybrid -- best quality)

深度搜索（混合搜索——最佳质量）

bash

qmd query "what decisions did we make about the API design?"
qmd query "deployment strategy" --full   # full document content

bash

qmd query "what decisions did we make about the API design?"
qmd query "deployment strategy" --full   # 返回完整文档内容

Search + Read Pattern

搜索+读取模式

bash

undefined

bash

undefined

Find relevant notes, then read full content

找到相关笔记，然后读取完整内容

qmd search "auth" --json -n 3 # find candidates notesmd-cli print "auth-design" # read the one you need

undefined

qmd search "auth" --json -n 3 # 找到候选笔记 notesmd-cli print "auth-design" # 读取所需笔记

undefined

Note CRUD

笔记增删改查

Create

创建

bash

notesmd-cli create "project/meeting-notes" --content "# Meeting\n\n## Agenda\n"
notesmd-cli create "inbox" --content "\n- New thought" --append
notesmd-cli create "scratch" --content "Replaced" --overwrite

--append

and

--overwrite

are mutually exclusive. Without either, existing files are unchanged.

Content supports escape sequences:

\n

\t

\r

\\

\"

\'

bash

notesmd-cli create "project/meeting-notes" --content "# Meeting\n\n## Agenda\n"
notesmd-cli create "inbox" --content "\n- New thought" --append
notesmd-cli create "scratch" --content "Replaced" --overwrite

--append

与

--overwrite

互斥。若不指定任一参数，现有文件内容保持不变。

内容支持转义序列：

\n

、

\t

、

\r

、

\\

、

\"

、

\'

。

Read

读取

bash

notesmd-cli print "architecture"                # raw content to stdout
notesmd-cli print "architecture" --mentions      # with backlinks appended
qmd get vault/architecture.md                    # via qmd (by indexed path)

bash

notesmd-cli print "architecture"                # 将原始内容输出到标准输出
notesmd-cli print "architecture" --mentions      # 附加反向链接内容
qmd get vault/architecture.md                    # 通过qmd获取（按索引路径）

Move/Rename (with link updates)

移动/重命名（自动更新链接）

bash

notesmd-cli move "drafts/post" "published/post"

All

[[wikilinks]]

and

[markdown](links)

across the vault are updated automatically.

bash

notesmd-cli move "drafts/post" "published/post"

库中所有

[[维基链接]]

和

[Markdown](链接)

都会自动更新。

Partial Edit (surgical updates)

部分编辑（精准更新）

notesmd-cli has no partial edit — only

--append

and

--overwrite

. For surgical changes (replace a section, update a table row, fix a line), use this workflow:

bash

undefined

notesmd-cli不支持部分编辑——仅支持

--append

和

--overwrite

。如需精准修改（替换某章节、更新表格行、修正某一行），请使用以下工作流：

bash

undefined

1. Get vault path

1. 获取库路径

VAULT=$(notesmd-cli print-default --path-only)

2. Read the note

2. 读取笔记内容

notesmd-cli print "note-name"

3. Edit in place using the Edit tool with the full file path:

3. 使用编辑工具直接编辑完整文件路径：

"$VAULT/path/to/note.md"


**Rules:**
- ALWAYS read with `notesmd-cli print` first — never guess content
- ALWAYS resolve the vault path via `notesmd-cli print-default --path-only`
- NEVER hardcode the vault path
- Use the `Edit` tool for targeted string replacement, not `sed` or `awk`
- For full rewrites, prefer `notesmd-cli create --overwrite` instead


**规则：**
- 始终先使用`notesmd-cli print`读取内容——切勿猜测内容
- 始终通过`notesmd-cli print-default --path-only`获取库路径
- 切勿硬编码库路径
- 使用编辑工具进行目标字符串替换，而非`sed`或`awk`
- 如需完全重写，优先使用`notesmd-cli create --overwrite`

Delete

删除

bash

notesmd-cli delete "scratch-note"    # permanent, no undo

Does NOT update links in other files referencing the deleted note.

bash

notesmd-cli delete "scratch-note"    # 永久删除，无法撤销

该操作不会更新其他文件中引用已删除笔记的链接。

Daily Notes

日常笔记

bash

notesmd-cli daily              # create/open today's note
notesmd-cli daily --editor     # open in $EDITOR

Reads

.obsidian/daily-notes.json

for folder, date format (Moment.js), and template. Template content is applied only when creating a new note.

bash

notesmd-cli daily              # 创建/打开今日笔记
notesmd-cli daily --editor     # 在$EDITOR中打开

会读取

.obsidian/daily-notes.json

中的文件夹、日期格式（Moment.js）和模板设置。仅在创建新笔记时会应用模板内容。

Append to Daily Note

追加内容到日常笔记

bash

DATE=$(date '+%Y-%m-%d')
notesmd-cli create "$DATE" --content "\n- $(date '+%H:%M') Task completed" --append

bash

DATE=$(date '+%Y-%m-%d')
notesmd-cli create "$DATE" --content "\n- $(date '+%H:%M') Task completed" --append

Templates

模板

notesmd-cli does not have a

--template

flag. Templates are plain markdown files stored in

meta/templates/

— create them once, reuse via

cp

notesmd-cli没有

--template

参数。模板是存储在

meta/templates/

中的纯Markdown文件——创建一次后，可通过

cp

命令复用。

Create Templates

创建模板

bash

notesmd-cli create "meta/templates/meeting" --content "# Meeting Notes\n\n**Date:** \n**Attendees:** \n\n## Agenda\n\n## Discussion\n\n## Action Items\n\n- [ ] "

notesmd-cli create "meta/templates/project" --content "# Project Name\n\n## Overview\n\n## Goals\n\n## Timeline\n\n## Status\n"

notesmd-cli create "meta/templates/decision" --content "# Decision: \n\n## Context\n\n## Options\n\n## Decision\n\n## Rationale\n\n## Consequences\n"

bash

notesmd-cli create "meta/templates/meeting" --content "# Meeting Notes\n\n**Date:** \n**Attendees:** \n\n## Agenda\n\n## Discussion\n\n## Action Items\n\n- [ ] "

notesmd-cli create "meta/templates/project" --content "# Project Name\n\n## Overview\n\n## Goals\n\n## Timeline\n\n## Status\n"

notesmd-cli create "meta/templates/decision" --content "# Decision: \n\n## Context\n\n## Options\n\n## Decision\n\n## Rationale\n\n## Consequences\n"

Create Note from Template

通过模板创建笔记

bash

VAULT=$(notesmd-cli print-default --path-only)
cp "$VAULT/meta/templates/meeting.md" "$VAULT/meetings/$(date +%Y-%m-%d).md"

Daily note templates are handled automatically — configure in

.obsidian/daily-notes.json

with a

template

field pointing to the template note path.

bash

VAULT=$(notesmd-cli print-default --path-only)
cp "$VAULT/meta/templates/meeting.md" "$VAULT/meetings/$(date +%Y-%m-%d).md"

日常笔记模板会自动处理——在

.obsidian/daily-notes.json

中配置

template

字段，指向模板笔记的路径即可。

Frontmatter

前置元数据

bash

notesmd-cli fm "note" --print
notesmd-cli fm "note" --edit --key "status" --value "done"
notesmd-cli fm "note" --edit --key "tags" --value "[cli,tools]"
notesmd-cli fm "note" --delete --key "draft"

Type inference:

true

false

-> boolean,

[a,b]

-> array, else string.

bash

notesmd-cli fm "note" --print
notesmd-cli fm "note" --edit --key "status" --value "done"
notesmd-cli fm "note" --edit --key "tags" --value "[cli,tools]"
notesmd-cli fm "note" --delete --key "draft"

类型推断：

true

false

-> 布尔值，

[a,b]

-> 数组，其他为字符串。

AI Agent Memory

AI Agent记忆

Use the vault as persistent memory for Claude Code or other AI agents.

将Obsidian库作为Claude Code或其他AI Agent的持久化记忆。

Store Knowledge

存储知识

bash

notesmd-cli create "memory/session-$(date +%Y%m%d)" \
  --content "# Session Notes\n\n## Learnings\n- Key insight here" \
  --overwrite

bash

notesmd-cli create "memory/session-$(date +%Y%m%d)" \
  --content "# Session Notes\n\n## Learnings\n- Key insight here" \
  --overwrite

Retrieve Context

检索上下文

bash

undefined

bash

undefined

Semantic search for relevant memories

语义搜索相关记忆

qmd vsearch "how did we solve the caching issue" --md -n 5

Hybrid search for best results

混合搜索获取最佳结果

qmd query "authentication architecture decisions" --full -n 3

undefined

qmd query "authentication architecture decisions" --full -n 3

undefined

Append Learnings

追加学习内容

bash

notesmd-cli create "memory/patterns" \
  --content "\n\n## $(date '+%Y-%m-%d')\n- New pattern discovered" \
  --append

bash

notesmd-cli create "memory/patterns" \
  --content "\n\n## $(date '+%Y-%m-%d')\n- New pattern discovered" \
  --append

Build LLM Context

构建LLM上下文

bash

undefined

bash

undefined

Get structured results for injection into prompts

获取结构化结果以注入提示词

qmd search "relevant topic" --json -n 10 qmd multi-get "memory/*.md" --json --max-bytes 20480


For detailed search patterns and agent memory workflows, see:
- `references/search.md` -- qmd search modes, output formats, score interpretation
- `references/agent-memory.md` -- Memory organization, retrieval patterns, automation

qmd search "relevant topic" --json -n 10 qmd multi-get "memory/*.md" --json --max-bytes 20480


如需了解详细的搜索模式和Agent记忆工作流，请参阅：
- `references/search.md` -- qmd搜索模式、输出格式、分数解读
- `references/agent-memory.md` -- 记忆组织、检索模式、自动化