知识库
快来分享你的内容吧～
06-08 12:03·Java后端llm-wiki 不是另一个笔记软件，而是一个面向 AI Agent 时代的本地长期记忆层。查看全文加油鸭：这个开源项目太棒了！把AI会话沉淀为可检索、可维护的本地知识库，思路清晰又实用，为开发者提供了真正可持续的长期记忆方案。737分享
llm-wiki：把 AI 会话沉淀成可长期复用的本地知识库
> 开源地址：[https://github.com/fengguanghuai/llm-wiki](https://github.com/fengguanghuai/llm-wiki) > 关键词：AI Agent、长期记忆、知识库、Claude Code、Codex CLI、Gemini CLI、Markdown、Python CLI ## 一、为什么需要 llm-wiki 过去一段时间，越来越多开发者开始把 Claude Code、Codex CLI、Gemini CLI 等 AI Agent 融入日常研发流程。它们能帮我们读代码、改代码、排查问题、整理文档，甚至在多仓库、多工具链之间协作。 但实际用久了之后，会遇到一个很明显的问题： > AI 会话很多，真正可复用的经验却很容易散落在历史记录里。 比如： - 某个 adapter 当时为什么这样解析会话文件？ - 某次 sync 输出文件为什么发生覆盖，后来是怎么修复的？ - 某个 CLI 命令的参数和目录约定在哪里说明过？ - 某个项目设计决策能不能被不同 AI Agent 共享？ 如果每次都让 AI 从零开始问、从零开始读、从零开始猜，长期来看会浪费大量上下文成本。 `llm-wiki` 的目标就是解决这个问题：**把多个 AI Agent 的会话记录和人工精选笔记，沉淀成一份本地 Markdown 知识库，让它成为可检索、可维护、可迁移、可长期复用的项目记忆。** ## 二、项目简介 `llm-wiki` 是一个本地 Python CLI 工具，命令名是 `pel`。 它可以把 Claude Code、Codex CLI、Gemini CLI 等工具产生的本地会话记录转换为 Markdown，并按照 `raw/`、`wiki/`、`inbox/`、`concepts/`、`entities/` 等目录约定组织起来。 项目特点很克制： - **本地优先**：知识库就是一堆 Markdown 文件，没有数据库绑定。 - **零第三方运行依赖**：Python 3.11+ 标准库实现，不依赖 Node.js、不强制虚拟环境、不需要额外服务。 - **显式沉淀**：不是黑盒自动总结，而是 `capture → inbox → promote` 的可控流程。 - **多 Agent 共享**：Codex、Claude Code 等可以通过同一个 `SKILL.md` 指向同一个 wiki 根目录。 - **可追溯**：原始会话放在 `raw/`，长期结论放在 `wiki/`，修订写入 `log.md`。 一句话概括： > llm-wiki 不是另一个笔记软件，而是一个面向 AI Agent 时代的本地长期记忆层。  ## 三、它解决的核心问题 ### 1. AI 会话历史难复用 AI Agent 的会话记录往往保存在各自工具目录里，比如： - Claude Code：`~/.claude/projects/*/*.jsonl` - Codex CLI：`~/.codex/sessions/`、`~/.codex/archived_sessions/` - Gemini CLI：`~/.gemini/tmp/` 这些文件对工具自己有用，但对人来说并不适合直接阅读，也不方便跨工具检索。 `llm-wiki sync` 会把它们转换成统一的 Markdown： ```bash pel sync ``` 转换后，会话会进入： ```text raw/sessions/<adapter>/ ``` 比如： ```text raw/sessions/claude_code/ raw/sessions/codex_cli/ raw/sessions/gemini_cli/ ``` 这样原始证据就被保留下来了。 ### 2. 原始记录和长期知识混在一起 会话记录很长，里面有命令输出、工具调用、尝试过程、上下文噪音。它们适合作为证据，但不适合作为最终知识。 所以 `llm-wiki` 把知识库分成两层： ```text raw/ # 原始素材，只读证据层 wiki/ # 长期沉淀，可维护知识层 ``` 你可以先把一条结论捕获到 inbox： ```bash pel capture "Claude Code 子会话输出文件名应优先使用源文件 stem，避免多个 agent-*.jsonl 因父 sessionId 相同而互相覆盖。" ``` 再把它提升到长期页面： ```bash pel inbox pel promote <inbox-note> --to memory ``` 也可以提升到不同类型的知识页： ```bash pel promote <inbox-note> --to concept pel promote <inbox-note> --to entity pel promote <inbox-note> --to project pel promote <inbox-note> --to synthesis ``` 这套流程的好处是：**原始材料保留，长期结论可控。** ### 3. 多个 AI Agent 无法共享记忆 很多人会同时使用多个 AI 工具，比如： - Codex 负责代码修改 - Claude Code 负责复杂阅读和重构 - Gemini CLI 用来辅助分析 如果每个工具都有一套自己的历史和记忆，最终会变成“多个孤岛”。 `llm-wiki` 的设计是：所有 Agent 共享一个中心 wiki。 初始化时可以加上： ```bash python -m pelib.cli init --wiki-root "../LLM-WIKI Vault" --title "My LLM Wiki" --link-agents ``` 它会生成共享 skill，并链接到： ```text ~/.codex/skills/llm-wiki ~/.claude/skills/llm-wiki ``` 这样 Codex 和 Claude Code 看到的是同一份知识库，而不是各自复制一份。 ## 四、目录结构设计 初始化后，wiki 根目录大致如下： ```text <wiki_root>/ ├── CLAUDE.md ├── AGENTS.md ├── raw/ │ └── sessions/ ├── wiki/ │ ├── index.md │ ├── MEMORY.md │ ├── log.md │ ├── inbox/ │ ├── concepts/ │ ├── entities/ │ ├── projects/ │ ├── syntheses/ │ └── playbooks/ ├── site/ └── outputs/queries/ ``` 几个核心目录的定位： | 目录 | 作用 | |---|---| | `raw/` | 原始素材和会话转换结果，尽量只读 | | `wiki/MEMORY.md` | 长期记忆的简短结论 | | `wiki/inbox/` | 临时捕获，等待整理 | | `wiki/concepts/` | 可复用概念，例如“Session Adapter 输出命名策略” | | `wiki/entities/` | 实体页，例如某个系统、工具、模型、项目 | | `wiki/projects/` | 项目专题 | | `wiki/syntheses/` | 综合分析和阶段性总结 | | `wiki/log.md` | 操作与修订日志 | 这个结构有一个很重要的原则： > raw 保留证据，wiki 沉淀判断，log 记录变化。 ## 五、快速开始 ### 1. 克隆项目 ```bash git clone https://github.com/fengguanghuai/llm-wiki.git cd llm-wiki ``` ### 2. 初始化知识库 ```bash python -m pelib.cli init --wiki-root "../LLM-WIKI Vault" --title "My LLM Wiki" ``` 如果希望自动为 Codex / Claude Code 创建共享 skill 链接： ```bash python -m pelib.cli init --wiki-root "../LLM-WIKI Vault" --title "My LLM Wiki" --link-agents ``` 在 Windows 上，如果创建符号链接遇到权限限制，可以先不加 `--link-agents`，后续手动配置或以管理员权限处理链接。 ### 3. 查看状态 ```bash python -m pelib.cli status python -m pelib.cli doctor ``` `status` 用来看当前项目指向哪个 wiki 根目录，`doctor` 用来检查必要文件是否存在。 ### 4. 同步历史会话 先 dry-run： ```bash python -m pelib.cli sync --dry-run ``` 确认没有问题后正式同步： ```bash python -m pelib.cli sync ``` 也可以只同步某个 adapter： ```bash python -m pelib.cli sync --adapter claude_code python -m pelib.cli sync --adapter codex_cli python -m pelib.cli sync --adapter gemini_cli ``` ### 5. 捕获和沉淀结论 ```bash python -m pelib.cli capture "这是一条值得长期复用的工程经验" python -m pelib.cli inbox python -m pelib.cli promote <inbox-note> --to memory ``` ### 6. 检索知识库 ```bash python -m pelib.cli query "adapter 输出冲突" python -m pelib.cli query "capture promote" python -m pelib.cli query "旧知识库迁移" ``` ### 7. 修正知识并留痕 如果你手动修改了某个页面，可以追加一条修订记录： ```bash python -m pelib.cli correct "wiki/MEMORY.md" "修正了某条结论的适用范围" ``` ## 六、命令速查 | 命令 | 说明 | |---|---| | `init` | 初始化配置、wiki 骨架和共享 skill | | `status` | 查看项目配置和 Agent 链接状态 | | `doctor` | 检查 wiki 根目录、AGENTS.md、CLAUDE.md、shared skill | | `write-skill` | 重新渲染共享 SKILL.md | | `link-agents` | 将 shared skill 链接到 Codex / Claude Code | | `sync` | 同步本机 AI 会话到 raw/sessions | | `capture` | 捕获一条待整理结论 | | `inbox` | 查看待整理结论 | | `promote` | 将 inbox 内容提升到长期页面 | | `promote-batch` | 批量提升 inbox 内容 | | `query` | 检索长期知识页 | | `correct` | 记录人工修订日志 | | `adapters` | 查看已注册 adapter | ## 七、适合哪些场景 ### 1. 开源项目的设计决策沉淀 比如一个工具项目会持续出现这类问题： - CLI 命令为什么这样设计 - adapter 如何兼容不同工具的会话格式 - raw 和 wiki 两层目录为什么要分开 - Windows 下符号链接失败时如何处理 - 同步时如何避免重复转换和输出覆盖 - 旧知识库迁移时哪些内容应保留 这些内容很多不会自然出现在 README 里，但它们会影响后续维护和贡献者理解。 `llm-wiki` 适合把这些设计背景沉淀下来，后续让 AI 先查项目记忆，再参与代码修改或文档补充。 ### 2. 多 AI 工具协作 如果你同时用 Codex、Claude Code、Gemini CLI，`llm-wiki` 可以作为它们共享的本地记忆层。 一个 Agent 今天沉淀的知识，另一个 Agent 明天可以读取。 ### 3. 需要本地化和可控性的知识库 相比云端知识库，`llm-wiki` 更适合对本地可控性有要求的场景： - Markdown 文件可直接查看 - Git 可版本管理 - Obsidian 等工具可直接打开 - 不绑定某个 SaaS 平台 - 不依赖数据库迁移 ## 八、设计取舍 `llm-wiki` 没有把目标做成“大而全”的知识管理平台，而是选择了几个很明确的取舍。 ### 1. 不做黑盒记忆 它不会偷偷把所有会话总结成某种不可见的向量库，而是把过程暴露出来： ```text capture → inbox → promote ``` 你知道哪些内容被沉淀了，也可以随时修改。 ### 2. 不绑定数据库 知识库就是 Markdown 文件。 这意味着： - 可以直接 grep - 可以用 Git 做版本管理 - 可以用 Obsidian 打开 - 可以被任意 AI Agent 读取 ### 3. 不追求复杂依赖 项目使用 Python 3.11+ 标准库实现，运行依赖尽量保持为零。 这对本地工具很重要：越少依赖，越容易长期维护。 ## 九、一个项目相关案例 下面用 `llm-wiki` 项目本身举一个例子：在重新同步历史会话时，发现 Claude Code 和 Gemini CLI 的部分会话会输出到同一个 Markdown 文件，导致后写入的内容覆盖先写入的内容。 第一步，同步会话： ```bash pel sync ``` 第二步，把问题和修复结论捕获下来： ```bash pel capture "Session adapter 生成输出路径时，不能只依赖事件里的 sessionId；遇到子会话或同 sessionId 多文件时，应优先使用源文件 stem 保证输出唯一。" ``` 第三步，提升为概念页： ```bash pel inbox pel promote <note> --to concept --title "Session Adapter 输出命名策略" ``` 以后再维护同步逻辑时，就可以： ```bash pel query "输出命名策略" ``` 或者让 AI Agent 先读取 `llm-wiki`，再结合当前 adapter 代码和测试做判断。 这样，一次修复就不只是一次提交，而会变成可复用的项目维护知识。 ## 十、当前版本定位 当前项目更像是一个面向开发者和小团队的本地知识库基础设施，重点解决： - 会话历史归档 - 多 Agent 共享记忆 - 显式知识沉淀 - Markdown 化长期维护 - 本地优先和可迁移 它不是为了替代 Obsidian、语雀、Notion 这类笔记工具，而是更偏向于成为 AI Agent 的“工作记忆底座”。 如果你已经在日常研发里大量使用 AI Agent，那么 `llm-wiki` 可以帮你把这些碎片化会话变成长期资产。 ## 十一、总结 AI Agent 能提升单次任务效率，但真正的长期收益来自知识复用。 `llm-wiki` 做的事情很朴素： - 把会话留下来 - 把结论挑出来 - 把知识组织好 - 让不同 Agent 都能读 - 让历史经验能被下一次任务复用 对于经常使用 AI 辅助研发的人来说，这类本地长期记忆工具会越来越重要。 项目地址： [https://github.com/fengguanghuai/llm-wiki](https://github.com/fengguanghuai/llm-wiki) 欢迎试用、提 issue，也欢迎根据自己的工作流改造。
AFFiNE
地址：https://github.com/toeverything/AFFiNE
思源笔记
地址：https://github.com/siyuan-note/siyuan
Tiddlywiki
目前市面上的个人维基系统有很多种，但它们要么体积庞大、界面丑陋，要么搭建步骤复杂、对普通用户不友好，在一番比较后我最终选择了轻量化的 Tiddlywiki。 Tiddlywiki 的拥有丰富的功能和强大的插件，编辑时支持标签管理、条目关联、过滤器，也支持通过插件实现高亮代码、输入数学公式、标准 markdown 语法等等，还能自定义样式。 地址：https://github.com/Jermolene/TiddlyWiki5
开发者知识库
地址：https://www.itdaan.com/index.html
术语在线
地址：https://www.termonline.cn/index
Baklib
在线制作产品手册、帮助中心、FAQ、Guide、知识库、产品介绍、开发文档、在线手册，并发布到网站上。 地址：https://www.baklib.com/
语雀-云端知识库
十万阿里人都在用的笔记与文档知识库，面向企业、组织或个人，提供全新的体系化知识管理，打造轻松流畅的工作协同。金融级数据安全、丰富的应用场景、强大的知识创作与管理，助力企业、个人轻松拥有云端知识库。 语雀，是支付宝内部孵化的一款文档与知识管理工具。语雀使用了“结构化知识库管理”，形式上类似书籍的目录。与其他产品可以随意建立文档不同，语雀上的每一篇文档必须属于某一个知识库，语雀希望通过这样的产品设计，来从源头上帮助用户建立起知识管理的意识，培养良好的知识管理习惯。 地址：https://www.yuque.com/