1. 项目概述从沉睡的对话记录到可搜索的知识库如果你和我一样每天花大量时间与Claude Code、Cursor、GitHub Copilot这类AI编程助手对话那你一定也积攒了成百上千个.jsonl格式的会话文件。它们静静地躺在~/.claude/projects/或~/.cursor/workspaceS…这样的目录里记录了你每一次调试、每一次架构设计、每一次代码审查的完整思考过程。这些文件是宝贵的知识资产但现实是我们几乎从不回头去看它们——格式原始、分散各处、难以检索让这些“数字记忆”成了被遗忘的角落。Pratiyush的llm-wiki项目正是为了解决这个痛点而生。它不是一个简单的文件转换器而是一个完整的、本地优先的个人知识库构建系统。其核心思想是借鉴了AI领域知名研究者Andrej Karpathy提出的“LLM Wiki”模式将你与各种AI助手Claude Code, Codex CLI, Cursor, Gemini CLI, Copilot的原始对话记录以及你在Obsidian中的笔记自动转化、清洗、链接最终生成一个结构清晰、可全文搜索、支持双向链接的静态网站。这个网站既是给你自己看的“第二大脑”可视化界面也贴心地为其他AI Agent准备了纯文本、JSON-LD图谱等机器可读的格式方便你直接将这些知识喂给新的AI会话。简单来说它做了三件事聚合把你散落各处的对话记录收集起来、提纯转换成干净、可读的Markdown并自动脱敏、赋能构建成可交互、可查询的网站和知识图谱。整个过程完全在本地运行无需联网你的代码、API密钥、内部项目名称等敏感信息在转换的第一步就被安全地替换掉了。2. 核心架构与设计哲学拆解2.1 三层架构从原始数据到智慧结晶llm-wiki严格遵循Karpathy提出的三层知识管理架构每一层都有明确的职责和不可变性规则确保了系统的健壮性和可追溯性。第一层原始源文件 (raw/)这是系统的基石存放着从各个适配器Adapter转换而来的、不可变的Markdown文件。每个文件对应一次完整的AI会话命名规则如2024-04-08-build-llmwiki-cli.md。这一层是“事实”层任何后续的加工、分析都基于此但绝不修改它。这种不可变性设计至关重要它保证了无论上层的wiki如何迭代你总能回溯到最原始的对话记录。第二层维基知识库 (wiki/)这是由AI或者你手动生成的、结构化的知识层。llm-wiki按照内容类型将原始会话中提及的概念、实体、技术点提取出来分别存放在sources/、entities/、concepts/、syntheses/、comparisons/、questions/等目录下并使用[[双括号]]形式的维基链接将它们有机地连接起来。例如一次关于“用Rust构建Web服务器”的会话可能会生成一个sources/下的会话摘要一个entities/下的Rust.md页面一个concepts/下的Async-Await.md页面并在它们之间建立链接。这一层是“理解”层是知识的再组织。第三层导航与模式文件这是指导AI和你自己如何与这个知识库交互的“元知识”层。核心文件包括CLAUDE.md: 告诉Claude等AI助手这个知识库的结构、约定和如何从中查询信息。AGENTS.md: 更通用的Agent导航指南。MEMORY.md: 通过“Auto Dream”功能自动生成的、经过整合和提炼的长期记忆摘要。各种hints.md、hot.md文件提供当前上下文的“热”知识。这个三层结构清晰地将数据、知识和元知识分离使得整个系统既稳定又富有弹性。2.2 核心设计原则为什么它“好用”作为一个深度使用者我认为llm-wiki的成功离不开以下几个贯穿始终的设计原则1. 标准库优先与离线友好项目的核心运行时依赖只有Python标准库和markdown这个包。像PDF解析(pypdf)这样的功能被设计为可选的“extra”。生成的静态网站不使用任何需要从Google Fonts等外网加载的字体或CSS语法高亮通过CDN引入但设计了优雅降级。这意味着你可以在完全离线的环境中搭建和使用整个知识库这对处理公司内部敏感项目的开发者来说是天大的福音。2. 默认脱敏隐私至上在将原始.jsonl转换为raw/层Markdown时工具会主动进行脱敏处理。它会将你的系统用户名替换为通用的USER并利用正则表达式匹配和移除像sk-开头的API密钥、密码等敏感模式。这个步骤发生在数据进入知识库之前从源头杜绝了信息泄露的风险。服务默认绑定在127.0.0.1不收集任何遥测数据。3. 幂等性与安全性所有核心命令sync,build,lint都被设计为幂等的。这意味着你可以反复执行它们而不会产生重复数据或破坏性结果。例如重复运行llmwiki sync只会处理新增或修改的会话文件。这种设计让你可以放心地将命令加入定时任务或CI/CD流程而不用担心状态混乱。4. 适配器模式与可扩展性系统通过“适配器”(Adapter)来支持不同的数据源。每个适配器如ClaudeCodeAdapter、CursorAdapter负责理解特定工具的会话文件格式和存储路径并将它们统一转换成内部表示。添加对新AI工具的支持理论上只需要实现一个新的适配器类。这种设计使得项目能紧跟AI工具生态的快速发展。5. 人机双格式输出从v0.4版本开始llm-wiki为每个生成的HTML页面都创建了对应的机器可读兄弟文件.txt纯文本版和.json结构化元数据版。此外它还生成站点级的llms.txt遵循llmstxt.org规范、llms-full.txt整个站点的扁平化文本可直接丢给LLM、graph.jsonld知识图谱等。这实现了“一次构建两种消费”的理念让你的知识库既能被人浏览也能被AI直接查询和利用。3. 从零开始完整部署与深度配置指南3.1 环境准备与一键安装部署llm-wiki非常简单它不依赖复杂的服务或数据库。首先将项目克隆到本地git clone https://github.com/Pratiyush/llm-wiki.git cd llm-wiki对于macOS或Linux用户直接运行附带的安装脚本即可。这个脚本会完成所有繁重的工作./setup.sh这个setup.sh脚本具体做了以下几件事理解它们有助于排查可能的问题创建数据目录在项目根目录下创建raw/、wiki/、site/三个核心目录分别对应我们之前讲的三层架构。就地安装Python包以“可编辑”模式(-e)安装llmwiki这个Python包。这意味着你对项目源码的修改会立即反映到安装的包中非常适合开发或自定义。探测并配置适配器脚本会自动扫描你的系统寻找已安装的AI工具如Claude Code、Cursor的配置目录并启用对应的适配器。安装SessionStart钩子可选对于检测到的Claude Code脚本会询问你是否要安装自动同步钩子。如果同意它会在~/.claude/settings.json中添加一个配置使得每次启动Claude Code时自动在后台运行llmwiki sync实现会话的实时收录。执行首次同步运行一次初始的llmwiki sync让你立刻能看到一些输出确认安装成功。对于Windows用户过程类似只需运行setup.bat即可。注意如果你的Python环境管理比较严格例如使用pyenv或conda请确保在运行安装脚本前已经激活了目标Python环境。脚本会使用当前环境的python3和pip3命令。3.2 核心配置文件详解安装完成后首要任务是配置config.json。项目提供了一个示例文件examples/sessions_config.json你需要将其复制到项目根目录并重命名cp examples/sessions_config.json config.json接下来用你喜欢的编辑器打开config.json进行个性化设置。这个文件是控制llm-wiki所有行为的核心理解每个部分至关重要。{ filters: { live_session_minutes: 60, exclude_projects: [temp, scratch] }, redaction: { real_username: 你的系统用户名, replacement_username: USER, extra_patterns: [ (?i)(api[_-]?key|secret|token|bearer|password)\\s*[:]\\s*[\\\][^\\\][\\\], sk-[A-Za-z0-9]{20,}, gh[pous]_[A-Za-z0-9_], xox[baprs]-[A-Za-z0-9-] ] }, truncation: { tool_result_chars: 500, bash_stdout_lines: 5 }, adapters: { obsidian: { vault_paths: [/绝对路径/到/你的/Obsidian仓库] }, claude_code: { auto_sync: true } }, build: { auto_lint: true, theme: dark } }filters.live_session_minutes: 这个参数用于区分“进行中”的会话和“已完成”的会话。默认60分钟意味着如果最后一次修改时间在60分钟内的会话文件会被视为“活跃”会话在同步时可能会被跳过或特殊处理避免打断你正在进行的对话。你可以根据你的工作习惯调整这个值。redaction: 这是安全核心。务必正确设置real_username工具会将其在输出中统一替换为replacement_username。extra_patterns列表允许你添加自定义的正则表达式来匹配和擦除更多类型的敏感信息比如你公司内部特定的令牌格式。truncation: 为了提高可读性过长的工具调用结果如终端输出会被截断。tool_result_chars控制截断的字符数bash_stdout_lines控制Bash命令输出的保留行数。如果你需要查看完整输出可以在生成的页面中点击“展开”按钮。adapters: 在这里配置每个数据源的具体路径。例如如果你有多个Obsidian仓库可以在vault_paths数组中添加多个路径。build.auto_lint: 建议设为true。这样在每次构建站点前会自动运行代码质量检查确保Wiki内的链接有效、没有孤立的页面等。3.3 构建与浏览你的知识库配置完成后构建你的个人知识库就只需要两行命令./build.sh # 执行同步和构建 ./serve.sh # 启动本地服务器build.sh脚本实质上按顺序执行了llmwiki sync同步新会话和llmwiki build构建静态站点。执行完毕后打开浏览器访问http://127.0.0.1:8765你就能看到焕然一新的知识库网站了。网站首页会展示一个类似GitHub贡献图的活动热力图直观反映你与AI协作的活跃周期。所有会话会按项目分组支持全局模糊搜索快捷键CmdK或CtrlK调出命令面板每个会话页面都有完整的对话记录、语法高亮的代码块、可折叠的工具调用结果以及根据内容自动生成的“相关页面”推荐。3.4 高级集成与Obsidian双向同步对于Obsidian重度用户llm-wiki提供了无缝的双向集成体验。这不仅仅是导出文件而是建立一个符号链接让Obsidian可以直接将wiki/目录作为一个库打开。运行以下命令llmwiki link-obsidian该命令会提示你选择目标Obsidian仓库路径然后在其中创建一个指向llm-wiki项目wiki/目录的符号链接在Windows上可能是目录连接。之后你就可以在Obsidian中享受完整的图谱视图、反向链接、Dataview查询等所有强大功能了。llm-wiki甚至为Obsidian准备了开箱即用的Dataview查询模板和Templater模板帮助你快速生成周报、查找高置信度的页面或列出所有待解决的问题。3.5 自动化与持续集成手动运行命令毕竟麻烦llm-wiki提供了多种自动化方案1. 文件监控模式在项目根目录下运行llmwiki watch这将启动一个守护进程监控你所配置的所有适配器目录如~/.claude/projects/。一旦检测到新的.jsonl文件变化有防抖机制避免过于频繁触发就会自动执行llmwiki sync。这是最“无感”的同步方式。2. 计划任务对于希望定期如每天凌晨同步的用户可以使用llmwiki schedule命令来生成操作系统级别的计划任务文件。llmwiki schedule --platform macos --cadence daily --hour 2这条命令会生成一个macOS的launchdplist文件指导你在每天凌晨2点运行同步。类似地也支持Linux的systemd和Windows的“任务计划程序”。3. CI/CD集成你可以将llm-wiki的构建步骤集成到GitHub Actions、GitLab CI等持续集成流程中。这样每次向存放wiki/内容的Git仓库推送更新时CI会自动构建静态站点并部署到GitHub Pages、GitLab Pages或任何静态托管服务上。项目仓库中的.github/workflows/pages.yml就是一个现成的GitHub Pages部署范例。4. 核心工作流与实战技巧4.1 日常使用查询、审查与维护知识库建好了关键在于日常使用和维护。llm-wiki提供了强大的命令行工具来辅助你。快速检索信息当你记不清之前是如何解决某个特定错误时不再需要翻找聊天历史。使用llmwiki内置的搜索功能或者直接使用MCP服务器查询# 通过CLI搜索 llmwiki search ModuleNotFoundError # 或者如果你配置了MCP服务器可以在Claude Desktop等客户端直接问“在我的知识库里查一下之前是怎么解决ModuleNotFoundError的”MCP服务器的wiki_query工具会返回最相关的几个页面片段节省大量时间。定期质量检查就像代码需要lint一样知识库也需要定期维护。运行llmwiki lint会执行一系列检查结构检查是否有页面缺少必要的前言frontmatter内部维基链接是否指向了不存在的页面逻辑检查LLM驱动利用AI检查内容中是否存在事实矛盾、需要验证的断言或摘要是否准确反映了原文。生命周期管理自动标记超过90天未更新的页面为“陈旧”(stale)。我个人的习惯是每周运行一次llmwiki lint并根据报告清理或更新内容。项目还提供了llmwiki eval命令可以从“完整性”、“新鲜度”、“引用密度”等7个维度给你的知识库页面打个质量分百分制帮你快速定位需要加强的页面。利用“Auto Dream”整合记忆这是v1.0版本一个非常酷的功能。llm-wiki会监控你的编辑活动如果发现你在24小时内在同一主题下创建或修改了超过5个页面它会自动触发一个后台任务生成一个名为MEMORY.md的整合摘要。这个摘要会提炼核心结论、解决相对日期如“昨天提到的那个函数”、修剪过时的信息并将长度控制在200行以内。这相当于一个自动的、定期的知识消化和巩固过程。4.2 为AI Agent提供上下文llm-wiki生成的知识库其终极价值之一是作为超级上下文直接喂给你正在使用的AI编程助手。方法一直接引用文件在Claude Code或Cursor中开始一个新会话时你可以直接将某个会话的.txt兄弟文件拖入聊天窗口或者使用/wiki-read这样的预设指令如果配置了相关技能来引入特定页面的内容。这为你提供了无与伦比的上下文连续性。方法二使用llms-full.txt对于需要最广泛背景知识的任务比如规划一个全新模块的架构你可以将整个site/llms-full.txt文件它包含了所有页面的扁平化文本作为初始上下文提供给AI。虽然这会消耗大量token但对于需要深刻理解你整个技术栈和过往决策的任务来说是值得的。方法三配置技能(Skills)llmwiki install-skills命令可以将项目预置的查询技能位于.claude/skills/目录下镜像到其他AI工具的配置目录中如.codex/skills/。安装后你就可以在相应的AI工具中使用诸如/wiki-search、/wiki-sync这样的快捷命令与你的知识库无缝交互。4.3 故障排除与常见问题在实际使用中你可能会遇到一些典型问题。以下是我的排查清单问题1同步(sync)后看不到新会话。检查配置路径首先确认config.json中适配器的路径是否正确。特别是macOS上的Cursor其会话存储路径比较深例如~/Library/Application Support/Cursor/User/workspaceStorage/。检查文件权限确保llm-wiki有权限读取源.jsonl文件。查看日志运行llmwiki sync -vverbose模式查看详细输出看是否有错误或跳过文件的提示。确认会话已结束llm-wiki默认只会处理修改时间在live_session_minutes默认60分钟之前的文件以避免捕获未完成的会话。如果你刚结束一个对话就想同步可以临时调小这个值或者使用llmwiki sync --force。问题2构建(build)失败提示Markdown解析错误。最常见原因wiki/目录下的某个Markdown文件包含了不合规的YAML frontmatter前言。比如YAML中使用了:但未加引号或者缩进不一致。解决方案运行llmwiki lint它通常会指出具体是哪个文件出了问题。仔细检查该文件开头---之间的部分确保是合法的YAML。问题3生成的网站样式错乱或搜索不工作。清除缓存首先尝试删除site/目录然后重新运行llmwiki build。有时旧的静态资源缓存会导致问题。检查控制台在浏览器中打开开发者工具(Console)查看是否有JavaScript加载错误。可能是本地服务阻止了从CDN加载highlight.js。验证搜索索引构建过程会生成site/search-index.json。检查这个文件是否存在且内容非空。如果文件损坏删除它并重新构建。问题4Obsidian中看不到双向链接图谱。确认链接方式llmwiki link-obsidian创建的是符号链接。在Obsidian中你需要确保“设置 - 文件与链接 - 检测所有类型的文件扩展名”是开启的并且“确认文件名”中包含了.md。重启Obsidian有时Obsidian需要重启才能识别新添加的库。检查路径确保符号链接创建在了正确的Obsidian仓库子目录下并且你有该目录的读写权限。5. 扩展与定制让工具更贴合你的工作流5.1 编写自定义适配器虽然llm-wiki已经支持了主流的AI工具但如果你使用一些小众或自研的工具可能需要自己编写适配器。好消息是框架设计得非常清晰。一个最基本的适配器只需要继承BaseAdapter类并实现几个核心方法# 假设我们为“MyAITool”编写适配器保存为 llmwiki/adapters/my_ai_tool.py from llmwiki.adapters.base import BaseAdapter, Session class MyAIToolAdapter(BaseAdapter): # 标识这个适配器支持的原始数据模式版本 SUPPORTED_SCHEMA_VERSIONS {myaitool-v1} classmethod def is_available(cls): 检查MyAITool是否安装在系统上 # 例如检查特定的配置文件或目录是否存在 return (Path.home() / .myaitool / sessions).exists() classmethod def find_session_files(cls, config): 查找所有会话文件 sessions_dir Path.home() / .myaitool / sessions for jsonl_file in sessions_dir.glob(**/*.jsonl): yield jsonl_file classmethod def parse_session(cls, filepath, config): 将MyAITool的.jsonl文件解析为内部的Session对象 with open(filepath, r, encodingutf-8) as f: lines f.readlines() messages [] for line in lines: data json.loads(line) # 将MyAITool的消息格式转换为llm-wiki内部格式 msg { role: data.get(author), # 例如 user 或 assistant content: data.get(text), timestamp: data.get(created_at) } messages.append(msg) # 从文件路径或内容中提取项目名 project_name filepath.parent.name return Session( idfilepath.stem, projectproject_name, messagesmessages, adapter_namemy_ai_tool, raw_pathfilepath )编写完成后你需要在llmwiki/adapters/__init__.py中注册这个适配器然后就可以在配置中启用它了。5.2 定制输出样式与功能生成的静态网站样式可以通过修改templates/目录下的Jinja2模板文件来完全定制。例如如果你想在每页底部添加一个自定义的脚注可以编辑templates/base.html。更高级的定制比如添加新的页面类型或修改导航逻辑则需要深入build.py和相关模块。不过在动手之前建议先查阅项目的docs/framework.md和docs/maintainers/ARCHITECTURE.md理解各个模块的职责和边界避免破坏现有的数据流。5.3 与现有笔记系统融合如果你已经有一个庞大的Obsidian或Logseq仓库不想从头开始llm-wiki也考虑到了这一点。你可以直接将llm-wiki的wiki/目录构建在你现有仓库的某个子目录里。然后通过配置config.json中的adapters.obsidian.vault_paths让llm-wiki也去读取你现有的笔记文件将它们一并纳入知识图谱。这样你的AI对话记录和传统笔记就能在一个统一的视图中进行管理和检索实现知识的真正融合。6. 项目治理与贡献指南llm-wiki是一个活跃的开源项目拥有完善的贡献者指南和自动化治理流程。如果你在使用中发现了bug或者有很棒的新功能想法非常鼓励你参与贡献。贡献流程简述Fork Clone: Fork官方仓库克隆到本地。创建分支: 为你的修改创建一个描述性的分支如feat/add-new-adapter或fix/search-index-bug。编码与测试: 进行修改并确保通过现有测试。项目有超过2000个单元测试和端到端测试运行pytest tests/可以快速验证。提交信息: 使用规范的提交前缀如feat:、fix:、docs:、chore:、test:。发起拉取请求(PR): 确保PR只解决一个明确的问题并描述清楚变更。通过CI: GitHub Actions会运行完整的测试套件、代码风格检查(lint)和构建验证。所有检查必须通过才能合并。项目维护者使用一套内置的Claude Code技能如/review-pr、/triage-issue来高效处理贡献。详细的规则请阅读仓库根目录下的CONTRIBUTING.md文件。个人使用体会使用llm-wiki大半年它彻底改变了我与AI协作产出的管理方式。最大的收益不是“找到了某段代码”而是建立了知识之间的联系。通过维基链接我发现自己无意中在三个不同的项目中用类似的方法解决了分布式锁的问题这促使我将其抽象成了一个共享库。那个自动生成的活动热力图也像是一个客观的“生产力镜子”让我更清晰地看到自己的技术探索焦点在哪里。它不再是一个被动的存档柜而是一个能主动激发洞察的思维伙伴。如果你也深度使用AI编程助手我强烈建议你花一个小时把它搭起来开始积累你的“可搜索记忆”。