{"id":51222985,"url":"https://github.com/7xuanlu/wenlan","last_synced_at":"2026-07-01T04:00:34.879Z","repository":{"id":352508344,"uuid":"1215417088","full_name":"7xuanlu/wenlan","owner":"7xuanlu","description":"Wenlan (文瀾) is a personal knowledge base for the AI-native age. Your AI agents capture what they learn, Wenlan keeps it current and distills it into source-cited wiki pages you can trust","archived":false,"fork":false,"pushed_at":"2026-07-01T01:04:46.000Z","size":71651,"stargazers_count":47,"open_issues_count":4,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-01T01:17:04.038Z","etag":null,"topics":["ai-memory","claude","claude-code","claude-code-plugin","codex","git","knowledge-base","knowledge-graph","llm-wiki","local-first","mcp","mcp-server","rust","second-brain","self-evolving"],"latest_commit_sha":null,"homepage":"https://useorigin.app","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/7xuanlu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-19T22:07:06.000Z","updated_at":"2026-07-01T01:04:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/7xuanlu/wenlan","commit_stats":null,"previous_names":["7xuanlu/origin","7xuanlu/wenlan"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/7xuanlu/wenlan","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7xuanlu%2Fwenlan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7xuanlu%2Fwenlan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7xuanlu%2Fwenlan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7xuanlu%2Fwenlan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/7xuanlu","download_url":"https://codeload.github.com/7xuanlu/wenlan/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7xuanlu%2Fwenlan/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34992071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-memory","claude","claude-code","claude-code-plugin","codex","git","knowledge-base","knowledge-graph","llm-wiki","local-first","mcp","mcp-server","rust","second-brain","self-evolving"],"created_at":"2026-06-28T09:00:31.116Z","updated_at":"2026-07-01T04:00:34.861Z","avatar_url":"https://github.com/7xuanlu.png","language":"Rust","funding_links":[],"categories":["Source Catalog"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/assets/social-preview.png\" alt=\"Wenlan: a living personal knowledge library for the AI-native age.\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n[![CI](https://github.com/7xuanlu/wenlan/actions/workflows/ci.yml/badge.svg?branch=main\u0026event=push)](https://github.com/7xuanlu/wenlan/actions/workflows/ci.yml?query=branch%3Amain)\n[![Release](https://img.shields.io/github/v/release/7xuanlu/wenlan?sort=semver)](https://github.com/7xuanlu/wenlan/releases/latest)\n[![npm: wenlan](https://img.shields.io/npm/v/wenlan?label=wenlan)](https://www.npmjs.com/package/wenlan)\n[![npm: wenlan-mcp](https://img.shields.io/npm/v/wenlan-mcp?label=wenlan-mcp)](https://www.npmjs.com/package/wenlan-mcp)\n[![MCP Server](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](#license)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"macOS\" src=\"https://img.shields.io/badge/macOS-arm64%20%7C%20x64-A2AAAD?logo=apple\u0026logoColor=white\"\u003e\n  \u003cimg alt=\"Linux\" src=\"https://img.shields.io/badge/Linux-x64%20%7C%20arm64-FCC624?logo=linux\u0026logoColor=black\"\u003e\n  \u003cimg alt=\"Windows\" src=\"https://img.shields.io/badge/Windows-x64-0078D6?logo=windows\u0026logoColor=white\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#claude-code-in-30-seconds\"\u003e\u003cimg alt=\"Claude Code\" src=\"https://img.shields.io/badge/Claude%20Code-plugin-5D4E75\"\u003e\u003c/a\u003e\n  \u003ca href=\"#mcp-only-setup\"\u003e\u003cimg alt=\"OpenAI Codex\" src=\"https://img.shields.io/badge/OpenAI%20Codex-MCP-111827\"\u003e\u003c/a\u003e\n  \u003ca href=\"#mcp-only-setup\"\u003e\u003cimg alt=\"Cursor\" src=\"https://img.shields.io/badge/Cursor-MCP-111111\"\u003e\u003c/a\u003e\n  \u003ca href=\"#mcp-only-setup\"\u003e\u003cimg alt=\"VS Code\" src=\"https://img.shields.io/badge/VS%20Code-MCP-007ACC\"\u003e\u003c/a\u003e\n  \u003ca href=\"#mcp-only-setup\"\u003e\u003cimg alt=\"Claude Desktop\" src=\"https://img.shields.io/badge/Claude%20Desktop-MCP-D97757\"\u003e\u003c/a\u003e\n  \u003ca href=\"#mcp-only-setup\"\u003e\u003cimg alt=\"Gemini CLI\" src=\"https://img.shields.io/badge/Gemini%20CLI-MCP-4285F4\"\u003e\u003c/a\u003e\n  \u003ca href=\"#what-you-get\"\u003e\u003cimg alt=\"Obsidian\" src=\"https://img.shields.io/badge/Obsidian-Markdown%20pages-7C3AED\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  English | \u003ca href=\"./README.zh-Hans.md\"\u003e简体中文\u003c/a\u003e | \u003ca href=\"./README.zh-Hant.md\"\u003e繁體中文\u003c/a\u003e\n\u003c/p\u003e\n\n**A living personal knowledge library for the AI-native age, built by your agents and grounded in its sources.**\n\nWenlan (文瀾) takes its name from an imperial library that held one of China's largest book collections. Your agents capture what they learn as they work, and you add the pages and sources you already trust, so the library grows from the bottom up and the top down. Wenlan keeps it current on its own, distilling both into source-cited wiki pages.\n\nEach session opens with a brief and closes with a handoff, so the thread carries forward instead of restarting.\n\nUnlike a static llm-wiki, it keeps evolving between sessions. Unlike a black-box memory, every page shows its sources, so you can read, trust, or correct it.\n\n[![Watch the Wenlan demo](./docs/assets/demo-preview.gif)](https://youtu.be/k37gjWVPHwI)\n\n---\n\n## What makes Wenlan distinct\n\n1. **Trustworthy on its own.** Every page cites the memories it came from, and the daemon refuses unsourced pages rather than letting hallucinated summaries in. It dedupes facts and supersedes the old version when one changes, so you read a clean, current wiki instead of a pile of duplicates. The everyday flow never stops for approval; a capture only surfaces for you when something genuinely conflicts.\n2. **Evolves on its own.** Most memory tools just hand back what you put in. Wenlan keeps working between sessions, clustering your captures into source-cited wiki pages that feed retrieval alongside the atomic notes they came from. Unlike a static llm-wiki, it stays current without you maintaining it.\n3. **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.\n4. **Real git versioning.** Memory, page, and session writes commit into `~/.wenlan/.git/`, so you can inspect, diff, revert, or branch the Markdown artifacts.\n   ```text\n   a1b2c3d page: embedding-retrieval refreshed (4 sources)\n   9f8e7d6 session: handoff embedding-work\n   5a4b3c2 capture: decision mem_abc123\n   ```\n\n---\n\n## Quickstart\n\n### Claude Code in 30 seconds\n\n```text\n/plugin marketplace add 7xuanlu/claude-plugins\n/plugin install wenlan@7xuanlu\n/init\n```\n\nIf Claude Code asks for a restart after installing, restart once, then run `/init`. The plugin handles daemon setup, MCP wiring, local memory setup, and the first round-trip check.\n\nThen try `/brief`, `/capture \u003cdecision\u003e`, or `/handoff` inside Claude Code.\n\nPlugin details and daily commands: [plugin/](plugin/.claude-plugin/README.md).\n\n### MCP-only setup\n\nUse this if you want Wenlan tools in Claude Code without the plugin, or in Codex, Cursor, Claude Desktop, VS Code, or Gemini CLI.\n\n```bash\nnpx -y wenlan setup\n~/.wenlan/bin/wenlan mcp add claude-code      # or: codex, cursor, claude-desktop, vscode, gemini\n```\n\nMCP-only gives agents tools for capture, recall, context, doctor, and page distillation. It does not install Claude Code slash skills like `/brief`, `/handoff`, `/distill`, or `/init`.\n\n### Terminal runtime setup\n\nSet up the local Wenlan runtime:\n\n```bash\nnpx -y wenlan setup\n```\n\nThen start with `~/.wenlan/bin/wenlan status`, `~/.wenlan/bin/wenlan recall \u003cquery\u003e`, or `~/.wenlan/bin/wenlan store \u003ctext\u003e`. CLI details: [crates/wenlan-cli](crates/wenlan-cli/README.md).\n\nService management:\n\n```bash\nwenlan install            # register + start the daemon (stops a running one first)\nwenlan restart            # stop + start the daemon -- run this after upgrading\nwenlan status\nwenlan uninstall\n```\n\nAfter upgrading Wenlan (`npx -y wenlan setup` or `install.sh`), the new binary is on disk but the already-running daemon keeps serving the old code until you restart it. `wenlan install` now restarts automatically; if you upgraded another way, run `wenlan restart`.\n\n---\n\n## How Wenlan works\n\nThe same loop runs every session: capture while you work, let the daemon refine between sessions, and return with the knowledge already in context.\n\n```text\n      ┌──────── loops back · /handoff closes each pass ─────────┐\n      ▼                                                         │\n┌─────┴─────┐    ┌─────────────┐    ┌────────────────┐    ┌─────┴─────┐\n│ CAPTURE   │    │ DAEMON      │    │ ONE STORE      │    │ RECALL +  │\n│  in flow  │ ─▶ │  refines    │ ─▶ │  (local)       │ ─▶ │  BRIEF    │\n│  /capture │    │  between    │    │  · memories    │    │  next     │\n│           │    │  sessions   │    │  · wiki pages  │    │  session  │\n│           │    │  dedup·link │    │  · graph       │    │  /recall  │\n│           │    │  /distill   │    │                │    │  /brief   │\n└───────────┘    └─────────────┘    └────────────────┘    └───────────┘\n   one local daemon · one store · every MCP client reads it\n   Claude Code · Cursor · Codex · Claude Desktop · VS Code · Gemini\n```\n\nEach pass leaves the store sharper. Captures that would sit as loose snippets elsewhere get deduped, linked to the people and projects they touch, and distilled into source-citing pages, so the next session brings back knowledge, not raw history. That is the compounding the loop is named for.\n\nThese five verbs drive it:\n\n1. **Session starts.** `/brief [topic]` loads project status, identity, preferences, and topic-relevant memories so the agent walks in with context.\n2. **During work.** `/capture \u003cthing\u003e` saves a decision, lesson, gotcha, or project fact in flow. `/recall \u003cquery\u003e` looks anything up.\n3. **Session ends.** `/handoff` writes what changed, what's still open, and where to continue, so the next run picks up cleanly.\n4. **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.\n5. **Next session.** `/brief` brings it back in the Claude Code plugin; 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.\n\nFull skill reference: [plugin/skills](plugin/skills/README.md).\n\nWorks fully local with no API key, cloud account, or signup. Capture, recall, hybrid search, and graph context need nothing external; add a local model or API key only for automatic page distillation. No telemetry.\n\n---\n\n## What you get\n\n- **Atomic memory layer**: every capture is stored first as a typed memory with source agent, confidence, stability, and supersession metadata.\n- **Source-backed pages**: pages keep source memory IDs, stale reasons, and revision state so distillation can refresh them without losing provenance.\n- **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.\n- **Connected recall**: people, projects, tools, and decisions come back linked, so a memory arrives with the context around it instead of alone.\n- **Distill cycles**: run `/distill` manually today, or add a local model/API key for background extraction, page refreshes, recaps, and richer graph links.\n- **Stays fresh on its own**: 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.\n- **Review before trust**: low-confidence captures, pending revisions, contradictions, and supersessions can surface instead of silently entering context.\n- **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.\n- **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.\n\n### Spaces\n\nMemories belong to a **space** like `wenlan`, `career`, or\n`ideas`. Set the active space per shell:\n\n    WENLAN_SPACE=career claude\n\nOr declaratively via `~/.wenlan/spaces.toml` (see\n`plugin/examples/spaces.toml`). To manage spaces from the CLI:\n\n    wenlan space list\n    wenlan space add ideas --default\n    wenlan space show ideas\n    wenlan space move scratch career\n\n`wenlan doctor` prints the current resolver state so you can see exactly\nwhich layer chose the active space.\n\n---\n\n## Evaluation\n\n**Hybrid retrieval, transparent eval.** BGE-Base-EN-v1.5-Q + FTS5 + Reciprocal Rank Fusion; local BGE-Reranker-Base cross-encoder rerank is the default path when enabled, with BGE-Reranker-V2-M3 available as a higher-quality option. The retrieval table is not end-to-end answer quality. ~168 tokens per recall query. Eval harness at [`crates/wenlan-core/src/eval/`](crates/wenlan-core/src/eval/). Run it yourself.\n\nUpdate workflow and answer-quality snapshots live in [docs/eval](docs/eval/README.md).\n\n\n\u003c!-- EVAL_SNAPSHOT_START --\u003e\n| Benchmark | Recall@5 | MRR | NDCG@10 |\n|---|---:|---:|---:|\n| LME_Oracle (500 Q) | 93.6% | 0.857 | 0.883 |\n| LME_S (deep, 90 Q) | 87.7% | 0.815 | 0.822 |\n\u003c!-- EVAL_SNAPSHOT_END --\u003e\n\n---\n\n## Repo Map\n\nWenlan 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.\n\n\n| Path                                                   | What lives there                                                                                                                                                                                           |\n| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [crates/wenlan-core](crates/wenlan-core/README.md)     | Storage, search, embeddings, distill cycles, graph, pages, export, eval.                                                                                                                                   |\n| [crates/wenlan-server](crates/wenlan-server/README.md) | Local daemon and HTTP API.                                                                                                                                                                                 |\n| [crates/wenlan-mcp](crates/wenlan-mcp/README.md)       | MCP server, tools, npm package.                                                                                                                                                                            |\n| [crates/wenlan-cli](crates/wenlan-cli/README.md)       | User CLI for setup, service management, search, recall, store, list, agents, model/key setup, and doctor.                                                                                                  |\n| [plugin/](plugin/.claude-plugin/README.md)             | Claude Code plugin (`plugin.json`, skills, hooks, `.mcp.json`).                                                                                                                                           |\n| [docs/eval](docs/eval/README.md)                       | Benchmark workflow and methodology.                                                                                                                                                                        |\n\n\nFull contributor map: [CLAUDE.md](CLAUDE.md).\n\n---\n\n## Build from source\n\nWenlan 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:\n\n```bash\ngit clone https://github.com/7xuanlu/wenlan.git\ncd wenlan\ncargo build --workspace\ncargo run -p wenlan-server\n```\n\nBuild details for the daemon, MCP server, CLI, and core crates live in the crate READMEs linked above. Cross-platform specifics (service registration, paths, Windows install limitation) live in [AGENTS.md](AGENTS.md#cross-platform).\n\n---\n\n## Learn more\n\nLonger-form writing on AI work memory and how Wenlan compares lives at [useorigin.app/learn](https://useorigin.app/learn):\n\n**Concepts**\n- [What is AI work memory?](https://useorigin.app/learn/ai-work-memory): the shape of the problem Wenlan solves\n- [MCP memory server](https://useorigin.app/learn/mcp-memory-server): how Wenlan exposes memory through the Model Context Protocol\n- [Local-first AI memory](https://useorigin.app/learn/local-first-ai-memory): data, privacy, and control\n- [Markdown + local index](https://useorigin.app/learn/markdown-local-index-ai-memory): the storage model\n- [AI agent handoff loop](https://useorigin.app/learn/ai-agent-handoff-loop): session-end discipline that prevents context loss\n\n**Comparisons**\n- [Wenlan vs Basic Memory](https://useorigin.app/learn/origin-vs-basic-memory): Markdown knowledge base vs AI work-session memory\n- [Wenlan vs claude-mem](https://useorigin.app/learn/origin-vs-claude-mem): observer-style Claude Code memory vs MCP-first cross-tool memory\n- [Wenlan vs Superlocal Memory](https://useorigin.app/learn/origin-vs-superlocal-memory): tradeoffs against another local memory shape\n\n**Docs**\n- [Get started](https://useorigin.app/docs/get-started): install + verify the first local memory loop\n- [Daily workflow](https://useorigin.app/docs/daily-workflow): capture, handoff, distill\n- [MCP clients](https://useorigin.app/docs/mcp-clients): connect Claude Code, Cursor, Codex, Claude Desktop, Gemini CLI\n\n---\n\n## What Wenlan is NOT\n\n- **Not a Life OS.** No habits, calendar, journal, or life-management modules. Wenlan scopes to AI work artifacts only. If you want a full personal OS, look at [PAI](https://github.com/danielmiessler/PAI).\n- **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.\n- **Not a memory infrastructure SDK.** For people using AI daily, not as a backend for other apps building memory features.\n- **Not for one-off chats.** Best when work spans sessions, projects, and weeks.\n\n---\n\n## Contributing\n\nBug fixes, eval cases, docs, and features are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md). Architecture and development rules are in [CLAUDE.md](CLAUDE.md). Security reports: [SECURITY.md](SECURITY.md). Please also read the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n---\n\n## License\n\nWenlan is licensed under **Apache-2.0**. This includes the local runtime, CLI, MCP server, shared types, and Claude Code plugin files in this repo.\n\nThe permissive license keeps the daemon boundary usable for MCP clients and downstream local tools.\n\n---\n\n## Acknowledgments\n\nPredecessors:\n\n- [Karpathy's LLM-wiki note](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Raw-to-wiki distillation pattern.\n- Claude Code's `MEMORY.md`. The simplest version of the idea.\n\nPeers:\n\n- [agentmemory](https://github.com/rohitg00/agentmemory). Agent-side memory framework.\n- [basic-memory](https://github.com/basicmachines-co/basic-memory). Local-first knowledge management for Claude.\n- [obsidian-mind](https://github.com/breferrari/obsidian-mind). Obsidian-native memory and review loop for coding agents.\n- [pro-workflow](https://github.com/rohitg00/pro-workflow). Claude Code productivity suite.\n- [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service). Memory service for MCP.\n- [Memoria](https://github.com/matrixorigin/Memoria). \"Git for AI Agent Memory\" via Copy-on-Write.\n- [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.\n\nDifferent shapes of the same problem. Try the one that fits.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7xuanlu%2Fwenlan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F7xuanlu%2Fwenlan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7xuanlu%2Fwenlan/lists"}