Auto-sync entity created_at / updated_at timestamps into frontmatter

[bm-clawd]

Currently, Basic Memory tracks created_at and updated_at timestamps at the entity level (visible in JSON output via API/MCP), but these timestamps don't appear in the markdown files themselves.

Current behavior:

• Entity timestamps exist in the database
• They're accessible via JSON output
• Frontmatter doesn't include them unless manually written/maintained

Desired behavior:

• BM automatically writes created_at and updated_at into YAML frontmatter when creating/updating notes
• These fields would be managed by BM itself (not AI/user-maintained)
• Timestamps would be visible in the plain-text files, not just the database

Use cases:

• Consistent timestamp metadata across all notes without manual maintenance
• Temporal queries/filters based on frontmatter (e.g., "notes created this week")
• Better compatibility with tools that read frontmatter but not BM's database
• Fits BM's transparency philosophy: important metadata should be in the file itself

Suggested implementation:

• Auto-inject created_at on note creation
• Auto-update updated_at on note modification
• Make these "reserved" frontmatter fields (schema validation aware, but not user-editable)
• Respect existing timestamps if already present (don't overwrite manual entries)

Related:

• Picoschema metadata: section could declare these as system-managed fields
• Would complement existing frontmatter features (status, tags, priority)

[claude]

Claude finished @bm-clawd's task in 58s —— View job

---

Triage Analysis

• Read and understand the issue
• Search for duplicate issues
• Classify issue type, priority, and complexity
• Add appropriate labels
• Provide triage summary

---

Summary

Type: Enhancement (improvement to existing feature)

Priority: Medium — improves transparency and compatibility with external tools, aligns with BM's "files as source of truth" philosophy, but not blocking any core functionality.

Component: Database/sync + MCP tools (write_note, edit_note)

Complexity: Medium — requires changes across the markdown writing pipeline, sync layer, and potentially frontmatter parsing.

---

Duplicate Check

No exact duplicate found. Related issue: #616 (Temporal query optimization) touches created_at/updated_at as search dimensions, but focuses on querying — not on writing timestamps into frontmatter. These are complementary, not duplicates. Implementing this issue would actually help #616 by making dates visible in frontmatter for temporal filtering.

---

Implementation Notes

Key areas to touch:

• src/basic_memory/markdown/ — frontmatter serialization when writing notes
• src/basic_memory/services/ — entity write/update logic to inject timestamps
• src/basic_memory/sync/ — ensure timestamps are preserved across sync
• Need to handle the "reserved fields" concept (don't overwrite user-set values on first write, but manage on subsequent updates)

Edge cases to consider:

• What happens when a file is imported with existing created_at in frontmatter? (Respect it.)
• What format for timestamps? ISO 8601 is likely the right choice.
• updated_at should reflect file modification time, not DB update time — these should stay in sync.

Labels added: enhancement, medium, database, mcp

[bm-clawd]

Additional context from Discord #help

Expected behavior (per Drew Nellins):

• If created_at/updated_at exist in frontmatter → those should be authoritative (override DB)
• If they're missing → DB manages them automatically

Current observed behavior (per @titan):
When trying to validate these fields via schema:

schema:
  metadata:
    created_at:
      type: string
      format: datetime
    updated_at:
      type: string
      format: datetime

Result: validation treats metadata: itself as a required observation, not as a frontmatter section.

Root issue:
Picoschema currently validates observations and relations but not frontmatter fields. This means:

• Frontmatter can contain arbitrary YAML (by design)
• But schemas can't enforce which frontmatter fields exist or their types
• Timestamp fields in frontmatter may not be getting preserved/respected

Test needed:

1. Create note with created_at: 2024-01-01T10:00:00Z in frontmatter
2. Index it
3. Read entity JSON via API/MCP
4. Verify: does entity['created_at'] match frontmatter value or DB auto-generated value?

cc @titan for original use case