v0.4.2

[0.4.2] - 2026-11-01
Added

MemoryPolicy and Agent(memory=...): opt-in limits on what an agent keeps and sends, all off by default. history_mode="messages" sends a stateful agent's prior turns as structured chat history (backends declare supports_history; the others keep the text form), token_budget sets the conversation budget, tool_result_chars clips plugin results on both the native and TOOL: paths, and history_entry_chars bounds what task_history and reasoning_history store. maki serve YAML accepts the same fields under memory:; to_dict/from_dict round-trip the policy
Tiered memory: MemoryPolicy(pinned_chars=..., recent_turns=..., older_turn_chars=...). agent.remember(key, value, pin=True) puts a fact in the system message of every call and never evicts it (operator-only and size-capped: a plain remember() on a pinned key raises, /memory/set answers 409, and neither clear_memory() nor DELETE /memory removes pins, only unpin() does; pins survive reset_conversation() and to_dict()); the last recent_turns turns stay verbatim and older messages are cut to older_turn_chars, and cut turns count at their shortened size against the budget. When turns are evicted the first remaining message is prefixed [N earlier turn(s) dropped]
LLMResponse.cached_tokens and Usage.cached_tokens: prompt tokens served from the provider's cache, reported by the Anthropic and OpenAI backends and by streaming chat_collect() on OpenAI-compatible servers such as vLLM and llama.cpp (0 elsewhere)
maki/test/memory_bench.py: an offline benchmark of prompt tokens, recall and history size (python -m maki.test.memory_bench)

Documentation

New guide docs/user/agent-memory.md: what goes wrong in long conversations, the MemoryPolicy settings, pinned facts and how to choose values, with measured results. In a live test on Ollama gemma4:26b (4096-token window, one run per setting), a 13-message chat that stated a codename in message 1 was answered wrongly by the default setup (Response: Response: Response:) and correctly by both policy settings, which sent about 45% less text (108,670 to 59,462 characters). Offline: 51% fewer prompt tokens over 20 turns, and 90% less in a large-tool-result run and in stored history. The token estimate (len // 4) ran low on log text, so keep token_budget near half of the model's window
memory.md now covers only Obsidian and RAG and links to the new guide; the README, docs index, nav and agents.md link to it