Memory & Persona Management
Relevant source files
The following files were used as context for generating this wiki page:
Memory and Persona Management in Flow constitutes the "cognitive layer" of the platform, enabling agents to maintain long-term context across disparate execution cycles. This system ensures that agents do not treat every interaction as a "cold start" by persisting factual observations, reasoning patterns, and user-specific preferences.
The system is split into two primary domains: Tiered Memory (Episodic and Semantic) and Persona Management (SOUL.md). Memory focuses on factual and procedural retention from runs, while Persona management handles the high-level identity and behavioral constraints of the agent based on user identity and historical preferences.
Sources: README.md:1-15, apps/web/src/app/(app)/memory/page.tsx:112-118
Tiered Memory Architecture
Flow utilizes a tiered memory system to balance immediate context with long-term knowledge retrieval. This is managed primarily through the FlowMemoryMiddleware, which handles the injection of relevant memories before an agent runs and the extraction of new information after the run completes.
Memory Tiers
The system distinguishes between two main types of memory:
| Tier | Description | Storage/Retrieval Mechanism |
|---|---|---|
| Episodic | Summaries of previous runs and specific interaction events. | Captured after successful runs; retrieved via AsyncPostgresStore. |
| Semantic | General facts, embedded preferences, and promoted observations. | Stored as vectors (pgvector) for retrieval at planner-time. |
Sources: apps/web/src/app/(app)/memory/page.tsx:112-118, README.md:105-110, services/api/flow/infrastructure/llm/middleware/memory.py:102-125
Memory Lifecycle
The memory lifecycle is integrated into the agent execution pipeline via middleware.
The before_agent hook retrieves facts and patterns from the vector store based on the current user query, limiting results to a configurable maximum (default 8 facts). The after_agent hook uses an LLM judge to extract new facts and reasoning patterns from the agent's response to be persisted for future use.
Sources: services/api/flow/infrastructure/llm/middleware/memory.py:82-160
Persona & User Preferences
The Persona system, referred to as SOUL.md, defines the identity block injected as the first system message in every agent run. It is a synthesis of manual user input, historical preferences, and learned behaviors.
SOUL.md and Identity
The identity of an agent is dynamic and can be updated through several channels:
- Questionnaire: A structured process (
SOULQuestionnaire) where users define their role, passions, communication style, and focus. - Preference Learning: Automated extraction of user preferences (style, tooling, goals, etc.) from conversations.
- Manual Edits: Direct modification of the
SOUL.mdmarkdown block.
Preference Classification
The middleware extracts and weights preferences across several classes to ensure the agent adheres to user expectations.
| Preference Class | Example/Description |
|---|---|
| Style | Tone, level of detail, or formatting preferences. |
| Tooling | Preferred software, libraries, or developer tools. |
| Goal | High-level objectives currently prioritized by the user. |
| Veto | Patterns or actions the AI is explicitly instructed NOT to do. |
| Domain | Specific industries or technical areas of focus. |
Preferences have a score and status (provisional or active). Scores decay over time unless reinforced, and "provisional" preferences must "graduate" to active status before becoming permanent parts of the profile.
Sources: services/api/flow/infrastructure/llm/middleware/memory.py:53-75, apps/web/src/components/preferences/PersonaSection.tsx:16-25
Skill Management
Skills are specialized instruction sets formatted as Markdown with YAML frontmatter. They are assigned to agents to provide domain-specific capabilities beyond their base system prompt.
Skill Structure
Each skill contains:
- Triggers: Keywords or phrases that activate the skill.
- Allowed Tools: A subset of tools the agent can use for this specific skill (e.g.,
retrieve,sandbox). - Context & Instructions: Structured guidelines (often in XML-style tags like
<instructions>) that dictate the agent's logic.
Skill Integration
When an agent is initialized, active skills are fetched and their content is embedded into the prompt. The SkillEditor component allows for versioned updates to these skills, maintaining a history where only one version is active at a time.
Sources: apps/web/src/components/agents/SkillEditor.tsx:40-60, services/api/scripts/seed_skills.py:1015-1045
Implementation Details
Fact and Pattern Extraction
After an agent responds, the FlowMemoryMiddleware invokes extract_facts_from_answer and extract_pattern_summary.
- Facts: Individual pieces of information stashed in the vector store with a stable hash key.
- Patterns: Problem/Solution pairs that capture "metacognition"—how the agent solved a specific problem. Patterns are only extracted if the execution reached a minimum confidence threshold (default 0.7).
# services/api/flow/infrastructure/llm/middleware/memory.py:151-160
confidence = float(state.get("confidence") or 0.0)
if confidence < self._min_confidence:
return
try:
pattern = await extract_pattern_summary(self._llm, question, answer)
if pattern:
problem, solution = pattern
ns_pat = (runtime.workspace_id, runtime.agent_id, "patterns")
await self._store.aput(ns_pat, _stable_key(problem), {"problem": problem, "solution": solution})
Sources: services/api/flow/infrastructure/llm/middleware/memory.py:130-160
Persona Freshness
The system tracks when the Persona becomes "stale." If user preferences are updated or reinforced in the database after the last SOUL.md generation, the UI displays a warning suggesting a regeneration to ensure the agent's identity reflects the most recent user facets.
Sources: apps/web/src/components/preferences/PersonaSection.tsx:145-155
Summary
Memory and Persona Management transforms the Flow platform from a stateless utility into a personalized assistant. By combining vector-based semantic retrieval, episodic run summaries, and a dynamic identity block (SOUL.md), agents can effectively learn from user feedback and past performance. This cognitive architecture is maintained through a robust middleware system that operates transparently during the standard agent execution flow.