@meitouai/mem-note-cli 0.0.1

package/bin/conventions.md

@@ -0,0 +1,346 @@
+# mem-note 数据约定
+
+> 这份文档是 mem-note 数据目录的**真源约定**。所有写入该目录的代理（人、CLI、AI agent、外部脚本）都必须遵守。
+>
+> AI agent 在任何 mem-note skill 开始时应首先 `Read` 本文件，作为判断的依据。
+
+## 1. 核心哲学
+
+1. **文件即数据库**。所有数据是 markdown 文件，无隐藏索引 / 数据库 / 二进制状态。
+2. **CLI 最小化**。CLI 只覆盖 5 个场景：(a) hook 时 AI 不在场、(b) 人需要快捷入口、(c) 多步易错操作的封装、(d) 跨会话的一致性检查、(e) 初始化。其他所有读写由 AI agent 用原生工具（`Read` / `Write` / `Edit` / `Glob` / `Grep` / `Bash`）完成。
+3. **AI agent 负责智能**。语义判断、矛盾识别、重复检测、groom 决策全部由 skill 里的 AI agent 完成，CLI 不包含任何智能逻辑。
+4. **约定优于配置**。本文档定义的格式是硬约束；漂移由 `mem-note doctor` 发现。
+
+## 2. 目录布局
+
+```
+~/.aibox-mem-note/                   # 数据根（可由 $MEM_NOTE_DATA_DIR 覆盖）
+├── CONVENTIONS.md                   # 本文件（mem-note init 写入；已存在则跳过）
+├── notes/                           # 永久 note
+│   ├── NOTES.md                     # 根索引
+│   ├── <topic>/
+│   │   ├── NOTES.md                 # 子目录索引（必维护）
+│   │   └── <slug>.md                # 具体 note
+│   ├── skills/                      # 用户自定义 skill（保留子目录，不是 note）
+│   │   └── <skill-name>/
+│   │       ├── SKILL.md             # skill 本体（frontmatter: name, description）
+│   │       └── evals/               # 可选：该 skill 的 eval workspace
+│   └── _archived/                   # 归档的 note
+│       └── <YYYY-MM-DD>_<slug>.md
+├── inbox/                           # 待 groom 的原始输入池
+│   ├── <YYYY-MM-DD-HHMMSS>_<slug>.md
+│   └── .processed/                  # 已处理的 entry（merged / discarded）
+├── insights/                        # groom 过程产出的洞察
+│   └── <id>.md
+├── .context/                        # SessionStart / PreCompact 注入的上下文
+│   └── index.md                     # 由 groom skill 维护
+├── .reports/                        # 操作审计日志（append-only）
+│   └── <YYYY-MM-DD>.md
+└── .snapshots/                      # 可选：groom 前的快照
+    └── <snapshot-id>/
+```
+
+**特殊目录约定**：
+
+- `notes/_archived/` **不**参与任何 Glob scanning；AI agent 应显式排除
+- `notes/**/NOTES.md` 不是 note，AI agent 应显式排除
+- `notes/skills/` 是**保留子目录**，里面存的是用户自定义 skill 而不是 note：
+  - groom 不要 triage 它（不当作 inbox 输出目标，不更新 NOTES.md 条目）
+  - 任何 `Glob notes/**/*.md` 应显式排除 `notes/skills/**` 以免混入 SKILL.md
+  - 发现 user skill 时用 `Glob notes/skills/*/SKILL.md`，读 frontmatter 的 `name` + `description` 即可
+- `inbox/.processed/` 是软删除区，不参与 pending 统计
+
+## 3. Frontmatter Schema
+
+除 `CONVENTIONS.md`、`NOTES.md`、`.context/index.md`、`.reports/*.md`、
+`notes/skills/**/SKILL.md`（遵循 Claude Code skill 自有格式）外，
+所有 `.md` 文件必须有 YAML frontmatter。
+
+### 3.1 Note (`notes/**/*.md`，除 NOTES.md)
+
+```yaml
+---
+type: preference # 必填：preference | fact | lesson | reminder | note
+title: Dark mode preference # 必填：人类可读，用于 NOTES.md 索引展示
+description: > # 必填：一句话摘要，用于 NOTES.md 索引描述
+  Prefers dark mode across all editors, Monokai Pro theme.
+tags: [ui, editor] # 必填（可为空数组）：小写 kebab-case
+updated: 2026-04-10 # 必填：ISO 日期
+related: # 可选：相关 note 路径
+  - notes/user/editor-theme.md
+source: # 可选：原始来源 inbox entry 路径
+  - inbox/2026-04-09-142030_dark-mode.md
+---
+```
+
+### 3.2 Inbox entry (`inbox/**/*.md`)
+
+```yaml
+---
+type: note # 可选：保存者的初步判断；groom 时可被 AI agent 修改
+tags: [] # 可选：groom 时补充
+created: 2026-04-10-142030 # 必填：ISO 时间戳
+source:
+  terminal # 可选但推荐：去重 key
+  # 取值：terminal | hook:stop | hook:sync | auto-memory:<path>
+---
+```
+
+- `type` / `tags` **可为空**。inbox 的语义是"未分类的原始输入"，分类是 groom 的职责。
+- `source`：`mem-note save --source X` 会拒绝 source 已存在的导入（去重）。
+- 顶层 `inbox/*.md` 保持原始输入语义；当条目被移动到 `inbox/.processed/` 后，
+  处理后的副本**可以**追加一个 `processed` 对象记录处理结果，例如：
+
+```yaml
+processed:
+  status: user-ignored
+  at: 2026-04-11-090807
+  reason: Ignored by user from the mem-note inbox UI.
+```
+
+### 3.3 Insight (`insights/*.md`)
+
+```yaml
+---
+id: insight-v1K2p7 # 必填：短 nanoid
+kind: clarification # 必填：clarification | pattern | skill-candidate | contradiction | <custom>
+status: open # 必填：open | resolved | dismissed
+title: Testing framework contradiction
+created: 2026-04-10
+related:
+  - notes/user/testing-jest.md
+  - notes/user/testing-vitest.md
+---
+<自由 markdown 正文：evidence、reasoning、建议行动>
+```
+
+### 3.4 Archived note (`notes/_archived/**/*.md`)
+
+与原 note frontmatter 相同，追加一个 `archived` 字段：
+
+```yaml
+---
+type: fact
+title: Old deployment tool
+---
+archived: 2026-04-10 # 归档日期
+---
+```
+
+## 4. 文件命名
+
+| 类型          | 路径模板                                          | 示例                                      |
+| ------------- | ------------------------------------------------- | ----------------------------------------- |
+| Note          | `notes/<topic>/<slug>.md`                         | `notes/user/dark-mode.md`                 |
+| Inbox entry   | `inbox/<YYYY-MM-DD-HHMMSS>_<slug>.md` (collisions within the same second get a `-<n>` suffix before `.md`) | `inbox/2026-04-10-142030_dark-mode.md`    |
+| Archived note | `notes/_archived/<YYYY-MM-DD>_<original-slug>.md` | `notes/_archived/2026-04-10_dark-mode.md` |
+| Insight       | `insights/<id>.md`                                | `insights/insight-v1K2p7.md`              |
+
+**slug 约定**：小写 kebab-case，只含 `[a-z0-9-]`，最长 60 字符。`mem-note save` 自动从内容前若干字生成。
+
+## 5. NOTES.md 索引规则
+
+每个 `notes/` 子目录（包括 `notes/` 本身）必须维护一份 `NOTES.md` 作为该目录的人类可读索引。
+
+### 5.1 格式
+
+```markdown
+# notes/user
+
+User-scope preferences, facts, and lessons.
+
+## Notes
+
+- [Dark mode preference](dark-mode.md) — Prefers dark mode, Monokai Pro theme.
+- [Deploy lesson](deploy-lesson.md) — Always run DB migrations before deploying.
+
+## Subdirectories
+
+- [editor/](editor/NOTES.md) — Editor-specific preferences
+```
+
+### 5.2 维护契约
+
+**任何创建、重命名、归档 note 的代理都必须同步更新对应目录的 `NOTES.md`**：
+
+- 创建新 note → `## Notes` 追加 `- [<title>](<file>.md) — <description>`
+- 更新 note 的 title 或 description → 更新对应行
+- 归档 note → 从 `## Notes` 删除该行
+- 创建子目录 → `## Subdirectories` 追加条目
+- 删除空子目录 → 从 `## Subdirectories` 删除条目
+
+`<title>` 和 `<description>` 直接来自 note 的 frontmatter 同名字段。
+
+### 5.3 为什么不自动维护
+
+- NOTES.md 就地可读（人 / AI agent / git diff 都一目了然）
+- 避免"CLI 自动维护 + AI agent 手动维护"的 race
+- `mem-note doctor` 负责定期检查漂移，不靠运行时
+
+## 6. `.context/index.md` 约定
+
+`.context/index.md` 是 **groom skill 编译**出的"本会话 AI agent 应记住的核心信息"。
+SessionStart 和 PreCompact hook 都会注入它。
+
+### 6.1 结构
+
+```markdown
+# Context — 2026-04-10
+
+## Preferences
+
+- Dark mode, Monokai Pro, JetBrains Mono
+- Functional style, named exports, files under 200 lines
+
+## Active Reminders
+
+- API design review deadline: April 15
+- Tuesday 10am standup — prepare notes
+
+## Key Facts
+
+- Uses PostgreSQL 15 with PgBouncer
+- Tests: Jest (unit) + Playwright (e2e), 80% coverage
+- Planning REST → GraphQL migration (Apollo Server) in Q3
+```
+
+### 6.2 约束
+
+- `## Active Reminders` 是**必须**段落（可以为空）。groom skill 必须在每次
+  编译时扫描所有 `type: reminder` 的 note 重新生成这一段 —— 因为 PreCompact
+  hook 依赖它。
+- 整体文件大小建议 **< 2KB**。SessionStart 和 PreCompact 每次都注入，太大
+  会吃掉宝贵的 session context。
+- 由 groom skill 的最后一步 `Write` 生成，**不**由 CLI 维护。
+
+## 7. Inbox / Archive 生命周期
+
+```
+mem-note save
+    │
+    ▼
+inbox/<ts>_<slug>.md  ────── groom skill reads ──┐
+                                                 │
+                            ┌────────────────────┤
+                            │                    │
+                          merge                discard
+                            │                    │
+                            ▼                    ▼
+        notes/<topic>/<slug>.md           inbox/.processed/<original>.md
+        (+ update NOTES.md)                  (软删除)
+
+mem-note archive notes/<topic>/<slug>.md
+    │
+    ▼
+notes/_archived/<date>_<slug>.md  (+ remove from topic's NOTES.md)
+```
+
+`.processed/` 保留所有历史 inbox entry，便于回溯；不再在 listing 中出现。
+
+## 8. AI agent 的工具使用优先级
+
+AI agent 在 skill 会话中处理数据时，**优先使用原生文件工具**。
+CLI 只在下表标注的少数场景调用。
+
+| 操作                     | 首选                                                               | 不要用                             |
+| ------------------------ | ------------------------------------------------------------------ | ---------------------------------- |
+| 列出所有 note            | `Glob notes/**/*.md`（记得排除 `_archived/**`、`skills/**`、`NOTES.md`） | ❌ `mem-note list-notes`（不存在） |
+| 发现用户 skill           | `Glob notes/skills/*/SKILL.md` + 读 frontmatter                    | ❌ 任何 CLI                        |
+| 读一个 note              | `Read notes/path/foo.md`                                           | ❌ CLI                             |
+| 读某目录的索引视图       | `Read notes/<topic>/NOTES.md`                                      | ❌ CLI                             |
+| 写 / 更新 note           | `Write` / `Edit` + 记得同步 `NOTES.md`                             | ❌ CLI                             |
+| 搜索 note 内容           | `Grep "query" notes/**/*.md`                                       | ❌ CLI                             |
+| 处理 inbox entry         | `Bash mv inbox/x.md inbox/.processed/`                             | ❌ CLI                             |
+| 写 insight               | `Write insights/<id>.md`                                           | ❌ CLI                             |
+| 编译 `.context/index.md` | `Write .context/index.md`                                          | ❌ CLI                             |
+| **归档 note**            | ✅ `mem-note archive <path>`（封装多步操作）                       | `mv` + 手动更新 NOTES.md（易漏）   |
+| **检查一致性**           | ✅ `mem-note doctor`（每次 groom 末尾）                            | 手动检查（不现实）                 |
+| 追加 audit log           | `Bash` 追加 `.reports/<date>.md` 或最后一次 `Write`                | —                                  |
+
+## 9. CLI 命令清单（5 个）
+
+| #   | 命令                      | 职责                                                   | 典型调用方                       |
+| --- | ------------------------- | ------------------------------------------------------ | -------------------------------- |
+| 1   | `mem-note init`           | 幂等创建目录 + 写入 `CONVENTIONS.md`（已存在则跳过）   | 人（首次安装）                   |
+| 2   | `mem-note save <content>` | 存一条 inbox entry。支持 `--type`、`--source`、stdin   | 人 / hook / 外部脚本             |
+| 3   | `mem-note archive <path>` | 封装 "加日期前缀 + mv 到 `_archived/` + 更新 NOTES.md" | 人 / AI agent                      |
+| 4   | `mem-note doctor`         | 检查 frontmatter schema、NOTES.md 漂移、归档命名一致性 | 人 / AI agent（每次 groom 结束时） |
+| 5   | `mem-note quick-context`  | 输出 `.context/index.md` 内容（封装路径解析）          | hook (SessionStart / PreCompact) |
+
+其他一切都是 AI agent / 人用原生工具直接做。
+
+## 10. Groom Skill 默认工作流
+
+作为参考，groom skill 按以下顺序处理：
+
+1. `Read CONVENTIONS.md` —— 加载约定（若当前会话已加载可跳过）
+2. `Read notes/NOTES.md` + 感兴趣子目录的 `NOTES.md` —— 拿目录视图
+3. `Glob inbox/*.md` —— 列 pending inbox entries
+4. `Read` 每个 inbox entry
+5. 对每条 entry 决策 **create** / **merge** / **discard**：
+   - **create**：`Write notes/<topic>/<slug>.md` + `Edit notes/<topic>/NOTES.md`
+   - **merge**：`Edit notes/<topic>/existing.md` 合入新信息 + 更新 NOTES.md 的 description
+   - **discard**：无动作
+6. 所有情况都 `Bash mv inbox/<entry> inbox/.processed/`
+7. 如有冲突 / 过期 note，`mem-note archive <path>` 归档
+8. 如发现矛盾 / 模式，`Write insights/<id>.md`
+9. 重新编译 `.context/index.md`：`Write .context/index.md` 包含 Preferences / **Active Reminders** / Key Facts
+10. `Bash mem-note doctor` 检查一致性；有警告则修正
+11. `Bash` 追加一段 audit 到 `.reports/<YYYY-MM-DD>.md`
+
+## 11. Git 集成（可选但推荐）
+
+`mem-note init` 会检测 git 是否可用，可用则在数据根执行 `git init`、写入
+`.gitignore`、并做一次初始 commit。之后：
+
+- `mem-note save` / `mem-note archive` 每次成功写入后自 commit，message 形如
+  `save: <slug>` / `archive: <slug>`。
+- 插件的 Stop hook (`session-commit.sh`) 在每次 Claude Code 会话结束时兜底
+  commit 剩余未提交的改动，message 形如 `session: <ISO timestamp>`，
+  用于捕获 skill 通过 `Write`/`Edit`/`Bash mv` 直接做的写入。
+
+git 不可用时 mem-note 完全回退：所有功能照常工作，只是没有版本历史。
+
+**`.gitignore` 默认内容**：忽略 `.snapshots/` 和 OS 垃圾（`.DS_Store` 等）。
+其余所有内容（包括 `notes/`、`inbox/`、`inbox/.processed/`、`insights/`、
+`.context/index.md`、`.reports/`、`notes/skills/`）都进入 git。
+
+**为什么 `.processed/` 也 track**：虽然和 git 历史有重合，但它保留了"已处理
+inbox entry"的语义维度，方便后续 groom 或人类直接 `Read` 回溯；grep 友好。
+
+## 12. FAQ
+
+**Q: 为什么 inbox entry 的 frontmatter 可以为空？**
+A: inbox 是原始输入池。人 / hook / 外部脚本 save 时不应该被分类 schema 绑架。分类是 groom 的职责。
+
+**Q: 为什么 `archive` 有 CLI 但 `create-note` 没有？**
+A: archive 涉及"加日期前缀 + mv + 更新 NOTES.md"多步操作，手动容易漏；create 只是一次 `Write` + 一次 `Edit NOTES.md`，原生工具更透明。
+
+**Q: AI agent 怎么在会话里搜 note？**
+A: 用 `Grep "query" notes/**/*.md` 或 `Grep --glob '!**/NOTES.md' --glob '!**/_archived/**' "query" notes/`。
+
+**Q: 人想在 terminal 快速搜 note？**
+A: 用 ripgrep：`rg -i "query" ~/.aibox-mem-note/notes/`。懒的话 shell rc 加：
+
+```sh
+alias mns='rg -i ~/.aibox-mem-note/notes/'
+```
+
+**Q: 插件升级时 `CONVENTIONS.md` 会被覆盖吗？**
+A: 不会。`mem-note init` 检测到已存在的 `CONVENTIONS.md` 会跳过写入。如果 schema 升级需要迁移，由 `mem-note doctor --migrate` 处理（未来扩展）。
+
+**Q: `doctor` 检查哪些东西？**
+A:
+
+1. 每个 note 的 frontmatter 是否有必填字段（`type`、`title`、`description`、`tags`、`updated`）
+2. 每个 note 是否在对应目录的 `NOTES.md` 里有对应条目
+3. 每个 `NOTES.md` 条目是否指向存在的文件
+4. `notes/_archived/` 下的文件名是否符合 `<YYYY-MM-DD>_<slug>.md` 格式
+5. Inbox entry 的 `created` 字段是否存在
+6. `.context/index.md` 是否存在 `## Active Reminders` 段落
+
+**Q: 多个 AI agent 会话并发写怎么办？**
+A: 不支持真正的并发（没有锁）。groom 是单会话操作，假设没有并发 writer。
+
+**Q: 归档后能恢复吗？**
+A: 能。`Bash mv notes/_archived/<date>_<slug>.md notes/<topic>/<slug>.md` + `Edit NOTES.md`。没有专门 CLI 命令，因为是罕见操作。