Auto MOC and AI Tagger

Version 1.0.3 requires Obsidian 1.13.0 or later. See CHANGELOG.md for migration notes and validation scope.

Development

npm ci
npm run lint
npm test
npm run build

The repository includes official Obsidian lint checks, regression tests, and GitHub Actions build artifacts. Release assets must include main.js, manifest.json, and styles.css; keep manifest.json at the root of the default branch.

Data and network use

Tagging sends the active note body to the configured provider. Recommendations can send up to 2,000 characters from each candidate note across the vault to the configured embedding provider. Local Ollama endpoints keep these requests local; hosted endpoints receive the input. Requests begin when you start processing in the AI panel. Model lists are fetched when the relevant settings render.

API keys are stored in local plugin data.json and masked in the settings UI. Embedding vectors and note paths are stored in embeddings-cache.json. Neither file belongs in Git. This plugin has no telemetry. Missing Ollama models must be installed manually with ollama pull <model>.

Request timeout/cancellation stops waiting and prevents late note writes, but Obsidian's underlying HTTP request may continue at the provider. Existing legacy recommendation sections are preserved on migration; remove any duplicate old section manually.

For more pleasant quick-start, please read: 📖 docs Automatically maintain folder-level Maps of Content (MOCs) and use a local or cloud LLM to tag notes and recommend similar notes based on vector embeddings.

Features

• Auto MOCs — Generate and update a MOC.md for every folder in your whitelist, listing child folders and notes with their tags, last-modified date, and clickable wikilinks.
• AI Tagging — Send notes to Ollama, OpenAI, or Anthropic and write generated tags back to YAML frontmatter.
• Similar Notes — Embed note contents with a local or hosted embedding model and show the top-N most similar notes in a side panel.
• Live Updates — Create, delete, rename, and modify events update MOCs within a configurable debounce window.
• Bilingual UI — Switch between 中文 and English from the settings tab. The plugin UI, generated MOCs, and the LLM tag-extraction prompt all follow the chosen language.
• Privacy First — Bring-your-own endpoint. Local Ollama keeps everything on your machine; cloud providers are opt-in.

Installation

From Obsidian Community Plugins (after approval)

1. Open Settings → Community plugins.
2. Make sure Community plugins are enabled.
3. Click Browse and search for Auto MOC and AI Tagger.
4. Click Install, then Enable.

Manual / BRAT

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Create the folder <vault>/.obsidian/plugins/auto-moc-ai-tagger/.
3. Drop the three files inside.
4. Enable the plugin in Settings → Community plugins.

Quick Start

1. Open Settings → Auto MOC and AI Tagger.
2. Add the folders you want MOCs for to the Whitelist (e.g. 学习, 工具).
3. (Optional) Pick a tagging provider. Ollama is the easiest zero-cost option:
   • Install Ollama and pull a small model: ollama pull qwen2.5:0.5b.
   • Set taggingProvider to ollama (default).
4. (Optional) Pick an embedding provider for similar-notes. Recommended: nomic-embed-text via Ollama.
5. Run the command Update all MOCs from the command palette (or click the brain-circuit ribbon icon).

Commands

Settings

The plugin stores settings in .obsidian/plugins/auto-moc-ai-tagger/data.json. Adjustable from the settings tab:

• Whitelist — folders to maintain MOCs for.
• Recursive — include sub-folders when generating MOCs.
• Unclassified Header — section heading for notes without tags.
• Clean Broken Links — strip wikilinks that no longer resolve.
• Preserve User Content — keep your handwritten content outside the auto-generated block.
• MOC Show Stats — render the top summary callout (folder / note / tag counts).
• MOC Show Dates — append a 📅 YYYY-MM-DD modification date to each entry.
• MOC Show Icons — toggle the emoji chrome (📚 / 📁 / 📄 / 🕒 / 🤖).
• MOC Tag Style — render tags as `tag` (code) or #tag (hash).
• MOC Sort By — order notes inside each section by mtime (default) or name.
• Tagging Provider — ollama / openai / anthropic.
• Tag Count / Max Length — limits on generated tags.
• Embedding Provider — ollama / openai (for similar notes).
• Max Recommendations — top-N similar notes to show.

MOC Layout (v1.1)

Generated MOCs now ship with a stats callout, folder callouts, code-style tags, per-note dates, and a generation footer:

---
tags:
  - "笔记/MOC"
moc: true
创建: 2026-06-15
更新: 2026-06-15 14:30
---

# 📚 学习 · 知识地图

> [!info] **📊 知识地图概览**
> 📂 **5** 个子文件夹 · 📄 **42** 篇笔记 · 🏷️ 平均 **3.0** 个标签/篇
> 🕒 最后更新：2026-06-15 14:30

---

## 📁 子文件夹1 · 15 篇

> [!note] 🗂️ 拥有独立 MOC · [[子文件夹1/MOC|查看子目录]]

- 📄 [[Note1|Note1]] `tag1` `tag2` `tag3` · 📅 2026-06-15
- 📄 [[Note2|Note2]] `tag1` · 📅 2026-06-14

## ❓ 未分类 · 5 篇

- 📄 [[Note4|Note4]] · 📅 2026-06-12

---

🤖 Auto-generated by Auto MOC & AI Tagger · 2026-06-15 14:30

Existing MOCs are regenerated automatically on the next file event in the folder (or run 更新所有白名单的 MOC from the command palette to force-refresh the whole tree).

Privacy

Your notes and embeddings never leave your machine unless you explicitly configure a cloud provider (OpenAI, Anthropic). Embeddings are cached locally in embeddings-cache.json inside the plugin folder.

License

MIT — see LICENSE.

Author

zhangpl666ya — https://github.com/zhangpl666ya