Memory architecture

This page is the implementation view of memory and learning: how evidence flows into reviews, how reviews become durable state, and where everything is stored. For scopes, write modes, and day-to-day operation, start with Memory and learning.

Boundaries

Three rules shape the whole design:

Every write is a typed action. Memory state changes only through Valibot-validated actions that record before/after audit events — the same actions whether a human, the dashboard, or a learning workflow is the caller.
Model-backed learning is bounded. Reviews run as finite Flue workflows that prepare compact evidence snapshots first. The model returns structured memoryActions and skillPatches — never raw state, never SQL.
Active sessions stay stable. Changes mark loaded sessions stale rather than mutating them; new guidance loads on the next prompt snapshot.

System map

Memory sits between runtime evidence and future prompt snapshots. Conversation turns and PR/autopilot outcomes feed learning reviews; reviewer output lands as direct memory writes, review candidates, or skill patch proposals; everything is visible to the operator surfaces.

flowchart LR User["User turns"] PR["PR / autopilot outcomes"] Config["learning config"] Sessions["chat_sessions + prompt snapshots"] Events["learning_events"] Reviews["learning_reviews"] Reviewer["Flue workflow + learning_reviewer"] Candidates["learning_candidates"] Memory["memories"] Audit["memory_events"] Skills["runtime skills"] Operator["Learning panel / CLI / API"] User --> Sessions Sessions --> Reviews PR --> Events Events --> Reviews Config --> Reviews Reviews --> Reviewer Reviewer --> Candidates Reviewer --> Memory Candidates --> Memory Candidates --> Skills Memory --> Audit Memory --> Sessions Skills --> Sessions Reviews --> Operator Candidates --> Operator Events --> Operator Audit --> Operator

The feedback loop

sequenceDiagram participant Work as Chat / PR work participant State as Neondeck SQLite participant Flue as Bounded Flue workflow participant Model as Self-improvement model participant Actions as Typed actions participant Session as Future session Work->>State: compact outcome or turn count State->>State: record learning_event or cadence counter State-->>Flue: threshold or manual trigger Flue->>State: prepare bounded evidence snapshot Flue->>Model: ask learning_reviewer for structured output Model-->>Flue: memoryActions and skillPatches Flue->>Actions: validate and apply or create candidates Actions->>State: write memories, candidates, audit events State->>Session: record stale signals as needed Session->>State: next prompt snapshot loads active memory Session-->>Work: improved behavior

Work Neon already performs is compacted into learning events with stable, idempotent source ids, so repeat observations of the same outcome never inflate the signal. Cadence and threshold rules decide when a bounded workflow asks the self-improvement model for durable lessons; Neondeck validates the structured output, rejects secret-like or injection-like content, and applies the remainder through the action layer.

Storage layout

App state and Flue runtime state are separate databases. The app database owns memory, learning records, and session metadata; Flue owns transcripts and run state; runtime-home files hold config, secrets, and skills. Learning reviews read Flue run observations, but only compact summaries ever cross back into app state.

flowchart TB subgraph App["data/neondeck.db"] Memories["memories: current guidance"] MemoryEvents["memory_events: before / after audit"] LearningEvents["learning_events: triggers and outcomes"] LearningReviews["learning_reviews: bounded reviewer runs"] LearningCandidates["learning_candidates: review-mode decisions"] ChatSessions["chat_sessions: session metadata and loaded ids"] ConfigHistory["config_history: skill/config change audit"] end subgraph FlueDB["data/flue.db"] FlueRuns["Flue runs and agent runtime state"] Transcripts["display-assistant transcripts"] end subgraph Files["runtime-home files"] Skills["skills/ and built-in skill material"] Config["config.json"] Env[".env"] end Memories --> ChatSessions LearningReviews --> LearningCandidates LearningCandidates --> Memories LearningCandidates --> Skills Skills --> ConfigHistory FlueRuns --> LearningReviews Transcripts -. summaries only .-> ChatSessions

Safety properties

All public memory and learning inputs are Valibot validated.
Secret-like or prompt-injection-like memory values are rejected.
Model output becomes proposals or typed action calls, not raw SQL.
Memory changes are audited with before and after snapshots.
Skill patches keep before/after hashes and can be restored only when the file still matches the audited patched content.
Existing sessions stay stable until a new prompt snapshot is loaded.

Where to look in code

src/memory-actions.ts: memory CRUD, candidates, curation, audit events, and write policy.
src/learning-reviews.ts: conversation reflection, curation, PR retrospectives, and handled-event accounting.
src/learning-operator.ts: consolidated read-only operator state.
src/skill-patches.ts: skill patch proposal, apply, reject, audit, and restore.
src/workflows/review_conversation_for_learning.ts, src/workflows/curate_learning_store.ts, and src/workflows/review_pr_batch_for_learning.ts: bounded Flue workflow entry points.