pkm-documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

🚀 First Run

🚀 首次运行

If the

knowledge/

directory doesn't exist in your workspace, run the setup script:

bash

bash skills/pkm-documentation/scripts/setup.sh

This creates the vault structure and patches

AGENTS.md

SOUL.md

, and

MEMORY.md

with PKM instructions. Alternatively, create the directories manually:

knowledge/{decisions,devlog,learnings,projects,conversations,daily}

如果你的工作区中不存在

knowledge/

目录，请运行以下设置脚本：

bash

bash skills/pkm-documentation/scripts/setup.sh

该脚本会创建vault结构，并在

AGENTS.md

、

SOUL.md

和

MEMORY.md

中添加PKM相关说明。你也可以手动创建目录：

knowledge/{decisions,devlog,learnings,projects,conversations,daily}

。

PKM Documentation

PKM 文档系统

Document everything worth keeping using atomic, connected, iterative notes. Based on Zettelkasten method adapted for an AI agent workspace.

使用原子化、互相关联、可迭代的笔记记录所有值得留存的内容。基于Zettelkasten方法适配AI Agent工作区场景。

⚠️ THIS IS MANDATORY

⚠️ 此要求为强制项

Read this file BEFORE writing any note. No exceptions.

NO loose free text
NO writing without a template
NO documenting outside the
```
knowledge/
```
vault
If there's no template for it, don't write it

在撰写任何笔记前，请先阅读本文档，无例外。

禁止使用零散的自由文本
禁止不使用模板撰写内容
禁止在
```
knowledge/
```
vault外记录内容
如果没有对应模板，请勿撰写

Core Principles

核心原则

Atomic notes — One idea per file. If it covers two topics, split into two files.
Connect everything — Use
```
[[wiki-links]]
```
Obsidian-style for cross-references.
Never delete, iterate — Update notes with new context. Mark outdated info as
```
[SUPERSEDED]
```
rather than removing.
Process fast — Document while context is fresh. Delayed notes lose value (encoding principle).
Standardize — Every note follows a template. Every note is a file in its folder.

原子化笔记 — 每个文件仅记录一个观点。如果内容涵盖两个主题，请拆分为两个文件。
关联所有内容 — 使用Obsidian风格的
```
[[wiki-links]]
```
进行交叉引用。
永不删除，持续迭代 — 用新上下文更新笔记。将过时信息标记为
```
[SUPERSEDED]
```
而非直接删除。
快速记录 — 在记忆清晰时记录内容。延迟记录会降低笔记价值（编码原则）。
标准化 — 每篇笔记都遵循模板，且保存在对应文件夹中。

Vault Structure

Vault 结构

knowledge/
├── decisions/      → Decision Records (🔀)
├── devlog/         → Development Logs (🔧)
├── learnings/      → Learning Notes (💡)
├── projects/       → Project Notes (📦) — no date, updated in-place
├── conversations/  → Conversation Summaries (💬)
├── daily/          → Daily indices (links to the day's notes)
└── README.md       → Vault map

knowledge/
├── decisions/      → 决策记录 (🔀)
├── devlog/         → 开发日志 (🔧)
├── learnings/      → 学习笔记 (💡)
├── projects/       → 项目笔记 (📦) — 无日期，原地更新
├── conversations/  → 对话摘要 (💬)
├── daily/          → 每日索引 (仅链接当日笔记)
└── README.md       → Vault 映射说明

File Naming

文件命名规则

With date:
```
YYYY-MM-DD-descriptive-slug.md
```
(decisions, devlog, learnings, conversations)
Without date:
```
project-name.md
```
(projects — updated in-place)
Daily index:
```
YYYY-MM-DD.md
```
(only links to the day's notes)

带日期格式：
```
YYYY-MM-DD-descriptive-slug.md
```
（适用于决策记录、开发日志、学习笔记、对话摘要）
无日期格式：
```
project-name.md
```
（适用于项目笔记 — 原地更新）
每日索引格式：
```
YYYY-MM-DD.md
```
（仅包含当日笔记的链接）

Note Types & Templates

笔记类型与模板

1. Decision Record (decisions/)

1. 决策记录（decisions/）

Use when a technical or strategic decision is made.

markdown

undefined

用于记录技术或战略决策。

markdown

undefined

🔀 Decision: [title]

🔀 决策：[标题]

Date: YYYY-MM-DD
Context: Why this came up
Options considered: What alternatives existed
Decision: What we chose
Reasoning: Why
Consequences: What this affects
Related: [[type/file]] | [[type/file]]

undefined

日期： YYYY-MM-DD
背景： 决策的起因
备选方案： 曾考虑的其他选项
最终决策： 选择的方案
决策理由： 选择该方案的原因
关联内容： [[类型/文件名]] | [[类型/文件名]]

undefined

2. Development Log (devlog/)

2. 开发日志（devlog/）

Use when building, fixing, or shipping something.

markdown

undefined

用于记录功能开发、问题修复或版本发布等工作。

markdown

undefined

🔧 Dev: [what was built/fixed]

🔧 开发记录：[开发/修复内容]

Date: YYYY-MM-DD
Project: [[projects/name]]
What changed: Brief description
Technical details: Implementation notes worth remembering
Issues hit: Problems encountered and how they were solved
Related: [[type/file]] | [[type/file]]

undefined

日期： YYYY-MM-DD
关联项目： [[projects/项目名称]]
变更内容： 简要描述
技术细节： 值得留存的实现说明
遇到的问题： 遇到的问题及解决方案
关联内容： [[类型/文件名]] | [[类型/文件名]]

undefined

3. Learning Note (learnings/)

3. 学习笔记（learnings/）

Use when discovering something new — a tool, technique, pattern.

markdown

undefined

用于记录新发现的工具、技术或模式。

markdown

undefined

💡 Learning: [topic]

💡 学习笔记：[主题]

Date: YYYY-MM-DD
Source: Where this came from (tweet, docs, experiment)
Key insight: The core takeaway in 1-2 sentences
Details: Deeper explanation if needed
Application: How this applies to our work
Related: [[type/file]] | [[type/file]]

undefined

日期： YYYY-MM-DD
信息来源： 内容的出处（推文、文档、实验等）
核心见解： 1-2句话总结核心要点
详细说明： 如需补充的深度解释
应用场景： 该内容在工作中的应用方式
关联内容： [[类型/文件名]] | [[类型/文件名]]

undefined

4. Project Note (projects/)

4. 项目笔记（projects/）

Use when starting or significantly updating a project.

markdown

undefined

用于项目启动或重大更新时记录。

markdown

undefined

📦 Project: [name]

📦 项目：[名称]

Status: active | paused | completed | abandoned
Goal: What this project achieves
Stack: Technologies used
Architecture: Key design decisions
Current state: Where things stand
Next steps: What comes next
Related: [[type/file]] | [[type/file]]

undefined

状态： active | paused | completed | abandoned
目标： 项目要实现的成果
技术栈： 使用的技术
架构： 关键设计决策
当前进展： 项目现状
下一步计划： 后续工作
关联内容： [[类型/文件名]] | [[类型/文件名]]

undefined

5. Conversation Summary (conversations/)

5. 对话摘要（conversations/）

Use at end of significant conversations with the user.

markdown

undefined

用于与用户的重要对话结束后记录。

markdown

undefined

💬 Conversation: [topic]

💬 对话摘要：[主题]

Date: YYYY-MM-DD
Topics covered: Bullet list
Decisions made: What was decided (link to decision records)
Action items: What needs to happen next
Open questions: Unresolved items

undefined

日期： YYYY-MM-DD
讨论主题： 要点列表
达成的决策： 对话中做出的决策（链接到对应决策记录）
行动项： 后续需要完成的工作
未解决问题： 待处理的事项

undefined

6. Daily Index (daily/)

6. 每日索引（daily/）

Lightweight daily index. Links only.

markdown

undefined

轻量化每日索引，仅包含链接。

markdown

undefined

YYYY-MM-DD

Notes of the day

当日笔记

[[devlog/YYYY-MM-DD-slug]] — short description
[[decisions/YYYY-MM-DD-slug]] — short description
[[learnings/YYYY-MM-DD-slug]] — short description
[[conversations/YYYY-MM-DD-slug]] — short description

undefined

[[devlog/YYYY-MM-DD-slug]] — 简短描述
[[decisions/YYYY-MM-DD-slug]] — 简短描述
[[learnings/YYYY-MM-DD-slug]] — 简短描述
[[conversations/YYYY-MM-DD-slug]] — 简短描述

undefined

Cross-References (Wiki-Links)

交叉引用（Wiki-Links）

Use

[[folder/filename]]

to connect notes:

markdown

- **Related:** [[projects/webclaw-fork]] | [[devlog/2026-02-10-browserless-setup]]

Common patterns:

Devlog → Project it affects
Decision → Devlog that implements it
Learning → Devlog where it was discovered
Conversation → Decisions and action items from the day
Daily → Everything from the day

使用

[[文件夹/文件名]]

格式关联笔记：

markdown

- **关联内容：** [[projects/webclaw-fork]] | [[devlog/2026-02-10-browserless-setup]]

常见关联模式：

开发日志 → 关联其影响的项目
决策记录 → 关联实现该决策的开发日志
学习笔记 → 关联发现该内容的开发日志
对话摘要 → 关联当日的决策和行动项
每日索引 → 关联当日所有内容

Workflow

工作流

During conversations

对话过程中

Identify documentable moments (decisions, learnings, dev work)
After completing a significant task → document BEFORE moving to the next one

识别需要记录的时刻（决策、学习内容、开发工作）
完成重要任务后 → 记录完成后再进行下一项工作

Delegation to sub-agents

委托给子Agent

To avoid filling the main context or slowing down:

Write a detailed
```
task
```
with all necessary context
Spawn sub-agent with
```
sessions_spawn
```
The sub-agent creates notes in the vault following the templates
Example task:

Document in knowledge vault (knowledge/):
- Type: devlog
- File: knowledge/devlog/2026-02-10-feature-x.md
- Content: [detailed description of what was done, issues, etc.]
- Related: [[projects/name]] | [[decisions/date-slug]]
Also update knowledge/daily/2026-02-10.md adding the link.

为避免占用主上下文或拖慢速度：

撰写包含所有必要上下文的详细
```
task
```
使用
```
sessions_spawn
```
生成子Agent
子Agent按照模板在vault中创建笔记
示例任务：

在知识仓库（knowledge/）中记录：
- 类型：devlog
- 文件路径：knowledge/devlog/2026-02-10-feature-x.md
- 内容：[详细描述完成的工作、遇到的问题等]
- 关联内容：[[projects/项目名称]] | [[decisions/日期-slug]]
同时更新knowledge/daily/2026-02-10.md，添加该笔记的链接。

At the end of a significant session

重要会话结束时

Create conversation summary
Update daily index
If there's important info → update
```
MEMORY.md
```
with link to the vault

创建对话摘要
更新每日索引
如果包含重要信息 → 在
```
MEMORY.md
```
中添加指向vault的链接

Periodic review (during heartbeats)

定期回顾（心跳机制触发时）

Scan recent notes for patterns or connections
Promote important items to
```
MEMORY.md
```
(with links to the vault)
Update project statuses in
```
knowledge/projects/
```
Identify knowledge gaps

扫描近期笔记，寻找规律或关联点
将重要内容同步到
```
MEMORY.md
```
（附带指向vault的链接）
更新
```
knowledge/projects/
```
中的项目状态
识别知识缺口

MEMORY.md — The Distilled Index

MEMORY.md — 精炼索引

MEMORY.md

remains the executive summary loaded every session. But now:

Each item has a link to the vault:
```
→ see [[devlog/2026-02-10-slug]]
```
Keep it lean — 1-2 lines per item
Details live in the vault, not in MEMORY.md

MEMORY.md

仍是每次会话加载的执行摘要，但现在：

每个条目都包含指向vault的链接：
```
→ 查看 [[devlog/2026-02-10-slug]]
```
保持精简 — 每个条目1-2行
详细内容存储在vault中，而非MEMORY.md

Deep Learning Mode ("Learn about this")

深度学习模式（“学习此内容”）

When the user asks to learn about a topic:

Full analysis — read everything, scrape, web search
Go deep — don't summarize superficially
Document atomically — individual Learning Notes per concept

Deep dive files —

knowledge/learnings/YYYY-MM-DD-<topic>.md

Connect — links to existing projects, decisions, learnings
Distill — key takeaways to MEMORY.md with links to the vault

当用户要求学习某个主题时：

全面分析 — 阅读所有相关内容、爬取信息、网页搜索
深度挖掘 — 避免表面化总结
原子化记录 — 每个概念单独创建学习笔记

深度分析文件路径 —

knowledge/learnings/YYYY-MM-DD-<主题>.md

建立关联 — 链接到现有项目、决策、学习笔记
精炼内容 — 将核心要点同步到MEMORY.md，并附带指向vault的链接

What to Document

记录范围

✅ Always document:

Technical decisions and their reasoning
Bugs found and how they were fixed
New tools, libs, or techniques discovered
Architecture changes
Configuration that took trial and error
User preferences and requests

❌ Skip:

Routine operations (file reads, simple commands)
Obvious information the model already knows
Temporary debugging that led nowhere

✅ 必须记录：

技术决策及其理由
发现的Bug及修复方案
新发现的工具、库或技术
架构变更
经过反复尝试的配置
用户偏好与需求

❌ 无需记录：

常规操作（文件读取、简单命令）
模型已掌握的常识
未产生结果的临时调试