feat: context-hook injection mode (v1.5.0)

[samfoy]

Closes #23

Thanks @gebeer for the well-reasoned proposal — this implements exactly what you described, with one refinement to the architecture.

What changed

Memory is no longer injected by mutating event.systemPrompt. Instead, a new Mode D hybrid approach:

1. before_agent_start — fires once per user turn; runs the semantic search and caches the result in pendingContextBlock. Returns nothing — system prompt is never touched.
2. pi.on("context") — fires on every LLM call within the turn; reads pendingContextBlock and splices a custom/display: false memory message immediately before the latest user message.

Why the hybrid over pure context-hook

The context hook only receives messages[] — no event.prompt. Rather than extracting the user's prompt text from the messages array on every LLM call (including every tool-call continuation), before_agent_start captures it cleanly once and does the single expensive search there. The context hook becomes a cheap read + array splice on each continuation.

Cache story

Before (v1.4.0 — system prompt mutation):
  topic shift → system prompt miss → cascades through entire messages prefix

After (v1.5.0 — context hook):
  system prompt: always stable → unconditional cache hits
  conversation history up to new turn: always caches
  memory message: cache hit if same memories relevant, miss at injection point only

The injection position (immediately before the latest user message) falls at the natural Anthropic cache breakpoint — everything before it caches anyway.

Ephemerality

Injected messages are not persisted to agent.state.messages, session history, or the consolidation queue. transformContext receives a structuredClone and the result is only used for that one LLM call. No meta-memory accumulation.

Settings

{ "memory": { "injectionMode": "context-hook" } }   // new default
{ "memory": { "injectionMode": "system-prompt" } }  // restore v1.4.0 behaviour
{ "memory": { "perTurnInjection": false } }          // session_start dump (unchanged)

Testing

@gebeer — would love it if you could test this branch against your setup, especially if you're on a provider where prompt caching is observable (Anthropic Bedrock / claude.ai API). To try it:

git clone https://github.com/samfoy/pi-memory
cd pi-memory
git checkout feat/context-hook-injection
npm install && npm run build

Then point pi at the local build in your settings.json:

{ "packages": ["/path/to/pi-memory"] }

The default is now context-hook — no config needed to test the new behaviour. Set injectionMode: "system-prompt" to compare against the old path.

Things worth verifying:

• Memory appears correctly at the start of a fresh session
• Memory is still relevant when switching topics mid-conversation
• No duplicate memory blocks when a turn involves many tool calls