Memory and learning

Memory is Neon's small working set of durable guidance — the lessons it should carry into future sessions. It is not a transcript archive or an evidence graph; chat history, watch state, and workflow results live in their own stores. Learning is the audited loop that turns finished work into memory updates and skill improvements, at a level of autonomy you choose. For diagrams and internals, see Memory architecture.

What Neon remembers

New memory uses three scopes:

  • user — your preferences and expectations. "Prefers squash merges; keep summaries terse."
  • local — machine and tool facts not tied to one repo. "fnm manages Node; gh is authenticated as X."
  • project — repo and team conventions. "Run npm run verify before pushing to api-service."

Rows are active (loaded into new session prompts) or archived (kept for history, no longer shaping prompts). Neon rewrites, merges, and archives instead of deleting, so the audit trail can always explain what changed. Legacy session/watch rows remain readable but are never written anymore.

How memory changes

Every write goes through typed, validated actions — neondeck_memory_learn, _rewrite, _merge, _archive, and the candidate decision actions — each recording a before/after audit event. There is no path where the model edits memory state directly, and secret-like or prompt-injection-like values are rejected before they can become prompt-loadable.

How Neon learns

Three bounded review loops run as finite Flue workflows using the self-improvement model role. Each prepares a compact evidence snapshot (summaries and metadata — never raw transcripts, diffs, or logs) and gets back structured proposals, which Neondeck validates and applies only through the memory actions above.

  • Conversation reflection — every conversationReviewTurnInterval user turns (default 10), reviews the active session for durable lessons.
  • PR retrospectives — after prRetrospectiveThreshold handled PR/autopilot outcomes (default 5), reviews the batch for repeated operational lessons. Outcomes are recorded with idempotent source ids, so re-observing the same PR never inflates the signal.
  • Curation — periodically prunes the active set toward memoryMaxActiveItems with rewrites, merges, and archives.

Write modes

You pick the autonomy level per write path:

  • off — reviews may run, nothing is written.
  • review — proposals queue as candidates for your approval. This is the default posture.
  • auto — the workflow applies allowed changes itself, still through typed actions, still audited.

Skill patches have a separate, more conservative mode (skillWriteMode): automatic application is append-only, and whole-file skill rewrites always require review.

Skill patches

When a lesson is procedural — verification order, a recurring autopilot pitfall — learning can propose a patch to the built-in neondeck skill or your skills under NEONDECK_HOME/skills (never third-party or external skills). Patches preserve frontmatter and store before/after content, hashes, and a unified diff. An applied patch can later be restored from audit, but only with explicit confirmation and only while the skill file still matches the applied content — otherwise Neondeck refuses and leaves the diff for manual review.

Reviewing what Neon learned

The Learning dashboard panel shows review runs, pending memory and skill candidates, recent decisions, and manual trigger buttons. The same state is available everywhere: 

neondeck learning status | reviews | candidates | events
GET  /api/learning/state          # consolidated operator view
POST /api/learning/reviews/conversation
POST /api/learning/reviews/prs
POST /api/learning/curate
POST /api/learning/candidates/:id/approve | reject
POST /api/skills/patches/:id/apply | reject | restore

Neon itself reads the same state through neondeck_learning_operator_state_lookup, so you can just ask it what it learned lately.

Session stability

Memory writes are durable immediately, but a live chat session is never silently rewritten. Changes mark affected sessions stale; the new guidance loads when you start a new session (or explicitly refresh). If Neon seems unaware of something it just learned, that is why.

Configuration

Everything lives under learning in runtime-home config.json: 

{
  "learning": {
    "conversationReviewTurnInterval": 10,
    "memoryWriteMode": "review",
    "memoryCurationEnabled": true,
    "memoryCurationMode": "review",
    "memoryCurationTurnInterval": 200,
    "memoryMaxActiveItems": 200,
    "prRetrospectiveThreshold": 5,
    "maxPrBatchItems": 8,
    "skillWriteMode": "review"
  }
}

The reviewer model is models.selfImprovement (with models.selfImprovementThinkingLevel), falling back through FLUE_SELF_IMPROVEMENT_MODEL, the utility model, and the display assistant model.