everalgo-agent-memory 0.1.0__tar.gz

everalgo_agent_memory-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+
+# Environments
+.env
+.env.local
+.venv
+env/
+venv/
+
+# uv
+.uv/
+
+# Test / coverage / cache
+.pytest_cache/
+.cache
+.coverage
+.coverage.*
+coverage.xml
+report.xml
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+
+# Type checkers / linters
+.mypy_cache/
+.dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDE / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Logs
+*.log
+
+# Project local artifacts (placed under local/ per project convention)
+local/
+
+# Claude Code session-local state (scheduled tasks, agent caches, locks)
+.claude/

everalgo_agent_memory-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this package are documented here. Format follows
+[Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/). Versioning
+follows [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `AgentBoundaryDetector`: facade class that filters a `list[ConversationItem]` to only tool-call-carrying turns, calls `everalgo.boundary.detect_boundaries` on the result, then remaps indices back to the original sequence.
+- `AgentCaseExtractor`: 11-step pipeline — heuristic skip check, tool-call-round counting, message trimming / pre-compression, `AgentCase` extraction via LLM. Accepts `llm=` at construction time.
+- `AgentSkillExtractor`: add / update / retire operations with `cluster_id` binding; accepts `llm=` at construction time. `SkillConfig` pydantic model exposes maturity and retire thresholds.
+- English prompts for case and skill extraction under `agent_memory/prompts/en/`.
+
+### Changed
+
+- `AgentCaseExtractor` and `AgentSkillExtractor` rewired to the unified `MemCell` contract (replacing the previous `AgentMemCell` type).
+
+### Removed
+
+- Broad `except Exception → None` handler in `_evaluate_maturity`: the function now propagates exceptions from the LLM call.
+- `asyncio.gather(return_exceptions=True)` in `_pre_compress_to_list`: individual compression errors now propagate instead of being swallowed.
+- Fail-open path in `_is_worth_extracting`: the function raises on LLM error instead of returning `True` unconditionally.
+
+[Unreleased]: https://github.com/EverMind-AI/EverAlgo/compare/main...HEAD

everalgo_agent_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EverMind
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

everalgo_agent_memory-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: everalgo-agent-memory
+Version: 0.1.0
+Summary: EverAlgo agent memory: AgentCase / AgentSkill extractors and AgentBoundaryDetector facade.
+Project-URL: Homepage, https://github.com/EverMind-AI/EverAlgo
+Project-URL: Repository, https://github.com/EverMind-AI/EverAlgo
+Project-URL: Issues, https://github.com/EverMind-AI/EverAlgo/issues
+Project-URL: Documentation, https://github.com/EverMind-AI/EverAlgo/tree/main/packages/everalgo-agent-memory
+Project-URL: Changelog, https://github.com/EverMind-AI/EverAlgo/blob/main/packages/everalgo-agent-memory/CHANGELOG.md
+Author: EverMind
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: everalgo-boundary<2.0.0,>=0.1.0
+Requires-Dist: everalgo-clustering<2.0.0,>=0.1.0
+Requires-Dist: everalgo-core<2.0.0,>=0.1.0
+Description-Content-Type: text/markdown
+
+# everalgo-agent-memory
+
+Agent-side memory products for EverAlgo — `AgentCaseExtractor` distils an agent trajectory `MemCell` into one `AgentCase`; `AgentSkillExtractor` maintains a cluster's reusable skill set from accumulated cases. `AgentBoundaryDetector` handles boundary detection over mixed `ConversationItem` trajectories (chat + tool calls).
+
+See the umbrella project: [EverAlgo monorepo](../../README.md) and the architecture document at [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md).
+
+## Install
+
+```bash
+pip install everalgo-agent-memory
+# Auto-pulls: everalgo-core, everalgo-boundary, everalgo-clustering
+```
+
+## What this distribution provides
+
+| Symbol | Role |
+|---|---|
+| `AgentBoundaryDetector` | Boundary detection on agent trajectories (filter → detect → remap for mixed `ConversationItem` lists) |
+| `AgentCaseExtractor` | Distils one agent-trajectory `MemCell` into `[] \| [AgentCase]` (11-step pipeline) |
+| `AgentSkillExtractor` | Aggregates one new `AgentCase` into incremental skill operations for a cluster; returns add / update / retire entries |
+
+## Quick start
+
+```python
+import asyncio
+import json
+
+from everalgo.agent_memory.case import AgentCaseExtractor
+from everalgo.llm.types import ChatResponse
+from everalgo.testing.fake_llm import FakeLLMClient
+from everalgo.types import AgentCase, ChatMessage, MemCell, ToolCall, ToolCallFunction, ToolCallRequest, ToolCallResult
+
+_CASE_JSON = json.dumps({
+    "task_intent": "Search for Python async retry libraries",
+    "approach": "1. Search. 2. Filter. 3. Summarise.",
+    "quality_score": 0.82,
+    "key_insight": "Use tenacity AsyncRetrying for native async back-off.",
+})
+
+async def main() -> None:
+    fake = FakeLLMClient(responses=[ChatResponse(content=_CASE_JSON, model="fake")])
+    mc = MemCell(
+        items=[
+            ChatMessage(id="u1", role="user", content="Best async retry libs?", timestamp=1_700_000_000_000, sender_id="user"),
+            ToolCallRequest(tool_calls=[ToolCall(id="c1", function=ToolCallFunction(name="web.search", arguments='{}'))], timestamp=1_700_000_000_100, sender_id="assistant"),
+            ToolCallResult(tool_call_id="c1", content="Found: tenacity.", timestamp=1_700_000_000_200),
+            ToolCallRequest(tool_calls=[ToolCall(id="c2", function=ToolCallFunction(name="web.search", arguments='{}'))], timestamp=1_700_000_000_300, sender_id="assistant"),
+            ToolCallResult(tool_call_id="c2", content="tenacity supports async.", timestamp=1_700_000_000_400),
+            ChatMessage(id="a1", role="assistant", content="Use tenacity AsyncRetrying.", timestamp=1_700_000_000_500, sender_id="assistant"),
+        ],
+        timestamp=1_700_000_000_500,
+    )
+
+    cases: list[AgentCase] = await AgentCaseExtractor(llm=fake).aextract(mc)
+    if cases:
+        print(cases[0].task_intent)
+
+asyncio.run(main())
+```
+
+See [`examples/04_agent_memory_case.py`](../../examples/04_agent_memory_case.py) for the full runnable example.
+
+## API surface
+
+```python
+class AgentBoundaryDetector:
+    def __init__(self, *, llm: LLMClient) -> None: ...
+    async def adetect(
+        self, items: list[ConversationItem], *, is_final: bool = False, prompt: str | None = None
+    ) -> DetectionResult: ...
+
+class AgentCaseExtractor:
+    def __init__(self, *, llm: LLMClient) -> None: ...
+    async def aextract(
+        self, memcell: MemCell, *,
+        prompt_filter: str | None = None,
+        prompt_compress: str | None = None,
+        prompt_tool_pre_compress: str | None = None,
+    ) -> list[AgentCase]: ...  # length 0 (filtered) or 1
+
+class AgentSkillExtractor:
+    def __init__(self, *, llm: LLMClient) -> None: ...
+    async def aextract(
+        self,
+        case: AgentCase,
+        *,
+        existing_relevant_skills: Sequence[AgentSkill],
+        supporting_cases: Sequence[AgentCase],
+        prompt_success: str | None = None,
+        prompt_failure: str | None = None,
+        prompt_maturity: str | None = None,
+        skip_quality_threshold: float = 0.2,
+        skip_maturity_scoring: bool = True,
+        maturity_threshold: float = 0.6,
+        retire_confidence: float = 0.1,
+        failure_quality_threshold: float = 0.5,
+        max_case_history: int = 9,
+        max_description_tokens: int = 400,
+        max_content_tokens: int = 5000,
+        maturity_trivial_change_ratio: float = 0.2,
+        maturity_reeval_change_ratio: float = 0.4,
+    ) -> list[AgentSkill]: ...
+```
+
+All class methods have a sync bridge: `extractor.extract(...)` is `async_to_sync(aextract)`.
+
+### AgentCaseExtractor pipeline
+
+The extractor runs an 11-step pipeline: strip-before-first-user → structural pre-filter → heuristic trim → over-size bail → LLM filter (skipped when ≥2 tool rounds) → tool pre-compress → LLM compress → parse → validate → build `AgentCase`. Returns `[]` when the trajectory is filtered out; returns `[AgentCase]` on success.
+
+### AgentSkillExtractor return contract
+
+Pass the new `AgentCase` and the pre-filtered `existing_relevant_skills` (e.g. top-K cosine from the caller's store) plus the associated `supporting_cases` (cases referenced by existing skills). The caller decodes add / update / retire by checking whether `skill.id` is already in `existing_relevant_skills` and whether `skill.confidence < retire_confidence`.
+
+Cases with `quality_score < skip_quality_threshold` (default 0.2) short-circuit to `[]` without calling the LLM.
+
+`AgentSkill.cluster_id` is always `""` on extraction — the caller stamps the cluster identity after persisting.
+
+### Customising prompts
+
+```python
+import everalgo.agent_memory.prompts.case_filter as _cf
+_cf.AGENT_CASE_FILTER_PROMPT = my_custom_filter_prompt   # global override
+```
+
+Or per-call: pass `prompt_filter=` / `prompt_compress=` / `prompt_tool_pre_compress=` to `aextract`.
+
+## Related distributions
+
+- [`everalgo-boundary`](../everalgo-boundary/) — `detect_boundaries` primitive used by `AgentBoundaryDetector`
+- [`everalgo-clustering`](../everalgo-clustering/) — `cluster_by_llm` for skill-cluster assignment
+- [`everalgo-rank`](../everalgo-rank/) — `CaseRanker` / `SkillRanker` for read-time ranking

everalgo_agent_memory-0.1.0/README.md

@@ -0,0 +1,132 @@
+# everalgo-agent-memory
+
+Agent-side memory products for EverAlgo — `AgentCaseExtractor` distils an agent trajectory `MemCell` into one `AgentCase`; `AgentSkillExtractor` maintains a cluster's reusable skill set from accumulated cases. `AgentBoundaryDetector` handles boundary detection over mixed `ConversationItem` trajectories (chat + tool calls).
+
+See the umbrella project: [EverAlgo monorepo](../../README.md) and the architecture document at [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md).
+
+## Install
+
+```bash
+pip install everalgo-agent-memory
+# Auto-pulls: everalgo-core, everalgo-boundary, everalgo-clustering
+```
+
+## What this distribution provides
+
+| Symbol | Role |
+|---|---|
+| `AgentBoundaryDetector` | Boundary detection on agent trajectories (filter → detect → remap for mixed `ConversationItem` lists) |
+| `AgentCaseExtractor` | Distils one agent-trajectory `MemCell` into `[] \| [AgentCase]` (11-step pipeline) |
+| `AgentSkillExtractor` | Aggregates one new `AgentCase` into incremental skill operations for a cluster; returns add / update / retire entries |
+
+## Quick start
+
+```python
+import asyncio
+import json
+
+from everalgo.agent_memory.case import AgentCaseExtractor
+from everalgo.llm.types import ChatResponse
+from everalgo.testing.fake_llm import FakeLLMClient
+from everalgo.types import AgentCase, ChatMessage, MemCell, ToolCall, ToolCallFunction, ToolCallRequest, ToolCallResult
+
+_CASE_JSON = json.dumps({
+    "task_intent": "Search for Python async retry libraries",
+    "approach": "1. Search. 2. Filter. 3. Summarise.",
+    "quality_score": 0.82,
+    "key_insight": "Use tenacity AsyncRetrying for native async back-off.",
+})
+
+async def main() -> None:
+    fake = FakeLLMClient(responses=[ChatResponse(content=_CASE_JSON, model="fake")])
+    mc = MemCell(
+        items=[
+            ChatMessage(id="u1", role="user", content="Best async retry libs?", timestamp=1_700_000_000_000, sender_id="user"),
+            ToolCallRequest(tool_calls=[ToolCall(id="c1", function=ToolCallFunction(name="web.search", arguments='{}'))], timestamp=1_700_000_000_100, sender_id="assistant"),
+            ToolCallResult(tool_call_id="c1", content="Found: tenacity.", timestamp=1_700_000_000_200),
+            ToolCallRequest(tool_calls=[ToolCall(id="c2", function=ToolCallFunction(name="web.search", arguments='{}'))], timestamp=1_700_000_000_300, sender_id="assistant"),
+            ToolCallResult(tool_call_id="c2", content="tenacity supports async.", timestamp=1_700_000_000_400),
+            ChatMessage(id="a1", role="assistant", content="Use tenacity AsyncRetrying.", timestamp=1_700_000_000_500, sender_id="assistant"),
+        ],
+        timestamp=1_700_000_000_500,
+    )
+
+    cases: list[AgentCase] = await AgentCaseExtractor(llm=fake).aextract(mc)
+    if cases:
+        print(cases[0].task_intent)
+
+asyncio.run(main())
+```
+
+See [`examples/04_agent_memory_case.py`](../../examples/04_agent_memory_case.py) for the full runnable example.
+
+## API surface
+
+```python
+class AgentBoundaryDetector:
+    def __init__(self, *, llm: LLMClient) -> None: ...
+    async def adetect(
+        self, items: list[ConversationItem], *, is_final: bool = False, prompt: str | None = None
+    ) -> DetectionResult: ...
+
+class AgentCaseExtractor:
+    def __init__(self, *, llm: LLMClient) -> None: ...
+    async def aextract(
+        self, memcell: MemCell, *,
+        prompt_filter: str | None = None,
+        prompt_compress: str | None = None,
+        prompt_tool_pre_compress: str | None = None,
+    ) -> list[AgentCase]: ...  # length 0 (filtered) or 1
+
+class AgentSkillExtractor:
+    def __init__(self, *, llm: LLMClient) -> None: ...
+    async def aextract(
+        self,
+        case: AgentCase,
+        *,
+        existing_relevant_skills: Sequence[AgentSkill],
+        supporting_cases: Sequence[AgentCase],
+        prompt_success: str | None = None,
+        prompt_failure: str | None = None,
+        prompt_maturity: str | None = None,
+        skip_quality_threshold: float = 0.2,
+        skip_maturity_scoring: bool = True,
+        maturity_threshold: float = 0.6,
+        retire_confidence: float = 0.1,
+        failure_quality_threshold: float = 0.5,
+        max_case_history: int = 9,
+        max_description_tokens: int = 400,
+        max_content_tokens: int = 5000,
+        maturity_trivial_change_ratio: float = 0.2,
+        maturity_reeval_change_ratio: float = 0.4,
+    ) -> list[AgentSkill]: ...
+```
+
+All class methods have a sync bridge: `extractor.extract(...)` is `async_to_sync(aextract)`.
+
+### AgentCaseExtractor pipeline
+
+The extractor runs an 11-step pipeline: strip-before-first-user → structural pre-filter → heuristic trim → over-size bail → LLM filter (skipped when ≥2 tool rounds) → tool pre-compress → LLM compress → parse → validate → build `AgentCase`. Returns `[]` when the trajectory is filtered out; returns `[AgentCase]` on success.
+
+### AgentSkillExtractor return contract
+
+Pass the new `AgentCase` and the pre-filtered `existing_relevant_skills` (e.g. top-K cosine from the caller's store) plus the associated `supporting_cases` (cases referenced by existing skills). The caller decodes add / update / retire by checking whether `skill.id` is already in `existing_relevant_skills` and whether `skill.confidence < retire_confidence`.
+
+Cases with `quality_score < skip_quality_threshold` (default 0.2) short-circuit to `[]` without calling the LLM.
+
+`AgentSkill.cluster_id` is always `""` on extraction — the caller stamps the cluster identity after persisting.
+
+### Customising prompts
+
+```python
+import everalgo.agent_memory.prompts.case_filter as _cf
+_cf.AGENT_CASE_FILTER_PROMPT = my_custom_filter_prompt   # global override
+```
+
+Or per-call: pass `prompt_filter=` / `prompt_compress=` / `prompt_tool_pre_compress=` to `aextract`.
+
+## Related distributions
+
+- [`everalgo-boundary`](../everalgo-boundary/) — `detect_boundaries` primitive used by `AgentBoundaryDetector`
+- [`everalgo-clustering`](../everalgo-clustering/) — `cluster_by_llm` for skill-cluster assignment
+- [`everalgo-rank`](../everalgo-rank/) — `CaseRanker` / `SkillRanker` for read-time ranking

everalgo_agent_memory-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "everalgo-agent-memory"
+version = "0.1.0"
+description = "EverAlgo agent memory: AgentCase / AgentSkill extractors and AgentBoundaryDetector facade."
+requires-python = ">=3.12"
+license = "MIT"
+readme = "README.md"
+authors = [{ name = "EverMind" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "everalgo-core>=0.1.0,<2.0.0",
+  "everalgo-boundary>=0.1.0,<2.0.0",
+  "everalgo-clustering>=0.1.0,<2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/EverMind-AI/EverAlgo"
+Repository = "https://github.com/EverMind-AI/EverAlgo"
+Issues = "https://github.com/EverMind-AI/EverAlgo/issues"
+Documentation = "https://github.com/EverMind-AI/EverAlgo/tree/main/packages/everalgo-agent-memory"
+Changelog = "https://github.com/EverMind-AI/EverAlgo/blob/main/packages/everalgo-agent-memory/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/everalgo"]

everalgo_agent_memory-0.1.0/src/everalgo/agent_memory/__init__.py

@@ -0,0 +1,16 @@
+"""Agent-side memory extractors — 2 Extractors + boundary facade."""
+
+import logging
+
+from everalgo.agent_memory.boundary import AgentBoundaryDetector
+from everalgo.agent_memory.case import AgentCaseExtractor
+from everalgo.agent_memory.skill import AgentSkillExtractor
+
+__all__ = [
+    "AgentBoundaryDetector",
+    "AgentCaseExtractor",
+    "AgentSkillExtractor",
+]
+
+# Library logging setup (ADR-013): NullHandler on each subpackage logger.
+logging.getLogger(__name__).addHandler(logging.NullHandler())

everalgo_agent_memory-0.1.0/src/everalgo/agent_memory/_text.py

@@ -0,0 +1,52 @@
+"""Token-aware text utilities for agent_memory extractors (head/tail truncation, json_default)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from everalgo._tokenize import _get_tokenizer, count_tokens
+
+__all__ = ["count_tokens", "json_default", "truncate_text"]
+
+
+def truncate_text(
+    text: str,
+    max_tokens: int,
+    *,
+    head_ratio: float = 0.7,
+    suffix: str | None = None,
+) -> str:
+    r"""Truncate ``text`` to ``max_tokens`` tokens, preserving head + tail with a marker.
+
+    When ``suffix`` is ``None``: keep ``head_ratio`` of tokens from the start and the remainder from
+    the end, joined by ``"\\n[... trimmed N tokens ...]\\n"`` (or ``"..."`` when ``head_ratio == 1.0``).
+    When ``suffix`` is set: keep the head only and append ``suffix``.
+    Short / empty inputs are returned unchanged.
+    """
+    if not text:
+        return text
+    tokenizer = _get_tokenizer()
+    tokens = tokenizer.encode(text)
+    if len(tokens) <= max_tokens:
+        return text
+
+    if suffix is not None:
+        head = tokenizer.decode(tokens[:max_tokens])
+        return head.rstrip() + suffix
+
+    head_count = int(max_tokens * head_ratio)
+    tail_count = max_tokens - head_count
+    head_text = tokenizer.decode(tokens[:head_count])
+    if tail_count <= 0:
+        return head_text.rstrip() + "..."
+    tail_text = tokenizer.decode(tokens[-tail_count:])
+    trimmed = len(tokens) - max_tokens
+    return f"{head_text}\n[... trimmed {trimmed} tokens ...]\n{tail_text}"
+
+
+def json_default(obj: Any) -> Any:
+    """``json.dumps(default=...)`` fallback: datetime → ISO string, anything else → ``str``."""
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    return str(obj)

everalgo_agent_memory-0.1.0/src/everalgo/agent_memory/boundary.py

@@ -0,0 +1,129 @@
+"""Agent trajectory boundary detection facade.
+
+Wraps the low-level ``everalgo.boundary.detect_boundaries`` primitive with a filter → detect → remap
+pipeline to handle mixed trajectories (``ChatMessage`` + ``ToolCallRequest`` + ``ToolCallResult``).
+
+Tool items are filtered out before the LLM detection step so the LLM sees a clean conversation
+view; boundary indices from the chat-only result are then remapped back to the original
+``ConversationItem`` index space so that the output ``MemCell.items`` preserves the full
+trajectory (including tool calls).
+
+Uses explicit composition rather than inheritance: filter → detect → remap layers are separate
+functions rather than an extended class hierarchy.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from asgiref.sync import async_to_sync
+
+from everalgo.boundary import DetectionResult, detect_boundaries
+from everalgo.types import ChatMessage, MemCell
+
+if TYPE_CHECKING:
+    from everalgo.llm.protocols import LLMClient
+    from everalgo.types import ConversationItem
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["AgentBoundaryDetector"]
+
+
+class AgentBoundaryDetector:
+    """Boundary detection on an agent trajectory (mixed ``ConversationItem`` list).
+
+    The filter → detect → remap pipeline:
+
+    1. **Filter** — extract only ``ChatMessage`` items and remember their original indices.
+    2. **Detect** — run ``everalgo.boundary.detect_boundaries`` on the chat-only view.
+    3. **Remap** — translate chat-space cell boundaries back to the original ``ConversationItem``
+       index space; ``ToolCallRequest`` / ``ToolCallResult`` items between adjacent chat
+       messages are folded into the cell that contains the preceding chat message.
+
+    Invariant: ``sum(len(c.items) for c in result.cells) + len(result.tail) == len(items)``.
+
+    The LLM client is bound to the instance at construction time.
+    """
+
+    def __init__(self, *, llm: LLMClient) -> None:
+        self._llm = llm
+
+    async def adetect(
+        self,
+        items: list[ConversationItem],
+        *,
+        is_final: bool = False,
+        prompt: str | None = None,
+    ) -> DetectionResult:
+        """Detect boundaries on a mixed agent trajectory.
+
+        Args:
+            items: Ordered ``ConversationItem`` list for one trajectory slice — may contain
+                ``ChatMessage``, ``ToolCallRequest``, and ``ToolCallResult`` in any mix.
+            is_final: When ``True``, the caller guarantees no more items will arrive; trailing tool items
+                after the last cell's final chat message are folded into that cell rather than the tail.
+                When ``False`` (default), trailing tool items go to the tail.
+            prompt: Per-call boundary detection prompt override; ``None`` uses the built-in default.
+
+        Returns:
+            ``cells`` — remapped ``MemCell`` list preserving tool calls inside each cell.
+            ``tail`` — remainder items (not yet committed to a cell) for the non-final case.
+        """
+        chat_items: list[ChatMessage] = []
+        chat_to_orig: list[int] = []
+        for orig_idx, item in enumerate(items):
+            if isinstance(item, ChatMessage):
+                chat_items.append(item)
+                chat_to_orig.append(orig_idx)
+
+        if not chat_items:
+            # No chat messages → no LLM signal; everything goes to tail per should_wait semantics.
+            logger.debug("adetect: no ChatMessage items in trajectory (n_items=%d)", len(items))
+            return DetectionResult(cells=[], tail=list(items))  # type: ignore[arg-type]
+
+        chat_result = await detect_boundaries(chat_items, llm=self._llm, is_final=is_final, prompt=prompt)
+
+        remapped_cells: list[MemCell] = []
+        chat_cursor = 0
+        for cell in chat_result.cells:
+            cell_chat_count = len(cell.items)
+            start_chat_idx = chat_cursor
+            end_chat_idx = chat_cursor + cell_chat_count - 1
+            chat_cursor += cell_chat_count
+
+            start_orig = chat_to_orig[start_chat_idx]
+
+            if chat_cursor < len(chat_to_orig):
+                # More cells follow: include everything up to (exclusive) the next cell's first chat.
+                end_orig_exclusive = chat_to_orig[chat_cursor]
+            elif is_final:
+                # Last cell, caller says stream is done: absorb all remaining items.
+                end_orig_exclusive = len(items)
+            else:
+                # Last cell, stream is ongoing: include only up to (inclusive) the last chat in
+                # this cell; trailing tool items go to the tail so they can be re-processed.
+                end_orig_exclusive = chat_to_orig[end_chat_idx] + 1
+
+            remapped_cells.append(MemCell(items=list(items[start_orig:end_orig_exclusive]), timestamp=cell.timestamp))
+
+        # Tail: items after the last consumed original index.
+        if remapped_cells:
+            if is_final:
+                last_consumed_exclusive = len(items)
+            elif chat_cursor < len(chat_to_orig):
+                last_consumed_exclusive = chat_to_orig[chat_cursor]
+            else:
+                # chat_cursor == len(chat_to_orig): all chats consumed; last cell boundary already
+                # set to chat_to_orig[end_chat_idx] + 1, so tail starts right after.
+                last_consumed_exclusive = chat_to_orig[-1] + 1
+            tail = list(items[last_consumed_exclusive:])
+        else:
+            # detect_boundaries returned no cells — everything is tail.
+            tail = list(items)
+
+        return DetectionResult(cells=remapped_cells, tail=tail)  # type: ignore[arg-type]
+
+    detect = async_to_sync(adetect)
+    """Sync bridge — only callable from non-event-loop contexts."""