memex-search

name	memex-search
description	Search, filter, and retrieve Pi Coding Agent history via memex CLI. Use for context resumption, finding past code/decisions, and self-correction based on history.

Memex for Pi

memex is the primary memory retrieval tool. Use it to access historical sessions and indexed code interactions.

Usage Patterns

• Context Retrieval: "What did we discuss in the last session regarding the API?"
  • memex search "API discussion" --source pi --sort ts --limit 10
• Code Discovery: "Find the specific function implementation from last week."
  • memex search "function implementation" --source pi --hybrid
• Session Identification: "Which session covered the database migration?"
  • memex search "database migration" --source pi --unique-session

Search Modes

Need	Flag	Example
Exact terms, IDs, errors	(default)	memex search "Error: 500" --source pi
Concepts, intent	--semantic	memex search "auth flow" --source pi --semantic
Mixed specific + fuzzy	--hybrid	memex search "user_id logic" --source pi --hybrid

If the vector index is unavailable, memex warns on stderr and falls back to lexical search. Treat this as degraded retrieval and mention memex embed as the recovery step when useful.

Background Index Service

• Use memex index-service enable to install the background indexer. It runs via launchd on macOS and systemd user services on Linux.
• Use memex index-service enable --continuous for a long-lived watcher; add --poll-interval <seconds> to tune continuous mode.
• Default mode is periodic indexing, typically every 3600 seconds; add --interval <seconds> to tune interval mode.
• The service inherits indexing flags, so pass source and embedding options at install time when needed, e.g. memex index-service enable --pi --embeddings.
• On successful enable, memex writes auto_index_on_search = false to config when that setting is absent, so searches do not duplicate daemon work. Explicit user config is preserved.
• macOS writes ~/.memex/index-service.plist, ~/.memex/index-service.log, and ~/.memex/index-service.err.log. Linux writes systemd user units under ~/.config/systemd/user/.
• Use memex index-service disable to unload and remove the service.

Session Context

Use --session {session_id} to isolate a specific interaction thread.

1. Find Session ID:
   • memex search "topic" --source pi --unique-session
2. Narrow Search:
   • memex search "detail" --session <session_id>
3. Fetch Transcript:
   • memex session <session_id>

Output Parsing

Output is JSONL (JSON Lines). Each line is a valid JSON object.

Schema:

• doc_id: Unique record ID.
• session_id: Conversation thread ID.
• ts: ISO 8601 timestamp.
• source: Agent source name.
• source_path: Transcript path.
• role: user, assistant, tool_use, or tool_result.
• text: Content payload.
• score: Search relevance (float).
• event_id, parent_event_id, logical_parent_event_id, conversation_kind: Branch/tree metadata when available.

Interpretation:

• Filtering: Discard results below a relevance threshold unless the query is specific.
• Ordering: Sort by ts for timeline reconstruction.
• Grouping: Aggregate by session_id to view conversation turns.
• Branches: Use parent_event_id and logical_parent_event_id to reconstruct Pi branch points.