[!NOTE] Before starting anything, ensure you have identified the correct [ProjectId] for the project you are working on.

• use basicmemory mcp tools to read and write [Project Artifacts].
• Recognise types of [Project Artifacts]: [Spec], [Research], [Descision], [Epic], [Story], [Task], [Retrospective].
• Store [Project Artifacts] in basicmemory under the correct project context using [ProjectId].

• basicmemory_read_note - Read markdown notes
• basicmemory_read_content - Read file raw content by path
• basicmemory_view_note - View formatted notes
• basicmemory_write_note - Create/update markdown notes
• basicmemory_edit_note - Edit existing notes with operations
• basicmemory_move_note - Move notes to new locations
• basicmemory_delete_note - Delete notes by title
• basicmemory_canvas - Create Obsidian canvas files
• basicmemory_search_notes - Search across knowledge base
• basicmemory_search - Search for content across knowledge base
• basicmemory_fetch - Fetch full contents of search results
• basicmemory_recent_activity - Get recent activity
• basicmemory_build_context - Build context from memory URIs
• basicmemory_list_memory_projects - List all available projects
• basicmemory_create_memory_project - Create new projects
• basicmemory_delete_project - Delete projects
• basicmemory_list_directory - List directory contents
• basicmemory_sync_status - Check file sync status

basicmemory_write_note

• Extract the frontmatter block (everything between first

  ---

  and second

  ---

  )
• Extract the markdown body (everything after the closing

  ---

  )
• Keep them separate Step 2: Assemble Content for basicmemory The content passed to

  basicmemory_write_note

  must be:

---
field1: value1
field2: value2
links:
  - type: epic
    target: 2.1.1-epic-title
---

**Critical requirements:**
- Content MUST start with `---`
- Frontmatter block MUST end with `---`
- Blank line MUST separate frontmatter from markdown body
- All frontmatter fields from template MUST be preserved
- No `## Frontmatter` markdown sections
**Step 3: Call basicmemory_write_note**
```md
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
)

• Detects the YAML frontmatter (via

  has_frontmatter()

  )
• Parses all frontmatter fields
• Removes frontmatter from markdown body (via

  remove_frontmatter()

  )
• Preserves all fields in the final artifact as YAML frontmatter
• Converts back to proper markdown with YAML frontmatter

• epic_id: 1

  → stored in frontmatter as

  epic_id

• status: planned

  → stored as

  status

• priority: high

  → stored as

  priority

• estimated_effort: 2 weeks

  → stored as

  estimated_effort

• linked_spec: [...]

  → stored as YAML list in frontmatter

• derived_from: [...]

  → stored as YAML list in frontmatter These are structured metadata fields, not markdown content.

1. Always parse frontmatter carefully - Extract the YAML block as-is from the template
2. Preserve field order - YAML field order matters for readability
3. Validate YAML syntax - Ensure frontmatter is valid YAML before passing to basicmemory
4. Include all template fields - Don't drop fields; merge with generated fields instead
5. Use proper YAML lists - Use

   -

   for list items in frontmatter, not JSON arrays
6. Test round-trip - After creation, verify the artifact has frontmatter, not markdown code blocks

• Format:

  slugified-project-name

  (kebab-case, lowercase alphanumeric + hyphens)
• Source: Derived from git repository name or project name
• Generated by:

  ./scripts/get_project_id.sh

  (automatically slugifies)
• Examples:
  • Repository:

    github.com/username/dotfiles

    → ProjectId:

    dotfiles

  • Project name: "User Authentication System" → ProjectId:

    user-authentication-system

  • Example name "My App v2" → ProjectId:

    my-app-v2

• Follow the [ProjectId] naming convention.
• Confirm the project does not already exist by listing existing projects first.
• Store the project at ~/Notes/Projects/[ProjectId]
• Never store the project in the same folder as the repo you are working on.