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

%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 config

/usr/lib/nowledge-mem/
/usr/share/nowledge-mem/

Viewing Logs

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

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

%LOCALAPPDATA%\Packages\NowledgeLabsLLC.NowledgeMem_1070t6ne485wp\logs\app.log

%LOCALAPPDATA%\NowledgeGraph\logs\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.

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.

Your data is not lost. Your graph lives in one folder, but the app is now reading a different location where an empty database got created, and that empty one is shadowing your real data. The steps below move the real data back to where the app looks. You only copy or rename, never delete, so a wrong guess is always reversible.

Before you start: Fully quit Nowledge Mem, including from the system tray. Open Task Manager and confirm no nmem-server or Nowledge Mem process is still running.

Step 1: Find the real data.

Press Win + R and open each of these in turn. Some may not exist, and that is fine:

• %LOCALAPPDATA%\NowledgeGraph (what the app reads now, usually the empty one)
• %APPDATA%\NowledgeGraph (older location, real data is often here)
• %USERPROFILE%\Documents\NowledgeGraph (oldest location)

In each folder, compare the size of nowledge_graph_v2.db. Real data is tens of MB to several GB. A fresh empty database is small and was last modified on the day things broke. Also check whether a sizeable content.db and any content.db.backup.* files are present. The folder with the largest and oldest nowledge_graph_v2.db is your real data folder.

Step 2: Back up the current (empty) location.

In %LOCALAPPDATA%, rename the NowledgeGraph folder to NowledgeGraph_empty_backup. Rename it, do not delete it.

Step 3: Copy the real data into place.

Copy your real data folder into %LOCALAPPDATA%\ so that it is named NowledgeGraph. Copy it, do not move it, so the original stays as a backup.

Step 4: Start the app.

Open Nowledge Mem and go to Memories. The count should return.

Still stuck, or not comfortable doing this by hand: Take a screenshot of the nowledge_graph_v2.db sizes in the three folders and email them, together with your app.log (from Settings → Info), to hello@nowledge-labs.ai. Do not delete any NowledgeGraph or _empty_backup folder before you hear back.

Backend Won't Start / Crash Loop (Quarantine a Corrupt Database Journal)

Symptom: After an update or an interrupted rebuild, the app never finishes starting and the backend keeps restarting. Sometimes a hard crash or a power loss during a write leaves the database write-ahead journal (.wal) in a bad state, and the backend cannot open the graph.

Steps:

1. Fully quit the app, including from the system tray.
2. Open the graph data folder for your platform:
   • macOS: ~/Library/Application Support/NowledgeGraph
   • Windows: %LOCALAPPDATA%\NowledgeGraph
   • Linux: ~/.local/share/NowledgeGraph
3. If a file named nowledge_graph_v2.db.wal exists, rename it to nowledge_graph_v2.db.wal.corrupt-backup. Rename it, do not delete it.
4. If nowledge_graph_v2.db.shm is present, rename it aside as well.
5. Start the app.

Only the most recent, not-yet-saved changes can be affected. Everything already saved is intact. If it still will not start, send your app.log to hello@nowledge-labs.ai and keep the renamed files.

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>
5. To print the login key again, run nmem key --show-login on newer builds, or nmem key on older ones

Report Issue