✨ Feat: add active memory tools (StoreMemoryTool, SearchMemoryTool)

[JasonW404]

Summary

Add active memory tools that allow agents to explicitly store and search memories during their ReAct reasoning loop, complementing the existing passive memory injection system.

Changes

New Tools

• StoreMemoryTool (sdk/nexent/core/tools/store_memory_tool.py): Allows agents to explicitly save important information to long-term memory mid-conversation. Respects user preferences (agent_share_option, disabled_agent_ids), enforces a rate limit of 3 stores per run, and integrates with the observer pattern for UI feedback.
• SearchMemoryTool (sdk/nexent/core/tools/search_memory_tool.py): Allows agents to search long-term memory on-demand when they need context not available in the current conversation. Searches across all enabled memory levels (tenant, user, agent, user_agent) with configurable top_k.

Integration

• backend/agents/create_agent_info.py: Conditionally injects memory tools into the agent's tool list when memory is enabled. Tools are invisible in the tool management UI (not registered in ag_tool_info_t) and auto-injected at runtime.
• sdk/nexent/core/agents/nexent_agent.py: Added create_local_tool() branches for memory tools and _is_retriever_tool() classification for SearchMemoryTool (uses retriever tracing instead of tool tracing).
• sdk/nexent/core/tools/__init__.py: Registered both tools in exports.
• sdk/nexent/core/utils/tools_common_message.py: Added ToolSign.MEMORY_OPERATION = "n" to avoid collision with existing tool signs.

Bug Fix

• sdk/nexent/memory/memory_core.py: Fixed cache key from config_hash to (config_hash, id(event_loop)) to prevent cross-event-loop binding errors when the memory instance is reused across different async contexts.

Tests

• test/sdk/core/tools/test_store_memory_tool.py: 17 tests covering invocation, rate limiting, preference filtering, error handling.
• test/sdk/core/tools/test_search_memory_tool.py: 13 tests covering search, preference filtering, error handling, result formatting.

Design Decisions

1. Two tools only (no delete/list) — delete is dangerous, list is admin-only
2. No memory_level input — system auto-selects levels based on user preferences
3. No double-write guard — mem0's built-in dedup (NONE event for duplicates) handles passive/active overlap safely
4. Lazy imports — memory_service imported inside forward() to avoid import chain failures in test environments
5. Graceful degradation — memory tool injection wrapped in try/except so agent creation never fails due to memory issues

Testing

• All 8,707 existing CI tests pass (1 pre-existing failure unrelated to changes)
• 30 new unit tests for both tools pass
• Verified locally with Docker-based dev environment (ES, PG, MinIO)

[Copilot]

Pull request overview

This PR adds “active memory” capabilities to Nexent agents by introducing two new tools that can explicitly store and search long-term memory during an agent run, and wires them into agent/tool creation and tracing.

Changes:

• Added StoreMemoryTool and SearchMemoryTool plus corresponding unit tests.
• Integrated memory tools into runtime tool injection and tool classification/tracing.
• Adjusted memory-core caching behavior to avoid cross-event-loop binding errors.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
sdk/nexent/core/tools/store_memory_tool.py	New tool to actively store extracted facts into long-term memory with per-run rate limiting.
sdk/nexent/core/tools/search_memory_tool.py	New tool to actively query long-term memory across configured levels.
sdk/nexent/core/tools/__init__.py	Exports the new memory tools from the tools package.
sdk/nexent/core/agents/nexent_agent.py	Adds tool creation branch for memory tools and classifies SearchMemoryTool as a retriever for tracing.
backend/agents/create_agent_info.py	Injects active memory tools into the agent tool list when memory is enabled.
sdk/nexent/core/utils/tools_common_message.py	Adds a new ToolSign for memory operations and updates mappings.
sdk/nexent/memory/memory_core.py	Changes cache key derivation to incorporate event loop identity.
test/sdk/core/tools/test_store_memory_tool.py	New unit tests for store-memory behavior, limits, preferences, and error handling.
test/sdk/core/tools/test_search_memory_tool.py	New unit tests for search-memory behavior, preferences, formatting, and error handling.
doc/procedural-memory-verification.md	Adds documentation/report content about procedural memory dependency requirements.
.gitignore	Ignores pytest temp output and generated doc assets.

---

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

[JasonW404]

asyncio.run() 在 forward() 中调用，但 forward() 可能在已有事件循环的上下文中执行（如 agent 的 async run loop）。asyncio.run() 会创建新的事件循环，如果当前线程已有运行中的事件循环，会抛出 RuntimeError: asyncio.run() cannot be called from a running event loop。建议使用 asyncio.get_event_loop().run_until_complete() 或检查是否已有运行中的循环。

[YehongPan]

[代码规范] except Exception: 过于宽泛，建议捕获更具体的异常类型，避免掩盖潜在错误。

[YehongPan]

[代码规范] except Exception: 过于宽泛，建议捕获更具体的异常类型，避免掩盖潜在错误。

[YehongPan]

[代码规范] except Exception: 过于宽泛，建议捕获更具体的异常类型，避免掩盖潜在错误。

[JasonW404]

StoreMemoryTool 和 SearchMemoryTool 通过无参构造 tool_class() 实例化，然后通过手动赋值设置属性（observer, memory_config, tenant_id 等）。这种方式绕过了构造函数验证，如果属性名拼写错误或遗漏，运行时才会暴露问题。建议通过构造函数参数传入这些依赖，或在实例化后添加属性完整性检查。

[WMC001]

Bug 1 (CRITICAL): asyncio.run() inside sync forward() methods creates event loop per call — defeats get_memory_instance caching

sdk/nexent/core/tools/store_memory_tool.py line ~682 and sdk/nexent/core/tools/search_memory_tool.py line ~569 both call asyncio.run(search_memory_in_levels(...)) from a synchronous forward() method.

Two problems compound:

1. Event loop created per call. smolagents' Tool base class requires forward() to be synchronous, so each invocation of forward() calls asyncio.run(...), which creates a fresh event loop. The AsyncMemory instance lives inside that loop, so all its socket pools, ES connections, and LLM clients are torn down and recreated on every single tool call. This is catastrophic for latency and connection-pool reuse.

2. get_memory_instance cache is keyed by id(loop) (this same PR, memory_core.py line ~741). Because each forward() invocation runs in a brand-new event loop, id(loop) is always different, so the cache never hits — every tool call rebuilds the entire memory config (LLM, embedder, vector store) from scratch. The cache change is itself the cause of this issue: if the cache were still keyed by config hash alone, the previous loop's resources could be reused; with id(loop), every call is a cache miss.

3. asyncio.run() fails if a loop is already running. If forward() is ever invoked from inside an async context (e.g. an async test or a future integration where the tool is awaited from another coroutine), asyncio.run() raises RuntimeError: asyncio.run() cannot be called from a running event loop.

Fix options:

• Option A: Make the memory service synchronous (use Memory not AsyncMemory), and remove the id(loop) cache key. Simplest, no event-loop juggling.
• Option B: Move the asyncio.run() out of forward() entirely. Have create_local_tool or the agent runner precompute the sync-wrapped version once at agent init time (e.g., tool.forward = sync(forward_async)), so the loop is created once per agent run.
• Option C: Use a long-lived singleton loop running in a background thread (loop.run_in_executor style) and dispatch async work via asyncio.run_coroutine_threadsafe.

The current implementation will work but adds 1-2s of cold-start latency on every tool call due to ES + LLM client rebuild, and any future async-context caller will crash.

Bug 2 (HIGH): get_memory_instance cache key now misses every time after this PR

sdk/nexent/memory/memory_core.py line 740-742:

config_hash = _hash_config(memory_config)
loop = asyncio.get_event_loop()
cache_key = f"{config_hash}:{id(loop)}"

If get_memory_instance is called from within the per-call asyncio.run(...) (Bug 1), each call gets a different loop id, so the cache never hits. Even ignoring Bug 1, the id(loop) approach is fragile: Python's event loops are recycled (the CPython runtime may reuse the memory address of a freed loop), so two distinct loops over time could collide on id().

Fix: key the cache by config_hash alone (the original behavior), or by (config_hash, tenant_id) if tenant-level isolation is needed.