sessionwiki

sessionwiki

将你的 AI 编码会话整理成可搜索、相互链接的知识库——支持 Claude Code、Codex CLI、Cursor、Gemini CLI、Copilot、ZCode 和 OpenCode。本地优先，配备大模型综合整理、会话图谱和 MCP 服务，让你的 Agent 查找已解决的问题。

👉 在线演示：necroz.github.io/sessionwiki

27 个合成会话，涵盖五个项目和七种 Agent（2026 年 8 月至 11 月）——不含个人数据。每次推送到 master 时，都会根据 examples/demo-sessions/ 重新构建。

---

为什么使用

你使用的每个 Agent 都会将完整会话记录写入磁盘：计划、走过的弯路、修复方案以及背后的推理过程。数百份会话记录，分属五种不同格式，而你再也不会翻看它们。

sessionwiki 将这些历史记录转化为知识库：

• 所有 Agent 集中一处。 Claude Code、Codex CLI、Cursor、Gemini CLI、Copilot、ZCode 和 OpenCode 的会话都会汇入同一个知识库，并按 Agent、项目、模型和日期分类。
• 始终保持最新。 钩子、OpenCode 插件和夜间定时任务会自动保持同步，无需你手动操作。
• 易于阅读。 大模型综合整理会为每个会话生成摘要页面；低价值会话会归入集群页面，避免知识库杂乱。
• 可供你的 Agent 使用。 内置 MCP 服务可让 Claude Code、ZCode 或任何 MCP 客户端在重复解决问题前搜索过往决策。
• 由你掌控。 所有操作都在本地运行；转录内容在导入时会经过脱敏处理，而 sessionwiki audit 会在你发布任何内容前检查输出。

亮点

8 个来源	Claude Code、Codex CLI、Cursor、Gemini CLI、Copilot Chat / CLI、ZCode、OpenCode、Obsidian — 每个来源都有各自的 Agent 徽章
自动同步	Claude Code Stop hook、ZCode Stop hook + 每晚运行的 systemd / launchd / Task Scheduler 任务、OpenCode session.idle 插件
合成后端	Ollama、任何兼容 OpenAI 的服务（vLLM、SGLang、LM Studio、LiteLLM、托管服务）、Agent 委派、离线模拟
去芜存菁	合并低信号会话、清理维基链接、并发控制、费用 --estimate
静态站点	365 天热力图、令牌和缓存统计、可筛选的会话表格、带代码高亮的会话页面、带主题的项目页面、会话 ↔ 项目关系图、⌘K 搜索、深色模式
MCP 服务	12 个工具：查询、搜索、读取、列出来源、lint、同步、导出、仪表板……
AI 导出	llms.txt、llms-full.txt、JSON-LD 关系图、每页的 .txt / .json、站点地图、RSS
默认安全	脱敏用户名和 17 种机密模式、只读数据库导出、操作系统文件锁和原子状态写入、doctor 和 audit

截图

所有截图均来自在线演示，并通过 scripts/regen_docs_screenshots.py 重新生成。

每个会话，每个 Agent — 可按项目、模型和日期筛选；每一行都带有对应的 Agent 徽章。

会话页面 — 摘要、对话、高亮代码和运行过的工具，以及令牌和缓存用量。

项目 — 每个项目的主题、描述、活动和工具使用情况，索引页还带有新鲜度徽章。

关系图和搜索 — 会话按所属项目分组；⌘K 可即时搜索所有页面。

快速开始

git clone https://github.com/necroz/sessionwiki.git
cd sessionwiki
./setup.sh                 # Windows: setup.bat — creates .venv, detects your agents
./sync.sh                  # convert new sessions into raw/
./build.sh && ./serve.sh   # build the site and open http://127.0.0.1:8765

setup 会在当前检出目录中创建 .venv、安装软件包、搭建 raw/、wiki/、site/ 目录结构、启用它找到的 Agent 对应的适配器，并运行 sessionwiki doctor。包装脚本会自动使用虚拟环境；使用 CLI 时，请激活虚拟环境（source .venv/bin/activate），或调用 .venv/bin/sessionwiki。

也可以安装已发布的软件包 — 任选一种：

uv tool install sessionwiki          # uv: CLI in its own isolated environment
uvx sessionwiki --help               # uv: run without installing
pip install sessionwiki              # pip, inside a virtualenv
pip install 'sessionwiki[graph]'     # + graphify graph engine (also works with uv tool install)

Docker — 提供已构建的站点（镜像 ghcr.io/necroz/sessionwiki；docker compose 和在容器中运行 CLI 命令，请参阅 Docker 部署）：

docker run --rm -p 8765:8765 -v "$PWD/site:/wiki/site:ro" ghcr.io/necroz/sessionwiki

设置指南提供了带截图的分步说明。

连接你的 Agent

Claude Code、Codex CLI、Cursor、Gemini CLI、Copilot — 在运行 sessionwiki sync 时直接从各自的会话文件夹读取。若要在 Claude Code 每次回复后同步，请在 ~/.claude/settings.json 中添加 Stop hook：

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command",
      "command": "cd /path/to/sessionwiki && .venv/bin/python -m sessionwiki sync --no-auto-build >/dev/null 2>&1 &" }] }]
  }
}

并行运行 hook 是安全的：sync 和 synthesize 会获取 OS 文件锁，并以原子方式写入状态。

ZCode 将会话存储在 SQLite 中。sessionwiki 以只读方式导出会话，并为你安装 hook 和每夜运行的任务：

sessionwiki zcode install --dry-run   # show what will be written
sessionwiki zcode install             # Stop + SessionStart hooks, systemd / launchd / Task Scheduler

OpenCode（V2，opencode.db）会安装服务器插件，在会话空闲时运行自动同步：

sessionwiki opencode install --dry-run
sessionwiki opencode install          # honours $XDG_CONFIG_HOME

由 hook 触发的运行如果已有周期正在运行，会跳过而不是排队；定时运行则会等待并补上遗漏的任务。详情请参阅：ZCODE.md、docs/adapters/opencode.md，以及 sessionwiki adapters 查看完整列表。

大模型综合

sync 会将经过脱敏的转录填入 raw/。synthesize 会将其转换为 Wiki 页面：每个会话的摘要、项目页面和交叉链接。可在 config.local.json 中指定任意后端：

{
  "synthesis": {
    "backend": "openai",
    "base_url": "http://127.0.0.1:8000/v1",
    "model": "qwen3-coder",
    "max_concurrency": 8,
    "coalesce_low_signal": true
  }
}

sessionwiki synthesize --estimate     # what it will cost before you run it
sessionwiki synthesize                # new sessions only; idempotent
sessionwiki all --with-synth          # synthesize → build → graph → export → lint

后端：ollama（本地）、openai（任意兼容 OpenAI 的 /v1 服务：vLLM、SGLang、LM Studio、LiteLLM、托管 API）、agent-delegate（让你的编码 Agent 编写页面）、dummy（离线存根）。如果非 loopback 的 base_url 会将转录发送到你的设备之外，sessionwiki 会发出警告。请参阅 docs/modes/api/。

通过 Agent 查询你的 Wiki（MCP）

Claude Code 插件 — 包含 MCP 服务、一个会告知 Agent 何时搜索 Wiki 的技能，以及一个将项目最近会话加入上下文的 SessionStart hook。安装时会提示你选择 sessionwiki 文件夹：

/plugin marketplace add necroz/sessionwiki
/plugin install sessionwiki@sessionwiki

任意 MCP 客户端 — 使用 uvx 运行已发布的包，并将 SESSIONWIKI_HOME 指向包含 raw/ 和 wiki/ 的文件夹（请先在该文件夹中运行 sessionwiki sync）：

{
  "mcpServers": {
    "sessionwiki": {
      "command": "uvx",
      "args": ["sessionwiki", "mcp"],
      "env": { "SESSIONWIKI_HOME": "/path/to/your/sessionwiki" }
    }
  }
}

从源码检出目录运行时，使用 "command": "/path/to/sessionwiki/.venv/bin/sessionwiki" 和 "args": ["mcp"]；检出目录就是数据根目录，因此无需 env。

将其添加到 Claude Code、Claude Desktop、ZCode 或任意 MCP 客户端。工具包括 wiki_query（对任意语言的 Wiki 页面进行排序搜索，必要时回退到原始转录）、wiki_search（精确文本搜索，可选搜索原始转录）、wiki_read_page、wiki_list_sources、wiki_lint、wiki_sync、wiki_export、wiki_dashboard 等，共 12 个工具；使用 stdio 传输，无 SDK 依赖，并防范路径遍历。

CLI 参考

sessionwiki init                    # scaffold raw/ wiki/ site/
sessionwiki sync                    # export ZCode/OpenCode + convert transcripts to markdown
sessionwiki synthesize              # LLM summaries into wiki/ (--estimate, --coalesce-only, --force)
sessionwiki build                   # static site + AI exports
sessionwiki serve                   # local server on 127.0.0.1:8765
sessionwiki all                     # build → graph → export → lint (add --with-synth)
sessionwiki query "<question>"      # ask the wiki a question from the terminal
sessionwiki graph                   # session/project and wikilink graph
sessionwiki lint                    # wiki lint rules
sessionwiki export                  # llms.txt, JSON-LD, sitemap, RSS, …
sessionwiki candidates              # review candidate pages
sessionwiki adapters                # available adapters and their state
sessionwiki doctor                  # check Python, deps, config, agent paths
sessionwiki audit                   # scan raw/ wiki/ site/ for usernames and secrets
sessionwiki zcode                   # export · autosync · install
sessionwiki opencode                # export · autosync · install
sessionwiki mcp                     # MCP server on stdio
sessionwiki recall                  # a project's recent sessions, for a SessionStart hook
sessionwiki version

每个子命令都有 --help。完整参考请参阅：docs/reference/cli.md。

配置

设置采用分层加载；后加载的文件优先级更高：

examples/sessions_config.json  →  config.json  →  config.local.json
   (shared defaults)              (gitignored)      (gitignored, machine-local)

将机器专属的值 — 综合后端和密钥、脱敏模式、项目根目录、适配器开关 — 放入 config.local.json。参考文档：docs/configuration-reference.md。使用 .llmwikiignore 排除项目或会话。

工作原理

 Claude Code · Codex · Cursor · Gemini · Copilot       ZCode · OpenCode (SQLite)
              │ JSONL                                          │ read-only export
              └──────────────────────┬─────────────────────────┘
                                     ▼
                       sync  →  raw/sessions/*.md          redacted, immutable
                                     │
                       synthesize    ▼
                                  wiki/                    sources · projects · entities · concepts
                                     │
                    ┌────────────────┼──────────────────┐
                    ▼                ▼                  ▼
                 build → site/   MCP server        exports (llms.txt, JSON-LD)

分为三层，遵循 Karpathy 的 LLM Wiki 模式：raw/ 是不可变的事实来源，wiki/ 由大模型维护，site/ 则自动生成。你的 raw/ 和 wiki/ 均已加入 gitignore — 你的数据永远不会进入代码仓库。

隐私

• 转换时会对转录内容进行脱敏：包括你的用户名、主目录路径、17 种密钥和令牌，以及你自定义的模式。
• ZCode 和 OpenCode 数据库以只读方式打开。
• 除非你配置远程合成后端，否则不会有任何数据离开你的设备；配置后，sessionwiki 会发出警告。
• 发布网站前，sessionwiki audit 会扫描 raw/、wiki/ 和 site/。

请参阅 docs/privacy.md 和 SECURITY.md。

文档

• 文档中心 — 从这里开始
• 设置指南 · 安装 · 与 Claude Code 搭配使用 · Windows
• CLI · 配置 · 架构
• 部署到 GitHub Pages、Docker、Vercel/Netlify
• 与 llmwiki 有何不同 · 更新日志

基于 llmwiki

sessionwiki 最初基于 Pratiyush 的 llmwiki（MIT）v1.3.82 分叉而来，并保留了完整历史记录。转换器、网站、lint 和 MCP 的大部分基础工作都出自他手。sessionwiki 新增了支持自动同步的 ZCode 和 OpenCode 数据源、兼容 OpenAI 的合成后端、会话合并、锁定和原子状态、doctor 和 audit、会话图，以及大量修复——请参阅有何不同和迁移方法。

也感谢 Andrej Karpathy 提出 LLM Wiki 的构想，以及 Python Markdown、highlight.js 和 vis-network。

贡献

请阅读 CONTRIBUTING.md。每个 PR 只处理一个事项，标题使用 feat: / fix: / docs: / chore: / test:，为 feat 和 fix 添加 CHANGELOG 条目，切勿提交真实会话数据。CI 必须通过。

许可证

MIT © 2026 Igor Lashkevich（sessionwiki） · © 2026 Pratiyush（原始 llmwiki）。请参阅 NOTICE。