wenlan-mcp 0.10.1 → 0.12.1
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 +78 -116
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,27 +2,18 @@
|
|
|
2
2
|
<img src="./docs/assets/social-preview.png" alt="Wenlan: a living personal knowledge library for the AI-native age." width="100%">
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
|
-
[](https://github.com/7xuanlu/wenlan/actions/workflows/ci.yml?query=branch%3Amain)
|
|
6
|
-
[](https://github.com/7xuanlu/wenlan/releases/latest)
|
|
7
|
-
[](https://www.npmjs.com/package/wenlan)
|
|
8
|
-
[](https://www.npmjs.com/package/wenlan-mcp)
|
|
9
|
-
[](https://modelcontextprotocol.io)
|
|
10
|
-
[](#license)
|
|
11
|
-
|
|
12
5
|
<p align="center">
|
|
13
|
-
<img alt="
|
|
14
|
-
<img alt="
|
|
15
|
-
<img alt="
|
|
6
|
+
<a href="https://github.com/7xuanlu/wenlan/actions/workflows/ci.yml?query=branch%3Amain"><img alt="CI" src="https://github.com/7xuanlu/wenlan/actions/workflows/ci.yml/badge.svg?branch=main&event=push"></a>
|
|
7
|
+
<a href="https://github.com/7xuanlu/wenlan/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/7xuanlu/wenlan?sort=semver&label=release"></a>
|
|
8
|
+
<a href="#license"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
|
|
16
9
|
</p>
|
|
17
10
|
|
|
18
11
|
<p align="center">
|
|
19
12
|
<a href="#claude-code-in-30-seconds"><img alt="Claude Code" src="https://img.shields.io/badge/Claude%20Code-plugin-5D4E75"></a>
|
|
20
|
-
<a href="#codex-plugin
|
|
21
|
-
<a href="#mcp-
|
|
22
|
-
<a href="#
|
|
23
|
-
<a href="#
|
|
24
|
-
<a href="#mcp-only-setup"><img alt="Gemini CLI" src="https://img.shields.io/badge/Gemini%20CLI-MCP-4285F4"></a>
|
|
25
|
-
<a href="#what-you-get"><img alt="Obsidian" src="https://img.shields.io/badge/Obsidian-Markdown%20pages-7C3AED"></a>
|
|
13
|
+
<a href="#codex-plugin"><img alt="Codex" src="https://img.shields.io/badge/Codex-plugin-111827"></a>
|
|
14
|
+
<a href="#mcp-setup"><img alt="MCP clients" src="https://img.shields.io/badge/MCP-clients-2563EB"></a>
|
|
15
|
+
<a href="#start-with-the-app"><img alt="Desktop app" src="https://img.shields.io/badge/Desktop-app-24C8DB"></a>
|
|
16
|
+
<a href="#what-you-get"><img alt="Markdown pages" src="https://img.shields.io/badge/Markdown-pages-7C3AED"></a>
|
|
26
17
|
</p>
|
|
27
18
|
|
|
28
19
|
<p align="center">
|
|
@@ -31,20 +22,40 @@
|
|
|
31
22
|
|
|
32
23
|
**A living personal knowledge library for the AI-native age, built by your agents and grounded in its sources.**
|
|
33
24
|
|
|
34
|
-
|
|
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.
|
|
35
26
|
|
|
36
|
-
Each
|
|
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.
|
|
37
28
|
|
|
38
|
-
|
|
29
|
+
Wenlan (文瀾) takes its name from 文瀾閣. The imperial library held 四庫全書 as part of one of China's largest book collections.
|
|
39
30
|
|
|
40
|
-
|
|
31
|
+
<p align="center">
|
|
32
|
+
<img src="./docs/assets/desktop-wiki-preview.png" alt="Wenlan desktop app showing a source-cited wiki page with a source memory hover card." width="100%">
|
|
33
|
+
</p>
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
<a id="start-with-the-app"></a>
|
|
38
|
+
|
|
39
|
+
## Start with the app
|
|
40
|
+
|
|
41
|
+
The desktop app is the fastest way to read and curate your source-cited wiki. Agents keep capturing and recalling context in Claude Code, Codex, Cursor, VS Code, Claude Desktop, or any MCP client, and every path talks to the same local daemon and Markdown store.
|
|
42
|
+
|
|
43
|
+
Set up Wenlan once:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npx -y wenlan setup
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Then open the desktop app releases page and download the latest macOS Apple Silicon DMG: [wenlan-app releases](https://github.com/7xuanlu/wenlan-app/releases/latest).
|
|
50
|
+
|
|
51
|
+
App source: [wenlan-app](https://github.com/7xuanlu/wenlan-app). Product details: [wenlan.app](https://wenlan.app).
|
|
41
52
|
|
|
42
53
|
---
|
|
43
54
|
|
|
44
55
|
## What makes Wenlan distinct
|
|
45
56
|
|
|
46
|
-
1. **Trustworthy
|
|
47
|
-
2. **
|
|
57
|
+
1. **Trustworthy sources.** Every page cites the memories behind it, and Wenlan refuses unsourced pages rather than letting hallucinated summaries in. It dedupes facts and supersedes old versions when facts change, so the wiki stays clean without turning daily capture into an approval queue.
|
|
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.
|
|
48
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.
|
|
49
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.
|
|
50
61
|
```text
|
|
@@ -53,6 +64,12 @@ Unlike a static llm-wiki, it keeps evolving between sessions. Unlike a black-box
|
|
|
53
64
|
5a4b3c2 capture: decision mem_abc123
|
|
54
65
|
```
|
|
55
66
|
|
|
67
|
+
The short reel below shows the product loop: source-backed pages, source cards, graph structure, agent capture, and curation before recall.
|
|
68
|
+
|
|
69
|
+
<p align="center">
|
|
70
|
+
<img src="./docs/assets/feature-reel.gif" alt="Wenlan five-scene feature reel showing source-backed pages, source cards, graph structure, agent capture, and curation review." width="100%">
|
|
71
|
+
</p>
|
|
72
|
+
|
|
56
73
|
---
|
|
57
74
|
|
|
58
75
|
## Quickstart
|
|
@@ -60,22 +77,23 @@ Unlike a static llm-wiki, it keeps evolving between sessions. Unlike a black-box
|
|
|
60
77
|
### Claude Code in 30 seconds
|
|
61
78
|
|
|
62
79
|
```text
|
|
63
|
-
/plugin marketplace add 7xuanlu/
|
|
64
|
-
/plugin install wenlan@7xuanlu
|
|
80
|
+
/plugin marketplace add 7xuanlu/wenlan
|
|
81
|
+
/plugin install wenlan@7xuanlu-wenlan
|
|
65
82
|
/setup
|
|
66
83
|
```
|
|
67
84
|
|
|
68
85
|
If Claude Code asks for a restart after installing, restart once, then run `/setup`. The plugin handles local runtime setup, MCP wiring, local memory setup, and the first round-trip check.
|
|
69
86
|
|
|
70
|
-
|
|
87
|
+
Prefer one storefront for everything? [`7xuanlu/claude-plugins`](https://github.com/7xuanlu/claude-plugins) lists Wenlan alongside [boule](https://github.com/7xuanlu/boule) and [ultrapowers](https://github.com/7xuanlu/ultrapowers):
|
|
71
88
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
89
|
+
```text
|
|
90
|
+
/plugin marketplace add 7xuanlu/claude-plugins
|
|
91
|
+
/plugin install wenlan@7xuanlu
|
|
92
|
+
```
|
|
75
93
|
|
|
76
|
-
|
|
94
|
+
Plugin details and daily commands: [plugin/](plugin/.claude-plugin/README.md).
|
|
77
95
|
|
|
78
|
-
|
|
96
|
+
### Codex plugin
|
|
79
97
|
|
|
80
98
|
```bash
|
|
81
99
|
npx -y wenlan setup
|
|
@@ -83,58 +101,42 @@ codex plugin marketplace add .
|
|
|
83
101
|
codex plugin add wenlan@wenlan-local
|
|
84
102
|
```
|
|
85
103
|
|
|
86
|
-
Start a new Codex thread after installing so the
|
|
104
|
+
Start a new Codex thread after installing so the plugin and MCP server load.
|
|
87
105
|
|
|
88
|
-
|
|
106
|
+
Plugin details and development notes: [plugin-codex/](plugin-codex/README.md).
|
|
89
107
|
|
|
90
|
-
|
|
91
|
-
python3 ~/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py plugin-codex
|
|
92
|
-
codex plugin add wenlan@wenlan-local
|
|
93
|
-
```
|
|
108
|
+
<a id="mcp-setup"></a>
|
|
94
109
|
|
|
95
|
-
|
|
110
|
+
### MCP setup
|
|
96
111
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
```bash
|
|
100
|
-
python3 scripts/validate-codex-plugin-slice.py
|
|
101
|
-
python3 scripts/validate-plugin-contract.py
|
|
102
|
-
bash scripts/validate-plugin-contract.test.sh
|
|
103
|
-
```
|
|
112
|
+
Both plugins call the same local MCP server under the hood. The core tools are `context`, `capture`, `recall`, `pages`, and `doctor`.
|
|
104
113
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
Use this if you want Wenlan tools in Claude Code without the plugin, or in Codex without slash skills, Cursor, Claude Desktop, VS Code, or Gemini CLI.
|
|
114
|
+
Use this if you want Wenlan tools in Claude Code without the plugin, or in Codex, Cursor, Claude Desktop, VS Code, or Gemini CLI:
|
|
108
115
|
|
|
109
116
|
```bash
|
|
110
117
|
npx -y wenlan setup
|
|
111
|
-
|
|
118
|
+
wenlan connect claude-code # or: codex, cursor, claude-desktop, vscode, gemini
|
|
112
119
|
```
|
|
113
120
|
|
|
114
|
-
MCP-only
|
|
121
|
+
MCP-only clients use the same core tools for context, capture, recall, doctor checks, and page distillation.
|
|
115
122
|
|
|
116
|
-
###
|
|
123
|
+
### CLI
|
|
117
124
|
|
|
118
|
-
Set up
|
|
125
|
+
Set up Wenlan once:
|
|
119
126
|
|
|
120
127
|
```bash
|
|
121
128
|
npx -y wenlan setup
|
|
122
129
|
```
|
|
123
130
|
|
|
124
|
-
Then
|
|
125
|
-
|
|
126
|
-
Service management:
|
|
131
|
+
Then use the CLI directly:
|
|
127
132
|
|
|
128
133
|
```bash
|
|
129
|
-
wenlan background on # register + start the background runtime
|
|
130
|
-
wenlan restart # stop + start the background runtime after upgrading
|
|
131
134
|
wenlan status
|
|
132
|
-
wenlan
|
|
135
|
+
wenlan recall <query>
|
|
136
|
+
wenlan capture <text>
|
|
133
137
|
```
|
|
134
138
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
---
|
|
139
|
+
CLI details: [crates/wenlan-cli](crates/wenlan-cli/README.md).
|
|
138
140
|
|
|
139
141
|
## How Wenlan works
|
|
140
142
|
|
|
@@ -173,41 +175,21 @@ Works fully local with no API key, cloud account, or signup. Capture, recall, hy
|
|
|
173
175
|
|
|
174
176
|
## What you get
|
|
175
177
|
|
|
176
|
-
- **
|
|
178
|
+
- **Typed captures**: every capture is stored with source agent, confidence, stability, and supersession metadata.
|
|
177
179
|
- **Source-backed pages**: pages keep source memory IDs, stale reasons, and revision state so distillation can refresh them without losing provenance.
|
|
178
180
|
- **Hybrid retrieval on libSQL**: memories, pages, FTS5 text, vector embeddings, and graph context in one local store your MCP clients can query, fused with reciprocal-rank fusion. An optional local cross-encoder reranker sharpens the top results.
|
|
179
181
|
- **Connected recall**: people, projects, tools, and decisions come back linked, so a memory arrives with the context around it instead of alone.
|
|
180
182
|
- **Distill cycles**: run `/distill` manually today, or add a local model/API key for background extraction, page refreshes, recaps, and richer graph links.
|
|
181
|
-
- **
|
|
183
|
+
- **Refreshes between sessions**: background passes link entities, grow matching pages, and update each memory's effective confidence from type, access, and age, so recent and load-bearing memories surface while stale ones fade.
|
|
182
184
|
- **Review before trust**: low-confidence captures, pending revisions, contradictions, and supersessions can surface instead of silently entering context.
|
|
183
185
|
- **Explicit spaces**: tag memories, pages, and recalls with `space=work | personal | client-X` so a day-job capture never bleeds into a side-project brief. Auto-detected from the current repo or workspace when no space is set; overridable always.
|
|
184
186
|
- **You own the data**: everything is plain Markdown under `~/.wenlan/`, versioned in git. Grep it, symlink it into Obsidian, or walk away with the files anytime. No lock-in.
|
|
185
187
|
|
|
186
|
-
### Spaces
|
|
187
|
-
|
|
188
|
-
Memories belong to a **space** like `wenlan`, `career`, or
|
|
189
|
-
`ideas`. Set the active space per shell:
|
|
190
|
-
|
|
191
|
-
WENLAN_SPACE=career claude
|
|
192
|
-
|
|
193
|
-
Or declaratively via `~/.wenlan/spaces.toml` (see
|
|
194
|
-
`plugin/examples/spaces.toml`). To manage spaces from the CLI:
|
|
195
|
-
|
|
196
|
-
wenlan spaces list
|
|
197
|
-
wenlan spaces add ideas --default
|
|
198
|
-
wenlan spaces show ideas
|
|
199
|
-
wenlan spaces move scratch career
|
|
200
|
-
|
|
201
|
-
`wenlan doctor` prints the current resolver state so you can see exactly
|
|
202
|
-
which layer chose the active space.
|
|
203
|
-
|
|
204
188
|
---
|
|
205
189
|
|
|
206
190
|
## Evaluation
|
|
207
191
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
Update workflow and answer-quality snapshots live in [docs/eval](docs/eval/README.md).
|
|
192
|
+
Retrieval-only snapshot, not end-to-end answer quality. Method and update workflow live in [docs/eval](docs/eval/README.md).
|
|
211
193
|
|
|
212
194
|
|
|
213
195
|
<!-- EVAL_SNAPSHOT_START -->
|
|
@@ -219,29 +201,9 @@ Update workflow and answer-quality snapshots live in [docs/eval](docs/eval/READM
|
|
|
219
201
|
|
|
220
202
|
---
|
|
221
203
|
|
|
222
|
-
## Repo Map
|
|
223
|
-
|
|
224
|
-
Wenlan is daemon-first. `wenlan-server` owns the local database, embeddings, distill cycles, knowledge graph, and HTTP API on `127.0.0.1:7878`. The plugin, MCP server, CLI, and local tools are thin clients over that daemon.
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
| Path | What lives there |
|
|
228
|
-
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
229
|
-
| [crates/wenlan-core](crates/wenlan-core/README.md) | Storage, search, embeddings, distill cycles, graph, pages, export, eval. |
|
|
230
|
-
| [crates/wenlan-server](crates/wenlan-server/README.md) | Local daemon and HTTP API. |
|
|
231
|
-
| [crates/wenlan-mcp](crates/wenlan-mcp/README.md) | MCP server, tools, npm package. |
|
|
232
|
-
| [crates/wenlan-cli](crates/wenlan-cli/README.md) | User CLI for setup, service management, search, recall, store, list, agents, model/key setup, and doctor. |
|
|
233
|
-
| [plugin/](plugin/.claude-plugin/README.md) | Claude Code plugin (`plugin.json`, skills, hooks, `.mcp.json`). |
|
|
234
|
-
| [plugin-codex/](plugin-codex/) | Codex plugin (`.codex-plugin/plugin.json`, skills, `agents/openai.yaml`, `.mcp.json`). |
|
|
235
|
-
| [docs/eval](docs/eval/README.md) | Benchmark workflow and methodology. |
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
Full contributor map: [CLAUDE.md](CLAUDE.md).
|
|
239
|
-
|
|
240
|
-
---
|
|
241
|
-
|
|
242
204
|
## Build from source
|
|
243
205
|
|
|
244
|
-
Wenlan builds
|
|
206
|
+
Wenlan builds from source on macOS (Apple Silicon + Intel), Linux (x86_64 + ARM64; glibc), and Windows (x86_64). Current prebuilt releases cover macOS Apple Silicon, Linux x86_64/ARM64 with glibc, and Windows x86_64; macOS Intel remains source-build only. The npm wrapper (`wenlan`, `wenlan-mcp`) and `install.sh` auto-detect supported prebuilt platforms. Most users should install through the Claude Code plugin or `npx`. For local development:
|
|
245
207
|
|
|
246
208
|
```bash
|
|
247
209
|
git clone https://github.com/7xuanlu/wenlan.git
|
|
@@ -256,24 +218,24 @@ Build details for the daemon, MCP server, CLI, and core crates live in the crate
|
|
|
256
218
|
|
|
257
219
|
## Learn more
|
|
258
220
|
|
|
259
|
-
Longer-form writing on AI work memory and how Wenlan compares lives at [
|
|
221
|
+
Longer-form writing on AI work memory and how Wenlan compares lives at [wenlan.app/learn](https://wenlan.app/learn):
|
|
260
222
|
|
|
261
223
|
**Concepts**
|
|
262
|
-
- [What is AI work memory?](https://
|
|
263
|
-
- [MCP memory server](https://
|
|
264
|
-
- [Local-first AI memory](https://
|
|
265
|
-
- [Markdown + local index](https://
|
|
266
|
-
- [AI agent handoff loop](https://
|
|
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
|
|
267
229
|
|
|
268
230
|
**Comparisons**
|
|
269
|
-
- [Wenlan vs Basic Memory](https://
|
|
270
|
-
- [Wenlan vs claude-mem](https://
|
|
271
|
-
- [Wenlan vs Superlocal Memory](https://
|
|
231
|
+
- [Wenlan vs Basic Memory](https://wenlan.app/learn/wenlan-vs-basic-memory): Markdown knowledge base vs AI work-session memory
|
|
232
|
+
- [Wenlan vs claude-mem](https://wenlan.app/learn/wenlan-vs-claude-mem): observer-style Claude Code memory vs MCP-first cross-tool memory
|
|
233
|
+
- [Wenlan vs Superlocal Memory](https://wenlan.app/learn/wenlan-vs-superlocal-memory): tradeoffs against another local memory shape
|
|
272
234
|
|
|
273
235
|
**Docs**
|
|
274
|
-
- [Get started](https://
|
|
275
|
-
- [Daily workflow](https://
|
|
276
|
-
- [MCP clients](https://
|
|
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
|
|
277
239
|
|
|
278
240
|
---
|
|
279
241
|
|