storage-basicmemory

核心原则： 所有项目制品都必须存储在 basicmemory 的 [ProjectId] 下，并通过明确的链接和状态跟踪，确保并行项目之间的单一事实来源。

说明

开始任何工作之前，请确保已确定当前项目对应的正确 [ProjectId]。

要求：

• 使用 basicmemory mcp 工具读取和写入 [项目制品]。
• 识别 [项目制品] 的类型：[规范]、[研究]、[决策]、[史诗]、[故事]、[任务]、[回顾]。
• 使用 [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 画布文件
• basicmemory_search_notes - 搜索知识库
• basicmemory_search - 搜索知识库中的内容
• basicmemory_fetch - 获取搜索结果的完整内容
• basicmemory_recent_activity - 获取近期活动
• basicmemory_build_context - 根据记忆 URI 构建上下文
• basicmemory_list_memory_projects - 列出所有可用项目
• basicmemory_create_memory_project - 创建新项目
• basicmemory_delete_project - 删除项目
• basicmemory_list_directory - 列出目录内容
• basicmemory_sync_status - 检查文件同步状态

规划制品的 Frontmatter

规划制品的 Frontmatter 很重要。它必须以 YAML 格式保留在 Markdown 文件顶部，而不是作为 Markdown 代码块。

了解 Frontmatter

模板在顶部包含 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 的内容必须是：

---
field1: value1
field2: value2
links:
  - type: epic
    target: 2.1.1-epic-title
---
# Markdown Heading
Markdown body content here...

关键要求：

• 内容必须以 --- 开头
• Frontmatter 块必须以 --- 结尾
• Frontmatter 与 Markdown 正文之间必须空一行
• 必须保留模板中的所有 frontmatter 字段
• 不得添加 ## Frontmatter Markdown 章节 步骤 3：调用 basicmemory_write_note

basicmemory_write_note(
    title="artifact-title",
    folder="2-epics",  # or 1-prds, 3-research, etc.
    content=assembled_content,  # With frontmatter at top
    entity_type="epic",  # or spec, research, story, task, decision
    tags=extracted_tags,  # Optional, if tags are in frontmatter
    project=project_id
)

步骤 4：basicmemory 处理其余工作 basicmemory 会自动：

• 检测 YAML frontmatter（通过 has_frontmatter()）
• 解析所有 frontmatter 字段
• 从 Markdown 正文中移除 frontmatter（通过 remove_frontmatter()）
• 将所有字段保留为最终制品中的 YAML frontmatter
• 转换回带有 YAML frontmatter 的规范 Markdown

字段映射

模板中的 frontmatter 字段会成为制品中的 YAML frontmatter：

• epic_id: 1 → 以 epic_id 的名称存储在 frontmatter 中
• status: planned → 以 status 的名称存储
• priority: high → 以 priority 的名称存储
• estimated_effort: 2 weeks → 以 estimated_effort 的名称存储
• linked_spec: [...] → 以 YAML 列表的形式存储在 frontmatter 中
• derived_from: [...] → 以 YAML 列表的形式存储在 frontmatter 中 这些是结构化元数据字段，不是 Markdown 内容。

常见错误：Markdown 代码块

❌ 错误 - 创建 Markdown 代码块，导致 frontmatter 丢失：

---
title: Artifact Title
type: epic
permalink: some-path
---
# Artifact Title
## Frontmatter
\`\`\`yaml
epic_idid: 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...

实现最佳实践

1. 始终仔细解析 frontmatter - 从模板中按原样提取 YAML 块
2. 保留字段顺序 - YAML 字段顺序关系到可读性
3. 验证 YAML 语法 - 传递给 basicmemory 之前，确保 frontmatter 是有效的 YAML
4. 包含模板中的所有字段 - 不要删除字段；应与生成的字段合并
5. 使用正确的 YAML 列表 - 在 frontmatter 中使用 - 表示列表项，而非 JSON 数组
6. 测试往返过程 - 创建后，确认产物包含 frontmatter，而非 Markdown 代码块

[ProjectId] 命名和格式

ProjectId 约定：

• 格式：slugified-project-name（kebab-case，小写字母、数字和连字符）
• 来源：根据 git 仓库名称或项目名称生成
• 生成方式：./scripts/get_project_id.sh（自动转换为 slug 格式）
• 示例：
  • 仓库：github.com/username/dotfiles → ProjectId：dotfiles
  • 项目名称："用户身份验证系统" → ProjectId：user-authentication-system
  • 示例名称 "我的应用 v2" → ProjectId：my-app-v2

创建新项目

如果需要在 basicmemory 中创建新项目，请始终确保：

• 遵循 [ProjectId] 命名约定。
• 先列出已有项目，确认该项目不存在。
• 将项目存储在 ~/Notes/Projects/[ProjectId]
• 切勿将项目存储在你正在处理的仓库所在文件夹中。