feat(strands): add Neo4jSessionManager — push-based conversation persistence for Strands agents

[Andy2003]

Summary

Adds Neo4jSessionManager, a Strands Agents SessionManager backed by MemoryClient
(self-hosted bolt and hosted NAMS) — the same posture AWS Bedrock AgentCore takes with
AgentCoreMemorySessionManager. The existing Strands integration is pull-based (@tool
functions the agent must decide to call); this adds the push-based half: every turn is
persisted automatically, history is restored on agent restart, and relevant long-term
memories can be injected into each user message.

agent = Agent(
    model="anthropic.claude-sonnet-4-20250514-v1:0",
    tools=nams_context_graph_tools(),
    session_manager=Neo4jSessionManager.for_nams(
        "support-42", retrieval_config=Neo4jRetrievalConfig()
    ),
)

Design spec: docs/superpowers/specs/2026-06-05-strands-session-manager-design.md

What's included

• Neo4jSessionManager (integrations/strands/session_manager.py) — direct
  SessionManager ABC implementation: lifecycle, hook wiring, write-behind buffer
• _retrieval.py — Neo4jRetrievalConfig + concurrent long-term search and
  <user_context> block formatting (opt-in per-turn injection)
• _messages.py — pure Strands ↔ Memory message mapping
• AsyncBridge (integrations/base.py) — shared persistent-event-loop bridge for
  sync code driving loop-bound async transports
• Shared NAMS settings-from-env helpers in integrations/strands/config.py
  (deduplicates three previously-identical blocks)
• Restructured aws-strands.adoc: both modes presented as one integration, combined
  Quick Start, constructor reference, documented limitations
• Runnable shared-brain example (examples/strands-session-manager/, no API keys needed)

Key design decisions

• No Strands-specific node types in the graph. A Strands session maps to one
  Conversation; messages map to Message. Persistence is memory-grade: text turns are
  stored (and feed entity extraction / the shared brain); tool-use blocks and
  agent.state are not round-tripped — that's FileSessionManager's job.
• Write-behind one-slot buffer for redaction. NAMS has no message update/delete
  endpoint; guardrail redaction rewrites the buffer before the original ever reaches
  the backend. sync_agent is a strict no-op because the Strands base class also fires it
  on MessageAddedEvent — flushing there would defeat the redaction window.
• Injection never contaminates storage. Hooks fire in registration order, so the
  original message is persisted before the in-memory copy is augmented; injection is
  idempotent per message and degrades (warn + skip) on retrieval failures.
• Backend capability awareness. Structurally-unsupported NAMS calls
  (preference/fact search, message delete) are skipped or warned once, not retried per turn.

Limitations (documented in the guide)

agent.state and conversation-manager window state don't survive restarts; redaction
after a flush falls back to delete-and-re-add on bolt and warns on NAMS; one agent per
manager instance (Graph/Swarm persistence out of scope for v1); searches are
workspace-scoped (user_id scopes writes).

Test plan

• 53 unit tests (tests/unit/integrations/test_strands_session_manager.py) incl.
  buffer/redaction privacy invariants, hook-ordering, NAMS-mode semantics — green ×2
• 2 bolt integration tests against Docker Neo4j (persist/restore round-trip,
  redaction never stores the original)
• 12 example smoke tests; example runs end-to-end without API keys
• make lint / format clean; zero new mypy errors (253 baseline errors pre-exist on
  main); uvx ty check clean on all branch files
• 575 docs-syntax tests pass (remaining tests/docs failures pre-exist on main:
  7 need npm build output, 3 are stale-data assertions in unrelated pages)

[vercel]

@Andy2003 is attempting to deploy a commit to the lyonwj's projects Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agent-memory	Ready	Preview, Comment	Jul 10, 2026 3:41pm

[Andy2003]

The Strands integration here is ty- and mypy-clean. One deliberate cross-type cast remains in session_manager.py (_aresolve_conversation): MemoryClient.short_term is statically the concrete bolt ShortTermMemory, but list_conversations/create_conversation live on ShortTermProtocol (implemented by the NAMS backend). The proper fix — widening the property to ShortTermProtocol and removing two existing # type: ignores in __init__.py — is a core/public-API change, tracked separately in #143. That issue also captures the run_sync ParamSpec fix and the strands-extra checker config.

[Copilot]

Pull request overview

This PR adds a push-based Strands Agents integration by introducing Neo4jSessionManager, enabling automatic conversation persistence/restore backed by neo4j-agent-memory (bolt or hosted NAMS) and optional per-turn long-term memory injection (Neo4jRetrievalConfig). It complements the existing pull-based Strands @tool integration and documents both modes together.

Changes:

• Add Neo4jSessionManager with write-behind buffering (for redaction), lifecycle/hook wiring, optional tool-call mirroring, and a NAMS factory constructor.
• Add retrieval/context injection (_retrieval.py) and message mapping helpers (_messages.py), plus a shared persistent async↔sync bridge (AsyncBridge).
• Add extensive unit/integration/example/doc tests and update Strands documentation and changelog.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/unit/integrations/test_strands_session_manager.py	Comprehensive unit coverage for buffering/redaction, hook ordering, NAMS semantics, injection idempotency, and bridge behavior.
tests/unit/integrations/strands_fakes.py	Stateful fake MemoryClient surfaces used by the session-manager unit tests.
tests/integration/test_strands_session_manager.py	Bolt-backed integration tests for persist/restore and redaction invariants.
tests/examples/test_strands_session_manager_example.py	Smoke tests ensuring the runnable example structure, imports, and key calls remain intact.
tests/docs/test_code_snippets.py	Ensures new Strands integration exports are referenced and importable when Strands is installed.
src/neo4j_agent_memory/integrations/strands/tools.py	Tighten typing and deduplicate NAMS settings/env resolution via shared helpers.
src/neo4j_agent_memory/integrations/strands/session_manager.py	New Neo4jSessionManager implementation: persistence, buffering/redaction, injection, and NAMS resolution logic.
src/neo4j_agent_memory/integrations/strands/config.py	Add shared NAMS connection/settings helpers used by both tools and session manager.
src/neo4j_agent_memory/integrations/strands/_retrieval.py	New retrieval config + concurrent long-term searches + context block formatting.
src/neo4j_agent_memory/integrations/strands/_messages.py	Pure Strands ↔ stored message mapping helpers.
src/neo4j_agent_memory/integrations/strands/init.py	Export session manager + retrieval config and tighten llm_provider_from_strands typing.
src/neo4j_agent_memory/integrations/base.py	Add AsyncBridge for persistent background event loop bridging.
examples/strands-session-manager/README.md	Document the shared-brain demo and how to use the session manager (bolt + NAMS).
examples/strands-session-manager/main.py	Runnable three-phase demo (persist, seed LTM, inject, restore) without API keys.
docs/superpowers/specs/2026-06-05-strands-session-manager-design.md	Design spec capturing architecture, semantics, and constraints (bolt vs NAMS).
docs/modules/ROOT/pages/how-to/integrations/aws-strands.adoc	Restructure docs to present tools + session manager as complementary modes; add quick starts and limitations.
CHANGELOG.md	Add release notes entry for the new Strands session manager capabilities.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.