⁷

llm-wiki：把 AI 会话沉淀成可长期复用的本地知识库

2026-06-08 12:03

阅读1328

2026-06-08 12:03

阅读 1328

开源地址：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

欢迎试用、提 issue，也欢迎根据自己的工作流改造。

问答助学