故障排除
Nowledge Mem 的常见问题、快速检查路径与恢复步骤
全部文件路径总览（桌面端 + CLI）
这里给你一个简化后的目录总览（按大目录层级）：
- 配置/状态根目录：
co.nowledge.mem.desktop - 数据根目录：
NowledgeGraph - 用户工作目录：
ai-now - 客户端工具目录（
nmemCLI + OpenClaw 插件）：.nowledge-mem
~/Library/Application Support/co.nowledge.mem.desktop/ # 配置/状态
~/Library/Application Support/NowledgeGraph/ # 数据（DB/索引/日志）
~/ai-now/ # 用户工作目录
~/.nowledge-mem/ # nmem/OpenClaw 客户端配置升级后你可能仍会看到这些兼容旧路径：
~/Library/Application Support/nowledge-mem/~/Library/Logs/Nowledge Graph/
%APPDATA%\co.nowledge.mem.desktop\ # 配置/状态
%LOCALAPPDATA%\NowledgeGraph\ # 数据（DB/索引/日志）
%USERPROFILE%\ai-now\ # 用户工作目录
%USERPROFILE%\.nowledge-mem\ # nmem/OpenClaw 客户端配置~/.config/co.nowledge.mem.desktop/ # 配置/状态（XDG_CONFIG_HOME）
~/.local/share/NowledgeGraph/ # 数据（XDG_DATA_HOME）
~/ai-now/ # 用户工作目录
~/.nowledge-mem/ # nmem/OpenClaw 客户端配置你也可能看到这些安装路径（取决于安装方式）：
/usr/lib/nowledge-mem/
/usr/share/nowledge-mem/升级后你可能仍会看到这些兼容旧路径：
~/.local/share/co.nowledge.mem.desktop/~/.local/share/Nowledge Graph/~/.local/share/nowledge-mem/
查看日志
最快方式
打开设置 → 关于 → 显示日志文件，即可直接在访达或资源管理器中打开日志所在文件夹，无需使用终端。
如果应用在启动时遇到错误，启动界面也会显示显示日志按钮，效果相同。
在 macOS 上，系统日志文件的规范路径是 ~/Library/Application Support/NowledgeGraph/Logs/app.log。
你可以在终端中运行此命令查看：
open -a Console ~/Library/Application\ Support/NowledgeGraph/Logs/app.log如果你是从旧版本升级，也可能仍有旧路径：
open -a Console ~/Library/Logs/Nowledge\ Graph/app.log在 Windows 上，系统日志文件位于两个可能的位置，取决于安装方法：
%LOCALAPPDATA%\Packages\NowledgeLabsLLC.NowledgeMem_1070t6ne485wp\logs\app.log（从 Microsoft Store 安装）%LOCALAPPDATA%\NowledgeGraph\logs\app.log（从 Nowledge Mem 网站下载的安装包安装）
你可以将此粘贴到文件资源管理器的地址栏中查看：
%LOCALAPPDATA%\Packages\NowledgeLabsLLC.NowledgeMem_1070t6ne485wp\logs\app.log或者：
%LOCALAPPDATA%\NowledgeGraph\logs\app.log搜索与索引健康检查
如果你的问题与搜索质量或搜索索引占用空间有关，先从这里开始：
- 打开 设置 -> Memory Processing -> Search
- 如果搜索索引占用磁盘过大，使用 Optimize
- 如果搜索结果明显不对、缺失、过时或排序异常，使用 Rebuild Index
这两个操作解决的是不同问题：
- Optimize：压缩磁盘上的搜索索引占用，不需要整套重建
- Rebuild Index：从知识图谱重新生成搜索索引，适合索引状态陈旧或异常时使用
应用启动时间过长
症状： 应用在启动期间挂起或显示超时错误。
解决方案： 全局代理或 VPN 软件可能阻止应用直接访问 http://127.0.0.1:14242。
配置代理/VPN 绕过
配置你的代理或 VPN 工具绕过 localhost 地址。将以下内容添加到你的绕过/排除规则：
127.0.0.1, localhost, ::1这允许你保持代理/VPN 启用，同时确保 Nowledge Mem 可以与其本地服务器通信。更新绕过规则后，重启 Nowledge Mem。
Windows 启动失败：缺少 Visual C++ 运行库
症状： 启动时，app.log 出现：
Import error: DLL load failed while importing _lbug- 或
Backend exited during startup readiness check: exit code: 1
原因： 系统缺少数据库引擎所需的 Microsoft C++ 运行时依赖。
解决方案：
- 下载并安装 Microsoft Visual C++ Redistributable (x64)：
https://aka.ms/vs/17/release/vc_redist.x64.exe - 安装后重启 Nowledge Mem。
- 若仍失败，请反馈时附上
app.log。
AI Now 会话启动失败
症状： 点击 新任务 或恢复已暂停任务时失败，AI Now 无法打开会话。
第一步： 先查看 AI Now 内的启动诊断卡片。
使用 AI Now 启动诊断
会话启动失败时，AI Now 会显示诊断卡片，包含：
- 失败阶段（
spawn、initialize或new_session） - 平台和进程退出码
- 启动脚本最近的
stderr输出 - 可复制的诊断信息按钮
点击 详情 展开技术字段，再点击 复制诊断信息，用于反馈或提交 issue。
常见修复（尤其 Windows）：
- 确认安装完整（嵌入式 Python 与启动脚本存在）。
- 修改插件或模型配置后，重启 Nowledge Mem 再重试。
- 临时关闭会拦截 bundled Python / PowerShell 启动的杀毒或隔离规则。
- 若与插件有关，在 AI Now → 插件 中重新连接已过期 OAuth 插件后再试。
可选：在 Windows 使用热键打开开发者控制台
如果 AI Now 仍然卡在会话启动，可直接使用内置热键查看日志：
- 按 Ctrl + Shift + I 切换 Tauri/WebView 控制台。
- 打开 Console 标签页。
- 使用关键词过滤日志，例如
[AI Now]、[ACP]、[kimi-cli stderr]。
该方法同时适用于 Microsoft Store 安装版和官网安装包版本。
然后进入 AI Now 并点击 新任务 复现问题。
如果仍失败，请在反馈时附上“复制诊断信息”内容和 app.log。
模型缓存损坏
症状： 搜索、记忆提炼或知识提取功能意外停止工作。
解决方案： 清除模型缓存并重新下载模型。
清除缓存
导航到 设置 → 模型，然后点击：
清除缓存后，重新下载所需的模型。
搜索索引占用磁盘过大
症状： 搜索本身还能用，但你在 设置 -> Memory Processing -> Search 里看到搜索索引体积明显大得不合理。
怎么做： 直接点击同一面板里的 Optimize。
Optimize 会做什么
Optimize 会压缩磁盘上的搜索索引，并顺带刷写数据库变更。
从 v0.6.8 开始，这一步会更积极地清理旧索引版本。在一些真实案例里，压缩后可能出现 5 GB -> 300 MB 这样的大幅下降。
适合在这些情况下使用：
- 更新版本后，索引体积一直涨。
- 你并没有很多内容，但搜索索引看起来异常大。
- 搜索还能工作，但磁盘占用明显不正常。
如果执行 Optimize 后体积仍明显不对，再执行一次 Rebuild Index。如果仍异常，反馈时请附上 Memory Processing 面板截图。
搜索结果明显不对
症状： 搜索结果明显不靠谱，应该很容易搜到的记忆搜不出来，或者排序质量突然变差很多。
怎么做： 打开 设置 -> Memory Processing -> Search，点击 Rebuild Index。
什么时候该用 Rebuild Index
Rebuild Index 会基于当前知识图谱完整重建搜索索引。
当索引写入过程中出现中断、索引状态陈旧，或其他索引问题导致搜索质量明显下降时，这是最合适的恢复步骤。
适合在这些情况下使用：
- 某条记忆明明存在，但用合理查询就是搜不到。
- 升级、崩溃或大批量导入后，搜索质量突然明显变差。
- 搜索排序结果和你确信已经存进 Mem 的内容明显对不上。
重建完成后，用同一条查询再试一次。如果结果仍明显不对，反馈时请附上查询示例，以及你预期应该出现的那条记忆。
Windows：安装或升级后 PATH 被覆盖
症状： 安装或升级 Nowledge Mem 之后，其他命令行工具突然无法使用。运行 pnpm、git、node 等命令时提示"不是内部或外部命令"或"command not found"。检查用户 PATH 后发现它被缩减为仅剩 C:\Users\...\Nowledge Mem\cli，或者 %PNPM_HOME% 等环境变量引用丢失。
原因： 0.6.8 之前的版本在安装过程中可能会展开 PATH 中的环境变量引用（如 %PNPM_HOME% 被展开为实际路径），甚至在某些情况下将整个 PATH 替换为仅包含 Nowledge Mem CLI 目录的值。
此问题已在 0.6.8 及更新版本中修复。 安装程序现在会完整保留你的 PATH 条目及其环境变量引用。
如果你受到了影响，可以按以下步骤恢复 PATH：
- 按 Win + R，输入
sysdm.cpl，回车。 - 进入 高级 > 环境变量。
- 在 用户变量 下，选中 Path 并点击 编辑。
- 补回缺失的条目。常见的包括：
%PNPM_HOME%%USERPROFILE%\AppData\Local\Programs\Microsoft VS Code\bin%USERPROFILE%\.cargo\bin%USERPROFILE%\AppData\Roaming\npm
- 点击 确定，然后打开新的终端窗口。
提示
如果你不确定 PATH 里应该包含哪些条目，可以参考另一台正常的电脑，或者查阅你使用的各工具（pnpm、Node.js、Rust 等）的安装文档——每个工具的安装程序通常会说明它添加了哪个 PATH 条目。
找不到 CLI
症状： 在终端中运行 nmem 返回"command not found"。
各平台解决方案：
- macOS：从 设置 → 偏好设置 → 开发者工具 安装 CLI
- Windows：应用安装后打开新的终端窗口（PATH 更新需要新会话）
- Windows (WSL)：参见下方 WSL 设置
- Linux：CLI 包含在 deb/rpm 包中。如果手动安装，确保
/usr/local/bin在你的 PATH 中
快速检查： 运行 nmem status 以验证 CLI 可以连接到 Nowledge Mem。
在 WSL 中使用 nmem
如果你在 Windows 的 WSL 环境中运行 Claude Code、Codex 等编程代理，Windows 上的 nmem CLI 不会直接出现在 Linux 环境中。
从 v0.6.9 起，在设置中点击 安装 CLI 会自动在默认 WSL 发行版中创建一个轻量桥接脚本。如果需要手动设置，在 WSL 终端中粘贴以下命令：
mkdir -p ~/.local/bin && cat > ~/.local/bin/nmem << 'SHIMEOF'
#!/bin/bash
q=""; for a in "$@"; do q="$q \"$a\""; done
cmd.exe /s /c "\"nmem.cmd\"$q"
SHIMEOF
chmod +x ~/.local/bin/nmem这会创建一个薄封装脚本，通过 WSL 互操作调用 Windows 端的 nmem。由于命令实际作为 Windows 进程运行，它会直接连接到桌面端应用的 localhost——无需额外的网络配置。
验证是否正常工作：
nmem status如果创建脚本后 nmem 仍然找不到，请确认 ~/.local/bin 在你的 PATH 中。Ubuntu 默认会自动添加；其他发行版需要在 ~/.bashrc 或 ~/.zshrc 中加入 export PATH="$HOME/.local/bin:$PATH"。
前提条件
此方法依赖 WSL 互操作功能（默认已启用）。如果你在 /etc/wsl.conf 中设置了 interop=false 或 appendWindowsPath=false，请重新启用，或者改用 pip install nmem-cli 配合随处访问 Mem。
会话捕获
此桥接脚本以 Windows 进程运行 nmem，因此 nmem t save --from claude-code 等命令会在 Windows 主目录查找会话文件，而非 WSL 主目录。实际使用中这不影响——桌面端应用会通过内置的文件监视器自动捕获 WSL 中的会话。如果你需要从 WSL 直接通过 CLI 保存会话，请改用 pip install nmem-cli。
远程访问返回 429
症状： nmem status 或 curl 返回 429 Too many invalid auth attempts。
解决方案： 客户端多次使用了错误的 API key。
- 在 设置 → 随处访问 Mem 重新复制 URL + key
- 确认
NMEM_API_KEY完整且没有多余空格/引号 - 如果不确定，点击 Rotate 生成新 key
完整流程见：随处访问 Mem。
远程访问返回 401 Missing API key
症状： Tunnel URL 可访问，但 nmem status 或 curl 返回 401 Missing API key。
原因： 某些网络代理会移除鉴权头。
解决方案：
- 升级到最新版
nmem（会自动使用代理兼容回退） - 在 设置 → 随处访问 Mem 重新复制 URL + key
- 手动
curl可用：curl "$NMEM_API_URL/health?nmem_api_key=$NMEM_API_KEY"