feat(memory): Auto-inject stored memories into the system prompt each turn

[hamza-jeddad]

Background

docker-agent already ships a SQLite-backed memory toolset (pkg/tools/builtin/memory/) with explicit add_memory, get_memories, search_memories, update_memory, and delete_memory tools. The agent can persist and retrieve facts, but retrieval is entirely reactive — the model must decide to call get_memories or search_memories before it can use stored knowledge. This means memories are often ignored at the start of a turn, which undermines the value of the memory store.

Motivation

A proactive injection pattern solves this: before every model call, relevant memories are automatically retrieved and injected into the context as a transient system message. The agent always has its memories available without spending a tool-call round-trip. docker-agent's turn_start hook + builtin system is the natural home for this behaviour, following the precedent set by add_date, add_environment_info, and add_prompt_files.

Proposed Design

1. New inject_memories builtin

Register a new turn_start builtin named inject_memories:

• Input: current user turn text from hooks.Input.Prompt
• Retrieval strategy: run SearchMemories(ctx, keywords, "") extracting keywords from the prompt; fall back to GetMemories when the prompt is short/empty
• Result cap: configurable max_inject_memories limit (default: 20)
• Output: a transient turn_start system message — never persisted to session.Messages

2. Prefix-cache stability (frozen snapshot)

• Maintain a frozen snapshot of injected memory text
• Rebuild only after a compaction event or a memory write (add_memory, update_memory, delete_memory)
• Snapshot held in-process; not persisted

3. Per-agent configuration

Add an inject_memories boolean to AgentConfig, wired through builtins.AgentDefaults → ApplyAgentDefaults → buildHooksExecutors. Only activates when a memory toolset is also present for the agent.

agents:
  my_agent:
    tools:
      - type: memory
    inject_memories: true   # new flag

4. Implementation checklist

• pkg/hooks/builtins/inject_memories.go — new turn_start builtin
• pkg/hooks/builtins/builtins.go — register builtin constant + handler + AgentDefaults field
• pkg/agent/agent.go — add InjectMemories() bool accessor
• pkg/config/latest/types.go — add InjectMemories *bool to AgentConfig
• pkg/runtime/hooks.go — wire InjectMemories through AgentDefaults
• Frozen-snapshot invalidation on memory write and compaction
• Unit tests for new builtin (mock DB, assert injected text)
• Integration test: turn_start injects relevant memories, filters unrelated ones
• No config migration needed (false by default)

Acceptance Criteria

1. When inject_memories: true and a memory toolset are both set, relevant memories appear as a transient system message at every turn_start.
2. Injection does not persist to session.Messages.
3. Empty memory store → no injection system message added.
4. max_inject_memories cap respected; excess dropped without error.
5. Memory write invalidates the frozen snapshot; next turn reflects the change.
6. Compaction event triggers snapshot rebuild.
7. Keyword search used for non-trivial prompts; full dump used as fallback.
8. inject_memories: false (default) → no behavioural change from today.
9. ≥80% test coverage on new code.

Additional Context

• Related packages: pkg/tools/builtin/memory/, pkg/memory/database/, pkg/hooks/builtins/, pkg/runtime/hooks.go, pkg/session/session.go
• Two follow-up issues are planned: (a) Separate user-profile memory tier, (b) Background memory review daemon
• The existing tool-based memory (explicit model tool calls) is preserved; this adds automatic proactive injection on top.