Troubleshooting

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 (nmem CLI + 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 config

Viewing Logs

open -a Console ~/Library/Application\ Support/NowledgeGraph/Logs/app.log

open -a Console ~/Library/Logs/Nowledge\ Graph/app.log

Search 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

The storage line in that panel separates the main parts of your local data:

• Knowledge Graph: memories, entities, relationships, and graph metadata
• Messages: saved conversation messages and larger text payloads
• Search Index: a rebuildable search projection used for ranking and snippets

These two actions solve different problems:

• Optimize compacts on-disk search storage without rebuilding everything
• Rebuild Index recreates the search index from your saved memories, library content, and message store when the existing index may be stale or corrupted

If you are on a Linux server or using Mem remotely without the desktop app open:

• Run nmem status to see whether search is ready, needs a rebuild, or is only updating metadata
• Run nmem models status for the same signal plus model installation state
• If the status says updating metadata, let it finish. That path does not need a rebuild.

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.

127.0.0.1, localhost, ::1

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:

1. Download and install Microsoft Visual C++ Redistributable (x64): https://aka.ms/vs/17/release/vc_redist.x64.exe
2. Restart Nowledge Mem.
3. If it still fails, attach app.log when reporting the issue.

Linux: Blank Window or Slow Graph View

Symptom: On Linux, Mem opens to a blank or white window. Or the window works, but the knowledge graph and other pages feel very slow.

Cause: Both depend on how WebKitGTK, the web engine Mem uses on Linux, draws the window. On some graphics setups, such as the NVIDIA driver on X11 or some virtual machines, GPU-accelerated rendering leaves the window blank, so Mem turns it off at startup there. Without it, pages are drawn on the CPU and can feel slow on high-resolution screens.

What to do first: Quit Mem completely. Close the window with Alt+F4 or your window manager's close shortcut, or choose Quit from the tray menu. From a blank window this can take about half a minute, sometimes longer. Then check that pgrep -a nowledge-mem prints nothing. A setting passed while Mem is still running is ignored.

Blank or white window: start Mem with GPU-accelerated rendering turned off.

WEBKIT_DISABLE_DMABUF_RENDERER=1 nowledge-mem

Slow pages: start Mem with GPU-accelerated rendering kept on. If the window turns blank with this setting, quit Mem and start it normally again.

WEBKIT_DISABLE_DMABUF_RENDERER=0 nowledge-mem

For the AppImage, put the setting in front of the AppImage file instead, for example WEBKIT_DISABLE_DMABUF_RENDERER=1 ./Nowledge-Mem.AppImage.

You'll know it worked when the window shows your content and the knowledge graph moves smoothly as you drag or zoom it.

To keep a setting for launches from the app menu or at login, save it in your session environment, then log out and back in:

mkdir -p ~/.config/environment.d
echo 'WEBKIT_DISABLE_DMABUF_RENDERER=1' > ~/.config/environment.d/nowledge-mem.conf

Use 0 instead of 1 to keep GPU-accelerated rendering on. This works on desktops that use systemd, and it applies to every app that uses WebKitGTK. To undo it, delete the file, then log out and back in.

If neither setting helps, attach app.log when you report the issue (see Viewing Logs).

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.

Common fixes (especially on Windows):

1. Verify your installation is complete (embedded Python and startup scripts are present).
2. Restart Nowledge Mem after plugin or model configuration changes.
3. Update to the latest build if you use Windows and have shell customizations like Conda. Recent releases isolate AI Now and the bundled nmem launcher from broken PowerShell profile hooks so those scripts no longer fail before Mem starts.
4. Temporarily disable antivirus/quarantine rules that may block bundled Python or PowerShell startup.
5. 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.

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.

When to use it:

1. The index keeps growing after updates or repeated reindexing.
2. The search index is much larger than the knowledge you actually store.
3. Search still works, but disk usage looks obviously wasteful.

If the Search Index number still looks wrong after optimization, run Rebuild Index once. If the Messages number is large, that usually means you have imported or saved many conversations; use Data Transfer for backup and migration rather than deleting index files by hand. If storage remains abnormal, 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.

Try this when:

1. A memory exists, but search cannot find it with reasonable queries.
2. Results are suddenly much worse after an upgrade, crash, or heavy import.
3. 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:

1. Press Win + R, type sysdm.cpl, and press Enter.
2. Go to Advanced > Environment Variables.
3. Under User variables, select Path and click Edit.
4. 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
5. Click OK and open a new terminal window.

Windows: Memories Missing After Update (Even After Rolling Back)

Symptom: After a Windows update, your memory count drops to zero or near zero. Rolling back to the previous version does not bring them back.

This can happen when the app opens a different graph location, but the memory count alone cannot identify which database holds your earlier data or whether it is intact. File size and modification time are not reliable ways to choose a graph.

What to do first: If the app is open with missing Memories, stop adding new content and quit it, including the system tray instance. Keep every NowledgeGraph folder, database, journal, checkpoint, and backup as it is. Do not rename a folder, copy one database over another, or remove individual files to make the count change.

Email [email protected] with your app version, Windows version, the error shown at startup (if any), and whether you have already moved or renamed any graph files. You do not need to send database files, Memory content, or full personal paths. Support will identify the relevant graph and a safe recovery path before asking you to change any files.

If you already changed a graph folder, preserve both the original and changed locations, including the Recycle Bin and any existing backups. Tell support what you did; do not try another swap. An app that opens, or a count that returns, is not by itself proof that all earlier Memories and Threads are present.

Backend Won't Start / Crash Loop

Quit Nowledge Mem, including its tray or menu bar instance, and check that no other nmem-server process is using the same data. Update to 0.10.96 or a newer stable release. If startup still fails, check the specific error in the startup log.

Recovering a confirmed corrupt WAL

The current database engine replays changes from its .wal journal when opening the database. An explicit Corrupted wal file or WAL checksum error can mean that this replay is preventing startup. Renaming the corrupt WAL out of the replay path may let the main database open again.

Use nmem-server recover-graph from a 0.10.96 or newer installation to work on a copy, retain the source files, and validate the result. Use a bundled backend compatible with your data; check its --version and --help for the recovery command first. This is the backend executable, not the nmem CLI. If you cannot find the bundled backend or the terminal reports “command not found,” contact [email protected] for help locating it. On Windows, use the bundled nmem-server.exe; PowerShell can invoke it as & "full\path\to\nmem-server.exe".

1. Select the database actually used by your installation from the backup as --source. The paths below are examples; do not choose a different database by its size or modification date.
2. --output must name a new, nonexistent directory outside the source database directory. Its parent must already exist. Try strict recovery first:

nmem-server recover-graph --source "/backup/NowledgeGraph/nowledge_graph_v2.db" --output "/recovery/attempt-1"

3. Only if strict recovery reports a specific WAL replay corruption error, and you accept the loss risk above, retry with a different new output directory:

nmem-server recover-graph --source "/backup/NowledgeGraph/nowledge_graph_v2.db" --output "/recovery/attempt-2" --discard-corrupt-wal

For a recognized WAL corruption error, the tool renames the candidate copy's .wal to .wal.discarded and retries. It does not delete the original WAL or replace the active database. A manual rename also skips replay, but lacks these recovery and validation steps. Investigate on a complete copy first; do not rename the WAL in your original data directory and resume writing there.

4. Success requires exit code 0 and receipt.json in the output directory with status candidate_validated_not_activated. Check whether wal_discarded is true. The candidate is not active yet. Keep the original folder and recovery output, and contact [email protected] for help checking several pre-failure Memories and Threads in an isolated environment before deciding whether to activate it. Matching counts or successful startup alone do not prove complete recovery.

Startup errors that do not establish WAL corruption

Unreadable, LOCAL_GRAPH_ROOT_RECOVERY_REQUIRED, allocation failures, file locks, and generic assertions do not establish corrupt WAL. Do not bypass startup checks by removing WAL or other files when there is a checkpoint/shadow recovery error, an identity recovery marker, or more than one populated graph location.

Email [email protected] with your app and backend versions, operating system, relevant error codes, and any graph file changes you have made. Do not send database files, Memory content, or full personal paths. If you already renamed a file, retain it and the rest of the folder without deleting it or renaming it back on your own. Stop adding or changing content if earlier data is missing.

HawDB development

Our database HawDB is open source and is being developed to replace the current storage engine. Supported local desktop installations can try it through the experimental settings; otherwise, you can wait for a future stable replacement release. Migration requires readable legacy data and validation. Enabling the experiment does not repair a corrupt legacy WAL.

CLI Not Found

Symptom: Running nmem in terminal returns "command not found".

Solutions by platform:

• macOS: Open Nowledge Mem once, then open a new terminal. The app installs or repairs nmem after startup without blocking the app. If the command is still missing, use Settings → Preferences → Developer Tools → Install CLI to repair it manually.
• 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: Desktop packages include the CLI and the app repairs the wrapper after startup. Open a new terminal; if nmem is still missing, make sure ~/.local/bin is in your shell PATH.

Quick check: Run nmem status to verify the CLI can connect to Nowledge Mem.

CLI and Server Versions Differ

Symptom: nmem status shows "Version mismatch".

This means the command in your terminal and the Mem server it reached were installed or updated separately. The connection can still be healthy, but an older CLI may not know the latest commands or diagnostics.

Fix the side that is older:

• Desktop CLI: Open Settings → Preferences → Developer Tools → Install CLI, then restart the terminal.
• PyPI install: Run python -m pip install --upgrade nmem-cli.
• pipx install: Run pipx upgrade nmem-cli.
• One-shot use: Run uvx --from nmem-cli nmem status.
• Server older than CLI: Update or restart Nowledge Mem, or check that NMEM_API_URL points to the server you meant to use.

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'
#!/usr/bin/env bash
cd /mnt/c || exit 1
exec cmd.exe /c nmem.cmd "$@"
SHIMEOF
chmod +x ~/.local/bin/nmem

This creates a thin wrapper that calls the Windows nmem via interop from a Windows-mounted working directory. That avoids the common UNC-path failure mode from WSL home directories. Since the command runs as a Windows process, it connects to the desktop app on localhost directly, so no extra network configuration is needed.

Verify it works:

nmem status

If 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.

nmem status Returns "Not Found"

Symptom: nmem status shows "Not Found: Resource doesn't exist" when using a remote server, but the TUI works fine.

Cause: The CLI is hitting the wrong URL. This usually means ~/.nowledge-mem/config.json is missing or has the wrong apiUrl.

Fix:

1. Verify the config file exists and has the correct URL:

   {
     "apiUrl": "https://<your-url>",
     "apiKey": "nmem_..."
   }

2. Test with curl: curl -H "Authorization: Bearer $NMEM_API_KEY" "$NMEM_API_URL/health"
3. Update to the latest nmem CLI. Newer versions show clearer error messages and remote setup hints.

Full setup: Access Mem Anywhere.

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_KEY is 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"

Mem Says Graph Memory Was Increased

Symptom: Search, graph, or save operations start failing on a larger library, and Mem shows a title-bar notice that graph memory was updated.

Cause: Mem raised the graph-memory limit for the next launch after the current session ran out of room. The running backend is still on the old limit until you reopen the app.

Fix:

1. Quit and reopen Nowledge Mem. That applies the higher graph-memory limit.
2. If the notice keeps coming back, open Settings → Processing → Database Tuning and choose a larger Graph Memory value.
3. On headless or server installs, set NOWLEDGE_KUZU_BUFFER_POOL_SIZE=512MB (or higher) before starting nmem serve.

Mem Looks Like It Uses a Lot of RAM

Symptom: Activity Monitor (macOS) or Task Manager (Windows) shows Nowledge Mem using around a gigabyte of memory, which looks high for a notes-and-memory app.

This is normal, and the number is misleading. The figure your system monitor shows is not how much memory Mem actually needs. Most of it falls into three buckets that do not count as real pressure on your machine:

• Memory we have already finished with. After bursts of work like search, importing, or background processing, your operating system keeps those pages parked with Mem instead of reclaiming them right away, because handing them back and forth is slow. They are free to be reused the moment anything else needs them.
• Shared program code. Mem ships as a single self-contained app, so its program code shows up in the memory number, but it is shared and read-only and the system drops it instantly under pressure.
• Your knowledge stored on disk. Your graph and search index live as files on disk. The system counts them toward Mem's memory because it maps them in for fast reads, but they are not really sitting in RAM, and they are released as needed.

Mem's actual working memory is well under what the headline number suggests, and it holds no AI model in memory unless you are running a local model.

Linux Server Setup Says It Cannot Reach 127.0.0.1:14242

Symptom: Commands like nmem license activate, nmem models download, or nmem config ... fail with “Cannot reach http://127.0.0.1:14242”.

Cause: Those commands talk to your local Mem server. On a fresh Linux server, that usually means the server is not running yet, or you started it in the foreground and forgot you still need a second terminal.

Fix:

1. For a real server, install the background service first: sudo nmem service install --service-user <linux-user>
2. Then verify it is up: nmem service status and nmem status
3. If you are only doing a quick test with nmem serve, keep that terminal open and run the other nmem commands in a second terminal
4. To open the web app from your own computer over SSH, run nmem key --show-login first and forward the same port it prints: ssh -L <port>:127.0.0.1:<port> <server>. The login link works once and expires in a minute, so grab a fresh one after the tunnel is up
5. To sign in again, run nmem key --show-login on newer builds for a fresh single-use login link, or nmem key on older ones and paste the printed key into the web app

Report Issue