Module memory

Expand description

Pluggable memory architecture for newt’s chat REPL.

Modelled on hermes-agent’s MemoryProvider ABC + MemoryManager orchestrator, adapted for Rust and newt’s local-first constraints.

Fault isolation — one provider’s panic/error never blocks others.
Frozen system prompt — system_prompt_block() is captured once at session start and never rebuilt mid-session (preserves the model’s prefix cache / KV cache across turns).
Non-blocking sync — sync_turn should queue writes; the chat loop never waits on memory backends.
Single integration point — MemoryManager is the only thing the chat loop interacts with; it fans out to all registered providers.

Provider	Issue
`RollingWindow`	#105 — keep last N turns (ships here)
`TokenBudget`	#106 — prune by context-window %
`Summarizing`	#107 — LLM summarization of old turns
`NoteStore`	#108 — persistent NOTES.md the agent writes to

Re-exports§

MemMessage: A single message in a conversation.
MemoryIndex: A budgeted, frozen INDEX of memory the model can navigate (#319).
MemoryManager: Orchestrates all registered MemoryProviders.
NotesUnsupported: Error returned by the default MemoryProvider::add_note for providers that don’t persist notes.
RollingWindow: Keep the last max_turns conversation turns; discard older ones.
SessionContext: Context provided to each MemoryProvider::initialize call.
SoulProvider: Loads an agent identity from a Markdown soul file and injects it as a frozen system-prompt block.
Summarizing: LLM-powered summarisation of old turns when context fills.
TokenBudget: Keep turns up to threshold_pct of the model’s context window.

COACH_SOUL: FR-5 (#999): the ADVISE-first identity installed when a persona’s altitude is crate::Altitude::Coach (front-matter altitude = "coach"). It REPLACES DEFAULT_SOUL rather than layering over it — the doer soul (“never describe a change, make it”) directly contradicts a coach, so appending a coach overlay onto the doer soul would ship two opposing identities in one prompt. This IS the whole base identity for a coaching turn; the persona’s own markdown body still overlays on top, now without self-contradiction.
DEFAULT_CONTEXT_TOKENS: Static context-token budget used only when neither an explicit [memory] context_tokens override nor empirical capability data exists (a fresh model with no probe history — Step 18.2, #247).
DEFAULT_SOUL: Default agent identity injected when no soul file is found.
MEMORY_INDEX_BUDGET: The memory index budget: the maximum number of items the frozen memory INDEX may list, pinned by CI (the modulex DEFAULT_TOOL_BUDGET = 12 pattern — progressive-disclosure memory design §2.3/§3.3). The index is the cheap layer that rides in every request; the verbatim bodies are pulled on demand via memory_fetch. Growing this is a deliberate edit to this constant with its own justification, asserted by a test — never a side effect of a feature. Starts small (≈ the DEFAULT_TOOL_BUDGET order of magnitude); tune empirically against probe data, never down silently.