​
ContextUtility

class ContextUtility:
Utility class for context management and file operations. This utility provides generic functionality for managing context files, markdown generation, and session management that can be used by context-related features. Key features:
  • Session-based directory management
  • Generic markdown file operations
  • Text-based search through files
  • File metadata handling
  • Agent memory record retrieval

​
init

def __init__(self, working_directory: Optional[str] = None):
Initialize the ContextUtility. Parameters:
  • working_directory (str, optional): The directory path where files will be stored. If not provided, a default directory will be used.

​
_setup_storage

def _setup_storage(self, working_directory: Optional[str]):
Initialize session-specific storage paths and create directory structure for context file management.

​
_generate_session_id

def _generate_session_id(self):
Create timestamp-based unique identifier for isolating current session files from other sessions.

​
_create_or_update_note

def _create_or_update_note(self, note_name: str, content: str):
Write content to markdown file, creating new file or overwriting existing one with UTF-8 encoding. Parameters:
  • note_name (str): Name of the note (without .md extension).
  • content (str): Content to write to the note.
Returns: str: Success message.

​
save_markdown_file

def save_markdown_file(
    self,
    filename: str,
    content: str,
    title: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None
):
Generic method to save any markdown content to a file. Parameters:
  • filename (str): Name without .md extension.
  • content (str): Main content to save.
  • title (str, optional): Title for the markdown file.
  • metadata (Dict, optional): Additional metadata to include.
Returns: str: Success message or error message.

​
load_markdown_file

def load_markdown_file(self, filename: str):
Generic method to load any markdown file. Parameters:
  • filename (str): Name without .md extension.
Returns: str: File content or empty string if not found.

​
file_exists

def file_exists(self, filename: str):
Verify presence of markdown file in current session directory. Parameters:
  • filename (str): Name without .md extension.
Returns: bool: True if file exists, False otherwise.

​
list_markdown_files

def list_markdown_files(self):
Returns: List[str]: List of filenames without .md extension.

​
get_agent_memory_records

def get_agent_memory_records(self, agent: 'ChatAgent'):
Retrieve conversation history from agent’s memory system. Parameters:
  • agent (ChatAgent): The agent to extract memory records from.
Returns: List[MemoryRecord]: List of memory records from the agent.

​
format_memory_as_conversation

def format_memory_as_conversation(self, memory_records: List['MemoryRecord']):
Transform structured memory records into human-readable conversation format with role labels and message content. Parameters:
  • memory_records (List[MemoryRecord]): Memory records to format.
Returns: str: Formatted conversation text.

​
create_session_directory

def create_session_directory(
    self,
    base_dir: Optional[str] = None,
    session_id: Optional[str] = None
):
Create a session-specific directory. Parameters:
  • base_dir (str, optional): Base directory. If None, uses current working directory.
  • session_id (str, optional): Custom session ID. If None, generates new one.
Returns: Path: The created session directory path.

​
get_session_metadata

def get_session_metadata(self):
Returns: Dict[str, Any]: Session metadata including ID, timestamp, directory.

​
list_sessions

def list_sessions(self, base_dir: Optional[str] = None):
Discover all available session directories for browsing historical conversations and context files. Parameters:
  • base_dir (str, optional): Base directory to search. If None, uses parent of working directory.
Returns: List[str]: List of session directory names.

​
search_in_file

def search_in_file(
    self,
    file_path: Path,
    keywords: List[str],
    top_k: int = 4
):
Perform keyword-based search through file sections, ranking results by keyword frequency and returning top matches. Parameters:
  • file_path (Path): Path to the file to search.
  • keywords (List[str]): Keywords to search for.
  • top_k (int): Maximum number of results to return.
Returns: str: Formatted search results.

​
get_working_directory

def get_working_directory(self):
Returns: Path: The working directory path.

​
get_session_id

def get_session_id(self):
Returns: str: The session ID.

​
load_markdown_context_to_memory

def load_markdown_context_to_memory(self, agent: 'ChatAgent', filename: str):
Load context from a markdown file and append it to agent memory. Preserves existing conversation history without wiping it. Parameters:
  • agent (ChatAgent): The agent to append context to.
  • filename (str): Name of the markdown file (without .md extension).
Returns: str: Status message indicating success or failure with details.