autobyteus 1.2.0__py3-none-any.whl → 1.2.3__py3-none-any.whl

autobyteus/llm/utils/messages.py

@@ -1,10 +1,35 @@
-from typing import Dict, Union, List, Optional
+from dataclasses import dataclass
+from typing import Dict, Union, List, Optional, Any
 from enum import Enum
 
 class MessageRole(Enum):
     SYSTEM = "system"
     USER = "user"
     ASSISTANT = "assistant"
+    TOOL = "tool"
+
+@dataclass
+class ToolCallSpec:
+    id: str
+    name: str
+    arguments: Dict[str, Any]
+
+
+@dataclass
+class ToolCallPayload:
+    tool_calls: List[ToolCallSpec]
+
+
+@dataclass
+class ToolResultPayload:
+    tool_call_id: str
+    tool_name: str
+    tool_result: Any
+    tool_error: Optional[str] = None
+
+
+ToolPayload = Union[ToolCallPayload, ToolResultPayload]
+
 
 class Message:
     def __init__(self,
@@ -13,7 +38,8 @@ class Message:
                  reasoning_content: Optional[str] = None,
                  image_urls: Optional[List[str]] = None,
                  audio_urls: Optional[List[str]] = None,
-                 video_urls: Optional[List[str]] = None):
+                 video_urls: Optional[List[str]] = None,
+                 tool_payload: Optional[ToolPayload] = None):
         """
         Initializes a rich Message object for conversation history.
 
@@ -24,6 +50,7 @@ class Message:
             image_urls: Optional list of image URIs.
             audio_urls: Optional list of audio URIs.
             video_urls: Optional list of video URIs.
+            tool_payload: Optional tool payload (tool calls or tool result).
         """
         self.role = role
         self.content = content
@@ -31,8 +58,32 @@ class Message:
         self.image_urls = image_urls or []
         self.audio_urls = audio_urls or []
         self.video_urls = video_urls or []
+        self.tool_payload = tool_payload
+
+    def _serialize_tool_payload(self) -> Optional[Dict[str, Any]]:
+        if self.tool_payload is None:
+            return None
+        if isinstance(self.tool_payload, ToolCallPayload):
+            return {
+                "tool_calls": [
+                    {
+                        "id": call.id,
+                        "name": call.name,
+                        "arguments": call.arguments,
+                    }
+                    for call in self.tool_payload.tool_calls
+                ]
+            }
+        if isinstance(self.tool_payload, ToolResultPayload):
+            return {
+                "tool_call_id": self.tool_payload.tool_call_id,
+                "tool_name": self.tool_payload.tool_name,
+                "tool_result": self.tool_payload.tool_result,
+                "tool_error": self.tool_payload.tool_error,
+            }
+        return None
 
-    def to_dict(self) -> Dict[str, Union[str, List[str], None]]:
+    def to_dict(self) -> Dict[str, Any]:
         """
         Returns a simple dictionary representation of the Message object.
         This is for internal use and does not format for any specific API.
@@ -44,4 +95,5 @@ class Message:
             "image_urls": self.image_urls,
             "audio_urls": self.audio_urls,
             "video_urls": self.video_urls,
+            "tool_payload": self._serialize_tool_payload(),
         }

autobyteus/llm/utils/response_types.py

@@ -1,6 +1,7 @@
 from dataclasses import dataclass, field
 from typing import Optional, List
 from autobyteus.llm.utils.token_usage import TokenUsage
+from autobyteus.llm.utils.tool_call_delta import ToolCallDelta
 
 @dataclass
 class CompleteResponse:
@@ -24,3 +25,5 @@ class ChunkResponse:
     image_urls: List[str] = field(default_factory=list)
     audio_urls: List[str] = field(default_factory=list)
     video_urls: List[str] = field(default_factory=list)
+    tool_calls: Optional[List[ToolCallDelta]] = None  # API-provided tool call deltas
+

autobyteus/llm/utils/tool_call_delta.py

@@ -0,0 +1,31 @@
+# file: autobyteus/autobyteus/llm/utils/tool_call_delta.py
+"""
+Provider-agnostic representation of streaming tool call updates.
+
+This dataclass normalizes tool call deltas from different LLM providers
+(OpenAI, Anthropic, Gemini) into a common format for the streaming architecture.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ToolCallDelta:
+    """
+    A normalized, provider-agnostic representation of a tool call update
+    received during streaming.
+
+    Attributes:
+        index: Position in parallel tool calls (0-based). Used to track
+               multiple concurrent tool calls in the same response.
+        call_id: Unique ID for this tool call. Present only in the first
+                 chunk for this index.
+        name: Tool/function name. Present only in the first chunk for this index.
+        arguments_delta: Partial JSON string of arguments. Accumulated across
+                         multiple chunks to form complete arguments.
+    """
+    index: int
+    call_id: Optional[str] = None
+    name: Optional[str] = None
+    arguments_delta: Optional[str] = None

autobyteus/memory/__init__.py

@@ -0,0 +1,32 @@
+from autobyteus.memory.models.memory_types import MemoryType
+from autobyteus.memory.models.raw_trace_item import RawTraceItem
+from autobyteus.memory.models.episodic_item import EpisodicItem
+from autobyteus.memory.models.semantic_item import SemanticItem
+from autobyteus.memory.models.tool_interaction import ToolInteraction, ToolInteractionStatus
+from autobyteus.memory.store.file_store import FileMemoryStore
+from autobyteus.memory.turn_tracker import TurnTracker
+from autobyteus.memory.memory_manager import MemoryManager
+from autobyteus.memory.policies.compaction_policy import CompactionPolicy
+from autobyteus.memory.compaction.compactor import Compactor
+from autobyteus.memory.compaction.compaction_result import CompactionResult
+from autobyteus.memory.compaction.summarizer import Summarizer
+from autobyteus.memory.retrieval.memory_bundle import MemoryBundle
+from autobyteus.memory.retrieval.retriever import Retriever
+
+__all__ = [
+    "MemoryType",
+    "RawTraceItem",
+    "EpisodicItem",
+    "SemanticItem",
+    "ToolInteraction",
+    "ToolInteractionStatus",
+    "FileMemoryStore",
+    "TurnTracker",
+    "MemoryManager",
+    "CompactionPolicy",
+    "Compactor",
+    "CompactionResult",
+    "Summarizer",
+    "MemoryBundle",
+    "Retriever",
+]

autobyteus/memory/active_transcript.py

@@ -0,0 +1,69 @@
+import time
+from typing import List, Optional, Iterable, Any
+
+from autobyteus.llm.utils.messages import (
+    Message,
+    MessageRole,
+    ToolCallPayload,
+    ToolCallSpec,
+    ToolResultPayload,
+)
+
+
+class ActiveTranscript:
+    def __init__(self, initial_messages: Optional[Iterable[Message]] = None):
+        self._messages: List[Message] = list(initial_messages) if initial_messages else []
+        self.epoch_id: int = 1
+        self.last_compaction_ts: Optional[float] = None
+
+    def append_message(self, message: Message) -> None:
+        self._messages.append(message)
+
+    def append_user(self, content: str) -> None:
+        self._messages.append(Message(role=MessageRole.USER, content=content))
+
+    def append_assistant(self, content: Optional[str], reasoning: Optional[str] = None) -> None:
+        self._messages.append(
+            Message(
+                role=MessageRole.ASSISTANT,
+                content=content,
+                reasoning_content=reasoning,
+            )
+        )
+
+    def append_tool_calls(self, tool_calls: List[ToolCallSpec]) -> None:
+        self._messages.append(
+            Message(
+                role=MessageRole.ASSISTANT,
+                content=None,
+                tool_payload=ToolCallPayload(tool_calls=tool_calls),
+            )
+        )
+
+    def append_tool_result(
+        self,
+        tool_call_id: str,
+        tool_name: str,
+        tool_result: Any,
+        tool_error: Optional[str] = None,
+    ) -> None:
+        self._messages.append(
+            Message(
+                role=MessageRole.TOOL,
+                content=None,
+                tool_payload=ToolResultPayload(
+                    tool_call_id=tool_call_id,
+                    tool_name=tool_name,
+                    tool_result=tool_result,
+                    tool_error=tool_error,
+                ),
+            )
+        )
+
+    def build_messages(self) -> List[Message]:
+        return list(self._messages)
+
+    def reset(self, snapshot_messages: Iterable[Message], last_compaction_ts: Optional[float] = None) -> None:
+        self._messages = list(snapshot_messages)
+        self.epoch_id += 1
+        self.last_compaction_ts = last_compaction_ts if last_compaction_ts is not None else time.time()

autobyteus/memory/compaction/__init__.py

@@ -0,0 +1,9 @@
+from autobyteus.memory.compaction.compactor import Compactor
+from autobyteus.memory.compaction.compaction_result import CompactionResult
+from autobyteus.memory.compaction.summarizer import Summarizer
+
+__all__ = [
+    "Compactor",
+    "CompactionResult",
+    "Summarizer",
+]

autobyteus/memory/compaction/compaction_result.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+
+@dataclass
+class CompactionResult:
+    episodic_summary: str
+    semantic_facts: List[Dict[str, Any]] = field(default_factory=list)

autobyteus/memory/compaction/compactor.py

@@ -0,0 +1,89 @@
+import time
+from typing import List, Optional
+
+from autobyteus.memory.models.memory_types import MemoryType
+from autobyteus.memory.models.raw_trace_item import RawTraceItem
+from autobyteus.memory.models.episodic_item import EpisodicItem
+from autobyteus.memory.models.semantic_item import SemanticItem
+from autobyteus.memory.compaction.compaction_result import CompactionResult
+from autobyteus.memory.compaction.summarizer import Summarizer
+from autobyteus.memory.policies.compaction_policy import CompactionPolicy
+from autobyteus.memory.store.base_store import MemoryStore
+
+
+class Compactor:
+    def __init__(self, store: MemoryStore, policy: CompactionPolicy, summarizer: Summarizer):
+        self.store = store
+        self.policy = policy
+        self.summarizer = summarizer
+        self.memory_types = MemoryType
+
+    def select_compaction_window(self) -> List[str]:
+        raw_items = self.store.list(MemoryType.RAW_TRACE)
+        turn_ids: List[str] = []
+        seen = set()
+        for item in raw_items:
+            if not isinstance(item, RawTraceItem):
+                continue
+            if item.turn_id not in seen:
+                seen.add(item.turn_id)
+                turn_ids.append(item.turn_id)
+
+        if self.policy.raw_tail_turns <= 0:
+            return turn_ids
+        if len(turn_ids) <= self.policy.raw_tail_turns:
+            return []
+        return turn_ids[:-self.policy.raw_tail_turns]
+
+    def get_traces_for_turns(self, turn_ids: List[str]) -> List[RawTraceItem]:
+        raw_items = self.store.list(MemoryType.RAW_TRACE)
+        turn_set = set(turn_ids)
+        return [
+            item
+            for item in raw_items
+            if isinstance(item, RawTraceItem) and item.turn_id in turn_set
+        ]
+
+    def compact(self, turn_ids: List[str]) -> Optional[CompactionResult]:
+        if not turn_ids:
+            return None
+
+        traces = self.get_traces_for_turns(turn_ids)
+        result = self.summarizer.summarize(traces)
+
+        episodic_item = EpisodicItem(
+            id=f"ep_{int(time.time() * 1000)}",
+            ts=time.time(),
+            turn_ids=turn_ids,
+            summary=result.episodic_summary,
+            tags=[],
+            salience=0.0,
+        )
+
+        semantic_items = []
+        for idx, fact_data in enumerate(result.semantic_facts, start=1):
+            semantic_items.append(
+                SemanticItem(
+                    id=f"sem_{int(time.time() * 1000)}_{idx}",
+                    ts=time.time(),
+                    fact=fact_data.get("fact", ""),
+                    tags=fact_data.get("tags", []),
+                    confidence=fact_data.get("confidence", 0.0),
+                    salience=0.0,
+                )
+            )
+
+        self.store.add([episodic_item, *semantic_items])
+        self._prune_raw_traces(turn_ids)
+        return result
+
+    def _prune_raw_traces(self, compacted_turn_ids: List[str]) -> None:
+        raw_items = self.store.list(MemoryType.RAW_TRACE)
+        remaining_turns = {
+            item.turn_id
+            for item in raw_items
+            if isinstance(item, RawTraceItem) and item.turn_id not in compacted_turn_ids
+        }
+        prune = getattr(self.store, "prune_raw_traces", None)
+        if callable(prune):
+            prune(keep_turn_ids=remaining_turns, archive=True)

autobyteus/memory/compaction/summarizer.py

@@ -0,0 +1,11 @@
+from abc import ABC, abstractmethod
+from typing import List
+
+from autobyteus.memory.models.raw_trace_item import RawTraceItem
+from autobyteus.memory.compaction.compaction_result import CompactionResult
+
+
+class Summarizer(ABC):
+    @abstractmethod
+    def summarize(self, traces: List[RawTraceItem]) -> CompactionResult:
+        raise NotImplementedError

autobyteus/memory/compaction_snapshot_builder.py

@@ -0,0 +1,84 @@
+from typing import List, Dict
+
+from autobyteus.llm.utils.messages import Message, MessageRole
+from autobyteus.memory.models.raw_trace_item import RawTraceItem
+from autobyteus.memory.retrieval.memory_bundle import MemoryBundle
+from autobyteus.memory.tool_interaction_builder import build_tool_interactions
+from autobyteus.memory.models.tool_interaction import ToolInteractionStatus
+
+
+class CompactionSnapshotBuilder:
+    def build(self, system_prompt: str, bundle: MemoryBundle, raw_tail: List[RawTraceItem]) -> List[Message]:
+        parts: List[str] = []
+
+        if bundle.episodic:
+            parts.append("[MEMORY:EPISODIC]")
+            for idx, item in enumerate(bundle.episodic, start=1):
+                parts.append(f"{idx}) {item.summary}")
+            parts.append("")
+
+        if bundle.semantic:
+            parts.append("[MEMORY:SEMANTIC]")
+            for item in bundle.semantic:
+                parts.append(f"- {item.fact}")
+            parts.append("")
+
+        if raw_tail:
+            parts.append("[RECENT TURNS]")
+            parts.extend(self._format_recent_turns(raw_tail))
+            parts.append("")
+
+        summary_text = "\n".join(parts).strip()
+
+        messages = [Message(role=MessageRole.SYSTEM, content=system_prompt)]
+        if summary_text:
+            messages.append(Message(role=MessageRole.USER, content=summary_text))
+        return messages
+
+    def _format_recent_turns(self, raw_tail: List[RawTraceItem]) -> List[str]:
+        lines: List[str] = []
+        interactions = build_tool_interactions(raw_tail)
+        interaction_ids = {interaction.tool_call_id for interaction in interactions}
+
+        first_trace_by_call_id: Dict[str, RawTraceItem] = {}
+        for item in raw_tail:
+            if item.tool_call_id and item.tool_call_id not in first_trace_by_call_id:
+                first_trace_by_call_id[item.tool_call_id] = item
+
+        def sort_key(interaction):
+            trace = first_trace_by_call_id.get(interaction.tool_call_id)
+            return trace.seq if trace else 0
+
+        for interaction in sorted(interactions, key=sort_key):
+            trace = first_trace_by_call_id.get(interaction.tool_call_id)
+            if trace:
+                prefix = f"({trace.turn_id}:{trace.seq}) TOOL:"
+            else:
+                prefix = "(unknown) TOOL:"
+
+            if interaction.status == ToolInteractionStatus.PENDING:
+                result_text = "pending"
+            elif interaction.status == ToolInteractionStatus.ERROR:
+                result_text = interaction.error or "error"
+            else:
+                result_text = interaction.result
+
+            lines.append(
+                f"{prefix} {interaction.tool_name} {interaction.arguments} -> {result_text}"
+            )
+
+        for item in raw_tail:
+            if item.trace_type in {"tool_call", "tool_result"} and item.tool_call_id in interaction_ids:
+                continue
+            lines.append(self._format_raw_trace(item))
+
+        return lines
+
+    def _format_raw_trace(self, item: RawTraceItem) -> str:
+        prefix = f"({item.turn_id}:{item.seq}) {item.trace_type.upper()}:"
+        if item.trace_type == "tool_call":
+            return f"{prefix} {item.tool_name} {item.tool_args}"
+        if item.trace_type == "tool_result":
+            result = item.tool_error if item.tool_error else item.tool_result
+            return f"{prefix} {item.tool_name} {result}"
+        return f"{prefix} {item.content}"

autobyteus/memory/memory_manager.py

@@ -0,0 +1,183 @@
+import time
+from typing import Optional, List
+
+from autobyteus.agent.events.agent_events import ToolResultEvent
+from autobyteus.agent.tool_invocation import ToolInvocation
+from autobyteus.llm.user_message import LLMUserMessage
+from autobyteus.llm.utils.messages import ToolCallSpec
+from autobyteus.llm.utils.response_types import CompleteResponse
+from autobyteus.memory.models.raw_trace_item import RawTraceItem
+from autobyteus.memory.models.memory_types import MemoryType
+from autobyteus.memory.policies.compaction_policy import CompactionPolicy
+from autobyteus.memory.compaction.compactor import Compactor
+from autobyteus.memory.retrieval.retriever import Retriever
+from autobyteus.memory.store.base_store import MemoryStore
+from autobyteus.memory.turn_tracker import TurnTracker
+from autobyteus.memory.active_transcript import ActiveTranscript
+from autobyteus.memory.tool_interaction_builder import build_tool_interactions
+
+
+class MemoryManager:
+    def __init__(
+        self,
+        store: MemoryStore,
+        turn_tracker: Optional[TurnTracker] = None,
+        compaction_policy: Optional[CompactionPolicy] = None,
+        compactor: Optional[Compactor] = None,
+        retriever: Optional[Retriever] = None,
+        active_transcript: Optional[ActiveTranscript] = None,
+    ):
+        self.store = store
+        self.turn_tracker = turn_tracker or TurnTracker()
+        self.compaction_policy = compaction_policy or CompactionPolicy()
+        self.compactor = compactor
+        self.retriever = retriever or Retriever(store=store)
+        self.memory_types = MemoryType
+        self._seq_by_turn: dict[str, int] = {}
+        self.active_transcript = active_transcript or ActiveTranscript()
+        self.compaction_required: bool = False
+
+    def start_turn(self) -> str:
+        return self.turn_tracker.next_turn_id()
+
+    def request_compaction(self) -> None:
+        self.compaction_required = True
+
+    def clear_compaction_request(self) -> None:
+        self.compaction_required = False
+
+    def _next_seq(self, turn_id: str) -> int:
+        current = self._seq_by_turn.get(turn_id, 0) + 1
+        self._seq_by_turn[turn_id] = current
+        return current
+
+    def ingest_user_message(self, llm_user_message: LLMUserMessage, turn_id: str, source_event: str) -> None:
+        trace = RawTraceItem(
+            id=f"rt_{int(time.time() * 1000)}",
+            ts=time.time(),
+            turn_id=turn_id,
+            seq=self._next_seq(turn_id),
+            trace_type="user",
+            content=llm_user_message.content,
+            source_event=source_event,
+            media={
+                "images": llm_user_message.image_urls or [],
+                "audio": llm_user_message.audio_urls or [],
+                "video": llm_user_message.video_urls or [],
+            },
+            tags=["processed"],
+        )
+        self.store.add([trace])
+
+    def ingest_tool_intent(self, tool_invocation: ToolInvocation, turn_id: Optional[str] = None) -> None:
+        effective_turn_id = tool_invocation.turn_id or turn_id
+        if not effective_turn_id:
+            raise ValueError("turn_id is required to ingest tool intent")
+        trace = RawTraceItem(
+            id=f"rt_{int(time.time() * 1000)}",
+            ts=time.time(),
+            turn_id=effective_turn_id,
+            seq=self._next_seq(effective_turn_id),
+            trace_type="tool_call",
+            content="",
+            source_event="PendingToolInvocationEvent",
+            tool_name=tool_invocation.name,
+            tool_call_id=tool_invocation.id,
+            tool_args=tool_invocation.arguments,
+        )
+        self.store.add([trace])
+        self.active_transcript.append_tool_calls(
+            [ToolCallSpec(id=tool_invocation.id, name=tool_invocation.name, arguments=tool_invocation.arguments)]
+        )
+
+    def ingest_tool_result(self, event: ToolResultEvent, turn_id: Optional[str] = None) -> None:
+        effective_turn_id = event.turn_id or turn_id
+        if not effective_turn_id:
+            raise ValueError("turn_id is required to ingest tool result")
+        trace = RawTraceItem(
+            id=f"rt_{int(time.time() * 1000)}",
+            ts=time.time(),
+            turn_id=effective_turn_id,
+            seq=self._next_seq(effective_turn_id),
+            trace_type="tool_result",
+            content="",
+            source_event="ToolResultEvent",
+            tool_name=event.tool_name,
+            tool_call_id=event.tool_invocation_id,
+            tool_args=event.tool_args,
+            tool_result=event.result,
+            tool_error=event.error,
+        )
+        self.store.add([trace])
+        self.active_transcript.append_tool_result(
+            tool_call_id=event.tool_invocation_id or "",
+            tool_name=event.tool_name,
+            tool_result=event.result,
+            tool_error=event.error,
+        )
+
+    def ingest_assistant_response(self, response: CompleteResponse, turn_id: str, source_event: str) -> None:
+        trace = RawTraceItem(
+            id=f"rt_{int(time.time() * 1000)}",
+            ts=time.time(),
+            turn_id=turn_id,
+            seq=self._next_seq(turn_id),
+            trace_type="assistant",
+            content=response.content or "",
+            source_event=source_event,
+            tags=["final"],
+        )
+        self.store.add([trace])
+        if response.content or response.reasoning:
+            self.active_transcript.append_assistant(
+                content=response.content,
+                reasoning=response.reasoning,
+            )
+
+    def _get_raw_tail(self, tail_turns: int, exclude_turn_id: Optional[str] = None) -> List[RawTraceItem]:
+        raw_items = self.store.list(MemoryType.RAW_TRACE)
+        if tail_turns <= 0:
+            return []
+
+        ordered_turns = []
+        seen = set()
+        for item in raw_items:
+            if not isinstance(item, RawTraceItem):
+                continue
+            if exclude_turn_id and item.turn_id == exclude_turn_id:
+                continue
+            if item.turn_id not in seen:
+                seen.add(item.turn_id)
+                ordered_turns.append(item.turn_id)
+
+        if not ordered_turns:
+            return []
+
+        keep_turns = set(ordered_turns[-tail_turns:])
+        tail_items = [
+            item
+            for item in raw_items
+            if isinstance(item, RawTraceItem) and item.turn_id in keep_turns
+        ]
+
+        order_index = {turn_id: idx for idx, turn_id in enumerate(ordered_turns)}
+        tail_items.sort(key=lambda item: (order_index.get(item.turn_id, 0), item.seq))
+        return tail_items
+
+    def get_raw_tail(self, tail_turns: int, exclude_turn_id: Optional[str] = None) -> List[RawTraceItem]:
+        return self._get_raw_tail(tail_turns, exclude_turn_id=exclude_turn_id)
+
+    def get_transcript_messages(self):
+        return self.active_transcript.build_messages()
+
+    def reset_transcript(self, snapshot_messages):
+        self.active_transcript.reset(snapshot_messages)
+
+    def get_tool_interactions(self, turn_id: Optional[str] = None):
+        raw_items = self.store.list(MemoryType.RAW_TRACE)
+        if turn_id:
+            raw_items = [
+                item for item in raw_items
+                if isinstance(item, RawTraceItem) and item.turn_id == turn_id
+            ]
+        return build_tool_interactions([item for item in raw_items if isinstance(item, RawTraceItem)])

autobyteus/memory/models/__init__.py

@@ -0,0 +1,14 @@
+from autobyteus.memory.models.memory_types import MemoryType
+from autobyteus.memory.models.raw_trace_item import RawTraceItem
+from autobyteus.memory.models.episodic_item import EpisodicItem
+from autobyteus.memory.models.semantic_item import SemanticItem
+from autobyteus.memory.models.tool_interaction import ToolInteraction, ToolInteractionStatus
+
+__all__ = [
+    "MemoryType",
+    "RawTraceItem",
+    "EpisodicItem",
+    "SemanticItem",
+    "ToolInteraction",
+    "ToolInteractionStatus",
+]

autobyteus/memory/models/episodic_item.py

@@ -0,0 +1,41 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+from .memory_types import MemoryType
+
+
+@dataclass
+class EpisodicItem:
+    id: str
+    ts: float
+    turn_ids: List[str]
+    summary: str
+    tags: List[str] = field(default_factory=list)
+    salience: float = 0.0
+
+    @property
+    def memory_type(self) -> MemoryType:
+        return MemoryType.EPISODIC
+
+    def to_dict(self) -> Dict[str, Any]:
+        data: Dict[str, Any] = {
+            "id": self.id,
+            "ts": self.ts,
+            "turn_ids": self.turn_ids,
+            "summary": self.summary,
+            "salience": self.salience,
+        }
+        if self.tags:
+            data["tags"] = self.tags
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "EpisodicItem":
+        return cls(
+            id=data["id"],
+            ts=data["ts"],
+            turn_ids=data.get("turn_ids", []),
+            summary=data.get("summary", ""),
+            tags=data.get("tags", []),
+            salience=data.get("salience", 0.0),
+        )