wenlan-mcp 0.10.1 → 0.12.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 +69 -114
- 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.
|
|
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
|
+
<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:
|
|
35
44
|
|
|
36
|
-
|
|
45
|
+
```bash
|
|
46
|
+
npx -y wenlan setup
|
|
47
|
+
```
|
|
37
48
|
|
|
38
|
-
|
|
49
|
+
Then download the current macOS Apple Silicon build: [wenlan-app-darwin-arm64.dmg](https://github.com/7xuanlu/wenlan/releases/latest/download/wenlan-app-darwin-arm64.dmg).
|
|
39
50
|
|
|
40
|
-
|
|
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
|
|
@@ -67,15 +84,9 @@ Unlike a static llm-wiki, it keeps evolving between sessions. Unlike a black-box
|
|
|
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
|
-
Then try `/brief`, `/capture <decision>`, or `/handoff` inside Claude Code.
|
|
71
|
-
|
|
72
87
|
Plugin details and daily commands: [plugin/](plugin/.claude-plugin/README.md).
|
|
73
88
|
|
|
74
|
-
### Codex plugin
|
|
75
|
-
|
|
76
|
-
The Codex plugin lives in [plugin-codex](plugin-codex/) and is exposed through the repo-local marketplace at [.agents/plugins/marketplace.json](.agents/plugins/marketplace.json). It adds `/setup`, `/brief`, `/capture`, `/recall`, `/distill`, `/pages`, `/curate`, `/forget`, `/handoff`, and `/help` skills plus a `wenlan` MCP server.
|
|
77
|
-
|
|
78
|
-
From this repo:
|
|
89
|
+
### Codex plugin
|
|
79
90
|
|
|
80
91
|
```bash
|
|
81
92
|
npx -y wenlan setup
|
|
@@ -83,58 +94,42 @@ codex plugin marketplace add .
|
|
|
83
94
|
codex plugin add wenlan@wenlan-local
|
|
84
95
|
```
|
|
85
96
|
|
|
86
|
-
Start a new Codex thread after installing so the
|
|
97
|
+
Start a new Codex thread after installing so the plugin and MCP server load.
|
|
87
98
|
|
|
88
|
-
|
|
99
|
+
Plugin details and development notes: [plugin-codex/](plugin-codex/README.md).
|
|
89
100
|
|
|
90
|
-
|
|
91
|
-
python3 ~/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py plugin-codex
|
|
92
|
-
codex plugin add wenlan@wenlan-local
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
The plugin runner uses `~/.wenlan/bin/wenlan-mcp` when available and falls back to `npx -y wenlan-mcp@^0.10.0`. It passes `--agent-name codex` so captures are labeled as Codex writes.
|
|
96
|
-
|
|
97
|
-
The shared Claude/Codex plugin inventory lives in [plugin-contract.json](plugin-contract.json). Before changing plugin skills, manifests, MCP runner wiring, or the local marketplace, run:
|
|
101
|
+
<a id="mcp-setup"></a>
|
|
98
102
|
|
|
99
|
-
|
|
100
|
-
python3 scripts/validate-codex-plugin-slice.py
|
|
101
|
-
python3 scripts/validate-plugin-contract.py
|
|
102
|
-
bash scripts/validate-plugin-contract.test.sh
|
|
103
|
-
```
|
|
103
|
+
### MCP setup
|
|
104
104
|
|
|
105
|
-
|
|
105
|
+
Both plugins call the same local MCP server under the hood. The core tools are `context`, `capture`, `recall`, `pages`, and `doctor`.
|
|
106
106
|
|
|
107
|
-
Use this if you want Wenlan tools in Claude Code without the plugin, or in Codex
|
|
107
|
+
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
108
|
|
|
109
109
|
```bash
|
|
110
110
|
npx -y wenlan setup
|
|
111
|
-
|
|
111
|
+
wenlan connect claude-code # or: codex, cursor, claude-desktop, vscode, gemini
|
|
112
112
|
```
|
|
113
113
|
|
|
114
|
-
MCP-only
|
|
114
|
+
MCP-only clients use the same core tools for context, capture, recall, doctor checks, and page distillation.
|
|
115
115
|
|
|
116
|
-
###
|
|
116
|
+
### CLI
|
|
117
117
|
|
|
118
|
-
Set up
|
|
118
|
+
Set up Wenlan once:
|
|
119
119
|
|
|
120
120
|
```bash
|
|
121
121
|
npx -y wenlan setup
|
|
122
122
|
```
|
|
123
123
|
|
|
124
|
-
Then
|
|
125
|
-
|
|
126
|
-
Service management:
|
|
124
|
+
Then use the CLI directly:
|
|
127
125
|
|
|
128
126
|
```bash
|
|
129
|
-
wenlan background on # register + start the background runtime
|
|
130
|
-
wenlan restart # stop + start the background runtime after upgrading
|
|
131
127
|
wenlan status
|
|
132
|
-
wenlan
|
|
128
|
+
wenlan recall <query>
|
|
129
|
+
wenlan capture <text>
|
|
133
130
|
```
|
|
134
131
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
---
|
|
132
|
+
CLI details: [crates/wenlan-cli](crates/wenlan-cli/README.md).
|
|
138
133
|
|
|
139
134
|
## How Wenlan works
|
|
140
135
|
|
|
@@ -173,41 +168,21 @@ Works fully local with no API key, cloud account, or signup. Capture, recall, hy
|
|
|
173
168
|
|
|
174
169
|
## What you get
|
|
175
170
|
|
|
176
|
-
- **
|
|
171
|
+
- **Typed captures**: every capture is stored with source agent, confidence, stability, and supersession metadata.
|
|
177
172
|
- **Source-backed pages**: pages keep source memory IDs, stale reasons, and revision state so distillation can refresh them without losing provenance.
|
|
178
173
|
- **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
174
|
- **Connected recall**: people, projects, tools, and decisions come back linked, so a memory arrives with the context around it instead of alone.
|
|
180
175
|
- **Distill cycles**: run `/distill` manually today, or add a local model/API key for background extraction, page refreshes, recaps, and richer graph links.
|
|
181
|
-
- **
|
|
176
|
+
- **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
177
|
- **Review before trust**: low-confidence captures, pending revisions, contradictions, and supersessions can surface instead of silently entering context.
|
|
183
178
|
- **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
179
|
- **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
180
|
|
|
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
181
|
---
|
|
205
182
|
|
|
206
183
|
## Evaluation
|
|
207
184
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
Update workflow and answer-quality snapshots live in [docs/eval](docs/eval/README.md).
|
|
185
|
+
Retrieval-only snapshot, not end-to-end answer quality. Method and update workflow live in [docs/eval](docs/eval/README.md).
|
|
211
186
|
|
|
212
187
|
|
|
213
188
|
<!-- EVAL_SNAPSHOT_START -->
|
|
@@ -219,26 +194,6 @@ Update workflow and answer-quality snapshots live in [docs/eval](docs/eval/READM
|
|
|
219
194
|
|
|
220
195
|
---
|
|
221
196
|
|
|
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
197
|
## Build from source
|
|
243
198
|
|
|
244
199
|
Wenlan builds natively on macOS (Apple Silicon + Intel), Linux (x86_64 + ARM64; glibc), and Windows (x86_64). The npm wrapper (`wenlan`, `wenlan-mcp`) and `install.sh` auto-detect your platform and pull the matching prebuilt release. Most users should install through the Claude Code plugin or `npx`. For local development:
|
|
@@ -256,24 +211,24 @@ Build details for the daemon, MCP server, CLI, and core crates live in the crate
|
|
|
256
211
|
|
|
257
212
|
## Learn more
|
|
258
213
|
|
|
259
|
-
Longer-form writing on AI work memory and how Wenlan compares lives at [
|
|
214
|
+
Longer-form writing on AI work memory and how Wenlan compares lives at [wenlan.app/learn](https://wenlan.app/learn):
|
|
260
215
|
|
|
261
216
|
**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://
|
|
217
|
+
- [What is AI work memory?](https://wenlan.app/learn/ai-work-memory): the shape of the problem Wenlan solves
|
|
218
|
+
- [MCP memory server](https://wenlan.app/learn/mcp-memory-server): how Wenlan exposes memory through the Model Context Protocol
|
|
219
|
+
- [Local-first AI memory](https://wenlan.app/learn/local-first-ai-memory): data, privacy, and control
|
|
220
|
+
- [Markdown + local index](https://wenlan.app/learn/markdown-local-index-ai-memory): the storage model
|
|
221
|
+
- [AI agent handoff loop](https://wenlan.app/learn/ai-agent-handoff-loop): session-end discipline that prevents context loss
|
|
267
222
|
|
|
268
223
|
**Comparisons**
|
|
269
|
-
- [Wenlan vs Basic Memory](https://
|
|
270
|
-
- [Wenlan vs claude-mem](https://
|
|
271
|
-
- [Wenlan vs Superlocal Memory](https://
|
|
224
|
+
- [Wenlan vs Basic Memory](https://wenlan.app/learn/origin-vs-basic-memory): Markdown knowledge base vs AI work-session memory
|
|
225
|
+
- [Wenlan vs claude-mem](https://wenlan.app/learn/origin-vs-claude-mem): observer-style Claude Code memory vs MCP-first cross-tool memory
|
|
226
|
+
- [Wenlan vs Superlocal Memory](https://wenlan.app/learn/origin-vs-superlocal-memory): tradeoffs against another local memory shape
|
|
272
227
|
|
|
273
228
|
**Docs**
|
|
274
|
-
- [Get started](https://
|
|
275
|
-
- [Daily workflow](https://
|
|
276
|
-
- [MCP clients](https://
|
|
229
|
+
- [Get started](https://wenlan.app/docs/get-started): install + verify the first local memory loop
|
|
230
|
+
- [Daily workflow](https://wenlan.app/docs/daily-workflow): capture, handoff, distill
|
|
231
|
+
- [MCP clients](https://wenlan.app/docs/mcp-clients): connect Claude Code, Cursor, Codex, Claude Desktop, Gemini CLI
|
|
277
232
|
|
|
278
233
|
---
|
|
279
234
|
|