feat: agent memory management — consolidation, eviction, and retrieval for per-agent history

Summary

Per-agent conversation history is currently a raw ArrayBuffer[ChatMessage] (LLMExtension.scala:57) that only ever grows. Add memory management — summarization/consolidation, eviction, and optionally importance-based retrieval — so long-running simulations don't hit context limits.

Research/context only; design still to be done.

Problem

messageHistory: WeakHashMap[Agent, ArrayBuffer[ChatMessage]] accumulates every user/assistant pair for the life of the model. There is no summarization, no eviction, no truncation, no retrieval, and no token accounting.

Practical consequence: a model running a few hundred ticks with per-agent conversation will grow each agent's history until the provider rejects the request. The modeler's only tools today are llm:history / llm:set-history / llm:clear-history — i.e. hand-rolling the whole policy in NetLogo, with no visibility into token cost.

This is the largest capability gap that is not blocked by the NetLogo platform — it is entirely extension-side work.

Prior art: mesa-llm

mesa-llm ships four memory classes (local clone, HEAD 57a51ff). Worth knowing what is and isn't worth copying:

Two useful details:

• EpisodicMemory needs no vector DB. It credits Generative Agents but implements only importance + recency — relevance-via-embeddings is explicitly unimplemented (their #209; verified — the only embedding/vector hits in their codebase are two comments saying it is pending). So importance-based retrieval is achievable with zero new dependencies.
• Their two-phase staging is well designed. Content accumulated before a step is snapshotted, then merged with post-step content into one entry. Message and action events accumulate as lists within a tick; observations overwrite. Worth borrowing if we add structured memory entries.

LongTermMemory (summarize every step) is a cost trap — an extra LLM call per agent per tick. STLTMemory's amortized consolidation is the better shape.

Possible directions (to be decided)

• Bounded history — a configurable cap with oldest-first eviction. Cheapest useful thing; no LLM calls.
• Consolidation — when over budget, summarize the oldest N into a running summary and keep it pinned at the head of the history. STLT-style.
• Importance-based retrieval — score entries and include only the top-k. Higher value for long simulations, higher complexity.
• Token accounting — needed to make any of these budget-aware rather than count-based. Depends on token/cost tracking.

Open questions

• Where does policy live — extension config (memory_mode, memory_capacity), new primitives, or both?
• Consolidation costs an LLM call. Should it be opt-in per model, and should it be visible to the modeler when it fires?
• Does consolidation interact badly with llm:set-history, which replaces history wholesale?
• Is per-agent the right scope, or is a shared/blackboard memory also wanted (roadmap item)?

Start at LLMExtension.scala:57 and trace how messageHistory is created, updated, and exposed through llm:history, llm:set-history, and llm:clear-history. Review the mesa-llm memory classes and the listed possible directions, then define the policy, configuration or primitives, token accounting, and completion criteria before implementation.