wenlan-mcp 0.13.1 → 0.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +243 -165
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,5 +1,14 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(max-width: 600px)" srcset="./docs/assets/readme-banner-mobile.png">
|
|
4
|
+
<img src="./docs/assets/readme-banner.png" alt="Wenlan: your source-backed knowledge base, built to compound." width="100%">
|
|
5
|
+
</picture>
|
|
6
|
+
</p>
|
|
7
|
+
|
|
8
|
+
Useful work with AI shouldn't disappear when a conversation ends. Wenlan builds the right pages and keeps them current as sources change, asking only when judgment is needed.
|
|
9
|
+
|
|
10
|
+
<p align="center">
|
|
11
|
+
English | <a href="./README.zh-Hans.md">简体中文</a> | <a href="./README.zh-Hant.md">繁體中文</a>
|
|
3
12
|
</p>
|
|
4
13
|
|
|
5
14
|
<p align="center">
|
|
@@ -9,188 +18,269 @@
|
|
|
9
18
|
</p>
|
|
10
19
|
|
|
11
20
|
<p align="center">
|
|
12
|
-
<a href="#
|
|
13
|
-
<a href="#
|
|
14
|
-
<a href="#
|
|
15
|
-
<a href="#
|
|
16
|
-
<a href="#
|
|
21
|
+
<a href="#start-in-30-seconds">Get started</a> ·
|
|
22
|
+
<a href="#what-does-wenlan-build">What is this?</a> ·
|
|
23
|
+
<a href="#what-can-it-do">Capabilities</a> ·
|
|
24
|
+
<a href="#how-does-it-work">Daily workflow</a> ·
|
|
25
|
+
<a href="#evaluation">Evaluation</a> ·
|
|
26
|
+
<a href="#learn-more">Learn more</a>
|
|
17
27
|
</p>
|
|
18
28
|
|
|
19
29
|
<p align="center">
|
|
20
|
-
|
|
30
|
+
<img src="./docs/assets/desktop-wiki-preview.png" alt="Wenlan desktop app showing a source-backed wiki page with inspectable citations." width="100%">
|
|
21
31
|
</p>
|
|
22
32
|
|
|
23
|
-
**A living personal knowledge library for the AI-native age, built by your agents and grounded in its sources.**
|
|
24
|
-
|
|
25
|
-
Unlike a normal llm-wiki that generates pages from a fixed document set, Wenlan keeps a source-cited wiki current with live agent work and trusted sources. It is built for long-running work with AI agents, from software development and research to writing, consulting, product decisions, and client work.
|
|
26
|
-
|
|
27
|
-
Your agents capture what they learn during sessions, you add pages and sources you already trust, and Wenlan distills both into Markdown pages that refresh between sessions. Each new thread starts from that updated wiki, with a brief to bring context forward and a handoff to record where the work should continue.
|
|
28
|
-
|
|
29
|
-
Wenlan (文瀾) takes its name from 文瀾閣. The imperial library held 四庫全書 as part of one of China's largest book collections.
|
|
30
|
-
|
|
31
33
|
<p align="center">
|
|
32
|
-
<
|
|
34
|
+
<sub>A maintained Page in the desktop app: open any citation to inspect the Source or Memory behind the claim.</sub>
|
|
33
35
|
</p>
|
|
34
36
|
|
|
35
37
|
---
|
|
36
38
|
|
|
39
|
+
<a id="quickstart"></a>
|
|
40
|
+
<a id="start-in-30-seconds"></a>
|
|
41
|
+
|
|
42
|
+
## Get started
|
|
43
|
+
|
|
37
44
|
<a id="start-with-the-app"></a>
|
|
45
|
+
<a id="open-the-wiki"></a>
|
|
46
|
+
|
|
47
|
+
### Desktop app
|
|
48
|
+
|
|
49
|
+
The desktop app is the fastest way to see the complete workflow: read pages, inspect their sources, and curate the knowledge system. The current macOS Apple Silicon preview is not yet notarized, so this installer verifies the GitHub release, installs Wenlan, clears quarantine for this app only, and opens it without changing macOS security settings:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/7xuanlu/wenlan/main/scripts/install-macos-app.sh)"
|
|
53
|
+
```
|
|
38
54
|
|
|
39
|
-
|
|
55
|
+
The [installer is inspectable](scripts/install-macos-app.sh). It checks the release archive against GitHub's published SHA-256 before replacing an existing app. Prefer the DMG or want to inspect the app source? See [wenlan-app releases](https://github.com/7xuanlu/wenlan-app/releases/latest) and [wenlan-app](https://github.com/7xuanlu/wenlan-app).
|
|
40
56
|
|
|
41
|
-
|
|
57
|
+
<a id="claude-code-in-30-seconds"></a>
|
|
42
58
|
|
|
43
|
-
|
|
59
|
+
<a id="codex-plugin"></a>
|
|
60
|
+
|
|
61
|
+
<a id="mcp-setup"></a>
|
|
62
|
+
<a id="mcp-clients"></a>
|
|
63
|
+
|
|
64
|
+
### Set up with your AI
|
|
65
|
+
|
|
66
|
+
Paste this into Claude Code, Codex, or another tool that can follow a setup guide:
|
|
67
|
+
|
|
68
|
+
```text
|
|
69
|
+
Set up Wenlan for this AI client by following:
|
|
70
|
+
https://raw.githubusercontent.com/7xuanlu/wenlan/main/docs/setup-with-ai.md
|
|
71
|
+
|
|
72
|
+
Install only what this client needs. Then verify the local runtime,
|
|
73
|
+
its Wenlan connection, and a capture/recall round trip.
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
The guide detects which client you are using and keeps client-specific commands out of this README. It does not configure every AI tool unless you ask it to.
|
|
77
|
+
|
|
78
|
+
Need only the headless runtime on macOS Apple Silicon?
|
|
44
79
|
|
|
45
80
|
```bash
|
|
46
81
|
npx -y wenlan setup
|
|
47
82
|
```
|
|
48
83
|
|
|
49
|
-
|
|
84
|
+
This downloads the prebuilt CLI, daemon, and MCP connector, starts the local runtime, and verifies it. No Rust toolchain or Cargo is required. Linux x64/ARM64 with glibc has an automated [shell setup path](docs/setup-with-ai.md#install-the-runtime); Windows x64 uses the matching archive from [Releases](https://github.com/7xuanlu/wenlan/releases/latest). macOS Intel currently has [no supported complete-runtime install](crates/wenlan-cli/README.md#macos-intel).
|
|
50
85
|
|
|
51
|
-
|
|
86
|
+
Manual and client-specific instructions: [AI-assisted setup](docs/setup-with-ai.md) · [Claude Code plugin](plugin/.claude-plugin/README.md) · [Codex plugin](plugin-codex/README.md) · [CLI and MCP](crates/wenlan-cli/README.md).
|
|
52
87
|
|
|
53
88
|
---
|
|
54
89
|
|
|
55
|
-
|
|
90
|
+
<a id="what-does-wenlan-build"></a>
|
|
91
|
+
<a id="why-it-compounds"></a>
|
|
56
92
|
|
|
57
|
-
|
|
58
|
-
2. **Current between sessions.** Wenlan clusters new captures into source-cited pages between sessions, and feeds retrieval with both the pages and the atomic notes behind them. The wiki reflects your latest work instead of a stale snapshot.
|
|
59
|
-
3. **One home, locked to none.** Every MCP client queries the same local daemon, so context built in one tool shows up in the next. Obsidian is one optional view you can symlink in, not where your work lives.
|
|
60
|
-
4. **Real git versioning.** Memory, page, and session writes commit into `~/.wenlan/.git/`, so you can inspect, diff, revert, or branch the Markdown artifacts.
|
|
61
|
-
```text
|
|
62
|
-
a1b2c3d page: embedding-retrieval refreshed (4 sources)
|
|
63
|
-
9f8e7d6 session: handoff embedding-work
|
|
64
|
-
5a4b3c2 capture: decision mem_abc123
|
|
65
|
-
```
|
|
93
|
+
## What is this?
|
|
66
94
|
|
|
67
|
-
|
|
95
|
+
Wenlan turns documents, notes, and past AI conversations into a source-backed knowledge base that stays current as your work evolves. Sources remain traceable; decisions, lessons, and corrections become durable memories; both can support the same maintained Pages.
|
|
68
96
|
|
|
69
97
|
<p align="center">
|
|
70
|
-
<
|
|
98
|
+
<picture>
|
|
99
|
+
<source media="(max-width: 600px)" srcset="./docs/assets/wenlan-system-mobile.png">
|
|
100
|
+
<img src="./docs/assets/wenlan-system.png" alt="Sources and memories independently support a maintained Page. Wenlan can rebuild a stale Page from its current support; optional conflict review can surface protected conflicts, and changes to human writing wait for the user." width="100%">
|
|
101
|
+
</picture>
|
|
71
102
|
</p>
|
|
72
103
|
|
|
73
|
-
|
|
104
|
+
<a id="what-wenlan-is-not"></a>
|
|
74
105
|
|
|
75
|
-
|
|
106
|
+
**Built for work that continues.** Wenlan is for researchers, writers, consultants, product teams, and software teams whose knowledge is scattered across documents, notes, and AI conversations. It turns that material into inspectable Pages that can improve across projects and weeks, not another chat history or isolated memory store. It is not a life-management system or a memory SDK embedded inside another product.
|
|
76
107
|
|
|
77
|
-
|
|
108
|
+
**One knowledge system, three roles:**
|
|
78
109
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
/setup
|
|
83
|
-
```
|
|
110
|
+
- **Sources keep the material Wenlan reads traceable.** Imported conversations remain as captured records; registered files sync their current contents as they change.
|
|
111
|
+
- **Memories preserve what work teaches you.** Agents capture atomic decisions, lessons, corrections, and supersession with provenance.
|
|
112
|
+
- **Pages compile current knowledge.** Wenlan turns relevant Sources and Memories into source-cited Markdown you can reuse, refresh, and review.
|
|
84
113
|
|
|
85
|
-
|
|
114
|
+
**The LLM-wiki foundation, extended:**
|
|
86
115
|
|
|
87
|
-
|
|
116
|
+
- **[LLM-wiki v1](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f):** Karpathy defined immutable Sources, an AI-maintained Markdown Wiki, and a co-evolving Schema of rules for structuring and maintaining it. Wenlan implements that foundation with [typed Memory fields](docs/technical-foundations.md#typed-memory-schema) and built-in rules for Page structure, provenance, citations, refresh, ownership, and review.
|
|
117
|
+
- **[LLM-wiki v2](https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2):** Rohitg00 added a memory lifecycle. Wenlan makes that direction concrete with traceable Sources, agent-captured Zettelkasten-style atomic Memories (one complete idea each), and maintained Pages built from both.
|
|
88
118
|
|
|
89
|
-
|
|
90
|
-
/plugin marketplace add 7xuanlu/claude-plugins
|
|
91
|
-
/plugin install wenlan@7xuanlu
|
|
92
|
-
```
|
|
119
|
+
**Wenlan's distinctive move:** Sources and atomic Memories independently support maintained Pages. Memory history preserves how knowledge changed; Page history shows which current evidence supports the synthesis. Machine-maintained Pages can rebuild from current support, while changes to human writing wait as reviewable revisions.
|
|
93
120
|
|
|
94
|
-
|
|
121
|
+
<p align="center">
|
|
122
|
+
<img src="./docs/assets/feature-reel.gif" alt="Wenlan feature reel showing source-backed pages, source inspection, graph context, agent capture, and curation." width="100%">
|
|
123
|
+
</p>
|
|
95
124
|
|
|
96
|
-
|
|
125
|
+
<a id="knowledge-graph"></a>
|
|
97
126
|
|
|
98
|
-
|
|
99
|
-
npx -y wenlan setup
|
|
100
|
-
codex plugin marketplace add .
|
|
101
|
-
codex plugin add wenlan@wenlan-local
|
|
102
|
-
```
|
|
127
|
+
### A knowledge graph that gets more useful over time
|
|
103
128
|
|
|
104
|
-
|
|
129
|
+
The entity-relation graph is one part of Wenlan's wider connected wiki. **Knowledge Pages** hold maintained synthesis, **Entities** anchor reusable people, projects, and concepts, **Source Pages** make imported or synchronized material inspectable, and atomic **Memories** preserve decisions and changes. They work through separate, explicit links: Page-to-Page wikilinks, Page evidence, Memory-to-Entity links, and directed Entity relations.
|
|
105
130
|
|
|
106
|
-
|
|
131
|
+
<p align="center">
|
|
132
|
+
<picture>
|
|
133
|
+
<source media="(max-width: 600px)" srcset="./docs/assets/wenlan-knowledge-network-mobile.png">
|
|
134
|
+
<img src="./docs/assets/wenlan-knowledge-network.png" alt="Conceptual model of Wenlan's connected knowledge system, with Knowledge Pages, Source Pages, atomic Memories, and Entities connected through Page links, evidence, Memory-to-Entity links, and Entity relations." width="100%">
|
|
135
|
+
</picture>
|
|
136
|
+
</p>
|
|
107
137
|
|
|
108
|
-
|
|
138
|
+
Within the entity graph, a configured enrichment model extracts typed Entities, observations, and directed relations from Memories. Entity linking and resolution reuse existing nodes instead of treating every mention as new; each Memory keeps its Source and can link to multiple Entities. [How the connected model is stored ->](docs/technical-foundations.md#connected-knowledge-model)
|
|
109
139
|
|
|
110
|
-
|
|
140
|
+
- **Meaning and direction:** Relations use a seeded vocabulary such as `uses`, `part_of`, `contradicts`, and `replaced_by`; unknown types fall back to `related_to` and become reviewable vocabulary proposals.
|
|
141
|
+
- **Strength and provenance:** A relation can store confidence, an explanation, and its source Memory, so stronger and weaker claims remain distinguishable and inspectable.
|
|
142
|
+
- **Communities that compound:** Label propagation groups Entities by relation density, weighted by the relation count between each pair. These groups can organize optional corpus summaries while Entity links add retrieval context.
|
|
143
|
+
- **Correction without erasure:** Related claims, corrections, and explicit supersession stay inspectable together while original Sources and Memory history remain.
|
|
111
144
|
|
|
112
|
-
|
|
145
|
+
During retrieval, dense entity matching finds query-relevant entities. When eligible graph links exist, the default graph-memory stream boosts linked Memories as a third [RRF](https://cormack.uwaterloo.ca/cormacksigir09-rrf.pdf) signal. The path is data- and scope-dependent, and Space boundaries still apply. [How the graph path works ->](docs/technical-foundations.md#graph-assisted-retrieval)
|
|
113
146
|
|
|
114
|
-
|
|
147
|
+
<a id="retrieval"></a>
|
|
115
148
|
|
|
116
|
-
|
|
117
|
-
npx -y wenlan setup
|
|
118
|
-
wenlan connect claude-code # or: codex, cursor, claude-desktop, vscode, gemini
|
|
119
|
-
```
|
|
149
|
+
### Retrieval across words, meaning, and connections
|
|
120
150
|
|
|
121
|
-
|
|
151
|
+
Wenlan's core search is a local hybrid pipeline, not a single vector lookup. Each stage has a different job:
|
|
122
152
|
|
|
123
|
-
|
|
153
|
+
- **Exact wording — [SQLite FTS5](https://www.sqlite.org/fts5.html):** a full-text index finds literal terms, identifiers, and phrases.
|
|
154
|
+
- **Similar meaning — FastEmbed + [`Qdrant/bge-base-en-v1.5-onnx-Q`](https://huggingface.co/Qdrant/bge-base-en-v1.5-onnx-Q):** a quantized English model creates 768-dimensional embeddings; [libSQL cosine DiskANN](https://turso.tech/blog/approximate-nearest-neighbor-search-with-diskann-in-libsql) indexes them for approximate nearest-neighbor retrieval.
|
|
155
|
+
- **Combined ranking — weighted [RRF](https://cormack.uwaterloo.ca/cormacksigir09-rrf.pdf) (`k = 60`):** lexical and semantic rank lists are fused without pretending their raw scores share a scale; cosine similarity also weights the vector contribution.
|
|
156
|
+
- **Connected context — graph-memory stream:** eligible entity links add a third RRF signal while the active read scope still filters returned Memories.
|
|
157
|
+
- **Optional precision — cross-encoder reranking:** unlike embeddings, [`jinaai/jina-reranker-v1-turbo-en`](https://huggingface.co/jinaai/jina-reranker-v1-turbo-en) or [`BAAI/bge-reranker-base`](https://huggingface.co/BAAI/bge-reranker-base) reads each query-candidate pair and reorders the smaller pool; reranking is off by default.
|
|
124
158
|
|
|
125
|
-
|
|
159
|
+
Page, episodic, and fact channels are opt-in and degrade to the remaining search signals if unavailable. Space still limits the read scope. [Methods, defaults, and limitations ->](docs/technical-foundations.md)
|
|
126
160
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
161
|
+
<a id="what-makes-wenlan-distinct"></a>
|
|
162
|
+
<a id="why-is-wenlan-different"></a>
|
|
163
|
+
<a id="two-lifecycles"></a>
|
|
130
164
|
|
|
131
|
-
|
|
165
|
+
### Two lifecycles, one maintained knowledge system
|
|
132
166
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
167
|
+
A generated wiki can go stale; a memory store can fragment into disconnected facts. Wenlan links two lifecycles without collapsing them into one layer.
|
|
168
|
+
|
|
169
|
+
<p align="center">
|
|
170
|
+
<picture>
|
|
171
|
+
<source media="(max-width: 600px)" srcset="./docs/assets/wenlan-lifecycle-mobile.png">
|
|
172
|
+
<img src="./docs/assets/wenlan-lifecycle.png" alt="An earlier memory remains linked after an explicit superseding capture. When a Page is stale, Wenlan rebuilds it from current Sources and Memories, records the revision, and stages changes to human writing for review." width="100%">
|
|
173
|
+
</picture>
|
|
174
|
+
</p>
|
|
175
|
+
|
|
176
|
+
#### Atomic Memory
|
|
177
|
+
|
|
178
|
+
`CAPTURE -> CLASSIFY -> ENRICH -> LINK -> RECONCILE`
|
|
179
|
+
|
|
180
|
+
Capture and explicit supersession are core. Model-backed stages run only when the matching model is configured, and the reconcile pass is off by default.
|
|
138
181
|
|
|
139
|
-
|
|
182
|
+
| Operation | What Wenlan does |
|
|
183
|
+
|---|---|
|
|
184
|
+
| **Capture** | Agents write one complete, self-contained idea per Memory, following the Zettelkasten atomic-note principle instead of saving the whole conversation. |
|
|
185
|
+
| **Classify** | With the on-device model, Wenlan assigns `identity`, `preference`, `decision`, `lesson`, `gotcha`, or `fact`; a precise type supplied by the caller remains authoritative. |
|
|
186
|
+
| **Enrich** | With the on-device model, adds structured fields, retrieval cues, event dates, quality, importance, and tags when available. |
|
|
187
|
+
| **Link** | Retains provenance and, when enrichment is enabled, connects Memories to entities and relations in the knowledge graph. |
|
|
188
|
+
| **Reconcile** | Explicit replacements preserve a `supersedes` chain. An optional on-device pass can queue protected conflicts for review instead of overwriting history; it is off by default and must be explicitly enabled. |
|
|
140
189
|
|
|
141
|
-
|
|
190
|
+
Advanced configuration: set `WENLAN_ENABLE_DUAL_POOL_RESOLVE=1` to enable that reconcile pass.
|
|
142
191
|
|
|
143
|
-
|
|
192
|
+
#### Maintained Page
|
|
193
|
+
|
|
194
|
+
`DISTILL -> CITE -> TRACK -> REFRESH -> REVIEW`
|
|
195
|
+
|
|
196
|
+
| Operation | What Wenlan does |
|
|
197
|
+
|---|---|
|
|
198
|
+
| **Distill** | Compiles related Sources and Memories into one Markdown Page. |
|
|
199
|
+
| **Cite** | Retains citation records and verification status; automatic refresh discards a draft when its citation-support check fails. |
|
|
200
|
+
| **Track** | Records which evidence supports the Page, why it became stale, and a bounded changelog. |
|
|
201
|
+
| **Refresh** | When a Page is marked stale, rebuilds the eligible machine-maintained Page from current evidence. |
|
|
202
|
+
| **Review** | Turns changes to a Page you edited into a proposed revision instead of a silent rewrite. |
|
|
203
|
+
|
|
204
|
+
For example, import a design document and capture a debugging decision in Codex. Wenlan can compile one Page that cites both. When that Page is refreshed, it rebuilds from its current support; if you have edited it, the proposed change waits for review.
|
|
205
|
+
|
|
206
|
+
<a id="local-markdown"></a>
|
|
207
|
+
|
|
208
|
+
### Local Markdown that works with Obsidian
|
|
209
|
+
|
|
210
|
+
Your durable synthesis remains ordinary files rather than a proprietary editor format:
|
|
211
|
+
|
|
212
|
+
- **Plain files:** Pages and session notes stay as Markdown under `~/.wenlan/`.
|
|
213
|
+
- **Inspectable history:** Distill and handoff workflows can commit logical file batches to a local git repository.
|
|
214
|
+
- **Obsidian coexistence:** Wenlan reads an existing vault as a source. Symlink `~/.wenlan/pages/` into the vault or export a Page from the desktop app; your edits remain human-owned, and later machine refreshes become reviewable revisions.
|
|
215
|
+
|
|
216
|
+
The local history is directly inspectable:
|
|
144
217
|
|
|
145
218
|
```text
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
│ CAPTURE │ │ DAEMON │ │ ONE STORE │ │ RECALL + │
|
|
150
|
-
│ in flow │ ─▶ │ refines │ ─▶ │ (local) │ ─▶ │ BRIEF │
|
|
151
|
-
│ /capture │ │ between │ │ · memories │ │ next │
|
|
152
|
-
│ │ │ sessions │ │ · wiki pages │ │ session │
|
|
153
|
-
│ │ │ dedup·link │ │ · graph │ │ /recall │
|
|
154
|
-
│ │ │ /distill │ │ │ │ /brief │
|
|
155
|
-
└───────────┘ └─────────────┘ └────────────────┘ └───────────┘
|
|
156
|
-
one local daemon · one store · every MCP client reads it
|
|
157
|
-
Claude Code · Cursor · Codex · Claude Desktop · VS Code · Gemini
|
|
219
|
+
$ git -C ~/.wenlan log --oneline
|
|
220
|
+
a1b2c3d distill: 4 pages
|
|
221
|
+
9f8e7d6 session: embedding-work
|
|
158
222
|
```
|
|
159
223
|
|
|
160
|
-
|
|
224
|
+
---
|
|
161
225
|
|
|
162
|
-
|
|
226
|
+
<a id="what-you-get"></a>
|
|
227
|
+
<a id="what-can-it-do"></a>
|
|
228
|
+
<a id="what-can-i-bring-in"></a>
|
|
229
|
+
|
|
230
|
+
## Capabilities
|
|
231
|
+
|
|
232
|
+
- **Chat import:** Bring in ChatGPT or Claude export ZIPs; Wenlan automatically skips conversations already imported.
|
|
233
|
+
- **Document Sources:** Ingest one `.md`, `.txt`, or text-extractable `.pdf` file; recurse through a folder of them; or index Markdown from an Obsidian vault.
|
|
234
|
+
- **Incremental sync:** Regular file and folder Sources track changes in the background; Obsidian vaults stay read-only and resync on demand.
|
|
235
|
+
- **Atomic Memory:** MCP clients save one complete decision, lesson, correction, preference, or fact, with [provenance and supersession](https://wenlan.app/learn/ai-memory-provenance) recording where it came from and what it replaces.
|
|
236
|
+
- **[Typed enrichment](docs/technical-foundations.md#typed-memory-schema):** A configured model classifies each Memory, then adds the structured fields defined for its type, plus dates, tags, retrieval cues, and graph links.
|
|
237
|
+
- **[Source-backed Pages](https://wenlan.app/docs/source-backed-pages):** Distill related Sources and Memories into Markdown Pages with source references and `[[wikilinks]]`; the daemon can verify and record per-claim citations.
|
|
238
|
+
- **Citation-gated refresh:** Automatic refresh rejects citation-poor drafts; machine Pages update while human edits become reviewable revisions.
|
|
239
|
+
- **[Hybrid retrieval](docs/technical-foundations.md#retrieval-pipeline):** FTS5 finds exact words, local BGE embeddings find meaning, and RRF fuses their ranks; graph links can add context.
|
|
240
|
+
- **[Retrieval channels](docs/technical-foundations.md#optional-channels-and-defaults):** Optional Page, episodic, and per-fact channels widen recall; cross-encoder reranking can improve precision.
|
|
241
|
+
- **[Knowledge graph](docs/technical-foundations.md#graph-data-and-entity-resolution):** Typed entities, relations, and observations connect people, projects, claims, and supporting Memories.
|
|
242
|
+
- **[Human-in-the-loop review](https://wenlan.app/docs/review-and-trust):** Routine work stays automatic; protected conflicts, Page revisions, entity merges, and new vocabulary wait for judgment.
|
|
243
|
+
- **[Spaces](https://wenlan.app/docs/spaces):** Keep work, personal, client, and repository knowledge inside an explicit retrieval scope.
|
|
244
|
+
- **[Local daemon + MCP](https://wenlan.app/docs/architecture):** One lightweight Rust daemon remains the local source of truth. The desktop app and CLI call it directly; AI clients use small MCP connectors to reach the same knowledge.
|
|
245
|
+
- **Custom integrations:** The localhost HTTP API accepts prepared text, webpage content, and Memories from other capture workflows.
|
|
246
|
+
- **Background maintenance:** The daemon keeps working after the desktop app closes, running configured sync, enrichment, citation work, and eligible Page refresh.
|
|
247
|
+
- **[Model choice](docs/technical-foundations.md#model-roles):** Base retrieval stays local; enrichment and synthesis can use on-device Qwen, a local endpoint, or a configured cloud model.
|
|
248
|
+
- **[Inspectable ownership](https://wenlan.app/learn/markdown-local-index-ai-memory):** Memories and graph data stay in local libSQL; Markdown, citations, revisions, git history, and Obsidian exports remain inspectable.
|
|
249
|
+
- **Read-only health checks:** [`doctor`](https://wenlan.app/docs/diagnostics-and-issue-reports) verifies the runtime; [`lint`](plugin/skills/lint/SKILL.md) finds malformed citations, orphan links, broken embeddings, and search-index or graph integrity problems without rewriting knowledge.
|
|
163
250
|
|
|
164
|
-
|
|
165
|
-
2. **During work.** `/capture <thing>` saves a decision, lesson, gotcha, or project fact in flow. `/recall <query>` looks anything up.
|
|
166
|
-
3. **Session ends.** `/handoff` writes what changed, what's still open, and where to continue, so the next run picks up cleanly.
|
|
167
|
-
4. **Between sessions.** The daemon deduplicates overlapping captures and links related ideas in the background. `/distill` synthesizes wiki pages from clusters of related memories when you want a deliberate pass.
|
|
168
|
-
5. **Next session.** `/brief` brings it back in the Claude Code and Codex plugins; MCP-only clients call the `context` tool for the same memory. Recall pulls the relevant slice, not your whole history, so the context window goes to the work.
|
|
251
|
+
---
|
|
169
252
|
|
|
170
|
-
|
|
253
|
+
<a id="how-wenlan-works"></a>
|
|
254
|
+
<a id="how-does-it-work"></a>
|
|
171
255
|
|
|
172
|
-
|
|
256
|
+
## Daily workflow
|
|
173
257
|
|
|
174
|
-
|
|
258
|
+
The system above becomes a small daily loop: start with relevant knowledge, capture what matters while you work, close with a handoff, and let Wenlan refine what should return next time. Each pass leaves the same knowledge base sharper instead of creating another disconnected history.
|
|
175
259
|
|
|
176
|
-
|
|
260
|
+
The loop has four steps:
|
|
177
261
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
- **
|
|
186
|
-
- **
|
|
262
|
+
1. **Find current knowledge.** Open a relevant Page, search, or use `/recall <query>`; `/brief [topic]` can optionally assemble a broader session-start snapshot. Clients without plugin commands use the equivalent page, search, recall, and context tools.
|
|
263
|
+
2. **Capture and find knowledge while you work.** `/capture <thing>` saves a decision, lesson, gotcha, or fact with its source. `/recall <query>` retrieves only what is relevant instead of loading your whole history.
|
|
264
|
+
3. **Close the loop.** `/handoff` records what changed, what remains open, and where the next session should continue.
|
|
265
|
+
4. **Keep the wiki current.** `/distill` deliberately creates or refreshes pages. Between sessions, optional model-backed passes can enrich captures, connect related entities, and refresh eligible pages. `/lint` checks knowledge health; `/curate` brings proposed revisions and any conflict-review items created by the optional reconcile pass to you.
|
|
266
|
+
|
|
267
|
+
### Models and privacy
|
|
268
|
+
|
|
269
|
+
- **Local base retrieval:** The [BGE embedding model](https://huggingface.co/Qdrant/bge-base-en-v1.5-onnx-Q) runs through FastEmbed on your machine for hybrid search and needs no API key.
|
|
270
|
+
- **Optional on-device synthesis:** Enrichment and Page synthesis can use user-selected [`Qwen3 4B`](https://huggingface.co/unsloth/Qwen3-4B-Instruct-2507-GGUF) or [`Qwen3.5 9B`](https://huggingface.co/unsloth/Qwen3.5-9B-GGUF) through [llama.cpp](https://github.com/ggml-org/llama.cpp). Wenlan does not download or activate a language model until you choose one.
|
|
271
|
+
- **Other providers:** An OpenAI-compatible local endpoint such as Ollama or LM Studio, or a configured cloud provider, can supply model-backed enrichment and synthesis instead.
|
|
272
|
+
- **Cloud disclosure:** If the model endpoint you select is remote, Wenlan sends that task's system and user prompts to it. Local retrieval and on-device synthesis stay on your machine.
|
|
273
|
+
- **No telemetry:** Wenlan sends no telemetry.
|
|
274
|
+
|
|
275
|
+
Full workflow reference: [plugin/skills](plugin/skills/README.md). Technical model roles: [technical foundations](docs/technical-foundations.md#model-roles).
|
|
187
276
|
|
|
188
277
|
---
|
|
189
278
|
|
|
190
|
-
|
|
279
|
+
<a id="evaluation"></a>
|
|
191
280
|
|
|
192
|
-
|
|
281
|
+
## Evaluation
|
|
193
282
|
|
|
283
|
+
This is a retrieval-only snapshot, not a claim about end-to-end answer quality. Method, environment receipts, and the update workflow live in [docs/eval](docs/eval/README.md).
|
|
194
284
|
|
|
195
285
|
<!-- EVAL_SNAPSHOT_START -->
|
|
196
286
|
| Benchmark | Recall@5 | MRR | NDCG@10 |
|
|
@@ -201,82 +291,70 @@ Retrieval-only snapshot, not end-to-end answer quality. Method and update workfl
|
|
|
201
291
|
|
|
202
292
|
---
|
|
203
293
|
|
|
204
|
-
|
|
294
|
+
<a id="learn-more"></a>
|
|
205
295
|
|
|
206
|
-
|
|
296
|
+
## Learn more
|
|
207
297
|
|
|
208
|
-
|
|
209
|
-
git clone https://github.com/7xuanlu/wenlan.git
|
|
210
|
-
cd wenlan
|
|
211
|
-
cargo build --workspace
|
|
212
|
-
cargo run -p wenlan-server
|
|
213
|
-
```
|
|
298
|
+
More detailed documentation, concepts, and comparisons:
|
|
214
299
|
|
|
215
|
-
|
|
300
|
+
### Docs
|
|
216
301
|
|
|
217
|
-
|
|
302
|
+
- [Get started](https://wenlan.app/docs/get-started): install and verify the first local loop.
|
|
303
|
+
- [Daily workflow](https://wenlan.app/docs/daily-workflow): brief, capture, recall, handoff, distill, lint, and curate.
|
|
304
|
+
- [MCP clients](https://wenlan.app/docs/mcp-clients): connect Claude Code, Codex, Cursor, Claude Desktop, and other clients.
|
|
218
305
|
|
|
219
|
-
|
|
306
|
+
### Concepts
|
|
220
307
|
|
|
221
|
-
|
|
308
|
+
- [Why a living wiki, not just AI memory](https://wenlan.app/learn/ai-work-memory): the problem and product model in depth.
|
|
309
|
+
- [MCP memory server](https://wenlan.app/learn/mcp-memory-server): how Wenlan exposes knowledge across AI tools.
|
|
310
|
+
- [Local-first AI memory](https://wenlan.app/learn/local-first-ai-memory): data, privacy, and control.
|
|
311
|
+
- [Markdown and local index](https://wenlan.app/learn/markdown-local-index-ai-memory): storage, retrieval, and ownership.
|
|
312
|
+
- [AI agent handoff loop](https://wenlan.app/learn/ai-agent-handoff-loop): carrying work cleanly into the next session.
|
|
222
313
|
|
|
223
|
-
|
|
224
|
-
- [What is AI work memory?](https://wenlan.app/learn/ai-work-memory): the shape of the problem Wenlan solves
|
|
225
|
-
- [MCP memory server](https://wenlan.app/learn/mcp-memory-server): how Wenlan exposes memory through the Model Context Protocol
|
|
226
|
-
- [Local-first AI memory](https://wenlan.app/learn/local-first-ai-memory): data, privacy, and control
|
|
227
|
-
- [Markdown + local index](https://wenlan.app/learn/markdown-local-index-ai-memory): the storage model
|
|
228
|
-
- [AI agent handoff loop](https://wenlan.app/learn/ai-agent-handoff-loop): session-end discipline that prevents context loss
|
|
314
|
+
### Comparisons
|
|
229
315
|
|
|
230
|
-
|
|
231
|
-
- [Wenlan vs
|
|
232
|
-
- [Wenlan vs
|
|
233
|
-
- [Wenlan vs Superlocal Memory](https://wenlan.app/learn/wenlan-vs-superlocal-memory): tradeoffs against another local memory shape
|
|
234
|
-
|
|
235
|
-
**Docs**
|
|
236
|
-
- [Get started](https://wenlan.app/docs/get-started): install + verify the first local memory loop
|
|
237
|
-
- [Daily workflow](https://wenlan.app/docs/daily-workflow): capture, handoff, distill
|
|
238
|
-
- [MCP clients](https://wenlan.app/docs/mcp-clients): connect Claude Code, Cursor, Codex, Claude Desktop, Gemini CLI
|
|
316
|
+
- [Wenlan vs Basic Memory](https://wenlan.app/learn/wenlan-vs-basic-memory)
|
|
317
|
+
- [Wenlan vs claude-mem](https://wenlan.app/learn/wenlan-vs-claude-mem)
|
|
318
|
+
- [Wenlan vs Superlocal Memory](https://wenlan.app/learn/wenlan-vs-superlocal-memory)
|
|
239
319
|
|
|
240
320
|
---
|
|
241
321
|
|
|
242
|
-
##
|
|
322
|
+
## Contributing
|
|
243
323
|
|
|
244
|
-
|
|
245
|
-
- **Not a workflow suite.** ~30 MCP tools across one daemon. If you want 30+ skills, 8+ agents, and an auto-research loop bundled, look at [pro-workflow](https://github.com/rohitg00/pro-workflow). Wenlan trades breadth for focus.
|
|
246
|
-
- **Not a memory infrastructure SDK.** For people using AI daily, not as a backend for other apps building memory features.
|
|
247
|
-
- **Not for one-off chats.** Best when work spans sessions, projects, and weeks.
|
|
324
|
+
Bug fixes, eval cases, docs, and features are welcome. Installing Wenlan does not require building from source. For local development, run each group from the root of the named repository:
|
|
248
325
|
|
|
249
|
-
|
|
326
|
+
```bash
|
|
327
|
+
# 7xuanlu/wenlan — runtime, CLI, and MCP
|
|
328
|
+
cargo build --workspace
|
|
329
|
+
cargo test --workspace
|
|
250
330
|
|
|
251
|
-
|
|
331
|
+
# 7xuanlu/wenlan-app — desktop app
|
|
332
|
+
pnpm install
|
|
333
|
+
pnpm tauri dev
|
|
334
|
+
pnpm build:all
|
|
335
|
+
```
|
|
252
336
|
|
|
253
|
-
|
|
337
|
+
Use `pnpm dev:all` in the app repository when you want a fresh daemon-plus-app sequence. See this repository's [AGENTS.md](AGENTS.md) and [CONTRIBUTING.md](CONTRIBUTING.md), plus [wenlan-app's AGENTS.md](https://github.com/7xuanlu/wenlan-app/blob/main/AGENTS.md), for the complete development workflow. Security reports: [SECURITY.md](SECURITY.md). Please also read the [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
254
338
|
|
|
255
339
|
---
|
|
256
340
|
|
|
257
|
-
|
|
341
|
+
<a id="license"></a>
|
|
258
342
|
|
|
259
|
-
|
|
343
|
+
## License
|
|
260
344
|
|
|
261
|
-
|
|
345
|
+
Wenlan is licensed under **Apache-2.0**. This includes the local runtime, CLI, MCP server, shared types, and Claude Code/Codex plugin files in this repository.
|
|
262
346
|
|
|
263
347
|
---
|
|
264
348
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
Predecessors:
|
|
349
|
+
<a id="acknowledgments"></a>
|
|
268
350
|
|
|
269
|
-
|
|
270
|
-
- Claude Code's `MEMORY.md`. The simplest version of the idea.
|
|
351
|
+
## Lineage and peers
|
|
271
352
|
|
|
272
|
-
|
|
353
|
+
Wenlan (文瀾) takes its name from 文瀾閣, an imperial library that held 四庫全書 as part of one of China's largest book collections.
|
|
273
354
|
|
|
274
|
-
-
|
|
275
|
-
- [basic-memory](https://github.com/basicmachines-co/basic-memory). Local-first knowledge management for Claude.
|
|
276
|
-
- [obsidian-mind](https://github.com/breferrari/obsidian-mind). Obsidian-native memory and review loop for coding agents.
|
|
277
|
-
- [pro-workflow](https://github.com/rohitg00/pro-workflow). Claude Code productivity suite.
|
|
278
|
-
- [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service). Memory service for MCP.
|
|
279
|
-
- [Memoria](https://github.com/matrixorigin/Memoria). "Git for AI Agent Memory" via Copy-on-Write.
|
|
280
|
-
- [OpenMemory](https://github.com/CaviraOSS/OpenMemory), [claude-memory-compiler](https://github.com/coleam00/claude-memory-compiler), [PAI](https://github.com/danielmiessler/PAI), Palinode. Adjacent shapes.
|
|
355
|
+
Wenlan's llm-wiki v2 model is its own product direction, informed by the LLM-wiki and agent-memory lineages:
|
|
281
356
|
|
|
282
|
-
|
|
357
|
+
- [Karpathy's LLM-wiki note](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) established the raw-source-to-maintained-wiki pattern.
|
|
358
|
+
- [Rohitg00's LLM Wiki v2 proposal](https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2) extends that pattern with memory lifecycle, confidence, graph, and retrieval mechanisms. [agentmemory](https://github.com/rohitg00/agentmemory) is its concrete agent-memory implementation.
|
|
359
|
+
- [nashsu/llm_wiki](https://github.com/nashsu/llm_wiki) is a full desktop implementation of the document-centered LLM-wiki pattern.
|
|
360
|
+
- [basic-memory](https://github.com/basicmachines-co/basic-memory), [obsidian-mind](https://github.com/breferrari/obsidian-mind), [mcp-memory-service](https://pypi.org/project/mcp-memory-service/), [Memoria](https://github.com/matrixorigin/Memoria), and [OpenMemory](https://github.com/CaviraOSS/OpenMemory) explore adjacent local knowledge and agent-memory shapes.
|