NoteLLM 插件

English

通过 agent skills 和托管的 NoteLLM MCP 服务器，把你的原始 NoteLLM 转录内容带入 Codex 和 Claude Code。

快速开始：

npx notellm-plugin install

为什么需要 NoteLLM 插件？

当过去的想法散落在语音笔记、转录文本、会议记录或头脑风暴里时，Agent 很容易丢失有用的用户上下文。

NoteLLM 插件为 Agent 提供了一条直接检索 NoteLLM 内容的路径，让它们可以：

• 查找最近的原始转录内容
• 按主题搜索过去的笔记
• 找回你之前说过的原话，而不需要你重新描述
• 把旧笔记作为上下文使用，而不是当作绝对事实

包含内容

Skills

| Skill | 作用 | | --- | --- | | notellm-recent-notes | 立即显示最近的 NoteLLM 笔记 | | notellm-search-notes | 使用当前任务或对话作为上下文搜索 NoteLLM |

MCP 服务器

插件会连接到：

https://notellm.app/api/mcp

预期的 MCP tools：

| Tool | 作用 | | --- | --- | | list_recent_notes | 获取最近的 NoteLLM 笔记 | | search_notes | 按主题、短语、项目或人物搜索笔记 | | get_note | 打开指定笔记 | | batch_get_notes | 获取一小组已知相关的笔记 |

这些是 MCP tools，不是 skills。它们不会出现在 skills 列表中。

使用方式

可以直接用自然语言请求：

Show my recent NoteLLM notes.

Find my NoteLLM notes about the mobile app launch.

What did I previously say in NoteLLM about pricing?

也可以从 skills 列表中直接选择：

notellm-recent-notes
notellm-search-notes

在 Codex 中，它们可能会带有包名前缀：

$notellm:notellm-recent-notes
$notellm:notellm-search-notes

选择 notellm-recent-notes 时，Agent 应该立即检索最近的笔记。

选择 notellm-search-notes 时，Agent 应该使用当前对话搜索 NoteLLM。如果当前没有可用主题，它会询问要搜索什么。

安装

npx notellm-plugin install

选择一个选项：

1) Codex
2) Claude Code
3) Both
4) Exit

安装器会为所选客户端添加 NoteLLM skills，并配置 NoteLLM MCP 服务器。

非交互式安装：

npx notellm-plugin install --client codex
npx notellm-plugin install --client claude-code
npx notellm-plugin install --client all
npx notellm-plugin install --client claude-code --project

MCP 配置默认使用用户/全局 scope。需要把 Claude Code MCP 配置写入当前项目的 .mcp.json 时，显式加 --project。

更新使用同样的选择器：

npx notellm-plugin update

卸载也使用同样的选择器：

npx notellm-plugin uninstall

非交互式更新和卸载同样支持 --client codex、--client claude-code 和 --client all。

Codex 验证

添加 MCP 服务器后，Codex 会启动 NoteLLM OAuth 流程。打开授权 URL，登录 NoteLLM，并批准 asr:read scope。

验证：

codex mcp list

你应该看到：

notellm  https://notellm.app/api/mcp

然后启动 Codex 并询问：

Show my recent NoteLLM notes.

Claude Code 验证

默认情况下，安装器会把 Claude Code MCP 配置写入用户 scope，使其跨项目可用。

选择 2) Claude Code 后，安装结束时应该看到类似输出：

Added HTTP MCP server notellm with URL: https://notellm.app/api/mcp to user config

这是预期行为。Claude Code 不会在执行 mcp add 时启动 OAuth。

启动 Claude Code：

claude

从 skills 列表中选择 notellm-recent-notes，或者直接询问：

Show my recent NoteLLM notes.

当第一次使用 NoteLLM MCP tool 时，Claude Code 会从客户端会话中启动 OAuth。

如果需要项目级 Claude Code MCP 配置，运行：

npx notellm-plugin install --client claude-code --project

认证

NoteLLM MCP 使用带 PKCE 的 OAuth 2.1。

必需 scope：

asr:read

插件不会询问用户的 NoteLLM 密码，也不会内嵌 access token。

本地开发

运行隔离的本地 E2E 测试：

npm run e2e:local

该测试会验证 skill 安装、Codex MCP 注册、Codex OAuth 启动，以及 Claude Code MCP 配置写入，并且不会修改你的真实 home 目录。

如果要在真实 Codex 环境中测试当前 checkout：

codex mcp remove notellm || true
node bin/notellm-plugin.js install --source .
codex

菜单出现后，选择 1) Codex。

然后从 skills 列表中选择 notellm-recent-notes，或者询问：

Show my recent NoteLLM notes.

发布测试前清理本地安装产物：

node bin/notellm-plugin.js uninstall

菜单出现后，选择你之前安装过的客户端。

不要在此仓库根目录运行 npx skills remove ...；本仓库本身也包含 skills/ 下的源 skill。

使用同样的交互流程测试更新：

node bin/notellm-plugin.js update --source .

菜单出现后，选择要更新的客户端。

测试项目级 Claude Code MCP 配置时，请在一次性项目目录中使用 --project。

构建

npm run build
npm run verify

构建输出：

dist/codex/.codex/
dist/claude-code/.claude/

发布冒烟测试

发布后：

codex mcp remove notellm || true
npx notellm-plugin install --client codex
codex

当 notellm-recent-notes 或自然语言 NoteLLM 请求在 OAuth 后返回真实 NoteLLM 内容时，发布包即为有效。

支持的客户端

• Codex
• Claude Code