Architecture

How Wenlan is put together: one local daemon, thin clients, shared wire types, local artifacts, and retrieval owned by wenlan-core.

Qi-Xuan LuUpdated Jul 2, 20267 min read

At a glance

Wenlan is daemon-first: wenlan-server owns storage, search, pages, graph context, distill cycles, and the HTTP API.

Claude Code, MCP clients, the CLI, and local tools are thin clients over the same local source of truth.

The boundary

Wenlan keeps product behavior in one local daemon instead of scattering memory logic across every client. The daemon listens on 127.0.0.1:7878 and owns the database, embeddings, search, pages, graph context, and distill cycles.

That boundary is what lets Claude Code, Codex, Cursor, Claude Desktop, Gemini CLI, VS Code, and terminal commands share the same memory layer without each tool inventing its own store.

Workspace map

The public repository is a Cargo workspace. The desktop app lives in a separate repo, while the local runtime, CLI, MCP server, shared wire types, core logic, and Claude Code plugin live together.

Repository map

wenlan-server  -> local daemon on 127.0.0.1:7878
wenlan-core    -> storage, search, graph, pages, eval
wenlan CLI     -> setup, service management, recall, doctor
wenlan-mcp     -> MCP connector for AI clients
wenlan-types   -> shared HTTP/MCP wire types
plugin/        -> Claude Code slash commands and hooks

Runtime flow

A client stores or recalls memory through HTTP, MCP, or the CLI. wenlan-server frames the request and calls wenlan-core. wenlan-core handles storage, hybrid retrieval, knowledge graph context, pages, quality gates, enrichment, and eval-facing logic.

The client receives a compact response: memories, pages, decisions, graph context, or diagnostic state. The source of truth stays local.

Claude Code plugin: slash commands such as /brief, /capture, /recall, /distill, and /handoff.
wenlan-mcp: MCP tools such as context, capture, recall, distill, list_pending, confirm_memory, forget, and doctor.
wenlan CLI: setup, service management, status, recall, search, store, spaces, model, key, and doctor.

Storage and retrieval

The local database uses libSQL for document chunks, vector search, FTS5 search, graph tables, pages, and metadata. Recall combines vector search, full-text search, graph context, and relevant pages with Reciprocal Rank Fusion.

Human-facing artifacts stay under ~/.wenlan. Pages and session logs are Markdown. The daemon-owned database remains the retrieval source of truth; readable artifacts are the projection people can inspect.

Model paths

Local memory mode works without a model download or API key. Store, embed, search, recall, and MCP memory are available immediately.

On-device models and Anthropic keys are optional. They unlock heavier extraction, page synthesis, recaps, and richer graph work, but the basic memory loop does not depend on them.

Platform services

Wenlan installs a local runtime into ~/.wenlan/bin. The service manager differs by operating system: launchd on macOS, systemd user units on Linux, and a per-user Task Scheduler logon task on Windows.

The same daemon contract is used across platforms. Cross-platform support in the public release covers macOS arm64/x64, Linux x86_64/aarch64 with glibc, and Windows x86_64.

Why this shape

The daemon-first shape keeps memory behavior consistent. It also makes Wenlan easier to test: wenlan-core has no Axum or Tauri dependency, wenlan-types stays lightweight, and clients do not own business logic.

For users, the practical result is simpler: one local home for AI work context, with multiple tools reading and writing through the same boundary.

View the source repository

Commands and Tools

The essential Claude Code commands and MCP tools for running Wenlan day to day.