Hydration Profiles (agent/compact/audit/full)

[valiantone]

Summary

Add Hydration Profiles so different consumers get appropriately sized memory views: agent (small context), compact (minimal metadata), audit (full provenance), full (complete reconstruction).

Scope

• Add profile= to the hydrate path (CLI + API where applicable), defaulting to current behavior.
• Define per-profile inclusion rules:

  Profile	Context	Metadata	Provenance	Files
  agent	small/summarized	core only	none	none
  compact	minimal	minimal	none	none
  audit	full	full	full	refs only
  full	complete	full	full	refs + payload (lazy)

• agent truncates/summarizes long content to a bounded context size; audit/full include byte ranges, checksums, timestamps, source type.
• File-backed memories: agent/compact return metadata only; audit returns references; full may hydrate payload lazily.
• Backwards compatible: callers with no profile get the current payload shape.

Acceptance Criteria

• All four profiles produce distinct, documented payloads
• agent output is bounded (context size cap) and contains no file payloads
• audit includes full provenance + file references, no payloads
• full can lazily hydrate file payloads
• Default (no profile) matches v0.1 output shape
• Profile selection has no measurable cost when payload is not requested

Migration

Additive query param/flag. No schema change. Default behavior preserved.

Testing

• Unit: each profile returns the expected field set for inline + file-backed memories.
• Unit: agent respects the context cap; full hydrates only on request.
• Unit: default profile == current payload shape (golden test).

Depends on

• Memory Record v2 schema + provenance + migration #36 (provenance + metadata fields)
• File-backed memories (URI + range + checksum hydration) #38 (lazy payload hydration)

[valiantone]

Design addendum from recent OKF planning:

Compatibility constraints:

• Hydration profiles are response shaping only. They must not change canonical storage.
• Default behavior with no profile must match the current v0.1 payload shape.
• Existing clients and MCP tools must continue working unchanged.

Profile constraints:

• agent should be small, bounded, prompt-ready, and should not include file payload bytes.
• compact should be minimal metadata with no provenance expansion by default.
• audit should include full provenance and file references, but not eagerly hydrate file payloads.
• full may hydrate payloads, but file reads should still be lazy and explicit.

Execution constraints:

• Profile selection should avoid file I/O unless payload content is requested.
• File-backed memories must not force vector indexing.
• Profiles should make HotMem more inspectable without turning it into a hierarchy or escalation protocol.

[valiantone]

Planning sync: this ticket remains the hydration-profile work. The expanded OKF epic adds related tickets for compatibility golden tests, bundle reading/indexing, inspectors, optional vector indexing, local hygiene warnings, and native-helper exploration. Those will be created separately and linked back here so #40 stays focused on profile semantics and non-breaking response shaping.