ultrabrain

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ultrabrain

Drive a personal, LLM-maintained wiki at

~/.ultrabrain/

. This skill is a thin trigger layer — the vault is self-contained and methodology rules live in

~/.ultrabrain/AGENTS.md

, not here.

管理存储在

~/.ultrabrain/

路径下的个人LLM维护维基。该技能是一个轻量触发层——知识库（vault）是独立封装的，方法规则存储在

~/.ultrabrain/AGENTS.md

中，而非本文件内。

Trigger Contract

触发约定

Five operations. The first two are skill-side; the last three delegate to vault rules.

Operation	Trigger examples
`bootstrap`	"bootstrap ultrabrain", "initialize vault", "設定 ultrabrain", or any other operation fires with no vault present
`capture`	"記下來 X", "capture this", "save to vault", "存進 vault", or "capture <path-or-url>"
`ingest`	"ingest", "integrate raw", "整合 raw", "整理 vault"
`query`	description-driven for factual/technical/decision questions, or explicit: "查 vault", "search ultrabrain"
`lint`	"lint vault", "健檢 vault", "check wiki"

包含五种操作。前两种由技能侧处理；后三种委托给知识库规则执行。

操作	触发示例
`bootstrap`	"bootstrap ultrabrain", "initialize vault", "設定 ultrabrain"，或任何在知识库不存在时触发的操作
`capture`	"記下來 X", "capture this", "save to vault", "存進 vault"，或 "capture <path-or-url>"
`ingest`	"ingest", "integrate raw", "整合 raw", "整理 vault"
`query`	针对事实性/技术性/决策类问题的描述触发，或明确指令："查 vault", "search ultrabrain"
`lint`	"lint vault", "健檢 vault", "check wiki"

Query skip clause

查询跳过规则

Before reading any vault file for

query

, verify the user's question plausibly concerns retained knowledge. Skip the vault (answer normally) when the question is:

Small talk — greetings, thanks, session meta-questions.
Context-local — answerable from the current session or open files ("what does this file do", "why did that fail").
Execution requests — "write this", "run that", "refactor X". Vault holds facts, not tasks.

When classification is uncertain, default to skipping. Aggressive description triggering is balanced by this negative filter, not overridden.

在为

query

操作读取任何知识库文件之前，请确认用户的问题确实与已存储的知识相关。当问题属于以下情况时，跳过知识库（正常回答即可）：

闲聊——问候、致谢、会话元问题。
上下文本地问题——可通过当前会话或打开的文件回答的问题（如“这个文件是做什么的”、“为什么会失败”）。
执行请求——“编写这个”、“运行那个”、“重构X”。知识库存储事实，而非任务。

当无法确定分类时，默认跳过。宽泛的描述触发机制会通过这个负面过滤器进行平衡，而非被覆盖。

Operations

操作说明

Full step-by-step lives in

references/operations.md

. Summary:

bootstrap
creates

~/.ultrabrain/

with

AGENTS.md

(copied from

references/agents-template.md

CLAUDE.md

(one line:

@AGENTS.md

), empty

index.md

and

log.md

, and

raw/

wiki/

directories. Refuses if the vault exists unless

--force

is passed.

capture
writes session or file content to
```
raw/YYYY-MM-DD-<slug>.md
```
with frontmatter. Resolves ambiguous "記下來" requests by proposing a scope and waiting for user confirmation. Never silently overwrites — collisions go to suffixed filenames or a user-chosen append.
ingest
loads
```
~/.ultrabrain/AGENTS.md
```
and follows its
```
Operation: Ingest
```
section to integrate unprocessed
```
raw/
```
files into
```
wiki/
```
, moving processed raw to
```
raw/.processed/
```
.
query
loads
```
AGENTS.md
```
, reads
```
index.md
```
first, then follows the vault's query rules (index-first strict; no Grep fallback). Answers cite specific wiki pages. Falls back to general knowledge if the vault is empty, with an explicit note.
lint
loads
```
AGENTS.md
```
and produces a health report (contradictions, orphans, stale pages, index drift, missing cross-references). Never auto-fixes; asks the user which findings to address.

Every operation appends one line to

log.md

in the format

ISO-8601 OPERATION details

完整的分步流程请查阅

references/operations.md

。概述如下：

bootstrap
操作会创建
```
~/.ultrabrain/
```
目录，并生成
```
AGENTS.md
```
（从
```
references/agents-template.md
```
复制）、
```
CLAUDE.md
```
（仅一行内容：
```
@AGENTS.md
```
）、空文件
```
index.md
```
和
```
log.md
```
，以及
```
raw/
```
和
```
wiki/
```
子目录。如果知识库已存在则会拒绝执行，除非传入
```
--force
```
参数。
capture
操作将会话或文件内容写入
```
raw/YYYY-MM-DD-<slug>.md
```
文件，并添加前置元数据。对于模糊的“記下來”请求，会先提议一个范围并等待用户确认。绝不会静默覆盖文件——文件名冲突时会使用带后缀的文件名或询问用户选择追加方式。
ingest
操作加载
```
~/.ultrabrain/AGENTS.md
```
并遵循其中的「Operation: Ingest」章节，将未处理的
```
raw/
```
文件整合到
```
wiki/
```
目录中，已处理的原始文件会移动到
```
raw/.processed/
```
。
query
操作加载
```
AGENTS.md
```
，优先读取
```
index.md
```
，然后遵循知识库的查询规则（严格优先索引；不使用Grep回退）。回答时会引用具体的维基页面。如果知识库为空，则会回退到通用知识回答，并附上明确说明。
lint
操作加载
```
AGENTS.md
```
并生成健康报告（包括矛盾内容、孤立页面、过期页面、索引偏差、缺失交叉引用等）。绝不会自动修复问题；会询问用户要处理哪些问题。

每个操作都会向

log.md

追加一行内容，格式为

ISO-8601 操作类型 详情

。

Vault Contract

知识库约定

Vault location:

~/.ultrabrain/

AGENTS.md
is the single source of truth for methodology. The skill's contract with it is behavioral, not structural —

AGENTS.md

must define how to perform

ingest

query

, and

lint

, in whatever structure the methodology author prefers. The skill makes no assumptions about section headings, page types, tag schemas, or cross-reference syntax.

~/.ultrabrain/CLAUDE.md

is exactly one line:

@AGENTS.md

. This makes the vault rules auto-load if the user

cd

s into the vault inside Claude Code;

AGENTS.md

stays canonical for cross-tool compatibility.

Vault-side operations (

ingest

query

lint

) halt if

AGENTS.md

is missing. Ask the user to

bootstrap

or restore the file.

The skill treats the vault as read-only except for paths each operation is defined to touch (see

references/operations.md

知识库位置：

~/.ultrabrain/

。

AGENTS.md
是方法规则的唯一可信来源。本技能与该文件的约定是行为层面而非结构层面——

AGENTS.md

必须定义如何执行

ingest

、

query

和

lint

操作，作者可自行选择文件结构。本技能不会对章节标题、页面类型、标签架构或交叉引用语法做出任何假设。

~/.ultrabrain/CLAUDE.md

文件仅包含一行内容：

@AGENTS.md

。这样当用户在Claude Code中进入知识库目录时，会自动加载知识库规则；

AGENTS.md

保持为跨工具兼容的权威文件。

如果

AGENTS.md

缺失，知识库侧操作（

ingest

、

query

、

lint

）会终止。此时需询问用户执行

bootstrap

操作或恢复该文件。

本技能将知识库视为只读，仅会修改各操作定义中允许触碰的路径（详见

references/operations.md

）。

Methodology Swap

方法切换

The v1.0.0 default methodology is Karpathy's LLM-maintained-wiki pattern (see

references/karpathy-original.md

for the source and

references/agents-template.md

for the agent-readable rendering). To swap:

Replace
```
references/agents-template.md
```
with rules for a different methodology. Only requirement: the new template must define
```
ingest
```
,
```
query
```
, and
```
lint
```
behaviors.
Run
```
bootstrap --force
```
to wipe and rebuild the vault. Destructive — back up
```
~/.ultrabrain/raw/
```
first if you want to preserve source material for re-capture.

v1.0.0版本的默认方法是Karpathy的LLM维护维基模式（原始来源请查阅

references/karpathy-original.md

，Agent可读版本请查阅

references/agents-template.md

）。切换方法步骤如下：

将
```
references/agents-template.md
```
替换为其他方法的规则。唯一要求：新模板必须定义
```
ingest
```
、
```
query
```
和
```
lint
```
的行为。
执行
```
bootstrap --force
```
命令清空并重建知识库。此操作具有破坏性——如果想保留原始材料以便重新记录，请先备份
```
~/.ultrabrain/raw/
```
目录。

Hooks

钩子

Two hooks are available but not auto-installed:

```
SessionStart
```
— injects vault status (wiki count, unprocessed raw, last ingest) at session start so Claude is aware the vault is available.
```
PreCompact
```
— injects a reminder before context compaction to capture important session content before detail is lost.

On explicit user request ("install ultrabrain hooks"), follow

references/setup.md

to copy both hook scripts and merge the entries into

~/.claude/settings.json

using Read → diff → confirm → Edit discipline. Both hooks install as a bundle; either can be uninstalled individually later.

提供两个钩子，但不会自动安装：

```
SessionStart
```
——会话开始时注入知识库状态（维基页面数量、未处理原始内容、上次导入时间），让Claude知晓知识库可用。
```
PreCompact
```
——上下文压缩前注入提醒，以便在细节丢失前记录重要的会话内容。

当用户明确请求（如“install ultrabrain hooks”）时，遵循

references/setup.md

中的步骤复制两个钩子脚本，并采用「读取→对比差异→确认→编辑」的流程将条目合并到

~/.claude/settings.json

中。两个钩子会作为一个包安装；之后可单独卸载任意一个钩子。

References

参考文件

```
references/karpathy-original.md
```
— verbatim source methodology + attribution

references/agents-template.md

— bootstrap copies this to

~/.ultrabrain/AGENTS.md

```
references/operations.md
```
— full step-by-step for all five operations
```
references/setup.md
```
— hook install/uninstall (SessionStart + PreCompact)
```
references/hooks/session-start.sh
```
— vault status injection on session start
```
references/hooks/pre-compact.sh
```
— capture reminder before compaction

```
references/karpathy-original.md
```
——原始方法原文及署名信息

references/agents-template.md

——bootstrap操作会将此文件复制到

~/.ultrabrain/AGENTS.md

```
references/operations.md
```
——所有五种操作的完整分步流程
```
references/setup.md
```
——钩子安装/卸载（SessionStart + PreCompact）
```
references/hooks/session-start.sh
```
——会话开始时注入知识库状态的脚本
```
references/hooks/pre-compact.sh
```
——压缩前触发记录提醒的脚本