MemoryMixin: 5 memory tools + 3 lifecycle hooks for any agent

[kovtcharov]

Summary

Build the agent integration layer for memory. A mixin that any Agent subclass can opt into, providing persistent memory through 3 automatic hooks and 5 LLM-facing tools.

Spec: docs/spec/agent-memory-architecture.md → "File 2: memory.py"

Depends on: #542 (MemoryStore)

Supersedes gaia6: Replaces 8-tool MemoryMixin with 5-tool CRUD design. Adds auto tool logging, error learning, temporal awareness, context scoping.

3 Lifecycle Hooks

Hook 1: System Prompt Injection

get_memory_system_prompt() — injects current time, preferences, facts, error patterns, upcoming/overdue items. Filters by active context, excludes sensitive items.

Critical: Invalidates _system_prompt_cache at start of each process_query() so memory context is always fresh.

Hook 2: Tool Execution Wrapper

_execute_tool() override — auto-logs every non-memory tool call to tool_history. Auto-stores novel errors as knowledge(category='error').

Hook 3: Post-Query Storage

_after_process_query() — stores conversation turns (tagged with context), runs heuristic extraction (regex patterns for preferences/facts).

5 LLM Tools

Tool	CRUD	Purpose
remember	Create	Store facts/preferences/skills with context, entity, due_at, sensitive
recall	Read	FTS5 search or filter by category/context/entity
update_memory	Update	Modify existing entries by ID, mark as reminded
forget	Delete	Remove entries by ID
search_past_conversations	—	Keyword + time-based conversation search

Class Interface

class MemoryMixin:
    init_memory(db_path, context)
    memory_store, memory_session_id, memory_context  # properties
    set_memory_context(context)
    get_memory_system_prompt()
    register_memory_tools()
    process_query()  # cache invalidation override
    _execute_tool()  # auto-logging override
    _after_process_query()  # conversation + extraction
    reset_memory_session()

Agent Base Changes (agent.py)

1. Add get_memory_system_prompt check to _get_mixin_prompts() (4 lines)
2. Add _after_process_query hook at end of process_query() (2 lines)

Acceptance Criteria

• MemoryMixin can be mixed into any Agent subclass
• System prompt includes fresh memory context each query
• All non-memory tool calls auto-logged to tool_history
• Tool errors auto-stored as knowledge(category='error')
• Conversation turns stored after each process_query
• Heuristic extraction catches "I prefer X", "my name is X" patterns
• Context scoping filters system prompt correctly
• Sensitive items excluded from system prompt
• Temporal items (due_at) surface in system prompt when approaching
• Integration tests for full lifecycle