Configuration

Wenlan Configuration

Configure Wenlan spaces, MCP clients, daemon bind address, local paths, models, and keys without editing the database by hand.

Qi-Xuan LuUpdated Jul 2, 20265 min read

At a glance

Configure Wenlan through /init, npx setup, wenlan mcp add, wenlan space, wenlan model, and wenlan key before editing files by hand.

Most users only need WENLAN_SPACE for context separation and, rarely, WENLAN_BIND_ADDR for Docker or VM access.

Run wenlan doctor after configuration changes to verify daemon health, MCP wiring, local paths, model state, and key state.

Configuration quick path

The safest way to configure Wenlan is command-driven: run /init in Claude Code, npx -y wenlan setup for other MCP clients, then let wenlan mcp add write the client-specific MCP configuration.

After changing spaces, MCP clients, daemon binding, models, or keys, run wenlan doctor. It checks the daemon, local runtime, MCP connector, model state, key state, and common path issues before you debug by hand.

Setup checks

/init
npx -y wenlan setup
~/.wenlan/bin/wenlan mcp add cursor
~/.wenlan/bin/wenlan doctor

Read the Claude Code memory guide

Spaces

Spaces separate work, personal, client, and project memory without requiring multiple Wenlan installs. Set a space for a shell session with WENLAN_SPACE, or define stable spaces in ~/.wenlan/spaces.toml.

Use wenlan space commands when you want the CLI to list, create, inspect, or move spaces instead of editing the file directly.

Space config

WENLAN_SPACE=client-a claude
wenlan space list
wenlan space add client-a

MCP client wiring

MCP clients need to launch the same local wenlan-mcp connector. The normal path is wenlan mcp add because each client stores MCP config differently.

If a client requires manual JSON, use wenlan mcp add --dry-run to inspect the command path for your machine, then paste the generated shape into that client's settings.

Client config

~/.wenlan/bin/wenlan mcp add claude-code
# or: codex, cursor, claude-desktop, vscode, gemini

Daemon bind address

The daemon binds to 127.0.0.1:7878 by default. That is the right setting for normal laptop use because the memory API stays local to the machine.

Only change WENLAN_BIND_ADDR when you deliberately need a non-loopback bind, such as a Docker or VM environment. Exposing the daemon is a privacy decision, not a normal setup step.

Environment

WENLAN_SPACE=client-a
WENLAN_HOST=http://127.0.0.1:7878
WENLAN_BIND_ADDR=127.0.0.1:7878
WENLAN_BIND_ADDR=0.0.0.0:7878  # Docker or VM only

Local files

Human-facing Wenlan artifacts live under ~/.wenlan. The daemon-owned database and platform service files live under the OS application data location.

Read Markdown pages and session logs freely. Avoid hand-editing the database; use capture, review, distill, forget, and the CLI so the index, pages, and metadata stay consistent.

Paths

~/.wenlan/
~/.wenlan/bin/
~/.wenlan/db/
~/.wenlan/pages/
~/.wenlan/sessions/
~/.wenlan/spaces.toml
~/Library/Application Support/wenlan/
~/.local/share/wenlan/
%LOCALAPPDATA%\origin\  # current Windows runtime legacy directory

Models and keys

Wenlan works in local memory mode without a model download or API key. Configure a model or Anthropic key only when you want daemon-side language work such as richer extraction, recaps, or page synthesis.

Treat keys as an explicit opt-in. The connected AI client may already call its own provider during chat; Wenlan's model and key settings only cover daemon-side work.

Read models and keys

Environment Variables

Know which Wenlan environment variables are normal configuration, which are development-only, and which belong to eval or Windows repair paths.