gbrain 脑库文件归档规则（Repo Architecture）：以主题为中心的文件归档决策协议

人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载导读repo-architecture是 gbrain 技能体系中专门回答这份新内容该归档到哪里的技能无论是从 PDF、邮件、会议记录还是原始数据导入中产生的脑库页面brain page它都强制按**内容的首要主题primary subject**决定归档目录而不是按文件格式或来源。读完本文你将掌握 gbrain 脑库的完整归档决策树、sources/目录的边界与特许例外、反向链接back-linking与引用citation铁律以及从技能契约到src/core/filing-audit.ts源码级的自动化校验机制。一、技能定位脑库写作技能的公共参考repo-architecture技能的完整定义位于 plugin/skills/repo-architecture/SKILL.md与 skills/repo-architecture/SKILL.md 内容一致它在技能清单 skills/manifest.json 中被描述为Where new brain files go. Filing rules and directory conventions新脑库文件去哪归档规则与目录约定并被定位为所有脑库写作技能的参考基准。该技能的前置元数据定义了它的触发场景与运行方式name: repo-architecture version: 1.0.0 description: | Where new brain files go. Decision protocol for filing brain pages by primary subject, not by format or source. Reference for all brain-writing skills. triggers: - where does this go - filing rules - create new page - which directory tools: - search - get_page - list_pages mutating: false注意mutating: false该技能本身不写脑库页面它只做分类建议因此不会触发 src/core/filing-audit.ts 中对writes_pages: true技能的归档目录审计。从路由角度看skills/RESOLVER.md 将触发词 Where does a new file go? / Filing rules 映射到本技能而更贴近脑库分类学家语义的触发词where does this brain page go、taxonomy check、refile brain page则路由到 skills/brain-taxonomist/SKILL.md —— 后者是写时归档门filing gaterepo-architecture则在其Integration with Other Skills一节被明确记录为delegates the filing decision to this skill将归档决策委托给 brain-taxonomist。二、核心契约Contract该技能承诺保证以下三条这是所有脑库写入方ingest、meeting-ingestion、idea-ingest、capture 等都必须遵守的底线每个新页面按首要主题归档而不是按格式它是 PDF 所以进 sources/或按来源它来自邮件所以进 sources/歧义情况必须走决策协议而不是随机猜测常见错误归档模式会被识别并拦截即下文反模式。三、归档决策协议Phases / Decision Tree技能的四个阶段完整如下识别首要主题Identify the primary subject问自己——如果未来要再找到这个页面你会用什么关键词搜索走决策树Walk the decision tree关于某个人 →people/{name-slug}.md关于某家公司 →companies/{name-slug}.md可复用的概念/框架 →concepts/{slug}.md原创想法 →originals/{slug}.md一场会议 →meetings/{slug}.md媒体内容 →media/{type}/{slug}.md原始数据导入 →sources/{slug}.md交叉链接Cross-link从相关目录反向链接到本页面可注明性检查Check notability见 skills/conventions/quality.md 的 notability gate。这套简化的七分支决策树在 skills/_brain-filing-rules.json 中被扩展为更完整的机器可读规则集下文第五节详述包括people/、companies/、deals/、meetings/、concepts/、projects/、analysis/、civic/、writing/、guides/、tech/、finance/、personal/、ideas/、research/、originals/、voice-notes/、openclaw/、daily/、media/、conversations/以及特殊目录sources/。四、输出格式Advisory建议而非执行技能规定输出必须是一种建议性陈述明确给出归档目标与理由Advisory: File this at{type}/{slug}.mdbecause the primary subject is {reason}.例如File this atcompanies/acme-corp.mdbecause the primary subject is a company (Acme Corp), not the PDF it came from.这条建议由 brain-taxonomist 实现为更结构化的推荐块见 skills/brain-taxonomist/SKILL.md包含 File at / Reasoning / Matched page_type / Active pack / Source 五个字段当歧义时通过skills/ask-user/向用户呈现 2 个候选绝不静默替用户做决定。五、完整归档规则库_brain-filing-rules.md详解技能正文引用 skills/_brain-filing-rules.md 作为完整规则源这份文件对所有写入脑库的技能都是**强制MANDATORY**的。其核心规则只有一句话内容的 PRIMARY SUBJECT 决定它归档到哪里。不是格式不是来源也不是正在运行的技能。5.1 决策协议Decision Protocol识别首要主题一个人公司概念政策议题归档到与主题匹配的目录从相关目录交叉链接拿不准时问自己以后会用什么关键词再找到这个页面5.2sources/的真正用途sources/只用于批量数据导入API 转储、CSV 导出、快照喂给多个脑库页面的原始数据如访客导出、联系人同步周期性捕获季度快照、同步导出。如果内容有一个明确的主题人、公司、概念、政策议题它就绝不属于sources/。5.3 可注明性门槛Notability Gate不是所有内容都值得建脑库页面。在创建新实体页面前必须检查人物你以后还会与其互动吗与你的工作相关吗公司与你的工作或兴趣相关吗概念这是未来值得引用的可复用心智模型吗拿不准就不建缺失的页面以后可以补建而垃圾页面会浪费注意力并降低搜索质量。skills/conventions/quality.md 给出了同样的门槛判定并补充了一个现实例子一个只有 400 粉丝、只发过一条推文的人不足以建页。5.4 反向链接铁律Iron Law: Back-Linking每一条提及了已有脑库页面的人或公司的记录都必须在被提及实体的页面上创建反向链接——这是双向的新页面链接到实体实体的页面也要链接回来。反向链接格式追加到 Timeline 或 See Also- **YYYY-MM-DD** | Referenced in page title -- brief context规则的最后一句话是An unlinked mention is a broken brain. The graph is the intelligence.未链接的提及就是断裂的大脑图谱即智能。skills/conventions/quality.md 以同样措辞强制了这一要求。5.5 引用要求Citation Requirements写入脑库页面的每个事实都必须携带内联[Source: ...]引用三种格式直接归因[Source: User, {context}, YYYY-MM-DD]API/外部[Source: {provider}, YYYY-MM-DD]或[Source: {publication}, {URL}]综合[Source: compiled from {list of sources}]来源优先级高到低① 用户的直接陈述最高权威→ ② 已编译事实既有脑库综合→ ③ 时间线条目原始证据→ ④ 外部来源API 增强、网络搜索最低。当来源冲突时同时标注双方引用不得静默二选一。5.6 原始来源保存Raw Source Preservation每条被摄取的内容都应保留原始来源以保证溯源provenance按大小自动路由通过gbrain files upload-raw实现 100 MB 的文本/PDF留在脑库 git 仓库中以.raw/边车目录与脑库页面并列存放 100 MB 或媒体文件视频、音频、图片上传到云存储Supabase Storage、S3 等在脑库仓库中留下.redirect.yaml指针 100 MB 的文件使用 TUS 断点续传6 MB 分块 重试。上传命令gbrain files upload-raw file --page page-slug --type type返回 JSON小文件为{storage: git}云存储为{storage: supabase, storagePath, reference}。.redirect.yaml指针格式target: supabase://brain-files/page-slug/filename.mp4 bucket: brain-files storage_path: page-slug/filename.mp4 size: 524288000 size_human: 500 MB hash: sha256:abc123... mime: video/mp4 uploaded: 2026-04-11T... type: transcript访问已存储文件gbrain files signed-url storage-path # 生成 1 小时有效期的签名 URL gbrain files restore dir # 下载回本地这样任何派生脑库页面都能追溯回原始来源且大文件不会撑爆 git 仓库。六、常见错误归档模式Anti-Patterns技能正文明确列出的反模式按格式归档它是 PDF所以进 sources/按来源归档它来自邮件所以进 sources/不先检查是否已存在就创建页面把sources/用于原始数据转储之外的任何内容。skills/_brain-filing-rules.md 将反模式扩展为一张对照表每条都给出错 → 对 → 原因错误正确原因话题分析 →sources/→ 对应主题目录sources/ 只放原始数据关于某人的文章 →sources/→people/首要主题是人会议衍生的公司信息只进meetings/→ 同时更新companies/实体传播entity propagation是强制要求关于某公司的研究 →sources/→companies/首要主题是公司可复用框架/论点 →sources/→concepts/它是心智模型关于政策的推文串 →media/→civic/或concepts/media/ 是内容运营目录七、特许例外综合输出 sui generissynthesis output按首要主题归档是原始摄取raw ingest的规则。对于一对一、单源且面向特定读者的综合输出如个性化书籍镜像 book-mirror、绑定到单一问题的战略阅读 playbook按主题归档会丢失这就是那本书的维度按作者归档又会混淆作者页与综合页。因此media/format/slug格式前缀路径是特许例外media/books/slug-personalized.mdbook-mirror 输出media/articles/slug-personalized.md长文个性化media/format/用于原始摄取仍然是反模式例外很窄综合的、一对一的、单源 sui generis 输出。八、Dream-cycle 综合/模式目录v0.23 起gbrain dream的synthesize与patterns阶段只能写入固定允许清单allow-list该清单由 skills/_brain-filing-rules.json 的dream_synthesize_paths.globs数组定义。编辑该 JSON 是添加综合子代理可写目录的唯一方式输出类型Slug 模式存放内容反思 Reflectionwiki/personal/reflections/YYYY-MM-DD-topic-hash[:6]自我认知、情绪处理、模式识别。用户的逐字引用 分析。原创想法 Original ideawiki/originals/ideas/YYYY-MM-DD-idea-hash[:6]新框架、论点、心智模型。保留用户的原话——那才是工件。人物增强 People enrichmentwiki/people/existing-slug会话提及追加到已有人员页的时间线重要新人建桩页。模式 Patternwiki/personal/patterns/theme跨 ≥3 次反思检测到的跨会话主题。最高杠杆输出若反思引用带日期内容一个模式可横跨 25 年。周期摘要 Cycle summarydream-cycle-summaries/YYYY-MM-DD一个 dream 周期产出的所有页面索引。由编排器确定性自动写入。综合输出的六条铁律① 逐字引用用户引号只用于可精确复现的片段dream.synthesize.quote_verify默认开启写入后以零 LLM 的机械化校验重查每个引用片段② 强制交叉引用每个新页面必须链接到既有脑库内容③ slug 纪律——仅小写字母数字与连字符、斜杠分隔禁止下划线与扩展名④ 编辑过的转录必须产生新 slug内容哈希后缀变化绝不静默覆盖旧反思⑤ 保留具体事实数字、日期、金额、姓名、谁决定什么不做例行后勤记录⑥ 每条论断都要有来源依据推测必须标注为推测。九、Takes 归属规则v0.32当写入!--- gbrain:takes:begin --栅栏时holder 列记录的是谁相信这条论断而不是这条论断关于谁。跨模态评测对 10 万条生产 takes 的归属打分仅为 6.5/10holder/subject 混淆是第一错误源。完整规则见 docs/takes-vs-facts.md六条契约如下Holder ≠ Subject此人是否说过或明确暗示过是 →holder people/slug否是你对 TA 的分析→holder brain。例如 Garry 有英雄/救赎者模式 →holderbrain是对 Garry 的分析不是 Garry 自己说的原子化论断复合行拆成多行每行一条论断转发 ≠ 背书仅转发信号上限weight 0.55自述 ≠ 已验证Saif 自报 7 位数收入 →holderpeople/saif,weight0.75而非holderworld/1.0不要虚假精度只用 0.05 步进0.35、0.55、0.75引擎层插入时会四舍五入到该网格So what 测试跳过元数据式琐事Twitter 账号、粉丝数、显而易见的个人资料字段一条 take 必须对未来某个查询有承载价值。Holder 合法格式v0.32 起为解析器警告v0.33 为错误world共识事实无个人声称者、brainAI 推断holder 确实模糊、people/slug个人陈述的信念、companies/slug机构事实无个人声称者。Slug 使用标准文法[a-z0-9._-]Garry、people/Garry-Tan、world/garry-tan均校验失败。另有创始人描述自家公司规则创始人说我们能到 $10M ARR →holderpeople/bo-lu而不是holdercompanies/clipboard-health——公司不说话员工才说话。十、机器可读规则与源码级校验10.1_brain-filing-rules.json规则的单一事实来源skills/_brain-filing-rules.json 是机器可读的规范化归档规则companion 字段指向人类可读的 .md 版其头部注明This JSON is what gbrain check-resolvable audits against这是gbrain check-resolvable审计的依据。除rules[]数组每种 kind 对应 directory、examples、description与sources_dir约束外它还承载了上一节的dream_synthesize_paths允许清单——注意其描述synthesize 阶段读取该清单并作为allowed_slug_prefixes线程传给每个子代理put_page 在服务端强制执行。10.2filing-audit.ts技能清单层面的确定性审计src/core/filing-audit.ts 是技能化检查清单skillify checklist第 6 项的实现。它对每个声明writes_pages: true的技能做声明级审计技能必须在 frontmatter 声明非空的writes_to: [dir, ...]writes_to:中的每个目录必须是 skills/_brain-filing-rules.json 中的合法归档目标sources/被显式放行因为批量数据捕获是合法归档目标。其源码注释特别区分了两个易混字段mutating: true表示有副作用cron、配置、报告写入等任何副作用而writes_pages: true表示向语义目录写脑库页面——cron/配置/报告类技能只设mutating: true而不设writes_pages: true从而正确豁免于归档审计噪音对应设计决策 D-CX-7。审计逻辑runFilingAudit对skillsDir下每个含SKILL.md的子目录解析 frontmatter → 过滤出writes_pages: true的技能 → 检查writes_to缺失filing_missing_writes_to或目录不在allowedDirectories集合内filing_unknown_directory两者均为 warning 级并给出可执行的修复建议修改SKILL.md的writes_to或在 JSON 的rules[]中新增目录。目录归一化函数normalizeDir将people、people/、/people、/people/统一为people/以便比较。10.3 与相邻技能的协作边界skills/brain-taxonomist/SKILL.md写时归档门。它没有硬编码目录表每个决策都通过gbrain schema show --json读取当前激活的 schema packgbrain-recommended或用户自定义 pack这比repo-architecture的固定决策树更进一步——支持多脑用户Persona B通过--source id获得按源不同的归档建议skills/eiirp/SKILL.mdEverything In Its Right Place——工作会话结束后的 7 阶段总整理器其中 Phase 2 TAXONOMY 对清单中每个输出调用 brain-taxonomistskills/_AGENT_README.md代理调用技能时的契约——若技能 frontmatter 声明writes_pages:/writes_to:必须查阅 skills/_brain-filing-rules.md 确认文件路径是被认可的。十一、实战流程示例一次完整的归档决策假设你刚通过邮件收到一份某家公司的季度研究分析需要决定归档位置识别首要主题主题是那家公司分析对象不是邮件也不是 PDF走决策树关于某家公司 →companies/而不是来自邮件 →sources/或是 PDF →media/归档companies/acme-corp.mdfrontmatter 携带匹配的type:正文每个事实带[Source: ...]引用交叉链接新页面链接到相关概念页、人物页同时在companies/acme-corp.md的时间线追加反向链接条目- **YYYY-MM-DD** | Referenced in 研究分析 -- 季度研究保留原始来源邮件里的 PDF 若 100 MB 留在.raw/边车目录否则走gbrain files upload-raw上云并留.redirect.yaml指针可注明性检查这家公司与你工作相关吗若只是偶然出现的一次性实体遵守拿不准就不建。结语repo-architecture看似只有一页决策树背后却是一套完整的分层归档治理体系技能正文提供面向所有写作技能的简短决策协议skills/_brain-filing-rules.md 承载人类可读的完整规则反向链接、引用、原始来源、综合例外、dream-cycle 路径、takes 归属skills/_brain-filing-rules.json 提供机器可读的规范事实源而 src/core/filing-audit.ts 在技能声明层面自动拦截不合规的writes_to目录。三者共同保证 gbrain 脑库按主题、可追溯、可链接的图结构不被混乱归档侵蚀——这正是图谱即智能的工程化落点。赞分享人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载相关推荐wger数据归档策略基于数据年龄的健身数据归档规则wger数据归档策略基于数据年龄的健身数据归档规则 还在为健身数据堆积如山而烦恼wger作为开源自托管的健身追踪平台提供了智能的数据归档机制帮助您有效管后端医疗健康Vant CLI 组件库模板中的组件文档规范以 DemoButton 示例组件为例Vant CLI 组件库模板中的组件文档规范以 DemoButton 示例组件为例 导读 本文以 create vant cli app 脚手架为 Vue 3前端UI组件上一篇React-Boilerplate LocalStorage本地存储与状态持久化终极指南下一篇ArchiveBox v1 Personas API 详解Persona 列表与浏览器身份同步接口v1_personas 模块创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考