Linux Server Deployment

Nowledge Mem can run as a headless server on Linux machines without a GUI. For a real server setup, use a Linux package and manage it from the command line. You can then open the built-in web app from a browser on the same machine, or connect other clients with an API key.

System Requirements

Installation

curl -fsSL https://nowledge-co.github.io/community/apt/install.sh | sudo bash
sudo apt-get install nowledge-mem

APT and .deb installs automatically:

• Installs the bundled Rust server and CLI binaries
• Creates the nmem CLI at /usr/local/bin/nmem
• Configures the APT repository for automatic updates (if installed via APT)
• Sets up the desktop entry (ignored on headless servers)

Verify the CLI is available:

nmem --version

If you used the AppImage instead, run the AppImage file directly each time. It does not add nmem to your PATH.

Docker (preview)

This page covers the .deb / APT / systemd path on Linux servers. Docker is a separate deployment model with its own walkthrough. It uses the same Mem backend, same web app, and same data, but the lifecycle (compose, bind mounts, image upgrades, optional web-UI auto-update) is different enough to live on its own page.

See Docker Deployment for the full guide: when Docker is the right choice (VPS, NAS, cloud VM, homelab), supported architectures (amd64 + arm64), quick start with nmemctl, the "For your agent" skill, where your data lives, memory tuning, image verification, Caddy TLS, backups and migration, and the optional web-UI auto-update.

Quick Start

For a real Linux server, set up the background service first. That gives you one stable local Mem server so the next commands work cleanly from SSH, across new terminals, and after reboot.

sudo nmem service install --service-user <linux-user>

nmem service install --user

sudo loginctl enable-linger <linux-user>

nmem service status
nmem status

nmem-server --build-info

nmem license activate <license-key>        # Email is usually inferred from the key
nmem license status    # Verify activation
nmem license renew     # Refresh this device later if authorization expires

nmem key --show-login

nmem key

http://127.0.0.1:14242/app

ssh -L <port>:127.0.0.1:<port> <server>

nmem models download
nmem models status     # Verify installation

nmem config provider set anthropic \
  --api-key sk-ant-xxx \
  --model claude-sonnet-4-20250514

nmem config provider test    # Verify connection

nmem config settings set backgroundIntelligence true
nmem config settings set autoDailyBriefing true

nmem status

nmem serve

Running as a systemd Service

For production deployments, use nmem service install to set up a background systemd service that automatically starts on boot:

# Install, enable, and start as your normal Linux user
sudo nmem service install --service-user <linux-user>

# If you are running sudo directly from that Linux user, Mem can usually infer it
sudo nmem service install

# Custom host/port
sudo nmem service install --service-user <linux-user> --host 0.0.0.0 --port 8080

sudo chown -R <linux-user>:<linux-user> ~/.config/co.nowledge.mem.desktop
sudo chown -R <linux-user>:<linux-user> ~/.local/share/NowledgeGraph

Managing the Service

nmem service status           # Show service status
nmem service stop             # Stop the service
nmem service start            # Start the service
nmem service uninstall        # Stop, disable, and remove
journalctl -u nmem -f         # Follow service logs (user-level service: journalctl --user -u nmem -f)

serve vs service

Data Location

All data (graph database, search index, version metadata) is stored in a single directory:

~/.local/share/NowledgeGraph/
├── nowledge_graph_v2.db/   # KuzuDB graph database
├── search_index/           # LanceDB vector + BM25 index
└── db_version.json         # Schema version tracking

The server resolves this path automatically using XDG_DATA_HOME (defaults to ~/.local/share). To use a custom location, set the NMEM_APP_DATA environment variable to the directory that holds nowledge_graph_v2.db before starting the server:

export NMEM_APP_DATA=/mnt/data/NowledgeGraph
nmem serve

Remote Access

By default, nmem serve listens on 127.0.0.1 only. That is enough for:

• nmem commands on the server itself
• the built-in web app on the same local URL (by default http://127.0.0.1:14242/app)

If you bind to 0.0.0.0 or another non-loopback address, Mem requires an API key for other machines. The key is auto-generated when needed, and you can print it again at any time with:

nmem key
# or
nmem key --show-login

--show-login also prints a single-use browser login link: open it on the device you want to connect and it signs you in. Each link works once and expires in a minute; older versions embed the key in the link instead.

Once the server is reachable, connect clients through the highest-level surface they support: native connectors first, then plugin settings or nmem config, and only then direct MCP when no better dedicated path exists. The main exception today is Codex, where the dedicated package already bundles local MCP and remote deployments should override that endpoint in Codex config.

# On the server
nmem serve
nmem key

Install the standalone CLI on remote machines:

pip install nmem-cli
# or
uv pip install nmem-cli

Then configure the connection. The recommended persistent setup is:

nmem config client set url http://your-server:14242
nmem config client set api-key nmem_...

That writes ~/.nowledge-mem/config.json for this machine. If you only need a temporary shell session, use environment variables instead:

export NMEM_API_URL=http://your-server:14242
export NMEM_API_KEY="nmem_..."

nmem status
nmem m search "query"

Priority: CLI flags > env vars > config file > defaults.

To disable authentication (not recommended for production):

NMEM_LAN_AUTH=disabled nmem serve

Interactive TUI

For an interactive terminal experience, use the TUI:

nmem tui

The TUI provides a full settings management interface including license activation, LLM configuration, and knowledge processing toggles.

It is bundled in the Docker image too. On a container deployment, run it inside the container:

docker compose exec -it mem nmem tui

It also includes Access Anywhere controls in Settings, and the same screen can reveal the current API key plus the local web login URL. That makes it practical to complete the /app login flow even on a headless server.
Full guide: Access Mem Anywhere.

If your server network blocks UDP/QUIC and Access Anywhere fails to come online, force Cloudflare transport to HTTP/2 before restarting Mem:

export TUNNEL_TRANSPORT_PROTOCOL=http2

Configuration Reference

Environment Variables

If you start nmem-server manually against a copied data directory, set both NMEM_APP_DATA and NMEM_DISABLE_APP_DATA_HEAL=1. The automatic legacy-data rescue is meant for normal app upgrades, not forensic/sandbox boots.

CLI Commands Summary

# APT package updates
sudo apt-get update
sudo apt-get install --only-upgrade nowledge-mem

Troubleshooting

Missing data after upgrade

Older versions (before 0.7) stored the database in ./data/ relative to the directory you ran nmem serve from. The current version stores data in the standard location (~/.local/share/NowledgeGraph/). If your memories disappeared after upgrading, your data is likely still on disk, just in the old location.

find / -name "nowledge_graph*.db" -type d 2>/dev/null

# Stop the server first
nmem service stop        # if using systemd
# or Ctrl+C              # if running in foreground

# Create the standard directory if needed
mkdir -p ~/.local/share/NowledgeGraph

# Move your database and related files
mv /old/path/data/nowledge_graph*.db* ~/.local/share/NowledgeGraph/
mv /old/path/data/search_index ~/.local/share/NowledgeGraph/  2>/dev/null
mv /old/path/data/db_version.json ~/.local/share/NowledgeGraph/  2>/dev/null

# Restart the server
nmem serve               # or: nmem service start

nmem m search "test"     # Search for your memories
nmem status              # Check server health

Next Steps

• CLI Reference: Complete CLI documentation
• API Reference: REST API endpoints
• Connectors: Connect with AI tools