Overview

package wittgenstein_episodic_memory

Wittgenstein Episodic Memory Library.

Provides models and services to manage temporal episodes and track entity journeys.

Classes

• Episode — A single episodic log representing a temporal event in a lead/entity's journey.

• MemoryQuery — Query parameters to filter and retrieve episodic memories.

• EpisodeRepository — Storage backend for episodes — implement this to plug in real persistence.

• InMemoryEpisodeRepository — Default repository — a plain in-process list, no persistence across restarts.

• EpisodicMemoryService — Service to record, query and consolidate temporal journey episodes.

• TemporalTimelineTracker — Helper to detect temporal patterns like inactivity or high frequency interactions.

wittgenstein_episodic_memory.Episode

mkapi_definition_mkapi class Episode()

Bases : BaseModel

A single episodic log representing a temporal event in a lead/entity's journey.

Core fields (id/entity_id/event_type/content/timestamp/metadata) cover the original CRM/lead-activity-timeline use case. The optional fields below extend this to also cover agent-execution episodes (wittgenstein-core's own consumption, ADR-092) — full raw I/O, an LLM summary, and lifecycle metadata that a generic timeline entry doesn't need. Consumers that only need the lightweight timeline shape can ignore them entirely; they default to None/0.5/False.

wittgenstein_episodic_memory.MemoryQuery

mkapi_definition_mkapi class MemoryQuery()

Bases : BaseModel

Query parameters to filter and retrieve episodic memories.

wittgenstein_episodic_memory.EpisodeRepository

mkapi_definition_mkapi class EpisodeRepository()

Bases : Protocol

Storage backend for episodes — implement this to plug in real persistence.

Methods

• add — Persist an episode, returning the stored representation (id populated).

• query — Return episodes matching the query, newest first, capped at query.limit.

wittgenstein_episodic_memory.EpisodeRepository.add

mkapi_definition_mkapi method EpisodeRepository.add(episode: Episode) → Episode

Persist an episode, returning the stored representation (id populated).

wittgenstein_episodic_memory.EpisodeRepository.query

mkapi_definition_mkapi method EpisodeRepository.query(query: MemoryQuery) → List[Episode]

Return episodes matching the query, newest first, capped at query.limit.

wittgenstein_episodic_memory.InMemoryEpisodeRepository

mkapi_definition_mkapi class InMemoryEpisodeRepository()

Default repository — a plain in-process list, no persistence across restarts.

This is the pre-ADR-092 behavior of EpisodicMemoryService, extracted so it can be the default, with real persistence as an opt-in injection instead of the only option.

Methods

• add

• query

wittgenstein_episodic_memory.InMemoryEpisodeRepository.add

mkapi_definition_mkapi method InMemoryEpisodeRepository.add(episode: Episode) → Episode

wittgenstein_episodic_memory.InMemoryEpisodeRepository.query

mkapi_definition_mkapi method InMemoryEpisodeRepository.query(query: MemoryQuery) → List[Episode]

wittgenstein_episodic_memory.EpisodicMemoryService

mkapi_definition_mkapi class EpisodicMemoryService(repository: Optional[EpisodeRepository] = None)

Service to record, query and consolidate temporal journey episodes.

Persistence is pluggable (ADR-092): pass a repository implementing the EpisodeRepository protocol (e.g. a database-backed one) to persist episodes for real. Without one, episodes live only in an in-process list for the lifetime of this instance — the original, pre-ADR-092 behavior.

Methods

• record_episode — Store an episode.

• query_memories — Query stored episodes based on criteria.

• consolidate_episodes — Consolidate multiple episodes for an entity into a unified summary story.

wittgenstein_episodic_memory.EpisodicMemoryService.record_episode

mkapi_definition_mkapi method EpisodicMemoryService.record_episode(episode: Episode) → Episode

Store an episode.

wittgenstein_episodic_memory.EpisodicMemoryService.query_memories

mkapi_definition_mkapi method EpisodicMemoryService.query_memories(query: MemoryQuery) → List[Episode]

Query stored episodes based on criteria.

wittgenstein_episodic_memory.EpisodicMemoryService.consolidate_episodes

mkapi_definition_mkapi method EpisodicMemoryService.consolidate_episodes(entity_id: str) → str

Consolidate multiple episodes for an entity into a unified summary story.

wittgenstein_episodic_memory.TemporalTimelineTracker

mkapi_definition_mkapi class TemporalTimelineTracker()

Helper to detect temporal patterns like inactivity or high frequency interactions.

Methods

• get_inactive_duration_days — Get the number of days since the last activity.

• detect_high_frequency_bursts — Returns True if there is a burst of interactions within a given window.

wittgenstein_episodic_memory.TemporalTimelineTracker.get_inactive_duration_days

mkapi_definition_mkapi staticmethod TemporalTimelineTracker.get_inactive_duration_days(episodes: List[Episode]) → int

Get the number of days since the last activity.

wittgenstein_episodic_memory.TemporalTimelineTracker.detect_high_frequency_bursts

mkapi_definition_mkapi staticmethod TemporalTimelineTracker.detect_high_frequency_bursts(episodes: List[Episode], window_hours: int = 24, count_threshold: int = 5) → bool

Returns True if there is a burst of interactions within a given window.