Troubleshooting
Common issues, quick checks, and recovery steps for Nowledge Mem
All File Locations (Desktop + CLI)
This is the simplified folder map used by Nowledge Mem:
- Config/state root:
co.nowledge.mem.desktop - Data root:
NowledgeGraph - User workspace:
ai-now - Client-side tools root (
nmemCLI + OpenClaw plugin):.nowledge-mem
~/Library/Application Support/co.nowledge.mem.desktop/ # config/state
~/Library/Application Support/NowledgeGraph/ # data (DB/index/logs)
~/ai-now/ # user workspace
~/.nowledge-mem/ # nmem/OpenClaw client configLegacy compatibility paths you may still see:
~/Library/Application Support/nowledge-mem/~/Library/Logs/Nowledge Graph/
%APPDATA%\co.nowledge.mem.desktop\ # config/state
%LOCALAPPDATA%\NowledgeGraph\ # data (DB/index/logs)
%USERPROFILE%\ai-now\ # user workspace
%USERPROFILE%\.nowledge-mem\ # nmem/OpenClaw client config~/.config/co.nowledge.mem.desktop/ # config/state (XDG_CONFIG_HOME)
~/.local/share/NowledgeGraph/ # data (XDG_DATA_HOME)
~/ai-now/ # user workspace
~/.nowledge-mem/ # nmem/OpenClaw client configPackage paths you may also see (depends on install method):
/usr/lib/nowledge-mem/
/usr/share/nowledge-mem/Legacy compatibility paths you may still see:
~/.local/share/co.nowledge.mem.desktop/~/.local/share/Nowledge Graph/~/.local/share/nowledge-mem/
Viewing Logs
Quickest way
Open Settings → Info → Show Log Files to reveal the log folder directly in Finder or Explorer. No terminal required.
If the app fails during startup, the error screen includes a Show Logs button that does the same thing.
On macOS, the canonical system log file is located at ~/Library/Application Support/NowledgeGraph/Logs/app.log.
You can view it by running this command in your terminal:
open -a Console ~/Library/Application\ Support/NowledgeGraph/Logs/app.logIf you upgraded from an older build, you may still have a legacy log path:
open -a Console ~/Library/Logs/Nowledge\ Graph/app.logOn Windows, the system log file is located on two possible locations based on the installation method:
%LOCALAPPDATA%\Packages\NowledgeLabsLLC.NowledgeMem_1070t6ne485wp\logs\app.log(installed from Microsoft Store)%LOCALAPPDATA%\NowledgeGraph\logs\app.log(installed from package file downloaded from Nowledge Mem website)
You can view it by pasting this into address bar of File Explorer:
%LOCALAPPDATA%\Packages\NowledgeLabsLLC.NowledgeMem_1070t6ne485wp\logs\app.logor this:
%LOCALAPPDATA%\NowledgeGraph\logs\app.logSearch And Index Health
If your issue is about search quality or search-index disk usage, start here first:
- Open Settings -> Memory Processing -> Search
- Use Optimize when the search index takes too much disk space
- Use Rebuild Index when search results look clearly incomplete, stale, or badly ranked
These two actions solve different problems:
- Optimize compacts on-disk search storage without rebuilding everything
- Rebuild Index recreates the search index from the knowledge graph when the existing index may be stale or corrupted
App Takes Too Long to Start
Symptom: The app hangs or shows a timeout error during startup.
Solution: Global proxies or VPN software can prevent the app from accessing http://127.0.0.1:14242 directly.
Configure Proxy/VPN Bypass
Configure your proxy or VPN tool to bypass localhost addresses. Add the following to your bypass/exclusion rules:
127.0.0.1, localhost, ::1This allows you to keep your proxy/VPN enabled while ensuring Nowledge Mem can communicate with its local server. After updating the bypass rules, restart Nowledge Mem.
Windows Startup Fails: Missing Visual C++ Runtime
Symptom: On startup, app.log shows:
Import error: DLL load failed while importing _lbug- or
Backend exited during startup readiness check: exit code: 1
Cause: A required Microsoft C++ runtime dependency is missing for the bundled database engine.
Fix:
- Download and install Microsoft Visual C++ Redistributable (x64): https://aka.ms/vs/17/release/vc_redist.x64.exe
- Restart Nowledge Mem.
- If it still fails, attach
app.logwhen reporting the issue.
AI Now Session Fails to Start
Symptom: Clicking New Task or resuming a paused task fails, and AI Now cannot open a session.
What to do first: Check the startup diagnostics card shown in AI Now.
Use Startup Diagnostics in AI Now
When startup fails, AI Now now shows a diagnostics card with:
- failure stage (
spawn,initialize, ornew_session) - platform and process exit code
- recent
stderroutput from the startup script - a copy button for sharing diagnostics
Click Details to expand technical fields, then click Copy diagnostics for support or issue reports.
Common fixes (especially on Windows):
- Verify your installation is complete (embedded Python and startup scripts are present).
- Restart Nowledge Mem after plugin or model configuration changes.
- Temporarily disable antivirus/quarantine rules that may block bundled Python or PowerShell startup.
- If a plugin is involved, reconnect expired OAuth plugins in AI Now → Plugins and retry.
Optional: Open Developer Console on Windows (Hotkey)
If AI Now is still stuck and you need extra startup logs, use the built-in Windows hotkey:
- Press Ctrl + Shift + I to toggle the Tauri/WebView console.
- Go to the Console tab.
- Filter logs with keywords like
[AI Now],[ACP], or[kimi-cli stderr].
This works for both Microsoft Store installs and website installer builds.
Then reproduce the issue by opening AI Now and clicking New Task.
If it still fails, include copied diagnostics plus app.log when reporting the issue.
Corrupted Model Cache
Symptom: Search, memory distillation, or knowledge extraction features stop working unexpectedly.
Solution: Clear the model cache and re-download the models.
Clear Cache
Navigate to Settings → Models, and click:
After clearing the cache, re-download the required models.
Search Index Uses Too Much Disk Space
Symptom: Search works, but the search index size in Settings -> Memory Processing -> Search looks much larger than expected.
What to do: Click Optimize in that same panel.
What Optimize does
Optimize compacts the search index on disk and flushes database changes.
From v0.6.8 onward, this can shrink storage dramatically on machines with older index versions left behind. In real cases, users may see something like 5 GB -> 300 MB after compaction.
When to use it:
- The index keeps growing after updates or repeated reindexing.
- The search index is much larger than the knowledge you actually store.
- Search still works, but disk usage looks obviously wasteful.
If storage still looks wrong after optimization, run Rebuild Index once. If it remains abnormally large, include a screenshot of the Memory Processing panel when reporting the issue.
Search Ranking Looks Obviously Wrong
Symptom: Search returns clearly bad matches, misses memories that should be easy to find, or feels much worse than before.
What to do: Open Settings -> Memory Processing -> Search and click Rebuild Index.
When Rebuild Index helps
Rebuilding recreates the full search index from the current knowledge graph.
This is the right recovery step when an interrupted write, stale index state, or another indexing issue has left search quality obviously degraded.
Try this when:
- A memory exists, but search cannot find it with reasonable queries.
- Results are suddenly much worse after an upgrade, crash, or heavy import.
- Ranking looks clearly inconsistent with what you know is already in Mem.
After reindexing finishes, rerun the same query. If the ranking is still clearly wrong, send the query example and the expected memory when reporting the issue.
Windows: PATH Corrupted After Install or Upgrade
Symptom: After installing or upgrading Nowledge Mem, other command-line tools stop working. Running pnpm, git, node, or similar commands returns "not recognized" or "command not found". Checking your user PATH shows it has been reduced to just C:\Users\...\Nowledge Mem\cli or has lost entries like %PNPM_HOME%.
Cause: Versions before 0.6.8 could overwrite your Windows user PATH during installation by expanding environment variable references (like %PNPM_HOME%) into literal paths, or in some cases replacing the entire PATH with just the Nowledge Mem CLI directory.
This is fixed in 0.6.8 and later. The installer now preserves your PATH entries and their environment variable references exactly as they were.
If you were affected, here is how to restore your PATH:
- Press Win + R, type
sysdm.cpl, and press Enter. - Go to Advanced > Environment Variables.
- Under User variables, select Path and click Edit.
- Re-add any missing entries. Common ones include:
%PNPM_HOME%%USERPROFILE%\AppData\Local\Programs\Microsoft VS Code\bin%USERPROFILE%\.cargo\bin%USERPROFILE%\AppData\Roaming\npm
- Click OK and open a new terminal window.
Tip
If you're not sure what your PATH should contain, check a working machine or refer to the installation docs of each tool you use (pnpm, Node.js, Rust, etc.). Each tool's installer typically documents which PATH entry it adds.
CLI Not Found
Symptom: Running nmem in terminal returns "command not found".
Solutions by platform:
- macOS: Install the CLI from Settings → Preferences → Developer Tools
- Windows: Open a new terminal window after app installation (the PATH update requires a fresh session)
- Windows (WSL): See the WSL setup section below
- Linux: The CLI is included with deb/rpm packages. If installed manually, ensure
/usr/local/binis in your PATH
Quick check: Run nmem status to verify the CLI can connect to Nowledge Mem.
Using nmem from WSL
If you run coding agents like Claude Code or Codex inside WSL on Windows, the Windows nmem CLI isn't directly available in the Linux environment.
From v0.6.9, clicking Install CLI in Settings automatically creates a lightweight shim inside your default WSL distribution. If you need to set it up manually, paste this into your WSL terminal:
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/nmemThis creates a thin wrapper that calls the Windows nmem via interop. Since the command runs as a Windows process, it connects to the desktop app on localhost directly — no extra network configuration needed.
Verify it works:
nmem statusIf nmem is still not found after creating the shim, make sure ~/.local/bin is in your PATH. On Ubuntu this happens automatically; on other distributions, add export PATH="$HOME/.local/bin:$PATH" to your ~/.bashrc or ~/.zshrc.
Requirements
This approach requires WSL interop (enabled by default). If you've set interop=false or appendWindowsPath=false in /etc/wsl.conf, re-enable them or use pip install nmem-cli with Access Mem Anywhere instead.
Thread capture
The shim runs nmem as a Windows process, so commands like nmem t save --from claude-code look for session files in your Windows home directory rather than your WSL home. This is fine in practice — the desktop app captures WSL sessions automatically through its built-in file watcher. If you need direct CLI thread capture from WSL, use pip install nmem-cli instead.
Remote Access Returns 429
Symptom: nmem status or curl returns 429 Too many invalid auth attempts.
Solution: The client retried with an invalid API key too many times.
- Re-copy URL + key from Settings → Access Mem Anywhere
- Ensure
NMEM_API_KEYis the exact value (no extra spaces/quotes) - If unsure, click Rotate to issue a new key
Full setup and validation steps: Access Mem Anywhere.
Remote Access Returns 401 Missing API key
Symptom: Tunnel URL is reachable, but nmem status or curl returns 401 Missing API key.
Cause: Some network proxies remove auth headers.
Fix:
- Update to latest
nmem(it retries with proxy-safe fallback automatically) - Re-copy URL + key from Settings → Access Mem Anywhere
- For manual
curl, verify with:curl "$NMEM_API_URL/health?nmem_api_key=$NMEM_API_KEY"