Data Flows
Nity has three primary data flows that define how information moves through the system. Understanding these flows is essential to reasoning about Nity's behavior.
1. Session Start Flow
When a user starts a session, Nity loads context from persistent memory and injects it into the agent's prompt.
User pi-coding-agent Nity Extension Storage
│ │ │ │
├──── start session ────────►│ │ │
│ ├─── session_start ─────────►│ │
│ │ ├─── load brain ───────►│
│ │ │◄─── BrainContext ─────┤
│ │ ├─── recall episodes ──►│
│ │ │◄─── Episode[] ────────┤
│ │ │ │
│ │ │ ┌──────────────┐ │
│ │ │ │ Merge context │ │
│ │ │ │ + episodes │ │
│ │ │ └──────┬───────┘ │
│ │ │ │ │
│ │◄─── injectContext ─────────┤ │ │
│ │ { │ │ │
│ │ nity_brain: ..., │ │ │
│ │ nity_episodes: ... │ │ │
│ │ } │ │ │
│ │ │ │ │
│◄─── session ready ─────────┤ │ │ │
│ (with context) │ │ │ │What Gets Injected
// Brain context provides:
{
type: 'nity_brain',
content: 'Project summary and active memories',
memories: [
{
id: 'mem_001',
content: 'Prefers FastAPI over Flask for this project',
importance: 85,
timestamp: '2026-03-20T14:00:00Z',
tags: ['preference', 'framework']
},
// ... more memories
],
activeSkills: [
// Skills relevant to the current project
],
priority: 'high'
}Brain context is injected at high priority — it appears early in the
prompt. Episodes are medium priority — they provide historical grounding
without dominating the context window.
2. Task Execution Flow
When a user provides a task, Nity analyzes it, selects a strategy, and executes with optional autonomous iteration.
User pi-coding-agent Coordinator Components
│ │ │ │
├─── provide task ────────►│ │ │
│ ├─── nity_analyze ────────►│ │
│ │ ├─── analyze_task ────►│ TaskAnalyzer
│ │ │◄─── TaskAnalysis ────┤
│ │ │ │
│ │ ├─── skill_find ──────►│ SkillRegistry
│ │ │◄─── SkillEntry[] ────┤
│ │ │ │
│ │ ├─── recall_episodes ─►│ EpisodicMemory
│ │ │◄─── Episode[] ───────┤
│ │ │ │
│ │ ├─── recommend ───────►│ StrategyPlanner
│ │◄─── analysis result ─────┤◄─── Execution ──────┤
│ │ (subtasks, │ Strategy │
│ │ complexity, │ │
│ │ strategy) │ │
│ │ │ │
│ ┌─── If complex ───┐ │ │ │
│ │ autonomous_loop │ │ │ │
│ └───────┬───────────┘ │ │ │
│ │ │ │ │
│ ▼ │ │ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Autonomous Loop │ │
│ │ │ │
│ │ ┌─────────┐ ┌──────────┐ ┌──────────────┐ │ │
│ │ │ Execute │───►│ Quality │───►│ Pass? │ │ │
│ │ │ iteration│ │ Gate │ │ │ │ │
│ │ └─────────┘ └──────────┘ │ Yes ──► End │ │ │
│ │ ▲ │ No ──► Reflect │ │
│ │ │ └──────────────┘ │ │
│ │ │ │ │ │
│ │ │ ┌──────────┐ │ │ │
│ │ └────────┤ Retry │◄─────────────┘ │ │
│ │ │ (adjust) │ │ │
│ │ └──────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │ │
│ │ ├─── record_episode ──►│ EpisodicMemory
│ │◄─── stream progress ─────┤ │
│◄─── result ──────────────┤◄─── final result ────────┤ │Flow Steps
- Decompose —
TaskAnalyzerbreaks the task into subtasks with dependency graph - Recall —
EpisodicMemoryfinds similar past tasks for context - Skills —
SkillRegistryfinds applicable learned skills - Plan —
StrategyPlannerselects the execution strategy:direct— simple tasks, no iteration neededautonomous_loop— complex tasks requiring self-correctionskill_based— task matches a known skillhuman_in_the_loop— task requires checkpoints
- Execute —
ExecutionRouterruns the selected strategy - Validate —
QualityGatescheck each iteration - Adapt — On quality failure,
SelfReflectionextracts learnings, loop retries - Record —
EpisodicMemorystores the episode for future recall
⚠️
The autonomous loop has a hard maxIterations cap (default: 10). If quality
never passes, Nity records a partial or failure episode and reports what
it learned — it does not loop forever.
3. Self-Evolution Flow
After each task completion, Nity reflects on what happened and updates its knowledge base. This is how Nity grows over time.
pi-coding-agent Nity Extension Components Storage
│ │ │ │
├─── turn_end ──────────►│ │ │
│ │ │ │
│ ├─── record_episode ────►│ EpisodicMemory ──────►│
│ │ │ │
│ ├─── self_reflect ──────►│ SelfReflection │
│ │ │ │ │
│ │ │ ├─── "Did we │
│ │ │ │ discover a │
│ │ │ │ reusable │
│ │ │ │ pattern?" │
│ │ │ │ │
│ │ │ │ ┌── Yes ──┐ │
│ │ │ │ │ │ │
│ │ │ │ ▼ │ │
│ │ │ ├─── skill_create ──►│ SkillRegistry
│ │ │ │ │ │ ──►│
│ │ │ │ │ │ │
│ │ │ │◄──┘ │ │
│ │ │ │ │ │
│ │ │ ├─── update │ │
│ │ │ │ adapter │ │
│ │ │ │ weights ──►│ AdapterRegistry
│ │ │ │ │ ──►│
│ │ │ │ │ │
│ │◄─── ReflectionRecord ──┤ │ │ │
│ │ │ │ │ │
├────────────────────────┤ │ │ │ │
│ ... │ (periodic) │ │ │ │
│ │ │ │ │ │
│ ├─── meta_learn ────────►│ MetaLearner │
│ │ │ │ │ │
│ │ │ ├─── analyze │ │
│ │ │ │ patterns │ │
│ │ │ │ across │ │
│ │ │ │ episodes │◄───┤
│ │ │ │ │ │
│ │ │ ├─── optimize │ │
│ │ │ │ strategies│ │
│ │ │ │ │ │
│ │ │ ├─── prune │ │
│ │ │ │ stale │ │
│ │ │ │ skills ───►│ SkillRegistry
│ │ │ │ │ ──►│
│ │ │ │ │ │
│ │◄─── optimization │ │ │ │
│ │ complete │ │ │ │What Happens at Each Stage
Every completed task (success, failure, or partial) is stored as an Episode:
- Task description and outcome
- Strategy used and iteration count
- Quality gate results
- Duration and timestamp
- Free-form notes from the agent
Episodes are the raw data that powers all of Nity's learning.
Evolution Over Time
Session 1 ──► Episode 1 ──► Reflection ──► No skill created
Session 2 ──► Episode 2 ──► Reflection ──► No skill created
Session 3 ──► Episode 3 ──► Reflection ──► Pattern detected!
│
▼
skill_create()
│
▼
Skill available for
all future sessions
│
Session 4 ──► task matches trigger ───────────┘
│
▼
skill_based strategy selected
(faster, higher quality)
│
▼
Episode 4 (success, 1 iteration)
│
▼
skill.successRate += 1The self-evolution flow is what makes Nity an eternal companion. Each session leaves the system slightly better than it found it. The compounding effect across hundreds of sessions is what transforms Nity from a basic agent into a deeply specialized assistant.
Cross-Flow Interactions
All three flows are connected:
┌─────────────────────────────────────────────────────────────────┐
│ │
│ Session Start Flow Task Execution Flow │
│ │ │ │
│ │ Injects context │ Uses context │
│ │ from brain │ for analysis │
│ │ ┌──────────────────┤ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ Nity Coordinator │ │
│ │ (wires all flows together) │ │
│ └──────────────────┬───────────────────┘ │
│ │ │
│ │ Records episodes │
│ │ Updates skills │
│ │ Evolves strategies │
│ ▼ │
│ Self-Evolution Flow │
│ │
└─────────────────────────────────────────────────────────────────┘- Session Start provides context that Task Execution uses for better analysis
- Task Execution produces episodes that Self-Evolution learns from
- Self-Evolution updates skills and strategies that Session Start loads next time
This creates a virtuous cycle — each session improves the system for the next.
Next Steps
- Overview ← — Component systems and architecture
- Extension Entry Point ← — How events wire into these flows
- Tool Reference ← — The tools that power each flow step