Auto-Zettelkasten for Obsidian

English — Auto-Zettelkasten turns conversations, files in an Obsidian vault, clipboard text, and web articles into reusable atomic notes. Inspired by A-MEM: Agentic Memory for LLM Agents, it automatically generates metadata and tags, retrieves related notes, creates bidirectional wikilinks, and performs lightweight memory evolution.

中文 — Auto-Zettelkasten 将对话、Obsidian vault 内的文件、剪贴板文本和网页文章转换成一组可复用的原子笔记（atomic notes）。它借鉴 A-MEM: Agentic Memory for LLM Agents 的思路，自动生成元数据和标签、检索相关笔记、建立双向链接，并进行轻量的记忆演化。

This is an Obsidian Community plugin project, not a wrapper around the A-mem Python repository. It maps A-mem's MemoryNote metadata, nearest-neighbor retrieval, and strengthen / update_neighbor evolution operations to Obsidian Markdown, YAML frontmatter, and wikilinks.

这是一个 Obsidian 社区插件项目，不是 A-mem Python 仓库的封装。它把 A-mem 的 MemoryNote 元数据、近邻检索和 strengthen / update_neighbor 演化流程映射到 Obsidian Markdown、YAML frontmatter 和 wikilinks。

Features / 已实现功能

Chatbot over notes / 基于 notes 的问答

• English — Open the chatbot with the Auto-Zettelkasten: Open notes chatbot command or the sidebar message icon. It embeds your question, retrieves the most relevant A-mem notes, answers only from those notes, and links to each source. Retrievals update each note's retrieval_count and last_accessed. Chat history stays in the sidebar session and is not written to the vault.
• 中文 — 通过命令面板的 Auto-Zettelkasten: Open notes chatbot 或侧栏消息图标打开。插件对问题生成 embedding，从 A-mem 索引检索最相关的 notes，再仅依据这些内容回答，并附上可点击的来源笔记。每次检索会更新对应 note 的 retrieval_count 与 last_accessed。聊天记录默认只存在当前侧栏会话，不会写入 Vault。

Input sources / 输入入口

• English — Vault files (Markdown, TXT, HTML, JSON, CSV) via the command or the file context menu; the current editor selection; clipboard text; and article URLs fetched through Obsidian requestUrl.
• 中文 — 通过命令或文件右键菜单处理 vault 内的文件（Markdown、TXT、HTML、JSON、CSV）；支持编辑器选中文本、剪贴板文本，以及通过 Obsidian requestUrl 获取的网页文章 URL。

A-mem-style note generation / A-mem 风格 note 生成

• English — Splits long content into chunks and asks the LLM to produce independent, retrievable atomic notes. Each note stores content, keywords, context, category, tags, timestamps, retrieval counts, links, and evolution history.
• 中文 — 将较长内容按段落分块，并要求 LLM 产出多个独立、可检索的 atomic notes。每条 note 都含有 content、keywords、context、category、tags、时间戳、检索次数、链接和演化历史。

Lightweight A-mem evolution / 轻量 A-mem 演化

• English — Embeds new and existing notes, takes the Top-K neighbors, then asks the LLM to make A-mem-aligned strengthen / update_neighbor decisions. It creates bidirectional wikilinks and optionally updates existing notes' context, tags, retrieval_count, and evolution_history.
• 中文 — 对新 note 和既有 note 调用 OpenAI-compatible embeddings，取 Top-K 近邻后，让 LLM 作出与 A-mem 对齐的 strengthen / update_neighbor 决策；建立双向 [[wikilink]]，并可更新旧 note 的 context、tags、retrieval_count 和 evolution_history。

Maintenance / 自动维护

• English — Maintains A-mem/_A-mem MOC.md and persists a lightweight semantic index in A-mem/_amem-index.json.
• 中文 — 自动维护 A-mem/_A-mem MOC.md，并在 A-mem/_amem-index.json 中保存轻量检索索引和向量。

Installation / 安装

1. Build / 构建

English — Run these commands in the project directory:

中文 — 在本项目目录执行：

npm install
npm run build

2. Install into your vault / 安装到你的 vault

English — Create the target folder:

中文 — 创建目标目录：

<your Obsidian vault>/.obsidian/plugins/auto-zettelkasten/

English — Copy the build artifacts into that folder, then enable the plugin.

中文 — 将以下构建产物复制到该目录，然后启用插件。

main.js
manifest.json
styles.css

English — In Obsidian: open Settings → Community plugins, disable Restricted mode if needed, refresh the community plugin list, and enable Auto-Zettelkasten.

中文 — 在 Obsidian 中：打开 Settings → Community plugins，如有需要先关闭 Restricted mode，刷新社区插件列表并启用 Auto-Zettelkasten。

English — For development, link or copy this project into the plugin folder, run npm run build after each change, then reload the plugin.

中文 — 开发时，可以把此项目目录直接链接或复制到上述插件目录；每次修改后运行 npm run build，然后在 Obsidian 中重新加载插件。

Model configuration / 配置模型

English — Open Settings → Auto-Zettelkasten and fill in:

中文 — 打开 Settings → Auto-Zettelkasten，填写：

Setting / 配置项	Description / 说明
OpenAI-compatible base URL	Root URL of the chat service, usually ending in /v1. The plugin calls POST /chat/completions. 聊天模型服务的根 URL，通常以 /v1 结尾。
API key	Chat model API key; use a restricted key where possible. 聊天模型 API key，建议使用可限制额度/权限的 key。
Chat model	A chat model that can return structured JSON. 能稳定返回 JSON 的对话模型。
Embedding model	Used for nearest-neighbor retrieval. 用于近邻检索的 embedding 模型。
Embedding base URL / API key	Optional. Set these when your chat provider does not expose /embeddings; leave empty to reuse the chat URL and key. 可选。如果聊天供应商没有 /embeddings，可单独填写另一个 OpenAI-compatible embedding 服务；留空则复用聊天 URL 与 key。

English — Chat and embedding APIs can be different services. If embedding fails, notes are still created with tags and the plugin falls back to keyword similarity.

中文 — 聊天和 embedding API 可以分开：例如用支持 /chat/completions 的模型生成笔记，再使用另一个兼容 /embeddings 的服务建立关联。如果 embedding 调用失败，插件仍会生成带标签的笔记，并降级为关键词相似度。

Usage / 使用方法

Conversations / 对话

English — Copy a conversation, then run Auto-Zettelkasten: Ingest clipboard text as A-mem notes. Alternatively, export the conversation as Markdown/JSON into the vault and run Auto-Zettelkasten: Ingest current file as A-mem notes.

中文 — 复制对话内容后，运行 Auto-Zettelkasten: Ingest clipboard text as A-mem notes。或者将对话导出为 Markdown/JSON 放入 vault，再对该文件运行 Auto-Zettelkasten: Ingest current file as A-mem notes。

English — An Obsidian plugin cannot read the current conversation state of an external web/desktop app (including the DSH GUI). Clipboard and exported chat files are the one-click entry points today.

中文 — Obsidian 插件无法直接读取外部网页/桌面应用（包括 DSH GUI）的当前对话状态；剪贴板和聊天导出文件是当前的一键入口。

Files and articles / 文件与文章

• English — Open a vault text file and run Auto-Zettelkasten: Ingest current file as A-mem notes.
• 中文 — 打开 vault 中的文本文件，运行 Auto-Zettelkasten: Ingest current file as A-mem notes。
• English — Right-click a file in the file explorer and choose Create A-mem notes from this file.
• 中文 — 或在文件资源管理器中右键文件，选择 Create A-mem notes from this file。
• English — Select text and run Auto-Zettelkasten: Ingest selected text as A-mem notes.
• 中文 — 选中一段内容，运行 Auto-Zettelkasten: Ingest selected text as A-mem notes。
• English — Run Auto-Zettelkasten: Ingest web article URL as A-mem notes and enter a URL.
• 中文 — 运行 Auto-Zettelkasten: Ingest web article URL as A-mem notes 并输入文章 URL。

English — Markdown, TXT, HTML, JSON, and CSV are supported directly. Convert PDFs to Markdown or plain text first. Dynamically rendered pages may need their content saved manually.

中文 — 当前直接支持 Markdown、TXT、HTML、JSON、CSV。PDF 需先用 OCR/文本提取器转换为 Markdown 或纯文本；动态渲染且正文不在初始 HTML 中的网站也可能需要先保存正文。

Output structure / 输出结构

English — Notes are written to A-mem/ by default:

中文 — 默认写入 vault 的 A-mem/ 目录：

A-mem/
├── 20250308-1530-example-note-a1b2c3.md
├── 20250308-1531-another-note-d4e5f6.md
├── _A-mem MOC.md
└── _amem-index.json

English — A generated note looks like:

中文 — 每条生成笔记类似：

---
id: "uuid"
amem: true
note_type: "insight"
category: "Research"
tags:
  - "amem"
  - "amem/source/article"
  - "amem/category/research"
  - "amem/agent-memory"
keywords:
  - "A-mem"
  - "Zettelkasten"
context: "…"
links:
  - "related-memory-id"
evolution_history: []
---

# 笔记标题

独立、可复用的笔记正文。

## Links

- [[A-mem/相关笔记|相关笔记]]

A-mem field mapping / 与 A-mem 的字段映射

A-mem field / 字段	Obsidian mapping / 映射
id, content	YAML id and Markdown body / YAML id 与 Markdown 正文
keywords, context, category, tags	YAML frontmatter + body sections / YAML frontmatter + 正文小节
links	YAML memory IDs + bidirectional [[wikilink]] / YAML 内存 ID + 双向 [[wikilink]]
timestamp, last_accessed, retrieval_count	YAML frontmatter
evolution_history	YAML evolution history / YAML 演化记录
Chroma similarity search	Cosine similarity over embeddings persisted in _amem-index.json / _amem-index.json 中持久化 embedding 的余弦相似度检索

Privacy and cost / 隐私与费用

• English — Source text and candidate note metadata are sent to your configured chat/embedding services. Do not process sensitive content until you confirm the provider's data policy.
• 中文 — 原始文本片段、候选 note 元数据会发送到你配置的聊天/embedding 服务；请勿在未确认供应商数据政策前处理敏感内容。
• English — API keys are stored in Obsidian plugin data, not the system keychain. Use restricted keys and avoid syncing data.json to untrusted locations.
• 中文 — API key 存在 Obsidian 插件数据中，而不是系统密钥链。请使用受限 key，并避免同步 data.json 到不可信位置。
• English — Long files can trigger multiple chat and embedding requests. Lower Maximum notes per ingestion or disable Auto-link and A-mem evolution to control cost.
• 中文 — 文章/长文件会产生多次聊天和 embedding 请求。可在设置中调低 Maximum notes per ingestion 或关闭 Auto-link and A-mem evolution 控制成本。

Design boundaries / 设计边界

• English — This is a lightweight implementation: embeddings are stored in the vault and no local ChromaDB or sentence-transformers service is required.
• 中文 — 这是轻量实现：向量索引保存在 vault 中，未启动本地 ChromaDB 或 sentence-transformers 服务。
• English — Neighbor updates are conservative: only the LLM's explicit update_neighbor action writes back to existing notes.
• 中文 — A-mem 的邻居更新是可选且保守的：只有 LLM 明确选择 update_neighbor 时才写回旧 note。
• English — Test in a scratch vault first to review tags, links, and model output before processing a large corpus.
• 中文 — 建议先在测试 vault 试跑，检查标签词表、链接质量和模型输出后再处理大量资料。

Development validation / 开发验证

English — The project is validated with:

中文 — 本项目已通过：

npx tsc --noEmit
npm run build