Agent skill
searching-messages
Search past messages to recall context. Use when you need to remember previous discussions, find specific topics mentioned before, pull up context from earlier in the conversation history, or find which agent discussed a topic.
Install this agent skill to your Project
npx add-skill https://github.com/letta-ai/letta-code/tree/main/src/skills/builtin/searching-messages
SKILL.md
Searching Messages
This skill helps you search through past conversations to recall context that may have fallen out of your context window.
When to Use This Skill
- User asks "do you remember when we discussed X?"
- You need context from an earlier conversation
- User references something from the past that you don't have in context
- You want to verify what was said before about a topic
- You need to find which agent discussed a specific topic (use with
finding-agentsskill)
CLI Usage
letta messages search --query <text> [options]
Options
| Option | Description |
|---|---|
--query <text> |
Search query (required) |
--mode <mode> |
Search mode: vector, fts, hybrid (default: hybrid) |
--start-date <date> |
Filter messages after this date (ISO format) |
--end-date <date> |
Filter messages before this date (ISO format) |
--limit <n> |
Max results (default: 10) |
--all-agents |
Search all agents, not just current agent |
--agent <id> |
Explicit agent ID (overrides LETTA_AGENT_ID) |
--agent-id <id> |
Alias for --agent |
Search Modes
- hybrid (default): Combines vector similarity + full-text search with RRF scoring
- vector: Semantic similarity search (good for conceptual matches)
- fts: Full-text search (good for exact phrases)
Companion Command: messages list
Use this to expand around a found needle by message ID cursor:
letta messages list [options]
| Option | Description |
|---|---|
--after <message-id> |
Get messages after this ID (cursor) |
--before <message-id> |
Get messages before this ID (cursor) |
--order <asc|desc> |
Sort order (default: desc = newest first) |
--limit <n> |
Max results (default: 20) |
--agent <id> |
Explicit agent ID (overrides LETTA_AGENT_ID) |
--agent-id <id> |
Alias for --agent |
Search Strategies
Strategy 1: Needle + Expand (Recommended)
Use when you need full conversation context around a specific topic:
-
Find the needle - Search with keywords to discover relevant messages:
bashletta messages search --query "flicker inline approval" --limit 5 -
Note the message_id - Find the most relevant result and copy its
message_id -
Expand before - Get messages leading up to the needle:
bashletta messages list --before "message-xyz" --limit 10 -
Expand after - Get messages following the needle (use
--order ascfor chronological):bashletta messages list --after "message-xyz" --order asc --limit 10
Strategy 2: Date-Bounded Search
Use when you know approximately when something was discussed:
letta messages search --query "topic" --start-date "2025-12-31T00:00:00Z" --end-date "2025-12-31T23:59:59Z" --limit 15
Results are sorted by relevance within the date window.
Strategy 3: Broad Discovery
Use when you're not sure what you're looking for:
letta messages search --query "vague topic" --mode vector --limit 10
Vector mode finds semantically similar messages even without exact keyword matches.
Strategy 4: Find Which Agent Discussed Something
Use with --all-agents to search across all agents and identify which one discussed a topic:
letta messages search --query "authentication refactor" --all-agents --limit 10
Results include agent_id for each message. Use this to:
- Find the agent that worked on a specific feature
- Identify the right agent to ask follow-up questions
- Cross-reference with the
finding-agentsskill to get agent details
Tip: Load both searching-messages and finding-agents skills together when you need to find and identify agents by topic.
Search Output
Returns search results with:
message_id- Use this for cursor-based expansionmessage_type-user_message,assistant_message,reasoning_messagecontentorreasoning- The actual message textcreated_at- When the message was sent (ISO format)agent_id- Which agent the message belongs to
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
letta-ai/letta-code
adding-models
Guide for adding new LLM models to Letta Code. Use when the user wants to add support for a new model, needs to know valid model handles, or wants to update the model configuration. Covers models.json configuration, CI test matrix, and handle validation.
letta-ai/letta-code
converting-mcps-to-skills
Connect to MCP (Model Context Protocol) servers and create skills for repeated use. Load when a user wants to use an MCP server, connect to external tools via MCP, or when they mention MCP, model context protocol, or specific MCP servers.
letta-ai/letta-code
working-in-parallel
Guide for working in parallel with other agents. Use when another agent is already working in the same directory, or when you need to work on multiple features simultaneously. Covers git worktrees as the recommended approach.
letta-ai/letta-code
Migrating from Codex and Claude Code
Find and search historical conversation data from Claude Code and OpenAI Codex CLIs. Use when you need to understand a user's coding patterns, learn about a project from past sessions, or bootstrap agent memory from historical context.
letta-ai/letta-code
migrating-memory
Migrate memory blocks from an existing agent to the current agent. Use when the user wants to copy or share memory from another agent, or during /init when setting up a new agent that should inherit memory from an existing one.
letta-ai/letta-code
creating-skills
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Letta Code's capabilities with specialized knowledge, workflows, or tool integrations.
Didn't find tool you were looking for?