second-brain-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Second Brain Audit

第二大脑审计

Notes rot in a specific way. Nothing is corrupted and nothing goes missing: a fact simply stops being true, the note keeps saying it, and nothing raises a hand.

The cause is almost always the same. The write path can only append. New information arrives and becomes a new line under the old line, which is correct for some facts and ruinous for others.

笔记会以一种特定的方式“老化”。没有内容损坏，也没有内容丢失：只是某个事实不再成立，但笔记仍保留着该内容，且没有任何提示。

其原因几乎总是相同的：写入路径仅支持追加。新信息到来后会被添加在旧内容下方，这对某些事实来说是正确的，但对另一些事实而言却是毁灭性的。

The one idea

核心思路

Every stored fact is one of two kinds.

	Meaning	Correct update
State	one current value, and it changes	replace it
Event	a timestamped thing that happened	append it

A price, a status, an owner, a deadline: state. A payment, a signature, a decision, a lesson learned: event.

The update rules are opposites. Replacing an event destroys history. Appending a state creates two answers to one question with nothing marking which is current, and the stale copy usually sits higher in the file, so it gets read first.

Structure carries this rule, not an instruction. Asking a model, or a person, to remember to update the old entry fails quietly and constantly. Give the page two sections and the rule follows from where a fact lands.

每个存储的事实都属于以下两种类型之一：

	含义	正确更新方式
State	单一当前值，会发生变化	替换该值
Event	带时间戳的已发生事件	追加记录

价格、状态、所有者、截止日期都属于State；付款、签名、决策、经验教训都属于Event。

两者的更新规则完全相反。替换Event会破坏历史记录；追加State会导致同一个问题出现两个答案，且没有任何标记说明哪个是当前有效的，而过时的副本通常位于文件上方，因此会被优先读取。

规则由结构承载，而非指令。要求模型或人员记住更新旧条目会频繁地无声失败。为页面设置两个分区，规则就会根据事实所在的位置自动生效。

Phase 1: establish the shape

阶段1：确定结构形态

Do not assume a wiki, a vault, or pages. Most people have none of those. Look at what actually exists before anything else, because it changes both what the audit can see and what the fix should be.

Shape	Looks like	Where state should live
Page per subject	`clients/acme.md` , `projects/x.md`	two sections on each page
One big file	a single `notes.md` or `CLAUDE.md`	a `## Current State` block at the top
Daily notes only	`2026-06-01.md` , and nothing else	nothing to convert. A state layer is missing entirely
Not markdown	Notion, Apple Notes, a chat assistant's memory	the idea still applies; the tooling does not

Then establish two things:

Where the notes live. A folder of markdown, for the scan.
What the agent reads on every session.
```
CLAUDE.md
```
, a
```
MEMORY.md
```
, a system prompt file, whatever loads automatically. This matters more than anything else: a stale fact in an archive is harmless, the same fact in the always-loaded file is the bug. If the user does not know, say so and run without it.

Daily-notes-only is the case most worth naming out loud. Dated notes are an event log, and events are supposed to accumulate; nothing about them is broken. What is missing is any place that says what is true now. Telling someone to restructure their journal would be actively wrong.

不要默认是维基、知识库或独立页面。大多数人并没有这些。首先查看实际存在的内容，因为这会影响审计的范围和修复方案。

形态	表现形式	State应存放的位置
每个主题对应一个页面	`clients/acme.md` 、 `projects/x.md`	每个页面分为两个分区
单个大文件	单个 `notes.md` 或 `CLAUDE.md`	文件顶部的 `## Current State` 区块
仅每日笔记	`2026-06-01.md` ，无其他内容	无需转换。完全缺少State层
非Markdown格式	Notion、苹果笔记、聊天助手的记忆	核心思路依然适用，但工具实现方式不同

然后确定两件事：

笔记的存储位置：用于扫描的Markdown文件夹。
Agent每次会话都会读取的内容：
```
CLAUDE.md
```
、
```
MEMORY.md
```
、系统提示文件等自动加载的内容。这是最重要的一点：归档中的过时事实并无危害，但始终加载的文件中的过时事实就是问题所在。如果用户不清楚，如实告知并继续执行审计。

仅使用每日笔记的情况最值得明确指出。带日期的笔记是事件日志，事件本就应该累积；它们本身没有任何问题。缺失的是一个能说明当前真实情况的区域。要求用户重新组织日志是完全错误的。

Phase 2: audit the always-loaded surface

阶段2：审计始终加载的内容

This is the part that works on every second brain, in any tool, in any domain, with or without the script. Run it always, even when the scan found plenty.

Whatever the agent reads on every session is small: that is what makes it always loadable. So it can be read in full and checked claim by claim.

Read that surface completely. The always-loaded file, or the top of the one big file, or the pinned page. All of it.
Extract every state-shaped claim. Anything phrased as a current fact: a status, an owner, a rate, a version, a deadline, a "currently", a "we use", a "lives at". Ignore anything phrased as an event, since events stay true.
For each claim, go and find the freshest evidence anywhere in the notes. Grep the subject. Read the newest file that mentions it.
Sort each claim into three piles:
- Confirmed. The detail agrees.
- Contradicted. Something newer disagrees. This is rot, and it is the headline.
- Unsupported. Nothing anywhere backs it up. Often the claim was true once and the evidence was never written, which is worth saying out loud.

Ten to thirty claims is normal, and it is a few minutes of reading. A research vault with no money in it, a personal wiki, a Notion workspace: all auditable this way, and none of them by the script.

Report the contradicted pile first, then the unsupported pile. Both are findings.

这部分适用于所有第二大脑，无论使用何种工具、属于哪个领域，无论是否有脚本。务必执行此步骤，即使扫描已经发现了大量问题。

Agent每次会话读取的内容通常很小：这正是它能被始终加载的原因。因此可以完整读取并逐条检查声明。

完整读取该内容：始终加载的文件、单个大文件的顶部，或是固定页面。全部内容都要读取。
提取所有State类型的声明：任何表述为当前事实的内容：状态、所有者、费率、版本、截止日期、“当前”、“我们使用”、“位于”等。忽略所有表述为Event的内容，因为事件始终是真实的。
针对每个声明，在所有笔记中查找最新证据：搜索主题相关内容，读取提到该主题的最新文件。
将每个声明分为三类：
- 已确认：细节一致。
- 矛盾：有更新的内容与之冲突。这就是“老化”的内容，也是重点问题。
- 无依据：没有任何内容支持该声明。通常该声明曾经是真实的，但从未记录相关证据，这一点值得明确指出。

通常会有10到30条声明，只需几分钟就能读完。无论是否有脚本，研究知识库、个人维基、Notion工作区都可以用这种方式审计。

首先报告矛盾类声明，然后是无依据类声明。两者都是审计发现。

Phase 3: run the scan, if the notes suit it

阶段3：运行扫描（如果笔记适合）

An accelerator, not the audit. It applies to markdown folders where facts carry monetary values, and it finds cross-file disagreements far faster than reading can. Skip it otherwise; phase 2 already did the work.

bash

python <skill>/scripts/audit.py <notes-dir> \
    --always-loaded MEMORY.md --always-loaded CLAUDE.md

Pass

--subject "Acme Corp"

to track named subjects by name, and

--json

for structured output. The script only reads; it never writes.

A zero is not a clean bill of health. Values are the only thing it can compare without guessing, so notes with no money in them are largely invisible to it. It prints a COVERAGE WARNING when it knows it was blind. Read that warning out rather than reporting "no problems found".

Why a script at all: the count has to be the same twice. A model asked to tally 600 bullets returns a confident number and a different one tomorrow, which is the class of failure this skill exists to fix. The script counts. The agent judges.

这是审计的加速工具，而非核心审计步骤。适用于包含货币价值事实的Markdown文件夹，能比人工读取更快地发现跨文件矛盾。否则跳过此步骤；阶段2已经完成了核心工作。

bash

python <skill>/scripts/audit.py <notes-dir> \
    --always-loaded MEMORY.md --always-loaded CLAUDE.md

传递

--subject "Acme Corp"

参数可按名称跟踪指定主题，传递

--json

参数可获取结构化输出。该脚本仅读取内容，从不写入。

零结果并不代表完全没问题。该脚本只能比较数值，因此不包含货币价值的笔记大多无法被检测到。当它知道自己存在检测盲区时，会打印出COVERAGE WARNING（覆盖范围警告）。应读出该警告，而不是报告“未发现问题”。

为何需要脚本：数值必须前后一致。让模型统计600条项目符号，它会给出一个确定的数字，但第二天可能会给出不同的结果，而这正是该技能要解决的问题类型。脚本负责统计，Agent负责判断。

Phase 4: read what neither can see

阶段4：检查两者都无法检测到的内容

Open a few flagged pages and look for what no regex will catch:

Lifecycle conflicts. A page saying "launching next week" while a log entry from three months ago records the project being cancelled. No number disagrees, so nothing is flagged, and it is completely wrong.
Facts never written down at all. The most common cause of a wrong answer is not bad organization; it is that the true value only ever existed in a conversation or a daily note. Reorganizing cannot reach it. Say so plainly rather than implying the restructure will help.
Pages that must not be touched. Checklists, reference lists, packing lists. They are lists on purpose. Converting one destroys what makes it useful, and every structural check still passes.

打开一些标记有问题的页面，查找正则表达式无法捕获的内容：

生命周期冲突：页面上写着“将于下周启动”，而三个月前的日志记录显示该项目已被取消。没有数值冲突，因此不会被标记，但内容完全错误。
从未记录的事实：错误答案最常见的原因并非组织不善，而是真实值仅存在于对话或每日笔记中。重新组织无法解决这个问题。应如实说明，而不是暗示重组会有帮助。
禁止修改的页面：清单、参考列表、打包清单。它们本身就是列表形式。修改这类页面会破坏其用途，且所有结构检查仍会通过。

Phase 5: report

阶段5：报告

Lead with the single most damaging finding, not a summary of the tool's output:

Three different answers for what Acme pays, and the oldest one is in the file the agent reads every session.

Where an agent already runs over these notes, demonstrate it. Ask the question the notes should answer and read the reply out. Watching an assistant confidently return a number that stopped being true in March lands harder than any report. Point out the common case where it is diligent and still wrong: it checks a page, warns that another file looks stale, and still misses the true value because that value was never promoted anywhere durable.

首先报告最具破坏性的单一发现，而非工具输出的摘要：

关于Acme的付款金额有三种不同的答案，其中最旧的那个在Agent每次会话都会读取的文件中。

如果已经有Agent在这些笔记上运行，进行演示。提出笔记应该能回答的问题并读出回复。看着助手自信地返回一个在3月就已失效的数值，比任何报告都更有冲击力。指出常见的“勤勉但仍出错”的情况：它检查了一个页面，警告另一个文件可能已过期，但仍未找到真实值，因为该值从未被记录到持久的位置。

Phase 6: fix one place

阶段6：修复一处

Never bulk-convert, and never convert a page the user did not agree to. Fix the single worst location, which depends on the shape found in phase 1:

Page per subject → give that one page the two sections below.
One big file → add a
```
## Current State
```
block at the top and leave everything else beneath it. No new files, no folder structure.
Daily notes only → create one file holding current values, and leave every journal entry untouched. The journal was already correct.
Not markdown → do not restructure anything. Explain where the current value should live in the tool they already use, and stop there.

The shape below is the page-per-subject version; adapt the same two ideas to the others. What has to be true in every case is only this: one place says what is true now, and it gets replaced rather than added to.

markdown

undefined

切勿批量转换，也不要转换用户未同意的页面。修复最严重的位置，具体取决于阶段1中确定的结构形态：

每个主题对应一个页面 → 为该页面添加以下两个分区。
单个大文件 → 在文件顶部添加
```
## Current State
```
区块，其余内容保留在下方。无需创建新文件或文件夹结构。
仅每日笔记 → 创建一个存储当前值的文件，所有日志条目保持不变。日志本身已经是正确的。
非Markdown格式 → 不要重组任何内容。说明在用户当前使用的工具中，当前值应该存放在哪里，然后停止操作。

以下是每个主题对应一个页面的结构形态；将同样的两个思路适配到其他形态。在所有情况下必须满足的只有一点：有一个地方记录当前真实情况，且该内容会被替换而非追加。

markdown

undefined

Current State

Retainer (2026-08-01): $3,200/mo, renewed through February 2027
Main contact (2026-05-02): Curtis Ilo

服务费 (2026-08-01): 3200美元/月，续约至2027年2月
主要联系人 (2026-05-02): Curtis Ilo

Log

日志

(2026-04-30) Delivered and paid, $21,000
(2026-05-02) Retainer started at $2,800/mo
(2026-06-15) Added reply drafting, retainer to $3,200/mo


Conversion rules, in order of importance:

1. **Lose nothing.** Every existing line lands in one of the two sections, verbatim.
   This is sorting, not rewriting. Improving the prose is how information disappears
   without anyone noticing.
2. **One entry per subject in Current State.** Where two lines describe the same
   current value, the newer wins and the older moves to the Log. Where the order is
   unclear, ask. Never guess.
3. **Date every Current State entry.** Ask for a missing date or take it from file
   history. An undated current value is barely better than a stale one.
4. **Never merge two subjects that merely look similar.** "Acme (May)" and "Acme Corp
   renewal" may be genuinely different things. A duplicate entry is a cheap mistake;
   a wrong merge destroys information. Report near-misses and let the user decide.
5. **Show a diff and get approval** before writing.

Re-ask the earlier question afterwards so the correct answer is visible. Same notes,
same agent, one page restructured.

(2026-04-30) 交付并收款，21000美元
(2026-05-02) 服务费开始为2800美元/月
(2026-06-15) 增加回复起草服务，服务费调整为3200美元/月


转换规则，按重要性排序：

1. **不丢失任何内容**：所有现有内容都要原封不动地放入两个分区之一。这是分类，而非改写。修改措辞会导致信息在无人察觉的情况下丢失。
2. **Current State中每个主题对应一条记录**：如果有两条描述同一当前值的内容，保留较新的一条，将较旧的一条移至日志。如果顺序不明确，询问用户。切勿猜测。
3. **为每个Current State条目添加日期**：询问缺失的日期或从文件历史中获取。未标注日期的当前值几乎和过时内容一样糟糕。
4. **切勿合并看似相似的两个主题**：“Acme（5月）”和“Acme Corp续约”可能是完全不同的内容。重复条目是小错误；错误合并会破坏信息。报告疑似重复的情况，让用户决定。
5. **在写入前显示差异并获得批准**。

修复后重新提出之前的问题，以便正确答案可见。笔记不变，Agent不变，仅重构了一个页面。

Phase 7: change the write path

阶段7：修改写入路径

This phase decides whether the audit was worth anything. Converting pages fixes today; changing how facts get written is what stops the recurrence.

Add to whatever file instructs the agent (

CLAUDE.md

AGENTS.md

, a system prompt):

markdown

undefined

这一阶段决定了审计是否有价值。重构页面只能解决当前问题；修改事实的写入方式才能防止问题再次发生。

在任何指导Agent的文件（

CLAUDE.md

、

AGENTS.md

、系统提示）中添加以下内容：

markdown

undefined

Writing to these notes

写入这些笔记的规则

Every fact is state or event.

State (one current value that changes: price, status, owner, date): find the matching line in
```
## Current State
```
and REPLACE it. Always date it. Never add a second line for the same subject.
Event (a thing that happened): append to
```
## Log
```
. Never edit or delete an existing Log entry.

If unsure, append to the Log and say so. A missing state update is recoverable; a rewritten history is not.


Then state the honest part: this instruction gets followed most of the time, not all
of the time. Anything that must happen every time needs a mechanism. Two cheap ones
worth more than the instruction:

- Re-run this audit on a schedule and watch whether the count climbs.
- Stamp dates with a script after the fact instead of asking for them.

每个事实要么是State，要么是Event。

State（会变化的单一当前值：价格、状态、所有者、日期）：在
```
## Current State
```
中找到对应的条目并进行替换。始终标注日期。切勿为同一主题添加第二条记录。
Event（已发生的事件）：追加到
```
## Log
```
中。绝不编辑或删除现有日志条目。

如果不确定，追加到日志中并说明情况。缺失的State更新可以恢复；被改写的历史则无法挽回。


然后说明实际情况：该指令大多时候会被遵循，但并非总是如此。任何必须每次都执行的操作都需要机制保障。以下两种低成本机制比指令更有效：

- 定期重新运行此审计，观察问题数量是否上升。
- 使用脚本事后添加日期，而非要求手动添加。

Set expectations honestly

如实设定预期

Restructuring alone often moves the number less than people expect. When it does not move, the reason is usually that the correct fact was never captured, and no amount of reorganizing reaches a fact nobody wrote down. Say that when it applies. The audit's real value is identifying which of the two problems is in play.

仅靠重构通常不会像人们预期的那样大幅减少问题数量。如果没有改善，原因通常是正确的事实从未被记录下来，无论如何重组都无法找到无人记录的事实。当出现这种情况时要如实说明。审计的真正价值在于确定当前存在的是哪一类问题。

Resources

资源

```
scripts/audit.py
```
: run it for the deterministic scan;
```
--help
```
lists all flags,
```
--json
```
returns structured findings. Never read it into context; only its output.

```
scripts/audit.py
```
：运行该脚本进行确定性扫描；
```
--help
```
列出所有参数，
```
--json
```
返回结构化发现。切勿将脚本内容读入上下文；仅使用其输出。