Chats

Chats#

List, search, and summarize past conversation logs.

Instructions

### When to use chats

Use chats when the user asks about or wants to reference a past conversation:
- "remember when we discussed X?" → search_chats('X')
- "find our earlier chat about Y" → search_chats('Y')
- "what did we say about Z last week?" → search_chats('Z')
- Listing recent sessions to give the user an overview → list_chats()
- Reading a specific prior conversation by ID → read_chat(id)

Do **not** use chats for:
- The current conversation — its content is already in the context window.
- Searching files or code — use the shell or read tool instead.
- Web or documentation search — use the browser tool.

Examples

Search for a specific topic in past conversations

User 
Can you find any mentions of "python" in our past conversations?
Assistant 
Certainly! I'll search our past conversations for mentions of "python" using the search_chats function.
chats


search_chats('python')
gptme.tools.chats.conversation_stats(since: str | None = None, as_json: bool = False, conversation_id: str | None = None) → None

Show statistics about conversation history.

Parameters:

  • since – Only include conversations since this date (YYYY-MM-DD or Nd).

  • as_json – Output as JSON instead of formatted text.

  • conversation_id – Optional conversation ID to inspect in detail.

gptme.tools.chats.find_empty_conversations(max_messages: int = 1, include_test: bool = False) → list[dict]

Find conversations with few or no messages.

Scans all conversations and returns those with at most max_messages messages. Useful for cleaning up abandoned or empty conversation logs.

Parameters:

  • max_messages – Maximum message count to consider “empty” (default: 1, system-only).

  • include_test – Whether to include test/eval conversations.

Returns:

List of dicts with conversation metadata and disk size.

gptme.tools.chats.list_chats(max_results: int = 5, metadata=False, include_summary: bool = False) → None

List recent chat conversations and optionally summarize them using an LLM.

Parameters:

  • max_results (int) – Maximum number of conversations to display.

  • include_summary (bool) – Whether to include a summary of each conversation. If True, uses an LLM to generate a comprehensive summary. If False, uses a simple strategy showing snippets of the first and last messages.

gptme.tools.chats.read_chat(id: str, max_results: int = 5, incl_system: bool = False, context_messages: int = 0, start_message: int | None = None) → None

Read a specific conversation log.

Parameters:

  • id (str) – The id of the conversation to read.

  • max_results (int) – Maximum number of messages to display.

  • incl_system (bool) – Whether to include system messages.

  • context_messages (int) – Number of messages to show before start_message.

  • start_message (int | None) – Start from this message number (1-indexed), if specified.

gptme.tools.chats.search_chats(query: str, max_results: int = 5, system=False, sort: Literal['date', 'count'] = 'date', context_lines: int = 1, max_matches: int = 1) → None

Search past conversation logs for the given query and print a summary of the results.

Parameters:

  • query (str) – The search query.

  • max_results (int) – Maximum number of conversations to display.

  • system (bool) – Whether to include system messages in the search.

  • context_lines (int) – Number of lines to show around each match.

  • max_matches (int) – Maximum number of matches to show per conversation.

gptme.tools.chats.search_external_chats(query: str, max_results: int = 5, include_cursor: bool = True, include_codex: bool = True, cursor_dir: Path | None = None, codex_dir: Path | None = None) → None

Search external agent sessions (Cursor, Codex) for query.

Prints matching snippets grouped by source agent, with a [Cursor] or [Codex] label so results are clearly distinguished from gptme native results.

Parameters:

  • query – The search query (case-insensitive substring match).

  • max_results – Maximum number of sessions to display.

  • include_cursor – Whether to search Cursor sessions.

  • include_codex – Whether to search Codex sessions.

  • cursor_dir – Override the default Cursor conversations directory.

  • codex_dir – Override the default Codex sessions directory.