Architecture
Architecture
How Wenlan is put together: one local daemon, thin clients, shared wire types, local artifacts, and retrieval owned by wenlan-core.
At a glance
01
Wenlan is daemon-first: wenlan-server owns storage, search, pages, graph context, distill cycles, and the HTTP API.
02
Claude Code, Codex, ChatGPT, other MCP clients, the CLI, and local tools are clients over the same source-backed Wenlan system.
01
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, ChatGPT, Claude.ai, and terminal commands build on the same source-backed wiki without each tool inventing its own store.
02
Workspace map
The public repository is a Cargo workspace. The local runtime, CLI, MCP server, shared wire types, core logic, Claude Code plugin, Codex plugin, and AGPL-3.0-only desktop app crate now live together in the versioned monorepo.
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 -> stdio + Streamable HTTP MCP for AI clients
wenlan-types -> shared HTTP/MCP wire types
plugin/ -> Claude Code slash commands and hooks
plugin-codex/ -> Codex skills and MCP runner03
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 and Codex plugins: slash workflows 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, background service management, status, recall, search, capture, memories, spaces, models, keys, and doctor.
04
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.
05
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.
06
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. Current prebuilt runtime artifacts cover macOS Apple Silicon, Linux x86_64, Linux aarch64 glibc, and Windows x86_64; macOS Intel should be treated as source/dev-only until a public release workflow publishes that artifact again.
07
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.
Next
Product Matrix
Map Wenlan's product surfaces, repositories, platforms, status, setup actions, and verification routes before choosing an install path.
Read next