用途
storage-basicmemory 用于在 basicmemory 中存储项目工件（Project Artifacts）。其核心原则是：所有项目工件都必须存储在 basicmemory 的 [ProjectId] 之下，并通过显式链接和状态跟踪，在多个并行项目之间维持单一事实来源。
在开始任何工作之前，需要先确认当前项目对应的正确 [ProjectId]。
主要能力
该技能要求使用 basicmemory 的 MCP 工具来读写 [Project Artifacts]，并识别以下工件类型：[Spec]、[Research]、[Decision]、[Epic]、[Story]、[Task]、[Retrospective]。所有工件都应使用 [ProjectId] 存入 basicmemory 中正确的项目上下文。
可用的 basicmemory MCP 工具包括：
- basicmemory_read_note - 读取 markdown 笔记
- basicmemory_read_content - 按路径读取文件原始内容
- basicmemory_view_note - 查看格式化笔记
- basicmemory_write_note - 创建/更新 markdown 笔记
- basicmemory_edit_note - 对现有笔记执行编辑操作
- basicmemory_move_note - 将笔记移动到新位置
- basicmemory_delete_note - 按标题删除笔记
- basicmemory_canvas - 创建 Obsidian canvas 文件
- basicmemory_search_notes - 在知识库中搜索笔记
- basicmemory_search - 在知识库中搜索内容
- basicmemory_fetch - 获取搜索结果的完整内容
- basicmemory_recent_activity - 获取最近活动
- basicmemory_build_context - 从 memory URI 构建上下文
- basicmemory_list_memory_projects - 列出所有可用项目
- basicmemory_create_memory_project - 创建新项目
- basicmemory_delete_project - 删除项目
- basicmemory_list_directory - 列出目录内容
- basicmemory_sync_status - 检查文件同步状态
使用方式
关键要求：所有 [Project Artifacts] 都必须通过 basicmemory MCP 工具进行交互。失败模式：不允许通过文件系统直接操作 [Project Artifacts]，否则会导致组织混乱和数据丢失。
规划工件的 Frontmatter
规划工件的 frontmatter 非常重要，它必须作为 YAML 保留在 markdown 文件顶部，而不是作为 markdown 代码块。模板在顶部包含由 --- 分隔的 YAML frontmatter 块，例如：
epic_id: 1 title: Epic Title status: planned priority: high estimated_effort: 2 weeks linked_spec:
- type: spec target: 2.1.1-spec-title
Rest of markdown content here
这是真正的 YAML frontmatter，不是 markdown 代码块。创建工件时必须原样保留该结构。
Frontmatter 保留工作流
通过 basicmemory_write_note 创建或更新规划工件时：
第 1 步：解析模板文件。提取 frontmatter 块（第一个 --- 与第二个 --- 之间的全部内容），提取 markdown 正文（闭合 --- 之后的全部内容），并将两者分开保存。
第 2 步：为 basicmemory 组装内容。传给 basicmemory_write_note 的内容必须满足：内容必须以 --- 开头；frontmatter 块必须以 --- 结尾；frontmatter 与 markdown 正文之间必须有空行分隔；模板中的所有 frontmatter 字段都必须保留；不得出现 ## Frontmatter 这样的 markdown 章节。
第 3 步：调用 basicmemory_write_note，例如：
basicmemory_write_note( title="artifact-title", folder="2-epics", # 或 1-prds, 3-research 等 content=assembled_content, # frontmatter 位于顶部 entity_type="epic", # 或 spec, research, story, task, decision tags=extracted_tags, # 可选，如果 frontmatter 中有 tags project=project_id )
第 4 步：basicmemory 会自动处理其余部分：检测 YAML frontmatter（通过 has_frontmatter()）、解析所有 frontmatter 字段、从 markdown 正文中移除 frontmatter（通过 remove_frontmatter()）、在最终工件中保留所有字段为 YAML frontmatter，并转换回带有 YAML frontmatter 的正确 markdown。
字段映射
模板 frontmatter 字段会成为工件中的 YAML frontmatter：epic_id: 1 存储为 epic_id；status: planned 存储为 status；priority: high 存储为 priority；estimated_effort: 2 weeks 存储为 estimated_effort；linked_spec: [...] 存储为 frontmatter 中的 YAML 列表；derived_from: [...] 存储为 frontmatter 中的 YAML 列表。这些是结构化元数据字段，不是 markdown 内容。
常见错误：Markdown 代码块
错误做法（会创建 markdown 代码块并丢失 frontmatter）：
title: Artifact Title type: epic permalink: some-path
Artifact Title
Frontmatter
epic_id: 1
status: planned
Rest of content...
正确做法（将 frontmatter 保留为 YAML）：
title: Artifact Title type: epic permalink: some-path epic_id: 1 status: planned
Artifact Title
Rest of content...
实现最佳实践
始终仔细解析 frontmatter，从模板中原样提取 YAML 块；保留字段顺序，YAML 字段顺序影响可读性；在传给 basicmemory 之前验证 YAML 语法；包含所有模板字段，不要丢弃字段，而应与生成的字段合并；使用正确的 YAML 列表，frontmatter 中使用 - 表示列表项，而不是 JSON 数组；创建后进行往返测试，验证工件包含的是 frontmatter 而非 markdown 代码块。
[ProjectId] 命名与格式
ProjectId 约定：格式为 slugified-project-name（kebab-case，小写字母数字加连字符）；来源为 git 仓库名或项目名；由 ./scripts/get_project_id.sh 生成（自动 slugify）。
示例：仓库 github.com/username/dotfiles → ProjectId: dotfiles；项目名 "User Authentication System" → ProjectId: user-authentication-system；示例名 "My App v2" → ProjectId: my-app-v2。
创建新项目
如果需要在 basicmemory 中创建新项目，始终确保：遵循 [ProjectId] 命名约定；先列出已有项目，确认该项目尚不存在；将项目存储在 ~/Notes/Projects/[ProjectId]；绝不将项目存储在你正在处理的仓库所在的同一文件夹中。
适用场景
适用于需要将项目工件（如规格、研究、决策、Epic、Story、Task、回顾等）集中存储到 basicmemory，并在多个并行项目之间保持单一事实来源的工作流。
限制
所有工件交互必须通过 basicmemory MCP 工具完成，禁止直接使用文件系统操作。frontmatter 必须作为真正的 YAML 保留在文件顶部，不能写成 markdown 代码块。ProjectId 必须遵循 kebab-case 命名约定，且项目不能与所在仓库存储在同一文件夹。