Module agent_notes 

agent_notes_since — walk a mem’s branch from a caller-provided cursor to the current tip and return one CommitNote per commit along the way, with the body parsed into structured fields.

This is the symmetric read-side of crate::vcs::format_commit_message: the same engine layer that writes the trailer block (Tool:, Actor:, Client:) parses it back out. Plugin and outer-repo cursor consumers that want agent-note bullets read this surface instead of shelling out to git log and re-implementing the trailer parser.

Subject shapes the engine emits (see callers of format_commit_message):

• memstead: <verb> <id> (entity CRUD: create, update, delete)
• memstead: <verb> <from> → <to> (rename, relate, unrelate)
• memstead: mem_<verb> <name> (lifecycle, with optional (config) / (seal) qualifier)

The parser captures the verb token and the remainder of the subject verbatim into entity_id — callers that need to split rename/relate arrows do so themselves; the engine does not over-structure here.

Empty-tree sentinel (EMPTY_TREE_SHA) is accepted as since and is treated as “walk every commit reachable from head” — mirrors crate::ops::changes::changes_since’s convention.

Structs

AgentNotesReport

Walked output of agent_notes_since. head echoes the resolved branch tip so callers record it as the next polling cursor without a follow-up memstead_health round-trip. memstead_ref carries the workspace-level __MEMSTEAD ref tip (unified schemas + per-mem configs) so consumers — today the outer-repo auto-commit cursor block — anchor it alongside the per-mem head without a second round-trip. None when the workspace has not been migrated to the unified layout yet.

CommitNote

One commit’s worth of structured agent-note state. Fields are populated best-effort: a body that doesn’t match the memstead: <verb> <id> subject shape leaves tool_verb / entity_id None; absent trailers leave the corresponding fields None. Callers branch on actor for agent-vs-external classification.

ParsedCommit

Parsed shape of one commit body. Mirrors the layout produced by crate::vcs::format_commit_message:

Functions

agent_notes_since

Walk the per-mem branch from since (exclusive) to the current branch tip (inclusive) and return one CommitNote per commit on the path, parsed via parse_commit_message. Order: newest first (matches git log default).

parse_commit_message

Parse one commit body — subject on the first line, optional note paragraph, then a trailer block. Trailers are recognised as lines matching <Capitalized>: <value>. The note is everything between the subject (after one blank line) and the first trailer (or end of body if none).

read_memstead_ref

Resolve refs/heads/__MEMSTEAD (unified schemas + per-mem configs) in the mem-repo gitdir shared by every writable mem. Returns None when the ref does not exist — pre-migration workspaces and fresh repos legitimately have no __MEMSTEAD yet.