Nix

Nix

https://paulocesaaars.github.io/nix/

MCP 服务，可向开发 Agent（Cursor、VS Code、Claude Code 和 Codex）提供 Markdown 格式的 Wiki。支持混合搜索，以及笔记读写——使用本地且免费的嵌入和向量数据库。推理由客户端负责；Nix 只提供工具。默认关闭的 Mega Brain 会将 Agent 之间的记忆保存在你选择的 Wiki 中。

传输方式：MCP stdio。在终端中，不带子命令运行 nix 会打开界面。MCP 客户端即使不使用终端，也会继续接收服务。

为什么使用

• 编辑器中的 Agent 能找到想法，而不只是关键词：在 vault 中进行语义 + 词法搜索。
• 无需离开 Cursor，即可用 Markdown 创建和更新笔记。
• 一切都在你的机器上运行。vault 中的任何内容都不会发送到嵌入 API。
• 由你控制索引何时更新：没有后台监视器。

要求

• Windows amd64、Linux（amd64 或 arm64）或 macOS Apple Silicon
• 一个 Markdown 笔记文件夹（.md）
• 首次同步需要约 220 MB 可用空间（默认模型 lulu）。spitz（BAAI/bge-m3）约占 2.3 GB

release 二进制文件无需安装 Python：下载的文件已包含运行时。如果公司屏蔽了 .exe、PowerShell 和安装程序下载链接，请在 Git Bash 中下载 release 中的源代码 zip，并通过 Python 安装，参见可执行文件、PowerShell 和下载链接被屏蔽时。

安装

安装程序会从最新版本下载 nix 和 nix-hook，校验各自的 SHA-256，并写入 NIX_HOME。之后可在界面中注册 wiki。会话钩子会调用 nix-hook。

Windows（PowerShell）：

irm https://raw.githubusercontent.com/paulocesaaars/nix/main/install.ps1 | iex

Linux 和 macOS：

curl -fsSL https://raw.githubusercontent.com/paulocesaaars/nix/main/install.sh | sh

完成后，运行 nix 打开界面。如果命令无法运行，请关闭终端，重新打开后再试。

安装目录在 Windows 上为 %LOCALAPPDATA%\nix，在 macOS 上为 ~/Library/Application Support/nix，在 Linux 上为 ~/.local/share/nix（或已存在的 NIX_HOME）。二进制文件位于 {NIX_HOME}/bin。Windows arm64 和 macOS Intel 没有可用的二进制文件：安装程序会提示并停止。

首次运行时，会将二进制文件解压到缓存目录（Windows 上为 %LOCALAPPDATA%\nix\onefile-<版本>，macOS 上为 ~/Library/Caches/nix/onefile-<版本>，Linux 上为 ~/.cache/nix/onefile-<版本>）。安装程序会自动完成首次启动。之后的运行会复用缓存。nix-hook 与 nix 放在一起：完整二进制文件每次启动时都会校验整个负载的 CRC，无法满足会话钩子的 300 ms 时间预算。nix hooks install 会将 Agent 指向 nix-hook，其缓存位于同一目录下的 hook-<版本>。

接下来，在编辑器中注册服务 — 请参阅 在 MCP 客户端中注册。安装程序会写入 NIX_HOME 并将 nix 添加到 PATH。运行 nix 打开界面。如果命令无法运行，请关闭终端，重新打开后再试。如果自动注册失败，请参阅手动注册 NIX_HOME 和 PATH。如果 Nix 包管理器（NixOS）已在 PATH 中，安装程序会发出提示：此 nix 将获得更高优先级。

NIX_VERSION=1.2.3（带或不带 v）可安装指定版本。

可执行文件、PowerShell 和下载链接遭到阻止时

有些网络会阻止下载 .exe、运行 PowerShell，以及下载 install.ps1 所需的文件（脚本和发行版二进制文件的 irm 请求）。解决方法是下载最新发行版中的源代码 zip 文件（Source code (zip)），然后使用 Python 安装，即从源代码安装（开发者）一节所述的方式。整个过程中不会在计算机上安装 nix.exe。

如果公司电脑无法访问 GitHub，请在另一台电脑上下载该 zip 文件，然后复制过来。解压并进入文件夹（nix-<versão>）。在 Git Bash 中，使用 Python 3.11 或更高版本：

python scripts/bootstrap.py

bootstrap.py 会创建 .venv、安装 requirements.txt 中的包、写入 NIX_HOME，并将 nix 添加到 PATH。之后可在界面中注册 Wiki。发行版 zip 文件包含此脚本和 requirements.txt。requirements-dev.txt 仅包含在完整的 Git 克隆中：开发者一节中使用此文件的命令列表，适用于从克隆修改代码的用户。pip 必须能够访问 PyPI。

如果当前 Bash 中没有 python，请使用 py 或 python3。如果可以使用 Git，同一脚本也可以在克隆后运行：

git clone https://github.com/paulocesaaars/nix.git
cd nix
python scripts/bootstrap.py

运行 nix 打开界面。如果命令无法运行，请关闭终端，再打开一个终端重试。在已打开的终端中：

source bin/env.sh

MCP 中没有 nix.exe。请将 command 指向环境中的 Python，并在 args 中传入模块。如果 zip 文件或克隆位于其他位置，请替换文件夹路径：

{
  "mcpServers": {
    "nix": {
      "command": "C:/Git/nix/.venv/Scripts/python.exe",
      "args": ["-P", "-m", "nix"]
    }
  }
}

此安装方式的钩子会调用 python -m nix hook。不会安装发行版中的 nix-hook.exe。

要撤销此安装，请在已解压的文件夹或克隆目录中运行：python scripts/uninstall.py。Wiki 文件夹不会受到影响。--yes 会跳过确认提示；--keep-data 会保留 settings.db 和索引。通过 install.ps1 或 install.sh 安装的二进制文件，请使用卸载一节中的命令移除。

首次同步仍会下载嵌入模型（约 220 MB，即 lulu）。

从源代码安装（开发者）

修改 Nix 的用户需使用 venv。根目录中的 install.ps1 会下载已发布的二进制文件，不会安装此代码库的检出版本。

python -m venv .venv
# Windows (Git Bash): source .venv/Scripts/activate
# Linux/macOS:        source .venv/bin/activate

pip install -r requirements-dev.txt
pip install -e .
python -m nix init                # ou: python -m nix init --wiki "C:/Notas/MinhaWiki"

相同的流程（包括 PATH 注册）也可以通过 python scripts/bootstrap.py 运行。要撤销此检出版本，请运行：python scripts/uninstall.py。

激活 venv 后即可使用 python -m nix。Cursor 不会继承终端的 PATH；在开发 MCP 配置中，请将 command 指向 .venv 中的 Python，并传入 -P -m nix，或者指向此代码库中的 shim bin/nix。

Agent 技能（开发者）

开发技能（更新文档、审查代码和提交代码）以版本控制形式存放在此代码库中，分别位于 .claude/skills/（Claude Code 和 Cursor）和 .agents/skills/（Cursor 和 VS Code）。skills-lock.json 会记录已同步技能的来源。

Mega Brain

在界面中，打开 Mega Brain → 配置，选择一个已注册的 wiki，并启用或禁用此功能。保存并重启 MCP 客户端。记忆工具无需 hooks 即可运行；自动捕获会话则需要 hooks。通过环境变量设置的字段会单独锁定；另一个字段仍可编辑。

默认关闭。选择页面所在的 wiki 并开启：

nix brain enable --wiki Default

此 wiki 计入 100 个的上限，且 Mega Brain 开启时无法移除。捕获仍需要 hook。没有任何 Agent 会被默认选中。修改已有文件前会提供预览、确认和备份。全局范围会提示可能记录其他仓库中的事件。

nix brain hooks install --scope project
nix brain hooks install --scope global

项目是 Git 根目录；如果没有仓库，则是该文件夹。.nix.toml 可以定义 project、[capture] enabled / exclude 和 [profile] contribute / consume。无法读取 Toml 时会关闭捕获。

Agent	项目中的 hook 文件
Cursor	.cursor/hooks.json
VS Code	.github/hooks/nix.json
Claude Code	.claude/settings.local.json
Codex	.codex/hooks.json（只有在 /hooks 中信任后才会执行）
Devin（CLI 和桌面端）	.devin/hooks.v1.json

nix brain hooks install --all 会按此顺序为这些客户端安装 hook。列表中的其他客户端（Command Code、OpenCode、Gemini CLI、GitHub Copilot CLI 等）只能进行部分捕获：不会凭空创建 JSON。只有确认路径后，全局范围才会写入文件。

会话页面会写入 Mega Brain wiki 中的 projects/<projeto>/sessions/。只有会话结束并运行 nix brain work 后，页面才会写入。交接和留言保存在知识库中，不在此页面内。

面板。 每张卡片代表一个项目：Agent 工作目录的 Git 根目录；如果没有仓库，则是该文件夹本身。名称取自文件夹名，或 .nix.toml 中的 project 字段。首次捕获会话后，卡片便会显示，并列出会话数量、Agent 和最近活动。打开项目后可查看概览、Agent、令牌、会话和知识。

收件箱。 这是 Agent 之间的留言队列，与交接分开。brain_message_send 会将文本发送给指定接收者，或发送给项目中的任何人。留言初始状态为等待中。brain_message_pop 会仅交付一次最早的留言，并将其标记为已交付。在此之前可以取消留言，将其移出队列。页面会列出项目、接收者、文本和状态（等待中、已交付或已取消），包括已交付的留言。

个人资料。 这是你在请求中写下的偏好，不涉及语言模型。Nix 会查找“始终使用”“我更喜欢”“绝不使用”及对应的英文表达，后面跟着一个词。已知工具（pnpm、pytest、ruff、docker、git 等）会存入 profile/tools/。其余内容会存入 profile/habits/。同一主题至少在两个项目中出现时，这句话才会被收录（profile.min_projects，默认值为 2）。较新的句子优先。nix brain profile rebuild 会重新学习；forget 会生成墓碑，下一轮不会重新创建该条目。会话开始时，简报会包含启用的句子；如果 .nix.toml 中设置了 [profile] consume = false，则不会包含。

nix brain handoff create --text "..." 每个项目最多创建一个交接。nix brain handoff accept --agent NOME 只能认领一次。会话开始时，简报会作为历史记录显示，而非指令。

nix run claude（或其他 Agent）会在缺少 hook 或 MCP 时安装它们。--no-autowire 可关闭此功能。对于 Claude Code 和 Codex，之前历史记录的只读副本会存放在 NIX_PREVIOUS_SESSION_HISTORY 中，并在 Agent 结束时消失。没有读取器时，命令会显示警告并继续运行。

remember 仍会写入默认 wiki，不属于 Mega Brain。

更新

要切换已安装的版本，请退出 nix 和 nix-hook，仅删除这两个二进制文件，然后重新运行安装程序。Wiki、settings.db 和 .nix 文件夹（索引和 Mega Brain）会保留。除非使用 --keep-data，否则下一节中的卸载程序也会删除 settings.db 和 .nix。

Windows（PowerShell）：

Stop-Process -Name nix,nix-hook -Force -ErrorAction SilentlyContinue
$root = if ($env:NIX_HOME) { $env:NIX_HOME } else { Join-Path $env:LOCALAPPDATA "nix" }
Remove-Item -Force (Join-Path $root "bin\nix.exe"), (Join-Path $root "bin\nix-hook.exe")
irm https://raw.githubusercontent.com/paulocesaaars/nix/main/install.ps1 | iex

重新打开 MCP 客户端，以便加载新的二进制文件。在 Windows 上，安装程序会先重命名现有二进制文件，再写入新文件；如果发生故障，则会恢复原文件。如果无法删除之前的副本（.bak），安装程序会发出警告，并保留该文件供你手动删除。

**Linux 和 macOS：**安装程序会替换文件。请退出相关进程，然后重新运行安装程序：

pkill -x nix || true
pkill -x nix-hook || true
curl -fsSL https://raw.githubusercontent.com/paulocesaaars/nix/main/install.sh | sh

卸载

卸载程序会移除 NIX_HOME 和 PATH 中的 nix 命令，删除 nix 和 nix-hook、解压缓存（onefile-* 和 hook-*），默认还会删除 .nix/（索引、备份、日志）和 settings.db。如果安装文件夹变空，也会一并删除。**Wiki 文件夹不会被更改。**若只想切换版本，请使用更新。

在 Windows 上，如果 nix.exe 或 nix-hook.exe 处于打开状态，卸载程序会在更改 PATH 前停止，并提示文件正在使用中。请关闭保持 Nix 运行的客户端，或结束相关进程，然后重新运行。

输入 s 确认。在脚本中，请传入 --yes。--keep-data 会保留 settings.db 和索引。

通过 PowerShell 安装的 Nix

通过 install.ps1 安装的用户无需进入仓库文件夹即可卸载。在 PowerShell 中：

irm https://raw.githubusercontent.com/paulocesaaars/nix/main/uninstall.ps1 -OutFile "$env:TEMP\uninstall-nix.ps1"
& "$env:TEMP\uninstall-nix.ps1"

在 Continuar? [s/N] 提示处输入 s。如果提示文件正在使用中，请结束相关进程，然后重新运行同一个卸载程序：

Stop-Process -Name nix,nix-hook -Force -ErrorAction SilentlyContinue
& "$env:TEMP\uninstall-nix.ps1"

脚本还会删除 onefile-* 和 hook-* 缓存。如果 %LOCALAPPDATA%\nix 变空，该文件夹也会被删除。确认完成的提示会说明文件夹已被删除，或其中剩余内容已被移除。之后请打开一个新的终端。

& "$env:TEMP\uninstall-nix.ps1" --yes
# para manter settings.db e o índice:
& "$env:TEMP\uninstall-nix.ps1" --keep-data --yes

在 Linux 和 macOS 上，release 脚本：

curl -fsSL https://raw.githubusercontent.com/paulocesaaars/nix/main/uninstall.sh | sh
# ou: curl -fsSL .../uninstall.sh -o uninstall.sh && sh uninstall.sh --yes

在仓库文件夹或 zip 文件夹中

在克隆目录或解压后的 Source code (zip) 文件夹中——即通过 bootstrap.py 安装的目录：

python scripts/uninstall.py
# ou: python scripts/uninstall.py --yes
# ou: python scripts/uninstall.py --keep-data --yes

此命令会在 NIX_HOME 指向该文件夹时移除它，并删除 .venv；除非使用 --keep-data，还会删除 .nix/ 和 settings.db。文件夹中的源代码会保留。

使用仓库根目录中的脚本：

uninstall.bat
:: ou, sem pergunta:
uninstall.bat --yes
:: para manter settings.db e o índice:
uninstall.bat --keep-data --yes

.\uninstall.ps1
# ou: .\uninstall.ps1 --yes
# ou: .\uninstall.ps1 --keep-data --yes

sh uninstall.sh
# ou: sh uninstall.sh --yes
# ou: sh uninstall.sh --keep-data --yes

之后请打开一个新终端：此项目中的 nix 将不再生效。如果永久注册失败，请参阅手动移除 NIX_HOME 和 PATH。还要从编辑器的 mcp.json 中移除 nix 服务。

嵌入模型可能仍留在 Hugging Face 缓存中（BAAI/bge-m3 大约占用 2.3 GB）。此缓存由其他程序共享，卸载程序不会删除它。每个项目的 mcp.json 中也会保留 nix 服务：请在编辑器中删除该条目。

在 MCP 客户端中注册

客户端会启动此进程。保存后，重新加载 MCP 服务。

command 必须指向安装文件夹（NIX_HOME）内的二进制文件，而不是 PATH 中的 nix 名称。从 Dock 或菜单打开的编辑器不会继承终端的 PATH（spawn nix ENOENT）。路径可在 nix doctor 的 comando nix: 行中找到。

Cursor — 工作区中的 .cursor/mcp.json：

Windows

{
  "mcpServers": {
    "nix": {
      "command": "${env:NIX_HOME}/bin/nix.exe"
    }
  }
}

在 Windows 上，IDE 会读取用户变量 NIX_HOME。也可以使用绝对路径，例如 C:/Users/voce/AppData/Local/nix/bin/nix.exe。

macOS / Linux

{
  "mcpServers": {
    "nix": {
      "command": "/Users/voce/Library/Application Support/nix/bin/nix"
    }
  }
}

替换为 nix doctor 中 comando nix: 行的路径。在 Linux 上，默认文件夹为 ~/.local/share/nix/bin/nix。在 IDE 中，"command": "nix" 会失败。${env:NIX_HOME} 通常不会展开：应用不会读取 .zshrc / .bashrc。

在界面中，打开集成 → 连接客户端，即可复制包含此安装绝对路径的配置。已确认格式的客户端说明使用项目级配置：

• Cursor： .cursor/mcp.json，包含上述示例中的 mcpServers 块。
• VS Code： .vscode/mcp.json，其中 servers.nix 包含 type: "stdio"，且 command 指向可执行文件。
• Claude Code： 在项目文件夹中运行 claude mcp add nix --scope project -- "CAMINHO_ABSOLUTO_DO_NIX"。配置保存在 .mcp.json 中。
• Codex： 在受信任的项目中创建或编辑 .codex/config.toml：

[mcp_servers.nix]
command = "C:/Users/voce/AppData/Local/nix/bin/nix.exe"

在 Codex 中信任此项目，以加载该配置。在 Linux 或 macOS 上，将命令替换为相应可执行文件的绝对路径。

• Devin： .devin/mcp_config.json，包含上述示例中的 mcpServers 块。

保存后，重启客户端或重新加载 MCP 服务。stdout 属于 MCP 协议：日志仅写入 Nix 文件夹中的 .nix/logs/nix.log。

如果通过 Python 安装，且没有 nix.exe，请使用 .venv 解释器，参见当可执行文件、PowerShell 和下载链接被阻止时。

入门

安装过程不会运行 nix init。在终端中运行 nix 以打开界面。如果找不到该命令，请关闭终端，重新打开一个终端再试。

首次添加 wiki 时，请进入 Wikis 页面或运行 nix init。该页面会记录文件夹（第一个文件夹会成为默认文件夹）。nix init 还会选择模型并写入 MCP 服务和 nix ui 命令所需的标记。没有该标记，编辑器将无法连接。

nix init
nix doctor
nix sync
nix status

首次运行 sync（或任何会生成嵌入的操作）时，会下载配置的模型。默认模型为 lulu（约 220 MB）。嵌入在 CPU 上运行；只有文件处理完成后，进度条才会前进。spitz（BAAI/bge-m3，约 2.3 GB）可提升搜索效果，但每条笔记可能需要数分钟。可在 nix init 中更换，或运行 nix config set index.embedding_model spitz，然后执行 nix sync --full。

路径中未指定文件夹的新笔记会保存到 wiki 的 default_new_note_folder（默认为 Inbox）。

手动注册 NIX_HOME 和 PATH

安装程序会尝试将 NIX_HOME（Nix 文件夹）和 {NIX_HOME}/bin 写入用户 PATH。如果失败（权限、策略或注册表受阻），二进制文件仍会继续安装。请自行注册这些变量，并打开一个新终端。

请使用实际安装文件夹替换示例中的路径。

Windows（界面）

1. 按 Win+R，运行 sysdm.cpl → 高级 → 环境变量。
2. 在用户变量中选择新建：
   • 名称：NIX_HOME
   • 值：Nix 文件夹，例如 C:\Users\voce\AppData\Local\nix
3. 选择用户变量 Path → 编辑 → 新建 → %NIX_HOME%\bin
4. 在所有窗口中点击确定。

Windows（PowerShell，永久）

$nixHome = "$env:LOCALAPPDATA\nix"
[Environment]::SetEnvironmentVariable("NIX_HOME", $nixHome, "User")
$expand = "%NIX_HOME%\bin"
$p = [Environment]::GetEnvironmentVariable("Path", "User")
if ($p -notlike "*$expand*") {
  [Environment]::SetEnvironmentVariable("Path", "$p;$expand", "User")
}

Linux、macOS 和 Git Bash

将内容添加到 ~/.bashrc（如果终端是登录终端，也添加到 ~/.profile）。macOS 上的路径是 $HOME/Library/Application Support/nix；Linux 上的路径是 $HOME/.local/share/nix。

# >>> nix >>>
export NIX_HOME="$HOME/.local/share/nix"
case ":$PATH:" in *":$NIX_HOME/bin:"*) ;; *) export PATH="$NIX_HOME/bin:$PATH" ;; esac
# <<< nix <<<

然后运行：source ~/.bashrc，或打开一个新终端。

仅在当前会话中生效（不会保存）

$env:NIX_HOME = "$env:LOCALAPPDATA\nix"
$env:Path = "$env:NIX_HOME\bin;$env:Path"

export NIX_HOME="${XDG_DATA_HOME:-$HOME/.local/share}/nix"
export PATH="$NIX_HOME/bin:$PATH"

手动移除 NIX_HOME 和 PATH

如果卸载程序没有还原这些变量，请删除安装程序写入的内容，并打开一个新终端。wiki 文件夹会保持完整。

请用实际安装文件夹替换 %LOCALAPPDATA%\nix。

Windows（界面）

1. 按 Win+R，运行 sysdm.cpl → 高级 → 环境变量。
2. 在用户变量中，选择 NIX_HOME → 删除（仅当其值是此 Nix 的文件夹时）。
3. 选择 Path（用户）→ 编辑 → 移除 %NIX_HOME%\bin（以及绝对路径 ...\nix\bin，如果存在）。
4. 在所有窗口中点击 确定。

Windows（PowerShell，永久生效）

$nixHome = "$env:LOCALAPPDATA\nix"
$stored = [Environment]::GetEnvironmentVariable("NIX_HOME", "User")
if ($stored -and ($stored -ieq $nixHome)) {
  [Environment]::SetEnvironmentVariable("NIX_HOME", $null, "User")
}
$bin = Join-Path $nixHome "bin"
$p = [Environment]::GetEnvironmentVariable("Path", "User")
if ($p) {
  $kept = $p.Split(";") | Where-Object {
    $t = $_.Trim().Trim('"')
    $t -and $t -ne "%NIX_HOME%\bin" -and $t -ne $bin
  }
  [Environment]::SetEnvironmentVariable("Path", ($kept -join ";"), "User")
}

Linux、macOS 和 Git Bash

如果 ~/.bashrc、~/.zshrc、~/.bash_profile 和 ~/.profile 中存在以下文件，请删除其中 # >>> nix >>> 与 # <<< nix <<< 之间的代码块；前提是该代码块中的 NIX_HOME 是此安装的文件夹。

然后运行：source ~/.bashrc，或打开一个新终端。

索引

核心规则如下：

在 Nix 之外（例如在文本编辑器中）所做的更改不会自动编入索引。通过 MCP 工具所做的更改会在同一操作中更新索引。

在 Nix 之外编辑笔记后，运行 nix sync，或让 Agent 调用 sync_index。如果写入时向量化失败，文件仍会保留在 wiki 中（这是事实来源），运行 nix sync 即可修正索引。

CLI

以下是你在终端中运行的命令。nix --help 会列出各命令组。nix COMANDO --help 会显示相应命令的选项。wiki 不会自动编入索引：运行 nix sync 或通过 MCP 工具写入内容，索引才会更新。

命令	作用
nix	在终端中打开界面；不在终端中时，由 MCP 客户端接收服务
nix --version	显示版本并退出
nix init	注册第一个 Wiki 和嵌入模型。--wiki 用于指定文件夹；不指定时，终端会询问。--name 用于为 Wiki 命名（默认值为 Default）。--embedding-model 用于选择 lulu 或 spitz。--force 会从头重写配置，但不会更改笔记
nix sync	根据 Wiki 中在 Nix 外部发生的更改更新索引。--full 会重建全部内容。--dry-run 仅显示结果。--json 会输出报告。--wiki NOME 用于选择一个或多个 Wiki。--all 会遍历所有 Wiki
nix status	显示索引是否落后于 Wiki。接受 --json、--wiki 和 --all
nix doctor	检查环境、配置、MCP 应调用的命令以及索引。--json 会输出完整报告
nix ui	在浏览器中打开界面。需要先运行 nix init。--no-browser 仅打印 URL。--port N 用于指定端口
nix run AGENTE	启动 Agent：Cursor、VS Code（copilot）、Claude Code（claude）、Codex（codex）、Devin（devin）或列表中的其他 Agent（Command Code 调用 cmd；Antigravity 调用 agy；Kiro 调用 kiro-cli；GitHub Copilot CLI 调用 copilot；IBM Bob 调用 bob；Qoder 调用 qodercli）。如果项目缺少 hook 和 MCP，则会安装；项目 MCP 仅支持 Claude Code、Cursor、VS Code 和 Devin。--no-autowire 不会改动这些文件。--project PASTA 用于选择仓库。对于 Claude Code 和 Codex，在 Agent 结束前，之前的原生历史记录会保留在 NIX_PREVIOUS_SESSION_HISTORY 中
nix wiki list	列出 Wiki、文件夹以及默认 Wiki。--json 会输出列表
nix wiki add NOME CAMINHO	注册另一个 Wiki。最多可注册 100 个
nix wiki rename ANTIGO NOVO	更改注册的名称。不会移动文件夹或索引
nix wiki remove NOME	从注册信息中移除 Wiki。默认 Wiki 和最后一个 Wiki 无法移除。笔记文件夹会保留
nix wiki default NOME	选择在命令或工具未指定名称时使用的 Wiki
nix wiki path NOME CAMINHO	将 Wiki 指向另一个文件夹
nix wiki set NOME CAMPO VALOR	保存该 Wiki 的一项设置：include、exclude、follow_symlinks、default_new_note_folder、default_frontmatter 或 longterm_folder。列表和对象需以 JSON 格式提供
nix config list	列出全局字段、生效值及其来源（默认值、数据库或环境变量）。--json 会输出列表
nix config get CAMPO	以 secao.chave 格式显示字段值
nix config set CAMPO VALOR	将字段保存到 settings.db。NIX_SECAO__CAMPO 环境变量仍优先于数据库设置
nix config unset CAMPO	删除已保存的值并恢复默认值
nix config history	列出最近的更改。--limit N 用于更改数量
nix config undo [ID]	恢复之前的值。不指定 ID 时，撤销最近一次更改
nix brain enable --wiki NOME	启用 Mega Brain，并选择用于会话页面的 Wiki。状态会被保存
nix brain status	显示 Mega Brain 是否已启用、使用哪个 Wiki，以及此项目的 hooks 状态
nix brain hooks install	安装捕获 hooks。在终端中会询问客户端，以及作用范围是整个账户还是仅当前仓库。此操作会先预览并要求确认。--scope project|global、--agent NOME、--all、--dry-run 和 --yes 可跳过提问
nix brain hooks remove --scope ESCOPO	从指定范围移除 Nix hooks。--agent 用于选择客户端
nix brain hooks status	按 Agent 显示文件和授权状态是否一致
nix brain handoff create --text "..."	创建项目交接记录：说明会话停在何处。只能有一个未关闭的交接记录
nix brain handoff list	列出项目的交接记录，按时间从新到旧排列
nix brain handoff accept --agent NOME	仅认领一次未关闭的交接记录，并显示文本
nix brain handoff cancel	取消未关闭的交接记录
nix brain profile list	列出个人资料中的有效短语
nix brain profile rebuild	根据已保存的请求重新学习个人资料，不使用语言模型
nix brain profile apply	在 Wiki 中重新写入有效条目的页面
nix brain profile review	显示尚未在足够多项目中出现的主题
nix brain profile forget CAMINHO	忘记一个条目。下次处理时不会恢复
nix hook、nix banner 和 nix brain work 用于内部流程。它们不是终端中的常规用法。

使用场景

• 打开界面。 安装后，运行 nix。如果找不到该命令，请关闭终端，重新打开后再试。注册 wiki 后，nix ui 会打开同一界面。
• 注册第一个 wiki。 nix init 会写入文件夹和模型。安装过程不再询问此项。
• 在编辑器中查找想法。 启用 Nix 的 MCP 后，请 Agent 搜索笔记。它会使用 wiki 索引中的 search_notes。
• 不离开编辑器，记录笔记。 请 Agent 创建或更新笔记。写入操作会通过 MCP 工具完成，并立即更新该笔记的索引。
• 将你在 Nix 之外编辑的内容加入索引。 运行 nix sync。--dry-run 会显示将发生的更改。--full 会重建索引，更换嵌入模型后必须使用此选项。
• 使用多个 wiki。 nix wiki add Trabalho C:/Notas/Trabalho 会注册第二个 wiki。nix wiki default Trabalho 会在省略名称时默认使用它。搜索时可以指定一个、多个或全部 wiki。
• 查明编辑器为何无法连接。 nix doctor 会检查命令、配置和索引。
• 在多个 Agent 之间保存记忆。 nix brain enable --wiki Default 会启用 Mega Brain。nix brain hooks install --scope global --all 会让 Cursor、VS Code、Claude Code、Codex 和 Devin 在每个会话事件发生时调用 Nix。VS Code 没有全局文件，因此只能部分捕获。
• 在 Codex 中继续 Claude 里正在做的事。 两个客户端都需要配置 Nix 的 MCP、启用 Mega Brain，并使用同一个项目文件夹。在 Claude 中，请它记录会话停在何处：它会调用 brain_handoff_create。打开 Codex，并告诉它继续 Claude 中正在做的事：它会使用 Agent codex 调用 brain_handoff_accept，并在需要更多内容时调用 brain_query 或 brain_read_page。如果没有 MCP，也可以在终端中打开并领取相同的文本，使用 nix brain handoff create 和 nix brain handoff accept --agent codex。单靠 hook，只会在会话开始时提供一份包含最近请求的简报。
• 给另一个 Agent 留言。 启用 Mega Brain 后，brain_message_send 会将消息放入项目队列。另一个 Agent 可以通过 brain_message_pop 领取消息，但只能领取一次。
• 读取 Mega Brain 已保存的内容。 brain_query 会搜索 Mega Brain 的 wiki 和观察记录。brain_recent_pages 会列出会话页面。brain_read_page 会按路径读取页面。找到的文本属于历史记录。
• 重新学习个人档案。 nix brain profile rebuild 会重新读取已记录的请求。nix brain profile list 会显示句子。nix brain profile forget CAMINHO 会忘记一条记录。nix brain profile apply 会将页面重新写入 wiki。
• 修正配置。 nix config history 会显示更改记录。nix config undo 会恢复之前的值。

服务端

在终端中，不带子命令的 nix 会打开界面。MCP 客户端会在没有终端的情况下启动同一命令，并接收 stdio 服务端。nix --version 会打印版本并退出。

首次配置

nix init 会将第一个 wiki 和嵌入模型写入 settings.db。安装过程不再执行此步骤。

• --wiki CAMINHO 用于指定文件夹。不指定时，终端会询问。
• --name NOME 用于命名第一个 wiki。不指定时，名称为 Default。此选项仅在创建时生效。之后可使用 nix wiki add 添加下一个 wiki。
• --embedding-model NOME 用于选择模型（lulu 或 spitz）。创建时不指定此选项，终端会询问。
• --force 会从头重写配置，但不会修改笔记。

Wiki

在同一安装中可使用 1 到 100 个 Wiki。在 sync 和 status 中省略 Wiki 名称时，将使用默认 Wiki。

• nix wiki list 显示名称、文件夹和默认 Wiki。--json 以 JSON 格式输出相同列表。
• nix wiki add NOME CAMINHO 添加另一个 Wiki。拒绝使用格式为 AAAAMMDDTHHMMSS 的名称。
• nix wiki rename ANTIGO NOVO 更改名称。索引和备份位置保持不变。如果搜索结果为空，请运行 nix sync --full --wiki NOVO。
• nix wiki default NOME 设置默认 Wiki。必须先指定另一个 Wiki 为默认 Wiki，才能移除当前默认 Wiki。最后一个 Wiki 无法移除。
• nix wiki remove NOME 移除 Wiki 注册信息。笔记文件夹会保留。Mega Brain 页面所在的 Wiki 在 Mega Brain 启用期间也无法移除。
• nix wiki path NOME CAMINHO 将同一名称指向另一个文件夹。
• nix wiki set NOME CAMPO VALOR 设置该 Wiki 的一项配置：include、exclude、follow_symlinks、default_new_note_folder、default_frontmatter 或 longterm_folder。列表和对象需以 JSON 格式传入。不会更改全局配置。

如果该 Wiki 正在同步，重命名、移除、path 和 set 操作会等待同步完成。

在 MCP 工具中，省略 wiki 时将使用默认 Wiki。搜索、列表、状态和同步操作接受单个名称、名称列表或 "*"（全部）。写入操作只接受一个名称。

全局配置

配置项保存在安装目录的 settings.db 中（NIX_HOME；使用 Python 检出版本时为克隆仓库的文件夹）。nix config set secao.chave valor 用于设置配置项。列表和对象需以 JSON 格式传入。

• nix config list 显示配置项。--json 会更改输出格式。
• nix config get secao.chave 读取一项配置。
• nix config unset secao.chave 将配置项恢复为默认值。
• nix config history 显示更改记录。--limit N 限制列表长度（默认值为 20）。
• nix config undo 撤销最近一次更改。nix config undo ID 撤销历史记录中的一项更改。

启用 Mega Brain：运行 nix brain enable --wiki NOME。随后重启 MCP 客户端，以显示 brain_* 工具。

NIX_SECAO__CAMPO 环境变量会覆盖数据库中的对应配置项，并在 nix config 和界面中锁定该项。Wiki 注册信息不使用此变量。

索引

在 Nix 外部编辑笔记不会更新索引。需要同步时，请运行 nix sync。

• 未指定 --wiki 且未指定 --all 时，将使用默认 Wiki。
• --wiki NOME 可重复指定。--all 会依次处理所有 Wiki。两者不能同时使用。
• --full 会重建整个索引。更换模型后请使用此选项（nix config set index.embedding_model spitz）。
• --dry-run 只显示将要进行的更改。
• --json 以 JSON 格式输出报告。nix status 和 nix doctor 也支持此选项。

nix status 显示笔记数、块数、上次同步时间，以及 Wiki 是否领先于索引。nix doctor 会检查环境、配置、MCP 应调用的命令，以及每个 Wiki 的索引。编辑器无法连接时，请从此命令开始排查。

界面

nix ui 会在 127.0.0.1 打开浏览器界面，提供状态、同步、诊断、搜索、Mega Brain（面板、配置、收件箱和个人资料）、客户端连接、MCP 流量、备份、Wiki 和配置。需要先运行 nix init。按 Ctrl+C 或点击“结束”按钮退出。--no-browser 只会输出 URL。--port N 用于指定端口。

Mega Brain

操作步骤见 Mega Brain。

• nix brain enable --wiki NOME 启用 Mega Brain 并选择 Wiki。status 显示状态。
• nix brain hooks install --scope project|global 为 Agent 安装钩子。remove 和 status 使用相同的 --scope。
• nix brain handoff create --text "..." 创建交接。list、accept --agent NOME 和 cancel 可完成整个流程。
• nix brain profile rebuild 重新学习。list、review、forget CAMINHO 和 apply 可查看并重新保存个人资料。
• nix run AGENTE 将后续参数传递给可执行文件。--no-autowire 不会更改钩子或 MCP。--project PASTA 用于选择仓库。

MCP 工具

Agent 不会在终端中运行 nix。你用日常语言提出请求，Agent 就会调用工具。Wiki 工具始终可用。只有启用 Mega Brain 后，brain_* 工具才会加入 MCP；运行 nix brain enable 后，请重启客户端。定义位于 src/nix/core/tools/registry.py。默认 Wiki 的笔记会作为资源 nix://note/{+rel_path} 显示；命名 Wiki 的笔记则会作为资源 nix://wiki/{name}/note/{+rel_path} 显示。当前用于列表和质量分析的工具名称是 list_wikis 和 wiki_insights。

在终端中	你对 Agent 说的话	工具
nix sync	同步索引，或获取 Nix 之外的变更	sync_index
nix status	索引过期了吗？	index_status
nix wiki list	已登记了哪些 Wiki？	list_wikis
nix brain status	这个项目的 Mega Brain 状态如何？	brain_status
nix brain handoff create	记录我们进行到哪一步了	brain_handoff_create
nix brain handoff list	有未完成的交接吗？	brain_handoff_list
nix brain handoff accept	继续我在另一个 Agent 上做的事	brain_handoff_accept
nix brain handoff cancel	取消交接	brain_handoff_cancel

nix、nix init、nix doctor、nix ui、nix run、nix config、其余的 nix wiki 命令、nix brain enable、nix brain hooks 和 nix brain profile 都在终端中运行。钩子会在每个会话事件发生时自动触发。

这些工具没有对应的命令。你可以通过以下说法来调用它们：

你说的话	工具
搜索笔记	search_notes
打开笔记、大纲或一段内容	read_note、get_note_outline、read_note_lines
列出笔记或标签	list_notes、list_all_tags
有哪些内容链接到这篇笔记	get_linked_notes
创建、追加或更新笔记、frontmatter 或标签	create_note、append_to_note、update_note、update_frontmatter、manage_tags
移动笔记或附件	move_note、move_file
删除笔记	delete_note（需要确认）
查找孤立笔记、重复笔记或链接建议	wiki_insights
记住……	remember
Mega Brain 关于……存了什么	brain_query
读取会话页面，或列出最近的页面	brain_read_page、brain_recent_pages
给我简报	brain_briefing
会话中发生了什么	brain_read_session_observations
记录规则、决策或个人资料	brain_write_page、brain_patch_page、brain_delete_page
这个页面有帮助	brain_feedback
留言、列出、取出或取消消息	brain_message_send、brain_message_list、brain_message_pop、brain_message_cancel

参考

工具	用途
search_notes	混合搜索（语义 + 词法），支持按文件夹、标签和日期筛选
read_note	读取整篇笔记。对于较长的笔记，建议先查看大纲，再按行读取
get_note_outline	标题、frontmatter 键、总行数和标题层级
read_note_lines	读取文件的行区间或某个标题下的内容（最多 400 行）
list_notes	列出已编入索引的笔记（文件夹、标签）
list_all_tags	列出已编入索引的标签及其数量；用于 tag 筛选
get_linked_notes	浏览 wikilinks（outgoing、incoming 或 both）
create_note	创建笔记并立即编入索引（写入即同步）
append_to_note	追加内容并重新编入索引
update_note	replace 需要 confirm=true；patch 会追加内容；prepend 会在 YAML 后插入内容
update_frontmatter	修改顶层键，并保留 YAML 的其余部分
manage_tags	添加或移除 frontmatter 标签；不修改正文中的标签
move_note	移动 .md 笔记，并重写指向该笔记的链接
move_file	移动附件（PDF、图像等）；.md 笔记请使用 move_note
delete_note	删除笔记及其索引；需要 confirm=true
sync_index	手动同步（full、dry_run）
index_status	按 wiki 显示数量、上次同步时间和索引延迟
wiki_insights	孤立笔记、重复笔记、链接建议或摘要
remember	将持久事实写入 wiki 的 longterm_folder
list_wikis	名称、路径、默认值，以及该 wiki 的索引是否已过期
brain_query	搜索 Mega Brain wiki 和会话观察记录。文本为历史记录
brain_status	本项目中的 wiki、会话和仍处于打开状态的会话
brain_briefing	个人资料、提供的交接、摘要和消息。不会使用交接
brain_read_page	按相对路径读取 Mega Brain wiki 页面
brain_recent_pages	按时间从新到旧列出已保存的会话页面
brain_write_page	创建或替换整理后的页面或个人资料页面
brain_patch_page	替换整理后的页面或个人资料页面中的字面片段
brain_delete_page	删除整理后的页面或个人资料页面。需要 confirm=true
brain_feedback	记录页面是否有用。不修改页面
brain_read_session_observations	读取会话的原始观察记录。文本为历史记录
brain_handoff_create	打开项目交接。同一时间只能有一个交接处于打开状态
brain_handoff_list	列出项目交接
brain_handoff_accept	仅认领一次处于打开状态的交接
brain_handoff_cancel	取消处于打开状态的交接
brain_message_send	向项目队列发送消息
brain_message_list	列出待处理和已送达的消息
brain_message_pop	仅送达一次下一条待处理消息
brain_message_cancel	取消仍处于待处理状态的消息

配置

位于 Nix 文件夹（NIX_HOME；在开发检出中为仓库文件夹）下的 settings.db 中。相对路径以该文件夹为基准解析。NIX_SECAO__CAMPO 环境变量优先于数据库中的全局字段（例如：NIX_INDEX__EMBEDDING_MODEL），对应字段会在 nix config 和界面中锁定。Wiki 注册信息不使用此变量：名称、文件夹、默认项和调整项（include、exclude、文件夹）通过 nix wiki 管理。nix wiki set NOME CAMPO VALOR 会保存一项调整；列表和对象以 JSON 格式输入。nix wiki path NOME CAMINHO 会更改文件夹。nix init 会保存第一个 Wiki 和模型。nix config set secao.chave valor 会更改全局字段；列表和对象以 JSON 格式输入。nix config undo 会恢复先前的值。

nix ui 会在浏览器中打开相同的操作，无需 LLM：

• **操作：**状态（在所选 Wiki 完成同步且编辑器调用工具之前，“开始”区块会一直显示；索引过期警告只会在完成同步后出现）、带预览和进度的同步（任务完成前按钮会保持禁用，即使重新加载页面也一样）以及诊断。
• **Wiki（只读）：**搜索一个、多个或全部 Wiki，查看笔记（包括大纲和片段）、标签和洞察。洞察页面会说明孤立项、重复项、链接建议和摘要。内容上方栏中的“活动 Wiki”选择器使用 ?wiki=；未指定时使用默认项。
• **Mega Brain：**面板、Wiki 和状态配置、收件箱及个人资料。个人资料或会话页面上的链接会打开 Mega Brain 中配置的 Wiki。
• **集成：**用于连接 Cursor、VS Code、Claude Code、Codex、Devin 及其他 19 个客户端的现成片段；MCP 流量（包括客户端发出的调用）会记录在 .nix/traffic.db 中。
• **维护：**写入备份（比较和下载）以及备份恢复；这是界面中唯一会写入 Wiki 的操作，且需要确认；Wikis 页面；配置表单和历史记录。

此命令需要先运行 nix init，仅监听 127.0.0.1，可通过 Ctrl+C 或“结束”按钮退出。--no-browser 只会输出 URL；--port 会固定端口。

键	默认值	功能
wiki（注册信息）	nix init 中的名称 Default	每个 Wiki 的文件夹，通过 nix wiki 管理。1 到 100 个，其中一个为默认项
Wiki 的 exclude	.trash/**、Templates/**、Privado/**	此 Wiki 中要忽略的文件夹。使用 nix wiki set NOME exclude VALOR 更改
default_new_note_folder	Inbox	路径中未指定文件夹的笔记的目标位置
longterm_folder	Nix/Memória	remember 工具的目标位置
index.data_dir	.nix/data	索引基础目录；每个 Wiki 使用 .nix/data/<nome>
logging.file	.nix/logs/nix.log	日志；只有启用 log_prompts 时才会记录查询
brain.enabled	已关闭	启用捕获功能和 brain_* 工具。需要重启 MCP 客户端

发布版本

当 vX.Y.Z 标签推送到远程仓库时，GitHub release 会自动创建。.github/workflows/release.yml 工作流会检查版本、运行 ruff 和 mypy，按平台（Windows amd64、Linux amd64、Linux arm64、macOS arm64）构建 nix 和 nix-hook，并将文件及 checksums.txt 发布到 Releases。

1. 更新 pyproject.toml 中的 [project].version（例如：1.2.3）。标签必须与该值一致，否则任务会失败。
2. 在主分支上提交并推送。
3. 创建并推送标签（前缀中的 v 是必需的）：

git tag v1.2.3
git push origin v1.2.3

4. 在 Actions 中跟踪 Release 工作流。成功后，release 会包含各平台的 nix 和 nix-hook、各平台的 .mcpb、checksums.txt 和 server.json。同一任务还会将条目发布到 MCP Registry。标签的源代码 zip 仅包含安装和使用 Nix 所需的内容；开发技能、文档和测试均不包含在内。

本仓库不会自动发布 site/ 中的指南。

若要重新发布现有标签的构件，请手动触发工作流：Actions → Release → Run workflow，并填写标签（例如：v1.2.3）。

文档

• PRD.md — 产品、需求和业务规则
• TDD.md — 技术规范：组件、索引、检索和 MCP stdio