MemoryController class final

Controls the agent's durable memory across sessions and projects.

Constructors

MemoryController({required ExecutionEnv env, String? projectRoot, String? userRoot, LlmProvider? llmProvider, String? projectStoragePath, String? userStoragePath, Future<MemoryConfig?> configSource()?, void onConfigChanged()?, void onDegrade(String message)?, void printSink(String message)?})

Properties

configSource → Future<MemoryConfig?> Function()?
Runtime config freshness: invoked before every memory operation; a non-null result REPLACES the active memory: section — stores whose resolved path changed are dropped and re-created lazily at the new location (editing .fah/config.yaml takes effect without a restart). A thrown error keeps the current config (a mid-session yaml typo must not kill memory ops; the next successful read recovers).
final
hashCode → int
The hash code for this object.
no setterinherited
isMaintaining → bool
True while a maintain run is in flight (the phase 2 running guard).
no setter
onConfigChanged → void Function()?
Invoked after a config swap actually changed the resolved store paths (the host re-composes its <memory> prompt section here).
final
onDegrade → void Function(String message)?
Observability breadcrumb for the gh-1393 degrade paths (LLM-backed search falling back to keyword, an unusable scope skipped, an add retrying through the provider-less plain store). The swallows are the ticket's intent — memory tools NEVER throw — but they must not be silent: the host (app AppLog, CLI diagnostics) wires its log here; null keeps the historical quiet behavior.
final
printSink → void Function(String message)?
Print interceptor for the flutter_agent_memory package's bare print() debug logs (gh-1510). The package logs with // ignore: avoid_print on the calling isolate; in TUI mode stdout IS the terminal, so those raw bytes interleave with the frame protocol, physically clobber cells, and the cell-diff renderer then skips repainting "unchanged" cells against the desynced grid — the screen buffer loses characters (memory round-tripcomplete). Every package-facing op runs inside a zone whose print delegates here; the CLI wires its diagnostic log. Null keeps the package's default print behavior (headless/embedders).
final
projectStore → Future<KBMemoryStore>
Lazily initializes the project-scope store + search engine.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
userStore → Future<KBMemoryStore?>
Lazily initializes the user-scope store + search engine.
no setter

Methods

add({required String text, String type = 'note', List<String> tags = const [], double importance = 0.5, String scope = 'project'}) → Future<MemoryEntry>
Adds a memory entry (project scope by default).
delete(String id, {String? scope}) → Future<String?>
Deletes a memory entry by id. With no explicit scope, scans project then user storage. Returns the scope it was deleted from, or null when the id exists in neither.
formatPromptSection() → Future<String>
Formats a ≤2 KiB <memory> block for the system prompt.
lastMaintenanceAt() → Future<DateTime?>
Reads the last-maintenance timestamp (null when never maintained).
list({int limit = 20}) → Future<List<MemoryEntry>>
Lists recent entries from both scopes (project first, then user).
maintain() → Future<bool>
Phase 2: runs maintainMemoryLevels() + consolidate() on both scopes sequentially (smol-role cost class). Guarded: a second call while one runs is a no-op returning false. Consolidation needs an LLM provider — without one only level maintenance runs.
maintenanceDue() → Future<bool>
True when maintenance is due: never run, or > maxMaintenanceAge old.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
noteAddForMaintenance() → bool
Records an add toward the maintenance counter. Returns true when the threshold was just crossed (host should schedule maintenance).
Searches both scopes (project first, then user).
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

addsBeforeMaintenance → const int
maxMaintenanceAge → const Duration
Maintenance cadence: due when the last run is older than 24 h.