Memory, learning & evolution

§0TL;DR — the proposal

Eight decisions, each one validated by where the market converged — and where it visibly walked back.

§1The shape: three knowledge stores + one retrieval layer

The single most important structural decision — and the one the market most expensively re-learned — is to keep the agent's knowledge in separate stores defined by who is allowed to change them, never one self-editing blob.

Cursor shipped a fuzzy auto-"Memories" layer alongside its inspectable Rules, found the two overlapping stores bred drift and distrust, and deleted auto-memories in v2.1, folding everything back into Rules. CoALA, Devin and Intercom independently land on the same separation. Loquent should adopt it deliberately from the start.

§2Where we are vs. the v3 doc

The v3 architecture already settled the data model and dropped the meta-agent idea. What remains unbuilt is the mechanism — the part this doc designs.

The v3 doc's R4 (memory = single MD doc, on-demand) and §8.4 (auto-refresh, admin rolls back) are the two points this doc proposes to refine — see the four refinements in the banner above, resolved in §8.

§3How the field solves this

19 platforms and paradigms, read mechanism-deep. The striking result: the trustworthy commercial peers have converged, and the cautionary tales are the ones that auto-applied behavior changes silently.

§4Memory taxonomy → Loquent

CoALA's four memory tiers (working · semantic · episodic · procedural) map cleanly onto what we already have — and pinpoint exactly what's new. Most of the substrate already exists.

4.1 Operations: write hot, manage cold, read layered

§5The learning mechanism

The deferred heart of §8. Five moving parts: the signal, the digest, the injection, the guardrails, and the trust gate.

5.1 The signal — the operator's edit is gold

The central open question in v3 ("observations created during runs" — but which runs, created how?). For a suggest-mode SMS product the answer is unusually clean: the owner already reviews and edits drafts. That edit is a free, naturally-occurring, ground-truth preference pair — the human literally produced the correct answer. No thumbs UI, no LLM self-grading, no behavior-change risk.

5.2 The digest — reflect, reconcile, propose

A background job (off the hot path, on the cheap model via learning_model_override, driven by the existing #1531 poller) reads undigested lessons + corrections + the recent thread log, and — GEPA / Generative-Agents style — synthesizes higher-level insight with provenance, then drafts a candidate version. Critically it reconciles against the current doc (Mem0's ADD/UPDATE/DELETE/NOOP) rather than appending, and frequency-gates so a one-off never becomes a rule.

5.3 Reaching the prompt — KV-cache-safe

v3 §8.3 injects "the current learning version (always) + recent undigested lessons." Two empirical hazards make the naive version costly:

• Context rot. Always-injecting bulk text degrades the model even when every item is correct (NoLiMa: half-baseline by 32K; Lost-in-the-Middle; plausible distractors cost 6–11 pts each).
• KV-cache invalidation. A mutating blob in the cached system prefix = 100% cache miss every turn (the Honcho/Hermes bug: ~5 min/turn). Anthropic prompt-caching keys on a byte-stable prefix.

5.4 Guardrails

5.5 The trust gate — auto-apply by default, owner can gate it

Decision (refines v3 §8.4 + fork 5): learnings and evolution auto-apply by default — the agent improves without nagging. A per-org setting (organization.learning_apply_mode = auto | approval) flips the whole org to require one-click approval for behavior-changing versions. The safety rails are on in both modes.

Always on in both modes: append-only version chain, one-click rollback, the visible change log, frequency-gating, scope-tagging. Org-scope (large blast radius) stays deferred regardless — see fork 7.

5.6 Cadence

Not a fixed weekly cron — a small business may get 3 threads a week or 300. Threshold + manual + weekly sweep: fire a proposal when N high-trust corrections accumulate (self-regulating by salience, à la Generative Agents); always offer an "Improve my agent now" button; run a light weekly sweep so quiet agents still consolidate. Debounce per thread (never reflect mid-burst). All off the hot path, driven by the per-minute poller (#1531).

5.7 Active learning — the agent asks

Learning isn't only passive. When an agent hits an important unknown it can't resolve from the database or memory — a fact it needs to act well ("Do you take weekend appointments?", "What's the cancellation policy?") — it should ask the owner rather than guess. The answer is the highest-trust signal there is, so it's written straight to memory (business_facts, owner-pinned read_only) and emitted as a lesson (source = operator_answer) so the behavior generalizes.

• Mechanism — reuse the attention surface (escalate_to_user + the draft-nudge of #1543 / #1477): the agent poses a short question; the owner answers in-thread; the answer feeds back as a trusted event.
• Restraint — rate-limited, reserved for genuinely blocking, reusable facts (not per-turn nagging). Re-derive from the DB first; ask only when the knowledge is emergent and durable.
• Payoff — owner-answered facts are the cheapest, highest-trust learning of all, and they make "auto-apply by default" safe: the agent is learning from the owner's own words.

§6Evolution & rollback

Five patterns to adopt, two to refuse. The version-chain is both the visible "evolution" surface and the rollback.

§7Proposed data model

Reconciling Design A and B: B's storage wins (version-chain, no parent table); A's good parts survive as columns (agent+org scope) and the ai_agent_lesson concept. Three new tables, one refactor, one deferred.

NEW — the evolution spine (Design B, the existing FK finally has a target)

table ai_agent_learning_version
  id, agent_id FK
  scope            enum[agent | org]        // org deferred; column present from day one
  body_markdown    text                    // head renders as ONE clean readable doc
  previous_version_id  FK? self            // rollback = repoint current_learning_version_id
  status           enum[pending|approved|active|superseded|rejected]
  change_summary   text                    // plain-language diff for the owner
  folded_lesson_ids       jsonb
  supporting_thread_log_ids jsonb            // provenance — "learned from these 3 chats"
  proposed_by      enum[digest | operator]
  confidence       f32
  approved_by, approved_at  null
  created_at
  // ai_agent.current_learning_version_id  →  active head (column already exists). Cap ≤20.

Plus one org-level knob — organization.learning_apply_mode = auto | approval (default auto) — the only setting that gates whether behavior-changing versions apply automatically or wait for owner approval (§5.5).

NEW — the episodic signal (lessons + the gold edit triple)

table ai_agent_lesson
  id, agent_id FK
  scope   enum[contact|agent|org]  default agent
  situation, what_went_wrong, what_to_do_instead  text   // Reflexion shape
  correction_kind enum[rejected|rewrite|tone|fact|approach|escalate|failed_run]
  source   enum[operator_edit|operator_answer|failed_run|escalation|llm_notable]
  source_thread_log_id FK          // external ground-truth label only
  support_count int, confidence f32      // frequency gate before promotion
  status   enum[undigested|proposed|digested|rejected|superseded]   // digested_by lives here
  created_at

table ai_draft_correction   // the suggest-mode gold signal — captured hot path, no LLM call
  id, agent_id, thread_id, contact_id null
  turn_log_id FK → ai_thread_log
  original_draft, final_text text     // final_text null = rejected outright
  edit_distance int, edit_ratio f32   // implicit reward AND learning threshold
  correction_kind enum
  context_embedding vector           // retrieve top-k by inbound-message similarity
  promoted_to_lesson_id null
  created_at

REFACTOR — the blob → typed reconciling blocks

table ai_agent_memory   // keep ONE row per agent + the read_my_memory / update_my_memory tool surface
  blocks jsonb[]  of { label enum[persona_belief|business_facts|preferences],
                    value text (char-capped),
                    read_only bool,        // owner-pinned facts the agent can't overwrite
                    updated_at }
  // update RECONCILES (ADD/UPDATE/DELETE/NOOP vs existing) — never clobbers the whole doc

NEW (in this epic) — per-contact memory, retiring today's contact blob

table ai_contact_memory   // replaces contact_note(area=Memory) + contact.ai_summary — see §7.1
  id, org_id, contact_id, fact_text
  category enum, sensitivity enum, confidence f32
  valid_from, valid_to            // bi-temporal: contradiction SUPERSEDES, never deletes (Zep)
  superseded_by_id null, source_thread_log_id, source_channel
  embedding vector, redacted_at null, created_at
  // retrieved top-k recency×importance×relevance; TTL/decay; per-contact erasure cascade (GDPR Art.17)

7.1 Obsoleting today's contact memory

Per-contact knowledge exists today as a monolithic, overwrite-on-update markdown note — the exact antipattern we're retiring for agent memory. ai_contact_memory replaces it; structured data and the interaction log stay.

The four inline-aisdk writers (update_contact_memory, enrich_contact_from_messages, summarize_call_for_note→memory, plan update_system_note) are retargeted from synthesize-and-overwrite to extract-and-reconcile (ADD/UPDATE/DELETE/NOOP, bi-temporal supersede) into ai_contact_memory, and move onto the rig / ai_agent runtime — this is the #1497 · L4 "ContactMemory / ContactEnrichment / AutoTag" onboarding. Readers (contact_read(include:memory), contact_find snippet) query the new store, retrieving the slice relevant to the inbound message.

Keep verbatim: ai_thread_log (raw episodic), ai_usage_log, ai_skill (lazy-loaded #1426). Keep separate from the #1495 config-snapshot table (different ownership).

§8Open decisions — resolved

The eight forks, each resolved against the research and approved 2026-06-13 — fork 5 refined to default-auto-apply + an org setting; org-scope confirmed deferred. The recommended option is marked; the resolution line gives the rationale.

§9Build sequence

Value ships early and de-risked: prompt hygiene first, then capture the gold signal, then the first real "it learns from your edits" win — all before the gated evolution loop. Memory already exists; config-versioning (#1495) is a sibling.

1. P1Populate the reserved slots + lazy skillssmall · low-risk

   Create ai_agent_learning_version (the target the FK has lacked), seed it only from existing rules/persona — no loop yet. Inject a small KV-cache-safe summary into the empty slots. Ship #1426 lazy skill index + load_skill. Net: immediate prompt-hygiene win, slots stop being empty, zero behavior-change risk. Depends: existing hooks, #1426.

2. P2Capture the gold signal + the agent asksmedium

   Add ai_draft_correction on every operator edit/reject (hot path, no LLM call) + ai_agent_lesson from failed/escalated/corrected runs. Add the active-learning ask — an escalate_to_user-style question whose owner answer writes to memory (source = operator_answer). Surface a simple metric ("your agent needed editing X% less"). Pure capture — nothing applied yet. Depends: P1, ai_thread_log + suggest-mode UX (built), attention surface #1543/#1477.

3. P3Dynamic few-shot from edits (contact-scoped)medium

   Induce a short NL preference (CIPHER) from above-threshold corrections, store contact/thread-scoped with a context embedding, retrieve top-k by inbound-message similarity, inject as few-shot example messages. Auto-applies safely (retrieval-only, can't leak) — the first real "it learns from your edits" win, no approval flow. Depends: P2 + an embedding path (pgvector or tsvector to start).

4. P4Refactor memory blob → typed reconciling blocksmedium

   Split ai_agent_memory into typed char-capped blocks with read_only pinning; keep the tools but make writes reconcile (ADD/UPDATE/DELETE/NOOP) not overwrite. Owner gets an editable "what your agent remembers" panel. Removes the silent-overwrite footgun. Depends: P1; parallel to P3.

5. P5Per-contact memory — retire the old contact bloblarge

   Add ai_contact_memory (typed, bi-temporal supersede, retrieve top-k by inbound relevance) and obsolete contact_note(area=Memory) + contact.ai_summary (§7.1). Retarget the four inline-aisdk writers to extract-and-reconcile and move them onto the rig runtime — this is #1497 · L4. Keep interaction notes + structured fields. Ship the per-contact erasure cascade + TTL/decay with it. Depends: P4 (typed/reconcile pattern); data-governance (GDPR Art.17 cascade, namespace isolation).

6. P6Background digest → versions (auto-apply default)large

   The job: read undigested lessons+corrections, reconcile/dedup/frequency-gate, write a new ai_agent_learning_version with provenance + plain-language summary. Auto-applies by default (repoints current_learning_version_id at the next thread boundary); the per-org learning_apply_mode = approval setting makes it land pending instead. Rollback via previous_version_id always. Agent-scope only. Depends: P2+P4, #1531 poller; share ≤20-cap/diff with #1495 (separate tables).

7. P7Trust surfaces — change log, shadow-replay, "struggled with"large

   The "what your agent learned" change log + one-click undo (the trust anchor for auto-apply). Optional shadow-replay against the last N real threads (especially in approval mode). Owner-first "topics your agent struggled with" report + per-reply retrieval observability. Corrected threads become regression fixtures (Sierra). Depends: P6; reuse #1534 activity + #1459 nudge.

8. P8Org-scope learning deferredlater

   Org-scope cross-agent promotion behind a stronger gate (the scope column is present from P6). Deferred deliberately — large blast radius — and shaped by what agent-scope learnings teach us (fork 7). Depends: P6+P7 proven at agent scope.

§10References

Primary sources behind the synthesis — 20 research agents, 19 platforms. Grouped by what they informed.

Memory architecture & taxonomy

• CoALA — Cognitive Architectures for Language Agents (Sumers, Yao, Narasimhan, Griffiths, TMLR 2024) — the working/semantic/episodic/procedural split
• A Survey on the Memory Mechanism of LLM-based Agents — write/manage/read operations, reflection
• From Human Memory to AI Memory: A Survey · From Storage to Experience: evolution of agent memory
• Letta Agent File (.af) — typed char-capped blocks, block-level versioning · LangMem semantic memory (reconcile, RemoveDoc, profile vs collection)
• Zep / Graphiti — bi-temporal supersede-don't-delete

Learning paradigms

• Generative Agents (Park et al. 2023) — memory stream, importance, reflection-with-provenance
• Reflexion (Shinn et al. 2023) · ExpeL — verbal RL, voted insight pool
• GEPA: Reflective Prompt Evolution (ICLR 2026) — reflect→propose→validate, 35× fewer rollouts · DSPy GEPA
• PRELUDE / CIPHER (Gao et al., NeurIPS 2024) — learning latent preference from user edits · Distilling Feedback into Memory-as-a-Tool

Commercial peers & products

• Decagon Duet Autopilot — versioned workspace, every change human-approved · Devin Playbooks (versioning + rollback)
• Cursor Rules · Memories removed in 2.1 (the cautionary tale)
• Claude Code Skills (3-level disclosure) · ChatGPT Dreaming (two-layer; auto-apply weakness)
• Ada AI coaching · Gmail Smart Compose · Grammarly Brand Tones

Failure modes & governance

• Context Rot (Chroma, 2025) — bulk injection degrades performance · Honcho KV-cache invalidation bug · Anthropic prompt caching
• MINJA — memory poisoning attacks in LLM agents · SSGM governed-memory framework
• Anthropic agent memory — immutable-version audit trail + redact for compliance · EDPB Opinion 28/2024

Loquent context

• AI Agents v3 architecture — §8 Learning & §9 Memory
• Issues: #1494 learning engine (L1) · #1495 agent versioning (L2) · #1426 lazy skills · #1531 schedule poller · #1534 owner activity · #1459 drafts nudge