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()?})

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
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.