agent-chat-search

Unified, zero-token full-text search across all your AI coding agents and machines.

Search conversational history, debugging traces, and code diffs across Hermes Agent, Google Antigravity (agy), OpenClaw, OpenAI Codex, and Anthropic Claude Code spanning your local workstation or an entire Tailscale mesh.

The Problem: The Agent Silo

Developers increasingly work with multiple autonomous coding agents across multiple machines — laptops, cloud VMs, and desktop workstations:

• You fix an obscure kernel or build issue on your workstation using Google Antigravity.

• Two days later, Claude Code or Hermes Agent running on your laptop encounters the exact same failure.

• The agent has no memory of the fix, because every tool stores its session history in an isolated, incompatible silo.

Why not RAG or Vector Databases?

• Token Cost & GPU Waste: Chunking and embedding hundreds of megabytes of raw terminal logs, tool outputs, and compiler diffs burns millions of LLM tokens and saturates GPUs.

• Lexical Superiority: Exact error codes (evdi#557, 0000:00:14.0), compiler flags (-ctk q4_0), package versions, and paths are retrieved far more accurately with BM25 full-text search than fuzzy semantic vector embeddings.

• Obsidian/Git Bloat: Funneling raw agent transcripts into Obsidian or Git repositories explodes repo size, merges conflict, and chokes mobile sync.

Related MCP server: claude-kb

The Solution: agent-chat-search

agent-chat-search decouples agent history into a lightweight, local-first search engine:

1. Multi-Runtime Ingestors: Automatically discovers and parses transcripts from:

   • Hermes Agent: Relational SQLite (~/.hermes/state.db)

   • Google Antigravity (agy): Metadata SQLite (conversation_summaries.db) + JSON message trees (brain/<uuid>)

   • OpenClaw: Event-sourced SQLite (openclaw-agent.sqlite)

   • OpenAI Codex CLI: Thread DB (state_*.sqlite) + JSONL rollout transcripts

   • Anthropic Claude Code: JSON sessions & project transcripts

2. Zero Dependencies: Pure Python standard library (sqlite3, http.server, urllib, json). Zero external packages required.

3. Sub-Millisecond Performance: Backed by SQLite FTS5 with BM25 ranking and context snippet highlighting.

4. Tailscale Native: Operates as a fast, private HTTP/MCP service over your Tailnet, transferring only matching snippets (~2–5 KB per query).

5. Dual Interface: Serves humans at the terminal (agent-search) and agents via Model Context Protocol (mcp_servers).

Fleet Baseline Benchmark

Across 5 nodes in an active multi-agent mesh, agent-chat-search indexed 427 sessions and 30,725 messages into an optimized ~43 MB database:

Search query latency: < 15 milliseconds over Tailscale.

Installation

One-Line Install

git clone https://github.com/aacero/agent-chat-search.git ~/Projects/agent-chat-search
cd ~/Projects/agent-chat-search
./install.sh

This installs agent-search directly to ~/.local/bin/agent-search (ensure ~/.local/bin is in your $PATH).

Quick Start

1. Index Local Machine Chats

agent-search sync

2. Search Past Conversations

# General search with BM25 ranking and highlighted snippets
agent-search "DisplayLink evdi freeze"

# Filter by agent runtime
agent-search --agent hermes "USB watchdog migration"
agent-search --agent agy "display brightness config"
agent-search --agent openclaw "onboarding model api key"
agent-search --agent codex "refactor schema"

# Filter by speaker role (e.g. only prompts you typed)
agent-search --role user "hard freeze"

# Filter by host
agent-search --host server-node "backup"

# Limit to local database only
agent-search --local "Tailscale"

3. Read Full Session Transcript

agent-search show "server-node:hermes:20260826_134805_88f136"

Multi-Machine Fleet Setup (Tailscale)

In a multi-machine setup, designate one always-on node (e.g. a home server or workstation) as the central index server:

On the Server Node (e.g. server-node / 100.64.0.1):

Run as a systemd user service:

# ~/.config/systemd/user/agent-chat-search.service
[Unit]
Description=Agent Chat Search Service
After=network.target

[Service]
Type=simple
Environment=PYTHONPATH=%h/.local/share/agent-chat-search-app
ExecStart=%h/.local/bin/agent-search serve --host 127.0.0.1 --port 8890
Restart=always

[Install]
WantedBy=default.target

Enable and start:

systemctl --user daemon-reload
systemctl --user enable --now agent-chat-search

On Client Nodes (Laptops, Desktops):

Point the CLI to your server node (and optional bearer token):

export AGENT_SEARCH_URL="http://100.64.0.1:8890"
# export AGENT_SEARCH_TOKEN="your-secret-token"

Queries will automatically hit the central server over Tailscale in <20ms, falling back to the local SQLite database if the server is unreachable.

Managing Fleet Nodes (Adding & Deleting)

1. Adding a New Node to the Fleet

To include a new machine (e.g. gpu-workstation) in the federated fleet search:

1. Install on the New Node:

   git clone <repo-url> ~/src/agent-chat-search
   cd ~/src/agent-chat-search
   ./install.sh

2. Configure Client on the New Node: Create ~/.config/agent-chat-search/config.toml on the new machine:

   [server]
   url = "http://<central-server-tailscale-ip>:8890"
   # auth_token = "your-optional-token"

   (Or set export AGENT_SEARCH_URL="http://<central-server-tailscale-ip>:8890" in ~/.bashrc).

3. Index Local Chats on the New Node:

   agent-search sync --local-only

4. Register in Fleet Configuration: On your admin workstation or central server, add the new hostname to hosts in ~/.config/agent-chat-search/config.toml:

   [fleet]
   hosts = [
       "server-node",
       "dev-laptop",
       "gpu-workstation"
   ]

5. Propagate and Sync: Deploy updated files and trigger a fleet sync:

   ./deploy-fleet.sh
   agent-search sync --fleet --force

2. Decommissioning / Deleting a Node from the Fleet

To remove an old node from the fleet index:

1. Remove Host from Fleet Config: In ~/.config/agent-chat-search/config.toml, remove the hostname from hosts = [...]. Run ./deploy-fleet.sh to propagate the updated host list.

2. Purge Historical Data from Database: To permanently purge the decommissioned host's sessions, messages, and full-text index records from the SQLite database:

   agent-search purge old-node

   (Use -y or --yes to skip the confirmation prompt). This deletes the host's records from sessions, cascades the deletion to messages and messages_fts, and reclaims disk space with VACUUM.

Agent Integration (MCP)

agent-chat-search acts as a Model Context Protocol (MCP) server so external agents can recall past conversations.

For Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  agent_search:
    command: /home/user/.local/bin/agent-search
    args:
      - mcp

Tools Exposed to Agents:

• fleet_chat_search: Searches historical conversations across all agents and machines with ranking and code snippets.

• fleet_chat_get_session: Retrieves the full message transcript of any past session by its unique ID.

Architecture Overview

[Workstation]          [Laptop]              [Cloud VM]
  Hermes / agy / claw    Hermes / Codex        Hermes / Claude Code
       │                      │                      │
  (Local Index)          (Local Index)          (Local Index)
       │                      │                      │
       └──────────────────────┼──────────────────────┘
                              │ Tailscale
                              ▼
            ┌───────────────────────────────────┐
            │   Central Search Daemon (:8890)   │
            │      SQLite FTS5 + BM25           │
            └─────────────────┬─────────────────┘
                              │
               ┌──────────────┴──────────────┐
               ▼                             ▼
       CLI (`agent-search`)           MCP Server (:mcp)
     (Fast human terminal)       (Cross-agent episodic memory)

License

MIT License © 2026 Tony Acero