feat(honcho): restore full integration parity in memory provider plugin

[erosika]

Summary

Restores full Honcho integration parity in the memory provider plugin and adds configurable observation modes.

Stacked on #4623. All ABC-compliant (session_id kwargs preserved on prefetch, queue_prefetch, sync_turn; **kwargs on on_turn_start).

---

What this adds

The base Honcho plugin in #4623 is functional but minimal — it always runs in hybrid mode with no cost controls, no session naming, no first-turn baking, no lazy init, and hard-codes both peers to observe everything. This PR restores the full feature set from the old baked-in integration and adds observation mode configurability.

Observation modes (new)

observationMode config field: unified (default) or directional.

Aspect	Unified (default)	Directional (opt-in)
Who observes	User peer observes self	AI peer observes user
Cross-AI portable	Yes — all agents share one pool	No — each agent has its own view
Peer config	aiPeer: observeOthers=false	aiPeer: observeOthers=true
peer.chat()	userPeer.chat(query)	aiPeer.chat(query, target=userPeer)
Conclusions	userPeer.conclusions_of(userPeer)	aiPeer.conclusions_of(userPeer)
Best for	Single agent or agent-switching users	Multi-agent workspaces with separation

Files changed: client.py (config field + normalization), session.py (add_peers, dialectic_query, create_conclusion all respect the mode).

Config aliases: shared → unified, separate/cross → directional.

Recall modes (B1)

recall_mode config field: context, tools, or hybrid (default).

Mode	System prompt	Tools	Prefetch
context	Full auto-injected context	Hidden (empty get_tool_schemas())	Every turn
tools	Minimal "use tools" instructions	All 4 tools	None (no injection)
hybrid	Auto-injected + tools available	All 4 tools	Every turn

Peer memory mode gating (B2)

Stub for peer_memory_mode — reads per-peer config (honcho / local / hybrid) and sets _suppress_memory / _suppress_user_profile flags. When Honcho owns a peer's memory, the built-in MEMORY.md/USER.md writes can be suppressed. Wiring into BuiltinMemoryProvider is a follow-up.

Session name resolution (B3)

Replaces the naive platform:user_id session key with cfg.resolve_session_name():

directory mappings → session title → session_id fallback → "hermes-default"

Per-directory session isolation works out of the box. Manual honcho map overrides respected.

First-turn context baking (B4)

On the first system_prompt_block() call, fetches the full Honcho context (user representation, peer card, AI representation, AI identity card) and bakes it into the system prompt. Subsequent calls return the cached block — prompt caching stability across multi-turn conversations.

Cost awareness (B5)

Config-driven cost controls:

Key	Default	Effect
injectionFrequency	every-turn	first-turn injects prefetch only on turn 0
contextCadence	1	Minimum turns between context API calls
dialecticCadence	1	Minimum turns between dialectic API calls
reasoningLevelCap	none	Caps auto-selected reasoning level

Turn tracking via on_turn_start(). Cadence checks gate both prefetch() consumption and queue_prefetch() firing.

Memory file migration (B6)

One-time migration of local memory files (MEMORY.md, USER.md, SOUL.md) into Honcho when a new session has zero messages. Uses migrate_memory_files() on the session manager.

Pre-warming (B7)

On eager init (context/hybrid mode), fires background prefetch_context() and prefetch_dialectic() threads immediately so the first turn has cached results ready.

---

Ports from open PRs

PR	Feature	Implementation
#3265	Token budget enforcement	_truncate_to_budget() — truncates prefetch result to context_tokens * 4 chars at word boundary
#4053	Cron guard	Checks agent_context and platform kwargs; skips all activation for cron/flush contexts
#2645	baseUrl-only flow	is_available() accepts api_key OR base_url (not both required)
#1969	aiPeer sync from SOUL.md	Parses YAML frontmatter name: or markdown # Heading to auto-set cfg.ai_peer
#1957	Lazy session init	Tools-only mode defers _do_session_init() until first handle_tool_call() via _ensure_session()

---

Architecture

initialize()
  ├─ cron guard check
  ├─ recall_mode from config
  ├─ cost-awareness config parse
  ├─ SOUL.md ai_peer sync
  ├─ peer_memory_mode gating
  ├─ tools-only? → defer to _ensure_session()
  └─ eager? → _do_session_init()
                ├─ resolve_session_name()
                ├─ get_or_create() session
                ├─ add_peers (observation_mode-aware)
                ├─ memory file migration (B6)
                └─ pre-warm prefetch threads (B7)

system_prompt_block()
  ├─ first-turn context baking (B4, locked)
  └─ recall_mode-adapted header text (B1)

prefetch()
  ├─ recall_mode gate (B1)
  ├─ injection_frequency gate (B5)
  ├─ join background thread, pop result
  └─ truncate to budget (#3265)

queue_prefetch()
  ├─ recall_mode gate (B1)
  ├─ dialectic cadence check (B5)
  ├─ fire dialectic thread
  └─ fire context thread if cadence allows (B5)

dialectic_query()
  ├─ unified: peer.chat(query) — self-observation
  └─ directional: aiPeer.chat(query, target=userPeer) — cross-observation

create_conclusion()
  ├─ unified: userPeer.conclusions_of(userPeer)
  └─ directional: aiPeer.conclusions_of(userPeer)

---

Files changed

plugins/memory/honcho/__init__.py | 387 +++++++++++++++++++++++++++++++++++---
plugins/memory/honcho/client.py   |  19 ++
plugins/memory/honcho/session.py  |  59 ++++--
 3 files changed, 440 insertions(+), 35 deletions(-)

---

What's NOT in this PR

• Tests for the new features (TODO before marking ready)
• BuiltinMemoryProvider wiring for _suppress_memory / _suppress_user_profile flags
• First-activation hook (resilience spec §1) — memory file migration still uses not session.messages guard
• Resilience patterns (backoff, dead letter, circuit breaker) — documented in resilience spec, follow-up
• Migration script for existing cross-observations → self-observations (needed for users upgrading to unified mode)

Related: #4623, #3276