Merge pull request #160 from vstorm-co/fix/agent-memory-injection-and-subagent-collision

fix: memory injection recency + subagent read_memory collision

Author: DEENUU1

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.33] - 2026-06-26
+
+### Fixed
+
+- **Agent memory injection now keeps the most recent lines, not the oldest** ([#157](https://github.com/vstorm-co/pydantic-deepagents/issues/157)) (`pydantic_deep/toolsets/memory.py`). `format_memory_prompt` truncated an over-budget `MEMORY.md` by keeping the first `max_lines`, but `write_memory` appends new content to the end of the file, so the newest observations were the first to drop out. Truncation now keeps the recency tail (the dropped-line marker moves above the kept tail). Two additions from the same report: authors can pin a foundational head with a `<!-- deep:pin-end -->` marker (`DEFAULT_PIN_END_MARKER`), which is always injected in full so it survives truncation; and injection can be budgeted in approximate tokens via a new `max_tokens` that takes precedence over `max_lines` (reusing the `NUM_CHARS_PER_TOKEN` heuristic). `AgentMemoryToolset` and `MemoryCapability` gain `max_tokens` / `pin_marker`; subagents accept `extra.memory_max_tokens` / `extra.memory_pin_marker`.
+- **Subagent delegation no longer fails with a `read_memory` tool name collision** ([#155](https://github.com/vstorm-co/pydantic-deepagents/issues/155)) (`pydantic_deep/agent.py`). With `include_memory=True` and `include_subagents=True` (both default), the default subagent factory passed `include_memory=True` into each subagent's own `create_deep_agent`, which registered a second `AgentMemoryToolset` ('deep-memory', under the wrong "main" namespace) on top of the one `_inject_subagent_memory_toolset` already injects — a regression since 0.3.30 that made every delegation fail with `AgentMemoryToolset 'deep-memory' defines a tool whose name conflicts ...: 'read_memory'`. The factory no longer creates its own memory toolset; the injected one, correctly namespaced to the subagent, is the single source.
+
 ## [0.3.32] - 2026-06-26
 
 ### Changed

pydantic_deep/__init__.py

@@ -218,6 +218,7 @@ class Analysis(BaseModel):
     DEFAULT_MAX_MEMORY_LINES,
     DEFAULT_MEMORY_DIR,
     DEFAULT_MEMORY_FILENAME,
+    DEFAULT_PIN_END_MARKER,
     AgentMemoryToolset,
     MemoryAccessError,
     MemoryFile,
@@ -412,6 +413,7 @@ class Analysis(BaseModel):
     "DEFAULT_MEMORY_DIR",
     "DEFAULT_MEMORY_FILENAME",
     "DEFAULT_MAX_MEMORY_LINES",
+    "DEFAULT_PIN_END_MARKER",
     # Eviction
     "EvictionCapability",
     "EvictionProcessor",

pydantic_deep/agent.py

@@ -229,7 +229,6 @@ def _make_default_deep_agent_factory(
     edit_format: Any,
     context_files: Any,
     context_discovery: Any,
-    include_memory: bool,
     memory_dir: Any,
     web_search: bool,
     web_fetch: bool,
@@ -266,7 +265,7 @@ def _factory(cfg: dict[str, Any]) -> Any:
             include_builtin_subagents=False,
             context_manager=False,
             cost_tracking=False,
-            include_memory=include_memory,
+            include_memory=False,
             memory_dir=memory_dir,
             context_files=context_files,
             context_discovery=context_discovery,
@@ -305,14 +304,16 @@ def _inject_subagent_memory_toolset(sa_config: SubAgentConfig, memory_dir: str |
     from pydantic_deep.toolsets.memory import (
         DEFAULT_MAX_MEMORY_LINES,
         DEFAULT_MEMORY_DIR,
+        DEFAULT_PIN_END_MARKER,
         AgentMemoryToolset,
     )
 
-    max_lines = extra.get("memory_max_lines", DEFAULT_MAX_MEMORY_LINES)
     mem = AgentMemoryToolset(
         agent_name=sa_config["name"],
         memory_dir=memory_dir or DEFAULT_MEMORY_DIR,
-        max_lines=max_lines,
+        max_lines=extra.get("memory_max_lines", DEFAULT_MAX_MEMORY_LINES),
+        max_tokens=extra.get("memory_max_tokens"),
+        pin_marker=extra.get("memory_pin_marker", DEFAULT_PIN_END_MARKER),
     )
     existing = list(sa_config.get("toolsets", []))
     existing.append(mem)
@@ -940,7 +941,6 @@ def _set_toolset_retries(toolset: AbstractToolset[DeepAgentDeps], max_retries: i
             edit_format=edit_format,
             context_files=context_files,
             context_discovery=context_discovery,
-            include_memory=include_memory,
             memory_dir=memory_dir,
             web_search=web_search,
             web_fetch=web_fetch,

pydantic_deep/capabilities/memory.py

@@ -9,7 +9,11 @@
 from pydantic_ai.capabilities import AbstractCapability
 from pydantic_ai.toolsets import AbstractToolset
 
-from pydantic_deep.toolsets.memory import DEFAULT_MEMORY_DIR, AgentMemoryToolset
+from pydantic_deep.toolsets.memory import (
+    DEFAULT_MEMORY_DIR,
+    DEFAULT_PIN_END_MARKER,
+    AgentMemoryToolset,
+)
 
 
 @dataclass
@@ -31,13 +35,17 @@ class MemoryCapability(AbstractCapability[Any]):
     agent_name: str = "main"
     memory_dir: str = DEFAULT_MEMORY_DIR
     max_lines: int = 200
+    max_tokens: int | None = None
+    pin_marker: str = DEFAULT_PIN_END_MARKER
     _toolset: AgentMemoryToolset | None = field(default=None, init=False, repr=False)
 
     def __post_init__(self) -> None:
         self._toolset = AgentMemoryToolset(
             agent_name=self.agent_name,
             memory_dir=self.memory_dir,
             max_lines=self.max_lines,
+            max_tokens=self.max_tokens,
+            pin_marker=self.pin_marker,
         )
 
     def get_toolset(self) -> AbstractToolset[Any] | None:

pydantic_deep/toolsets/memory.py

@@ -19,6 +19,8 @@
 from pydantic_ai.toolsets import FunctionToolset
 from pydantic_ai_backends import AsyncBackendProtocol
 
+from pydantic_deep.processors.eviction import NUM_CHARS_PER_TOKEN
+
 
 class MemoryAccessError(Exception):
     """The backend denied access to the memory path.
@@ -39,6 +41,15 @@ class MemoryAccessError(Exception):
 DEFAULT_MAX_MEMORY_LINES: int = 200
 """Default max lines to inject into system prompt."""
 
+DEFAULT_PIN_END_MARKER: str = "<!-- deep:pin-end -->"
+"""Marker delimiting the pinned memory head from the truncatable body.
+
+Everything above the first occurrence is always injected verbatim, so
+foundational notes survive truncation; everything below it is the
+recency-truncated body. The default is an HTML comment, invisible in rendered
+markdown.
+"""
+
 # Tool description constants
 
 READ_MEMORY_DESCRIPTION = """\
@@ -131,26 +142,72 @@ async def load_memory(
     return None
 
 
-def format_memory_prompt(memory: MemoryFile, max_lines: int) -> str:
+def _select_recent_lines(lines: list[str], max_lines: int, max_tokens: int | None) -> int:
+    """Return how many trailing lines fit the budget (>=1 when `lines` is non-empty).
+
+    The *most recent* lines are the ones kept, since `write_memory` appends new
+    content to the end of the file. `max_tokens` (approximate, via
+    `NUM_CHARS_PER_TOKEN`) takes precedence over `max_lines` when provided.
+    """
+    if not lines:
+        return 0
+    if max_tokens is None:
+        return min(len(lines), max_lines)
+
+    char_budget = max_tokens * NUM_CHARS_PER_TOKEN
+    used = 0
+    kept = 0
+    for line in reversed(lines):
+        used += len(line) + 1  # +1 approximates the joining newline
+        if used > char_budget and kept >= 1:
+            break
+        kept += 1
+    return kept
+
+
+def format_memory_prompt(
+    memory: MemoryFile,
+    max_lines: int,
+    *,
+    max_tokens: int | None = None,
+    pin_marker: str = DEFAULT_PIN_END_MARKER,
+) -> str:
     """Format memory content for system prompt injection.
 
-    Only the first `max_lines` lines are included to stay within
-    token budget. If truncated, a marker is added.
+    `write_memory` appends new content, so the newest observations live at the
+    end of the file. When memory exceeds the budget, the *most recent* lines are
+    kept (the tail), not the oldest. Content above the first `pin_marker` is a
+    pinned head that is always injected in full, so foundational notes survive
+    truncation. If the body is truncated, a marker noting the dropped lines is
+    inserted above the kept tail.
 
     Args:
         memory: Loaded memory file.
-        max_lines: Maximum number of lines to include.
+        max_lines: Maximum number of body lines to include.
+        max_tokens: Optional approximate token budget for the body. When set it
+            takes precedence over `max_lines`, using the `NUM_CHARS_PER_TOKEN`
+            heuristic used elsewhere in the library.
+        pin_marker: Marker whose first occurrence ends the always-injected head.
 
     Returns:
         Formatted system prompt section.
     """
-    lines = memory.content.splitlines()
-    if len(lines) > max_lines:
-        truncated_count = len(lines) - max_lines
-        content = "\n".join(lines[:max_lines])
-        content += f"\n\n... [{truncated_count} more lines in memory] ..."
-    else:
-        content = memory.content
+    pinned = ""
+    body = memory.content
+    marker_idx = memory.content.find(pin_marker)
+    if marker_idx != -1:
+        pinned = memory.content[:marker_idx].rstrip("\n")
+        body = memory.content[marker_idx + len(pin_marker) :].lstrip("\n")
+
+    body_lines = body.splitlines()
+    keep = _select_recent_lines(body_lines, max_lines, max_tokens)
+    if keep < len(body_lines):
+        dropped = len(body_lines) - keep
+        body = f"... [{dropped} more lines in memory] ..."
+        if keep:
+            body += "\n\n" + "\n".join(body_lines[-keep:])
+
+    content = f"{pinned}\n\n{body}" if pinned and body else pinned or body
 
     return f"## Agent Memory ({memory.agent_name})\n\n{content}"
 
@@ -176,14 +233,21 @@ def __init__(
         agent_name: str = "main",
         memory_dir: str = DEFAULT_MEMORY_DIR,
         max_lines: int = DEFAULT_MAX_MEMORY_LINES,
+        max_tokens: int | None = None,
+        pin_marker: str = DEFAULT_PIN_END_MARKER,
         descriptions: dict[str, str] | None = None,
     ) -> None:
         """Initialize the memory toolset.
 
         Args:
             agent_name: Name of the agent (used for path and prompt label).
             memory_dir: Base directory for memory files in the backend.
-            max_lines: Max lines to inject into system prompt.
+            max_lines: Max body lines to inject into the system prompt. The most
+                recent lines are kept (`write_memory` appends to the end).
+            max_tokens: Optional approximate token budget for injection. When set
+                it takes precedence over `max_lines`.
+            pin_marker: Marker whose first occurrence ends the always-injected
+                pinned head, so foundational notes survive truncation.
             descriptions: Optional mapping of tool name to custom description.
                 Supported keys: `read_memory`, `write_memory`, `update_memory`.
                 Any key not present falls back to the built-in description constant.
@@ -192,6 +256,8 @@ def __init__(
         self._agent_name = agent_name
         self._memory_dir = memory_dir
         self._max_lines = max_lines
+        self._max_tokens = max_tokens
+        self._pin_marker = pin_marker
         self._descs = descriptions or {}
         self._path = get_memory_path(memory_dir, agent_name)
 
@@ -285,5 +351,10 @@ async def get_instructions(self, ctx: RunContext[Any]) -> list[InstructionPart]
             return None
         if mem is None:
             return None
-        result = format_memory_prompt(mem, self._max_lines)
+        result = format_memory_prompt(
+            mem,
+            self._max_lines,
+            max_tokens=self._max_tokens,
+            pin_marker=self._pin_marker,
+        )
         return [InstructionPart(content=result, dynamic=True)] if result else None

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pydantic-deep"
-version = "0.3.32"
+version = "0.3.33"
 description = "Batteries-included agent harness for Python — tool-calling, sandboxed execution, multi-agent teams, and unlimited context on Pydantic AI"
 readme = "README.md"
 keywords = [

tests/test_agent.py

@@ -81,7 +81,6 @@ def _default_factory(**parent_kwargs: object) -> Any:
             edit_format=None,
             context_files=None,
             context_discovery=False,
-            include_memory=False,
             memory_dir=None,
             web_search=False,
             web_fetch=False,
@@ -147,6 +146,46 @@ def test_subagent_configs_not_mutated_and_no_toolset_doubling(self):
             assert "agent_factory" not in cfg
             assert cfg["toolsets"] == []
 
+    def test_subagent_factory_single_memory_toolset(self):
+        """Regression for #155: the default subagent factory must not register a
+        second AgentMemoryToolset.
+
+        `_inject_subagent_memory_toolset` adds one memory toolset under the
+        subagent's own name; the factory previously also passed
+        `include_memory=True`, so `create_deep_agent` added a second 'deep-memory'
+        toolset (under the wrong "main" name), causing a `read_memory` collision.
+        """
+        from pydantic_deep.agent import _inject_subagent_memory_toolset
+        from pydantic_deep.toolsets.memory import AgentMemoryToolset
+
+        cfg: SubAgentConfig = SubAgentConfig(
+            name="researcher", description="explores", instructions="explore", toolsets=[]
+        )
+        _inject_subagent_memory_toolset(cfg, None)
+
+        sub_agent = self._default_factory()(cfg)
+
+        seen: set[int] = set()
+        found: list[Any] = []
+
+        def _walk(toolsets: Any) -> None:
+            for ts in toolsets:
+                if id(ts) in seen:
+                    continue
+                seen.add(id(ts))
+                found.append(ts)
+                for attr in ("toolsets", "_toolsets", "wrapped"):
+                    inner = getattr(ts, attr, None)
+                    if isinstance(inner, (list, tuple)):
+                        _walk(inner)
+                    elif inner is not None and inner is not ts:
+                        _walk([inner])
+
+        _walk(list(getattr(sub_agent, "toolsets", []) or []))
+        memory_toolsets = [t for t in found if isinstance(t, AgentMemoryToolset)]
+        assert len(memory_toolsets) == 1
+        assert memory_toolsets[0]._agent_name == "researcher"
+
     def test_create_with_interrupt_on(self):
         """Test creating an agent with interrupt_on config."""
         agent = create_deep_agent(

tests/test_capabilities.py

@@ -87,6 +87,12 @@ def test_custom_name(self):
         cap = MemoryCapability(agent_name="worker")
         assert cap.agent_name == "worker"
 
+    def test_max_tokens_passed_to_toolset(self):
+        """`max_tokens` is forwarded to the underlying AgentMemoryToolset (#157)."""
+        cap = MemoryCapability(max_tokens=1500)
+        assert cap._toolset is not None
+        assert cap._toolset._max_tokens == 1500
+
     def test_get_toolset(self):
         cap = MemoryCapability()
         assert cap.get_toolset() is not None