Feature Request: Support custom timestamps in note frontmatter

[groksrc]

Feature Request

Users should be able to include a custom timestamp in the frontmatter of their notes to override the default file creation/modification time.

Use Case

When importing notes from other systems or creating historical records, users need the ability to set specific dates and times for their notes rather than using the current timestamp.

Proposed Implementation

Allow users to include a date or timestamp field in the YAML frontmatter:

---
title: Meeting Notes
date: 2024-03-15T14:30:00
tags: [meeting, project-x]
---

The timestamp should support standard ISO 8601 format and be used for:

• Display in the UI
• Sorting notes chronologically
• Search filters by date range
• Activity timeline

Additional Considerations

• Should support both date-only (2024-03-15) and full datetime formats
• Timezone handling (assume local timezone if not specified?)
• Backward compatibility with existing notes without timestamps
• How this interacts with the existing file modification time tracking

Benefits

• Better support for importing historical data
• More accurate chronological organization
• Improved workflow for users migrating from other note-taking systems
• Ability to backdate notes when documenting past events

[madsamjp]

Is this not a milestone anymore? Shouldn't notes have a created_date field by default? Unless I'm missing something here?

[phernandez]

@claude please implement this and open a PR. This single PR should cover both this issue (#238) and #684 — they touch the same frontmatter/timestamp code, so implementing them separately would create conflicting PRs.

Canonical fields: created / modified. BM's markdown parser already reads these from frontmatter into the entity timestamps (src/basic_memory/markdown/utils.py:59-60 maps markdown.created -> created_at, markdown.modified -> updated_at). Build on that — do not introduce a parallel created_at/updated_at or date frontmatter scheme. Accept date and created_at/updated_at as read-time aliases only if it's cheap; the written form is created/modified.

From #238 (user-supplied): honor a user-provided timestamp in frontmatter in ISO 8601, accepting both date-only (2024-03-15) and full datetime (2024-03-15T14:30:00). Assume local timezone when none is given, and normalize on write; document the tz choice. Most of the read path exists — verify it accepts date-only, and add coverage.

From #684 (system-managed): auto-write created/modified into the markdown frontmatter on note create/update so the timestamps are visible in the file, not just the DB. Respect existing values — never overwrite a timestamp the frontmatter already carries (this is exactly where #238 and #684 must agree: a user/frontmatter-set value wins; BM only fills what's missing and bumps modified on its own writes). Preserve backward compatibility for existing notes that have no timestamp fields.

Trace the round-trip and cover both ends:

• Read: src/basic_memory/markdown/entity_parser.py (where markdown.created/markdown.modified originate) and src/basic_memory/markdown/utils.py.
• Write/serialize: the entity -> markdown/frontmatter serialization path used on create/update (src/basic_memory/services/entity_service.py and the markdown writer / file_service). Find where frontmatter is emitted and make it write created/modified.

Tests:

• Unit: parse date-only + full datetime + explicit tz; "existing frontmatter timestamp is preserved, not overwritten"; auto-fill of missing created/modified on create.
• Integration (test-int/): round-trip a note through the file<->DB loop and assert created/modified are present and valid in the file's frontmatter, and that a hand-set created survives a subsequent edit.

Open decisions to state in the PR: exact tz normalization/format on write, and whether/which read-time aliases you accept.

Conventions: sign commits (git commit -s); PR title feat(core): <summary>; run just fast-check and the new tests before opening the PR.

[claude]

Claude finished @phernandez's task in 21m 46s —— View job • claude/issue-238-20260716-1955 • Create PR ➔

---

Done

Implemented custom + auto-managed timestamps in note frontmatter, covering both #238 (user-supplied) and #684 (system-managed), on the canonical created/modified fields.

Plan:

• Read markdown parsing/serialization code (entity_parser.py, utils.py, entity_service.py, markdown writer/file_service)
• Read path: entity_parser.py now honors a created/modified value in frontmatter (ISO 8601, date-only or full datetime) instead of always deriving timestamps from file stat times. Naive values are assumed local time via .astimezone(); explicit UTC offsets are preserved. Cheap read-time aliases date, created_at, updated_at are also accepted. Falls back to file stat times, then "now", when frontmatter has neither.
• Write path: apply_default_timestamps() (new helper in markdown/utils.py) is wired into create, full-update, and edit flows in entity_service.py. created is filled once and preserved afterward (never overwritten by BM); modified is bumped to "now" on every BM-initiated write unless the request itself explicitly supplies a modified value.
• Unit tests: date-only/full-datetime/explicit-tz parsing, alias handling, fallback-to-file-stats (tests/markdown/test_entity_parser.py); preserve-existing-created / bump-modified semantics across create/update/edit, updated two pre-existing tests whose exact-frontmatter-dict assertions needed to account for the new fields (tests/services/test_entity_service_prepare.py)
• Integration test: file↔DB round trip via write_note/edit_note MCP tools, asserting created/modified land in the persisted file's frontmatter and that a hand-set created survives a subsequent edit (test-int/mcp/test_frontmatter_timestamps_integration.py)
• Run just fast-check and targeted tests — could not run, see note below
• Commit (signed off), push, open PR

Open decisions (per the request):

• TZ normalization on write: BM always writes ISO 8601 with the local UTC offset (datetime.now().astimezone().isoformat()), e.g. 2026-07-16T20:03:49.123456+00:00.
• Read-time aliases accepted: date and created_at → created; updated_at → modified. The canonical written form is always created/modified.
• Scope boundary: move_note doesn't bump modified (it only changes location/permalink, not content). Edits to notes with no existing frontmatter block don't gain one just to add timestamps — this only activates for notes that already carry (or are gaining) frontmatter via create/update.

⚠️ Could not run just fast-check / tests: this sandbox has no just, uv, or project dependencies installed, and pip install/git diff piping requires an approval this headless run can't grant. I verified the change with python3 -m py_compile on all touched files, a manual line-length pass (100-char limit) against only the lines I added, and an empirical check of the exact yaml.dump/yaml.safe_load round-trip behavior for our timestamp strings (confirms they stay strings, not auto-parsed dates, after our frontmatter serialization). I also manually traced every existing test in the repo that could plausibly break from added created/modified frontmatter keys and updated the two that needed it. Please run just fast-check and just test on the PR branch (or update --allowedTools) to confirm before merging.

[phernandez]

Implementation decision after reviewing #1089

We will implement #238 independently before the managed-write behavior in #684.

Scope and contract

• Canonical markdown fields are created and modified.
• Accept ISO 8601 date-only and full datetime values.
• A naive value is interpreted in the machine's local timezone; an explicit offset is preserved.
• Frontmatter values are authoritative when present. Existing filesystem creation/modification times remain the fallback when they are absent.
• Parse timestamps exactly once into timezone-aware datetime values.
• Carry those typed values through prepared entity state, local indexing, DB-first accepted/cloud writes, search-index refresh, and materialization. Downstream layers must not reparse entity_metadata.
• Entity.updated_at must not use a blanket ORM onupdate=now; incidental checksum, relation, reindex, and materialization updates must not change the note's semantic timestamp.
• File bookkeeping remains separate: checksum, size, and physical mtime may change without changing semantic created_at / updated_at.
• Passive indexing does not rewrite or inject frontmatter.
• Read-time aliases are out of scope for the first implementation. They were optional and add write-normalization ambiguity; add them later only with an explicit compatibility contract.

Required verification

Coverage must prove the final file and DB values through:

• direct file indexing and reindexing;
• MCP/API note creation;
• DB-first accepted/cloud create and update;
• materialization;
• a date-only value, naive datetime, and datetime with explicit offset;
• notes without timestamp frontmatter continuing to use filesystem fallbacks.

The replacement PR for this scope should close #238. #684 will build on this foundation separately.