hm_timeline

Search the timeline for past events, decisions, and activity. The timeline is backed by a separate PostgreSQL database with full-text search (tsvector).

Parameters

Parameter	Type	Default	Description
`query`	`str \| None`	`None`	Full-text search query
`node_key`	`str \| None`	`None`	Filter entries related to a specific graph node key
`period`	`str \| None`	`None`	Relative window (`1h`, `3h`, `6h`, `12h`, `24h`, `7d`, `14d`, `30d`, `90d`, `1y`)
`start`	`str \| None`	`None`	Range start (ISO 8601, e.g. `2026-02-09T15:00:00`)
`end`	`str \| None`	`None`	Range end (ISO 8601)
`limit`	`int`	`50`	Maximum events returned

How the timeline works

The timeline is auto-logged — meaningful tool calls (hm_store, hm_update, hm_forget, hm_ingest) automatically produce human-readable diary entries. Bootstrap tools (hm_get_overview, hm_list_files, etc.) are skipped to avoid noise.

The timeline is not loaded automatically during hm_recall. It is only returned on explicit request via hm_timeline. This keeps graph search fast and focused.

Example

{
  "query": "API migration decisions",
  "period": "30d"
}

CLI equivalent

hm timeline --query "API migration decisions"

REST endpoint

POST /api/v1/memory/timeline

hm_timeline_write

Write an explicit diary entry to the timeline. Use this for decisions, milestones, or events that should be recorded outside of normal tool usage.

Parameters

Parameter	Type	Default	Description
`summary`	`str`	required	Diary entry text
`meta`	`dict \| None`	`None`	Optional structured metadata

Example

{
  "summary": "Decided to migrate from REST to GraphQL for the public API. Approved by Sarah and Marcus."
}

CLI equivalent

hm timeline-write "Decided to migrate from REST to GraphQL for the public API"

REST endpoint

POST /api/v1/memory/timeline/write