agent-cli 0.70.5__tar.gz → 0.71.0__tar.gz

{agent_cli-0.70.5 → agent_cli-0.71.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-cli
-Version: 0.70.5
+Version: 0.71.0
 Summary: A suite of AI-powered command-line tools for text correction, audio transcription, and voice assistance.
 Project-URL: Homepage, https://github.com/basnijholt/agent-cli
 Author-email: Bas Nijholt <bas@nijho.lt>
@@ -134,7 +134,7 @@ Since then I have expanded the tool with many more features, all focused on loca
 - **[`memory`](docs/commands/memory.md)**: Long-term memory system with `memory proxy` and `memory add`.
 - **[`rag-proxy`](docs/commands/rag-proxy.md)**: RAG proxy server for chatting with your documents.
 - **[`dev`](docs/commands/dev.md)**: Parallel development with git worktrees and AI coding agents.
-- **[`server`](docs/commands/server/index.md)**: Local ASR and TTS servers with dual-protocol (Wyoming & OpenAI), TTL-based memory management, and multi-platform acceleration. Whisper uses MLX on Apple Silicon or Faster Whisper on Linux/CUDA. TTS supports Kokoro (GPU) or Piper (CPU).
+- **[`server`](docs/commands/server/index.md)**: Local ASR and TTS servers with dual-protocol (Wyoming & OpenAI-compatible APIs), TTL-based memory management, and multi-platform acceleration. Whisper uses MLX on Apple Silicon or Faster Whisper on Linux/CUDA. TTS supports Kokoro (GPU) or Piper (CPU).
 - **[`transcribe-daemon`](docs/commands/transcribe-daemon.md)**: Continuous background transcription with VAD. Install with `uv tool install "agent-cli[vad]" -p 3.13`.
 
 ## Quick Start
@@ -498,21 +498,43 @@ agent-cli install-extras rag memory vad
 
  Usage: agent-cli install-extras [OPTIONS] [EXTRAS]...
 
- Install optional extras (rag, memory, vad, etc.) with pinned versions.
+ Install optional dependencies with pinned, compatible versions.
+
+ Many agent-cli features require optional dependencies. This command installs them with
+ version pinning to ensure compatibility. Dependencies persist across uv tool upgrade
+ when installed via uv tool.
+
+ Available extras:
+
+  • rag - RAG proxy server (ChromaDB, embeddings)
+  • memory - Long-term memory proxy (ChromaDB)
+  • vad - Voice Activity Detection (silero-vad)
+  • audio - Local audio recording/playback
+  • piper - Local Piper TTS engine
+  • kokoro - Kokoro neural TTS engine
+  • faster-whisper - Whisper ASR for CUDA/CPU
+  • mlx-whisper - Whisper ASR for Apple Silicon
+  • wyoming - Wyoming protocol for ASR/TTS servers
+  • server - FastAPI server components
+  • speed - Audio speed adjustment
+  • llm - LLM framework (pydantic-ai)
 
  Examples:
 
-  • agent-cli install-extras rag           # Install RAG dependencies
-  • agent-cli install-extras memory vad    # Install multiple extras
-  • agent-cli install-extras --list        # Show available extras
-  • agent-cli install-extras --all         # Install all extras
+
+  agent-cli install-extras rag           # Install RAG dependencies
+  agent-cli install-extras memory vad    # Install multiple extras
+  agent-cli install-extras --list        # Show available extras
+  agent-cli install-extras --all         # Install all extras
+
 
 ╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮
-│   extras      [EXTRAS]...  Extras to install                                           │
+│   extras      [EXTRAS]...  Extras to install: rag, memory, vad, audio, piper, kokoro,  │
+│                            faster-whisper, mlx-whisper, wyoming, server, speed, llm    │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
-│ --list  -l        List available extras                                                │
-│ --all   -a        Install all available extras                                         │
+│ --list  -l        Show available extras with descriptions (what each one enables)      │
+│ --all   -a        Install all available extras at once                                 │
 │ --help  -h        Show this message and exit.                                          │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 
@@ -571,13 +593,21 @@ agent-cli config edit
 
  Manage agent-cli configuration files.
 
+ Config files are TOML format and searched in order:
+
+  1 ./agent-cli-config.toml (project-local)
+  2 ~/.config/agent-cli/config.toml (user default)
+
+ Settings in [defaults] apply to all commands. Override per-command with sections like
+ [chat] or [transcribe]. CLI arguments override config file settings.
+
 ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
 │ --help  -h        Show this message and exit.                                          │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
-│ init   Create a new config file with all options commented out.                        │
+│ init   Create a new config file with all options as commented-out examples.            │
 │ edit   Open the config file in your default editor.                                    │
-│ show   Display the config file location and contents.                                  │
+│ show   Display the active config file path and contents.                               │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 
 ```
@@ -635,10 +665,37 @@ the `[defaults]` section of your configuration file.
 
  Usage: agent-cli autocorrect [OPTIONS] [TEXT]
 
- Correct text from clipboard using a local or remote LLM.
+ Fix grammar, spelling, and punctuation using an LLM.
+
+ Reads text from clipboard (or argument), sends to LLM for correction, and copies the
+ result back to clipboard. Only makes technical corrections without changing meaning or
+ tone.
+
+ Workflow:
+
+  1 Read text from clipboard (or TEXT argument)
+  2 Send to LLM for grammar/spelling/punctuation fixes
+  3 Copy corrected text to clipboard (unless --json)
+  4 Display result
+
+ Examples:
+
+
+  # Correct text from clipboard (default)
+  agent-cli autocorrect
+
+  # Correct specific text
+  agent-cli autocorrect "this is incorect"
+
+  # Use OpenAI instead of local Ollama
+  agent-cli autocorrect --llm-provider openai
+
+  # Get JSON output for scripting (disables clipboard)
+  agent-cli autocorrect --json
+
 
 ╭─ General Options ──────────────────────────────────────────────────────────────────────╮
-│   text      [TEXT]  The text to correct. If not provided, reads from clipboard.        │
+│   text      [TEXT]  Text to correct. If omitted, reads from system clipboard.          │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
 │ --help  -h        Show this message and exit.                                          │
@@ -682,9 +739,8 @@ the `[defaults]` section of your configuration file.
 │                                                   [default: info]                      │
 │ --log-file            TEXT                        Path to a file to write logs to.     │
 │ --quiet       -q                                  Suppress console output from rich.   │
-│ --json                                            Output result as JSON for            │
-│                                                   automation. Implies --quiet and      │
-│                                                   --no-clipboard.                      │
+│ --json                                            Output result as JSON (implies       │
+│                                                   --quiet and --no-clipboard).         │
 │ --config              TEXT                        Path to a TOML configuration file.   │
 │ --print-args                                      Print the command line arguments,    │
 │                                                   including variables taken from the   │
@@ -732,30 +788,50 @@ the `[defaults]` section of your configuration file.
 
  Usage: agent-cli transcribe [OPTIONS]
 
- Wyoming ASR Client for streaming microphone audio to a transcription server.
+ Record audio from microphone and transcribe to text.
+
+ Records until you press Ctrl+C (or send SIGINT), then transcribes using your configured
+ ASR provider. The transcript is copied to the clipboard by default.
+
+ With --llm: Passes the raw transcript through an LLM to clean up speech recognition
+ errors, add punctuation, remove filler words, and improve readability.
+
+ With --toggle: Bind to a hotkey for push-to-talk. First call starts recording, second
+ call stops and transcribes.
+
+ Examples:
+
+  • Record and transcribe: agent-cli transcribe
+  • With LLM cleanup: agent-cli transcribe --llm
+  • Re-transcribe last recording: agent-cli transcribe --last-recording 1
 
 ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
 │ --help  -h        Show this message and exit.                                          │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ LLM Configuration ────────────────────────────────────────────────────────────────────╮
-│ --extra-instructions                TEXT  Additional instructions for the LLM to       │
-│                                           process the transcription.                   │
-│ --llm                   --no-llm          Use an LLM to process the transcript.        │
+│ --extra-instructions                TEXT  Extra instructions appended to the LLM       │
+│                                           cleanup prompt (requires --llm).             │
+│ --llm                   --no-llm          Clean up transcript with LLM: fix errors,    │
+│                                           add punctuation, remove filler words. Uses   │
+│                                           --extra-instructions if set (via CLI or      │
+│                                           config file).                                │
 │                                           [default: no-llm]                            │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Audio Recovery ───────────────────────────────────────────────────────────────────────╮
-│ --from-file                                PATH     Transcribe audio from a file       │
-│                                                     (supports wav, mp3, m4a, ogg,      │
-│                                                     flac, aac, webm). Requires ffmpeg  │
-│                                                     for non-WAV formats with Wyoming   │
-│                                                     provider.                          │
-│ --last-recording                           INTEGER  Transcribe a saved recording. Use  │
-│                                                     1 for most recent, 2 for           │
-│                                                     second-to-last, etc. Use 0 to      │
-│                                                     disable (default).                 │
+│ --from-file                                PATH     Transcribe from audio file instead │
+│                                                     of microphone. Supports wav, mp3,  │
+│                                                     m4a, ogg, flac, aac, webm.         │
+│                                                     Requires ffmpeg for non-WAV        │
+│                                                     formats with Wyoming.              │
+│ --last-recording                           INTEGER  Re-transcribe a saved recording    │
+│                                                     (1=most recent, 2=second-to-last,  │
+│                                                     etc). Useful after connection      │
+│                                                     failures or to retry with          │
+│                                                     different options.                 │
 │                                                     [default: 0]                       │
-│ --save-recording    --no-save-recording             Save the audio recording to disk   │
-│                                                     for recovery.                      │
+│ --save-recording    --no-save-recording             Save recordings to                 │
+│                                                     ~/.cache/agent-cli/ for            │
+│                                                     --last-recording recovery.         │
 │                                                     [default: save-recording]          │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮
@@ -767,10 +843,12 @@ the `[defaults]` section of your configuration file.
 │                             [default: ollama]                                          │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮
-│ --input-device-index        INTEGER  Index of the audio input device to use.           │
-│ --input-device-name         TEXT     Device name keywords for partial matching.        │
-│ --list-devices                       List available audio input and output devices and │
-│                                      exit.                                             │
+│ --input-device-index        INTEGER  Audio input device index (see --list-devices).    │
+│                                      Uses system default if omitted.                   │
+│ --input-device-name         TEXT     Select input device by name substring (e.g.,      │
+│                                      MacBook or USB).                                  │
+│ --list-devices                       List available audio devices with their indices   │
+│                                      and exit.                                         │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮
 │ --asr-wyoming-ip          TEXT     Wyoming ASR server IP address.                      │
@@ -825,10 +903,9 @@ the `[defaults]` section of your configuration file.
 │                                 [env var: GEMINI_API_KEY]                              │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Process Management ───────────────────────────────────────────────────────────────────╮
-│ --stop            Stop any running background process.                                 │
-│ --status          Check if a background process is running.                            │
-│ --toggle          Toggle the background process on/off. If the process is running, it  │
-│                   will be stopped. If the process is not running, it will be started.  │
+│ --stop            Stop any running instance of this command.                           │
+│ --status          Check if an instance is currently running.                           │
+│ --toggle          Start if not running, stop if running. Ideal for hotkey binding.     │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ General Options ──────────────────────────────────────────────────────────────────────╮
 │ --clipboard              --no-clipboard                          Copy result to        │
@@ -842,9 +919,8 @@ the `[defaults]` section of your configuration file.
 │ --quiet              -q                                          Suppress console      │
 │                                                                  output from rich.     │
 │ --json                                                           Output result as JSON │
-│                                                                  for automation.       │
-│                                                                  Implies --quiet and   │
-│                                                                  --no-clipboard.       │
+│                                                                  (implies --quiet and  │
+│                                                                  --no-clipboard).      │
 │ --config                                   TEXT                  Path to a TOML        │
 │                                                                  configuration file.   │
 │ --print-args                                                     Print the command     │
@@ -852,11 +928,13 @@ the `[defaults]` section of your configuration file.
 │                                                                  including variables   │
 │                                                                  taken from the        │
 │                                                                  configuration file.   │
-│ --transcription-log                        PATH                  Path to log           │
-│                                                                  transcription results │
-│                                                                  with timestamps,      │
-│                                                                  hostname, model, and  │
-│                                                                  raw output.           │
+│ --transcription-log                        PATH                  Append transcripts to │
+│                                                                  JSONL file            │
+│                                                                  (timestamp, hostname, │
+│                                                                  model, raw/processed  │
+│                                                                  text). Recent entries │
+│                                                                  provide context for   │
+│                                                                  LLM cleanup.          │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 
 ```
@@ -912,46 +990,76 @@ uv tool install "agent-cli[vad]" -p 3.13
 
  Usage: agent-cli transcribe-daemon [OPTIONS]
 
- Run a continuous transcription daemon with voice activity detection.
+ Continuous transcription daemon using Silero VAD for speech detection.
+
+ Unlike transcribe (single recording session), this daemon runs indefinitely and
+ automatically detects speech segments using Voice Activity Detection (VAD). Each
+ detected segment is transcribed and logged with timestamps.
 
- This command runs indefinitely, capturing audio from your microphone, detecting speech
- segments using Silero VAD, transcribing them, and logging results with timestamps.
+ How it works:
 
- Examples: # Basic daemon agent-cli transcribe-daemon
+  1 Listens continuously to microphone input
+  2 Silero VAD detects when you start/stop speaking
+  3 After --silence-threshold seconds of silence, the segment is finalized
+  4 Segment is transcribed (and optionally cleaned by LLM with --llm)
+  5 Results are appended to the JSONL log file
+  6 Audio is saved as MP3 if --save-audio is enabled (requires ffmpeg)
 
+ Use cases: Meeting transcription, note-taking, voice journaling, accessibility.
 
-  # With role and custom silence threshold
+ Examples:
+
+
+  agent-cli transcribe-daemon
   agent-cli transcribe-daemon --role meeting --silence-threshold 1.5
+  agent-cli transcribe-daemon --llm --clipboard --role notes
+  agent-cli transcribe-daemon --transcription-log ~/meeting.jsonl --no-save-audio
+  agent-cli transcribe-daemon --asr-provider openai --llm-provider gemini --llm
 
-  # With LLM cleanup
-  agent-cli transcribe-daemon --llm --role notes
 
-  # Custom log file and audio directory
-  agent-cli transcribe-daemon --transcription-log ~/meeting.jsonl --audio-dir ~/audio
+ Tips:
 
+  • Use --role to tag entries (e.g., speaker1, meeting, personal)
+  • Adjust --vad-threshold if detection is too sensitive (increase) or missing speech
+    (decrease)
+  • Use --stop to cleanly terminate a running daemon
+  • With --llm, transcripts are cleaned up (punctuation, filler words removed)
 
 ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
-│ --role               -r                     TEXT   Role name for logging (e.g.,        │
-│                                                    'meeting', 'notes', 'user').        │
+│ --role               -r                     TEXT   Label for log entries. Use to       │
+│                                                    distinguish speakers or contexts in │
+│                                                    logs.                               │
 │                                                    [default: user]                     │
-│ --silence-threshold  -s                     FLOAT  Seconds of silence to end a speech  │
-│                                                    segment.                            │
+│ --silence-threshold  -s                     FLOAT  Seconds of silence after speech to  │
+│                                                    finalize a segment. Increase for    │
+│                                                    slower speakers.                    │
 │                                                    [default: 1.0]                      │
-│ --min-segment        -m                     FLOAT  Minimum speech duration in seconds  │
-│                                                    to trigger a segment.               │
+│ --min-segment        -m                     FLOAT  Minimum seconds of speech required  │
+│                                                    before a segment is processed.      │
+│                                                    Filters brief sounds.               │
 │                                                    [default: 0.25]                     │
-│ --vad-threshold                             FLOAT  VAD speech detection threshold      │
-│                                                    (0.0-1.0). Higher = more aggressive │
-│                                                    filtering.                          │
+│ --vad-threshold                             FLOAT  Silero VAD confidence threshold     │
+│                                                    (0.0-1.0). Higher values require    │
+│                                                    clearer speech; lower values are    │
+│                                                    more sensitive to quiet/distant     │
+│                                                    voices.                             │
 │                                                    [default: 0.3]                      │
-│ --save-audio             --no-save-audio           Save audio segments as MP3 files.   │
+│ --save-audio             --no-save-audio           Save each speech segment as MP3.    │
+│                                                    Requires ffmpeg to be installed.    │
 │                                                    [default: save-audio]               │
-│ --audio-dir                                 PATH   Directory for MP3 files. Default:   │
-│                                                    ~/.config/agent-cli/audio           │
-│ --transcription-log  -t                     PATH   JSON Lines log file path. Default:  │
+│ --audio-dir                                 PATH   Base directory for MP3 files. Files │
+│                                                    are organized by date:              │
+│                                                    YYYY/MM/DD/HHMMSS_mmm.mp3. Default: │
+│                                                    ~/.config/agent-cli/audio.          │
+│ --transcription-log  -t                     PATH   JSONL file for transcript logging   │
+│                                                    (one JSON object per line with      │
+│                                                    timestamp, role, raw/processed      │
+│                                                    text, audio path). Default:         │
 │                                                    ~/.config/agent-cli/transcriptions… │
-│ --clipboard              --no-clipboard            Copy each transcription to          │
-│                                                    clipboard.                          │
+│ --clipboard              --no-clipboard            Copy each completed transcription   │
+│                                                    to clipboard (overwrites previous). │
+│                                                    Useful with --llm to get cleaned    │
+│                                                    text.                               │
 │                                                    [default: no-clipboard]             │
 │ --help               -h                            Show this message and exit.         │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
@@ -964,10 +1072,12 @@ uv tool install "agent-cli[vad]" -p 3.13
 │                             [default: ollama]                                          │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮
-│ --input-device-index        INTEGER  Index of the audio input device to use.           │
-│ --input-device-name         TEXT     Device name keywords for partial matching.        │
-│ --list-devices                       List available audio input and output devices and │
-│                                      exit.                                             │
+│ --input-device-index        INTEGER  Audio input device index (see --list-devices).    │
+│                                      Uses system default if omitted.                   │
+│ --input-device-name         TEXT     Select input device by name substring (e.g.,      │
+│                                      MacBook or USB).                                  │
+│ --list-devices                       List available audio devices with their indices   │
+│                                      and exit.                                         │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮
 │ --asr-wyoming-ip          TEXT     Wyoming ASR server IP address.                      │
@@ -1022,12 +1132,14 @@ uv tool install "agent-cli[vad]" -p 3.13
 │                                 [env var: GEMINI_API_KEY]                              │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ LLM Configuration ────────────────────────────────────────────────────────────────────╮
-│ --llm    --no-llm      Use an LLM to process the transcript.                           │
+│ --llm    --no-llm      Clean up transcript with LLM: fix errors, add punctuation,      │
+│                        remove filler words. Uses --extra-instructions if set (via CLI  │
+│                        or config file).                                                │
 │                        [default: no-llm]                                               │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Process Management ───────────────────────────────────────────────────────────────────╮
-│ --stop            Stop any running background process.                                 │
-│ --status          Check if a background process is running.                            │
+│ --stop            Stop any running instance of this command.                           │
+│ --status          Check if an instance is currently running.                           │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ General Options ──────────────────────────────────────────────────────────────────────╮
 │ --log-level           [debug|info|warning|error]  Set logging level.                   │
@@ -1081,10 +1193,25 @@ uv tool install "agent-cli[vad]" -p 3.13
 
  Usage: agent-cli speak [OPTIONS] [TEXT]
 
- Convert text to speech using Wyoming or OpenAI-compatible TTS server.
+ Convert text to speech and play audio through speakers.
+
+ By default, synthesized audio plays immediately. Use --save-file to save to a WAV file
+ instead (skips playback).
+
+ Text can be provided as an argument or read from clipboard automatically.
+
+ Examples:
+
+ Speak text directly: agent-cli speak "Hello, world!"
+
+ Speak clipboard contents: agent-cli speak
+
+ Save to file instead of playing: agent-cli speak "Hello" --save-file greeting.wav
+
+ Use OpenAI-compatible TTS: agent-cli speak "Hello" --tts-provider openai
 
 ╭─ General Options ──────────────────────────────────────────────────────────────────────╮
-│   text      [TEXT]  Text to speak. Reads from clipboard if not provided.               │
+│   text      [TEXT]  Text to synthesize. If not provided, reads from clipboard.         │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
 │ --help  -h        Show this message and exit.                                          │
@@ -1096,9 +1223,10 @@ uv tool install "agent-cli[vad]" -p 3.13
 │                             [default: wyoming]                                         │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Audio Output ─────────────────────────────────────────────────────────────────────────╮
-│ --output-device-index        INTEGER  Index of the audio output device to use for TTS. │
-│ --output-device-name         TEXT     Output device name keywords for partial          │
-│                                       matching.                                        │
+│ --output-device-index        INTEGER  Audio output device index (see --list-devices    │
+│                                       for available devices).                          │
+│ --output-device-name         TEXT     Partial match on device name (e.g., 'speakers',  │
+│                                       'headphones').                                   │
 │ --tts-speed                  FLOAT    Speech speed multiplier (1.0 = normal, 2.0 =     │
 │                                       twice as fast, 0.5 = half speed).                │
 │                                       [default: 1.0]                                   │
@@ -1116,7 +1244,8 @@ uv tool install "agent-cli[vad]" -p 3.13
 ╭─ Audio Output: OpenAI-compatible ──────────────────────────────────────────────────────╮
 │ --tts-openai-model           TEXT  The OpenAI model to use for TTS.                    │
 │                                    [default: tts-1]                                    │
-│ --tts-openai-voice           TEXT  The voice to use for OpenAI-compatible TTS.         │
+│ --tts-openai-voice           TEXT  Voice for OpenAI TTS (alloy, echo, fable, onyx,     │
+│                                    nova, shimmer).                                     │
 │                                    [default: alloy]                                    │
 │ --tts-openai-base-url        TEXT  Custom base URL for OpenAI-compatible TTS API       │
 │                                    (e.g., http://localhost:8000/v1 for a proxy).       │
@@ -1142,28 +1271,27 @@ uv tool install "agent-cli[vad]" -p 3.13
 │                               [env var: GEMINI_API_KEY]                                │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮
-│ --list-devices          List available audio input and output devices and exit.        │
+│ --list-devices          List available audio devices with their indices and exit.      │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ General Options ──────────────────────────────────────────────────────────────────────╮
-│ --save-file           PATH                        Save TTS response audio to WAV file. │
+│ --save-file           PATH                        Save audio to WAV file instead of    │
+│                                                   playing through speakers.            │
 │ --log-level           [debug|info|warning|error]  Set logging level.                   │
 │                                                   [env var: LOG_LEVEL]                 │
 │                                                   [default: info]                      │
 │ --log-file            TEXT                        Path to a file to write logs to.     │
 │ --quiet       -q                                  Suppress console output from rich.   │
-│ --json                                            Output result as JSON for            │
-│                                                   automation. Implies --quiet and      │
-│                                                   --no-clipboard.                      │
+│ --json                                            Output result as JSON (implies       │
+│                                                   --quiet and --no-clipboard).         │
 │ --config              TEXT                        Path to a TOML configuration file.   │
 │ --print-args                                      Print the command line arguments,    │
 │                                                   including variables taken from the   │
 │                                                   configuration file.                  │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Process Management ───────────────────────────────────────────────────────────────────╮
-│ --stop            Stop any running background process.                                 │
-│ --status          Check if a background process is running.                            │
-│ --toggle          Toggle the background process on/off. If the process is running, it  │
-│                   will be stopped. If the process is not running, it will be started.  │
+│ --stop            Stop any running instance of this command.                           │
+│ --status          Check if an instance is currently running.                           │
+│ --toggle          Start if not running, stop if running. Ideal for hotkey binding.     │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 
 ```
@@ -1205,16 +1333,23 @@ uv tool install "agent-cli[vad]" -p 3.13
 
  Usage: agent-cli voice-edit [OPTIONS]
 
- Interact with clipboard text via a voice command using local or remote services.
+ Edit or query clipboard text using voice commands.
+
+ Workflow: Captures clipboard text → records your voice command → transcribes it → sends
+ both to an LLM → copies result back to clipboard.
+
+ Use this for hands-free text editing (e.g., "make this more formal") or asking questions
+ about clipboard content (e.g., "summarize this").
 
- Usage:
+ Typical hotkey integration: Run voice-edit & on keypress to start recording, then send
+ SIGINT (via --stop) on second keypress to process.
+
+ Examples:
 
-  • Run in foreground: agent-cli voice-edit --input-device-index 1
-  • Run in background: agent-cli voice-edit --input-device-index 1 &
-  • Check status: agent-cli voice-edit --status
-  • Stop background process: agent-cli voice-edit --stop
-  • List output devices: agent-cli voice-edit --list-output-devices
-  • Save TTS to file: agent-cli voice-edit --tts --save-file response.wav
+  • Basic usage: agent-cli voice-edit
+  • With TTS response: agent-cli voice-edit --tts
+  • Toggle on/off: agent-cli voice-edit --toggle
+  • List audio devices: agent-cli voice-edit --list-devices
 
 ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
 │ --help  -h        Show this message and exit.                                          │
@@ -1232,10 +1367,12 @@ uv tool install "agent-cli[vad]" -p 3.13
 │                             [default: wyoming]                                         │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮
-│ --input-device-index        INTEGER  Index of the audio input device to use.           │
-│ --input-device-name         TEXT     Device name keywords for partial matching.        │
-│ --list-devices                       List available audio input and output devices and │
-│                                      exit.                                             │
+│ --input-device-index        INTEGER  Audio input device index (see --list-devices).    │
+│                                      Uses system default if omitted.                   │
+│ --input-device-name         TEXT     Select input device by name substring (e.g.,      │
+│                                      MacBook or USB).                                  │
+│ --list-devices                       List available audio devices with their indices   │
+│                                      and exit.                                         │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮
 │ --asr-wyoming-ip          TEXT     Wyoming ASR server IP address.                      │
@@ -1286,10 +1423,10 @@ uv tool install "agent-cli[vad]" -p 3.13
 ╭─ Audio Output ─────────────────────────────────────────────────────────────────────────╮
 │ --tts                    --no-tts             Enable text-to-speech for responses.     │
 │                                               [default: no-tts]                        │
-│ --output-device-index                INTEGER  Index of the audio output device to use  │
-│                                               for TTS.                                 │
-│ --output-device-name                 TEXT     Output device name keywords for partial  │
-│                                               matching.                                │
+│ --output-device-index                INTEGER  Audio output device index (see           │
+│                                               --list-devices for available devices).   │
+│ --output-device-name                 TEXT     Partial match on device name (e.g.,      │
+│                                               'speakers', 'headphones').               │
 │ --tts-speed                          FLOAT    Speech speed multiplier (1.0 = normal,   │
 │                                               2.0 = twice as fast, 0.5 = half speed).  │
 │                                               [default: 1.0]                           │
@@ -1307,7 +1444,8 @@ uv tool install "agent-cli[vad]" -p 3.13
 ╭─ Audio Output: OpenAI-compatible ──────────────────────────────────────────────────────╮
 │ --tts-openai-model           TEXT  The OpenAI model to use for TTS.                    │
 │                                    [default: tts-1]                                    │
-│ --tts-openai-voice           TEXT  The voice to use for OpenAI-compatible TTS.         │
+│ --tts-openai-voice           TEXT  Voice for OpenAI TTS (alloy, echo, fable, onyx,     │
+│                                    nova, shimmer).                                     │
 │                                    [default: alloy]                                    │
 │ --tts-openai-base-url        TEXT  Custom base URL for OpenAI-compatible TTS API       │
 │                                    (e.g., http://localhost:8000/v1 for a proxy).       │
@@ -1328,14 +1466,14 @@ uv tool install "agent-cli[vad]" -p 3.13
 │                                 [default: Kore]                                        │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Process Management ───────────────────────────────────────────────────────────────────╮
-│ --stop            Stop any running background process.                                 │
-│ --status          Check if a background process is running.                            │
-│ --toggle          Toggle the background process on/off. If the process is running, it  │
-│                   will be stopped. If the process is not running, it will be started.  │
+│ --stop            Stop any running instance of this command.                           │
+│ --status          Check if an instance is currently running.                           │
+│ --toggle          Start if not running, stop if running. Ideal for hotkey binding.     │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ General Options ──────────────────────────────────────────────────────────────────────╮
-│ --save-file                         PATH                      Save TTS response audio  │
-│                                                               to WAV file.             │
+│ --save-file                         PATH                      Save audio to WAV file   │
+│                                                               instead of playing       │
+│                                                               through speakers.        │
 │ --clipboard       --no-clipboard                              Copy result to           │
 │                                                               clipboard.               │
 │                                                               [default: clipboard]     │
@@ -1347,9 +1485,8 @@ uv tool install "agent-cli[vad]" -p 3.13
 │ --quiet       -q                                              Suppress console output  │
 │                                                               from rich.               │
 │ --json                                                        Output result as JSON    │
-│                                                               for automation. Implies  │
-│                                                               --quiet and              │
-│                                                               --no-clipboard.          │
+│                                                               (implies --quiet and     │
+│                                                               --no-clipboard).         │
 │ --config                            TEXT                      Path to a TOML           │
 │                                                               configuration file.      │
 │ --print-args                                                  Print the command line   │
@@ -1400,7 +1537,28 @@ uv tool install "agent-cli[vad]" -p 3.13
 
  Usage: agent-cli assistant [OPTIONS]
 
- Wake word-based voice assistant using local or remote services.
+ Hands-free voice assistant using wake word detection.
+
+ Continuously listens for a wake word, then records your speech until you say the wake
+ word again. The recording is transcribed and sent to an LLM for a conversational
+ response, optionally spoken back via TTS.
+
+ Conversation flow:
+
+  1 Say wake word → starts recording
+  2 Speak your question/command
+  3 Say wake word again → stops recording and processes
+
+ The assistant runs in a loop, ready for the next command after each response. Stop with
+ Ctrl+C or --stop.
+
+ Requirements:
+
+  • Wyoming wake word server (e.g., wyoming-openwakeword on port 10400)
+  • Wyoming ASR server (e.g., wyoming-whisper on port 10300)
+  • Optional: TTS server for spoken responses (enable with --tts)
+
+ Example: assistant --wake-word ok_nabu --tts --input-device-name USB
 
 ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
 │ --help  -h        Show this message and exit.                                          │
@@ -1418,19 +1576,23 @@ uv tool install "agent-cli[vad]" -p 3.13
 │                             [default: wyoming]                                         │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Wake Word ────────────────────────────────────────────────────────────────────────────╮
-│ --wake-server-ip          TEXT     Wyoming wake word server IP address.                │
+│ --wake-server-ip          TEXT     Wyoming wake word server IP (requires               │
+│                                    wyoming-openwakeword or similar).                   │
 │                                    [default: localhost]                                │
 │ --wake-server-port        INTEGER  Wyoming wake word server port.                      │
 │                                    [default: 10400]                                    │
-│ --wake-word               TEXT     Name of wake word to detect (e.g., 'ok_nabu',       │
-│                                    'hey_jarvis').                                      │
+│ --wake-word               TEXT     Wake word to detect. Common options: ok_nabu,       │
+│                                    hey_jarvis, alexa. Must match a model loaded in     │
+│                                    your wake word server.                              │
 │                                    [default: ok_nabu]                                  │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮
-│ --input-device-index        INTEGER  Index of the audio input device to use.           │
-│ --input-device-name         TEXT     Device name keywords for partial matching.        │
-│ --list-devices                       List available audio input and output devices and │
-│                                      exit.                                             │
+│ --input-device-index        INTEGER  Audio input device index (see --list-devices).    │
+│                                      Uses system default if omitted.                   │
+│ --input-device-name         TEXT     Select input device by name substring (e.g.,      │
+│                                      MacBook or USB).                                  │
+│ --list-devices                       List available audio devices with their indices   │
+│                                      and exit.                                         │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮
 │ --asr-wyoming-ip          TEXT     Wyoming ASR server IP address.                      │
@@ -1481,10 +1643,10 @@ uv tool install "agent-cli[vad]" -p 3.13
 ╭─ Audio Output ─────────────────────────────────────────────────────────────────────────╮
 │ --tts                    --no-tts             Enable text-to-speech for responses.     │
 │                                               [default: no-tts]                        │
-│ --output-device-index                INTEGER  Index of the audio output device to use  │
-│                                               for TTS.                                 │
-│ --output-device-name                 TEXT     Output device name keywords for partial  │
-│                                               matching.                                │
+│ --output-device-index                INTEGER  Audio output device index (see           │
+│                                               --list-devices for available devices).   │
+│ --output-device-name                 TEXT     Partial match on device name (e.g.,      │
+│                                               'speakers', 'headphones').               │
 │ --tts-speed                          FLOAT    Speech speed multiplier (1.0 = normal,   │
 │                                               2.0 = twice as fast, 0.5 = half speed).  │
 │                                               [default: 1.0]                           │
@@ -1502,7 +1664,8 @@ uv tool install "agent-cli[vad]" -p 3.13
 ╭─ Audio Output: OpenAI-compatible ──────────────────────────────────────────────────────╮
 │ --tts-openai-model           TEXT  The OpenAI model to use for TTS.                    │
 │                                    [default: tts-1]                                    │
-│ --tts-openai-voice           TEXT  The voice to use for OpenAI-compatible TTS.         │
+│ --tts-openai-voice           TEXT  Voice for OpenAI TTS (alloy, echo, fable, onyx,     │
+│                                    nova, shimmer).                                     │
 │                                    [default: alloy]                                    │
 │ --tts-openai-base-url        TEXT  Custom base URL for OpenAI-compatible TTS API       │
 │                                    (e.g., http://localhost:8000/v1 for a proxy).       │
@@ -1523,14 +1686,14 @@ uv tool install "agent-cli[vad]" -p 3.13
 │                                 [default: Kore]                                        │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Process Management ───────────────────────────────────────────────────────────────────╮
-│ --stop            Stop any running background process.                                 │
-│ --status          Check if a background process is running.                            │
-│ --toggle          Toggle the background process on/off. If the process is running, it  │
-│                   will be stopped. If the process is not running, it will be started.  │
+│ --stop            Stop any running instance of this command.                           │
+│ --status          Check if an instance is currently running.                           │
+│ --toggle          Start if not running, stop if running. Ideal for hotkey binding.     │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ General Options ──────────────────────────────────────────────────────────────────────╮
-│ --save-file                         PATH                      Save TTS response audio  │
-│                                                               to WAV file.             │
+│ --save-file                         PATH                      Save audio to WAV file   │
+│                                                               instead of playing       │
+│                                                               through speakers.        │
 │ --clipboard       --no-clipboard                              Copy result to           │
 │                                                               clipboard.               │
 │                                                               [default: clipboard]     │
@@ -1598,7 +1761,39 @@ uv tool install "agent-cli[vad]" -p 3.13
 
  Usage: agent-cli chat [OPTIONS]
 
- An chat agent that you can talk to.
+ Voice-based conversational chat agent with memory and tools.
+
+ Runs an interactive loop: listen → transcribe → LLM → speak response. Conversation
+ history is persisted and included as context for continuity.
+
+ Built-in tools (LLM uses automatically when relevant):
+
+  • add_memory/search_memory/update_memory - persistent long-term memory
+  • duckduckgo_search - web search for current information
+  • read_file/execute_code - file access and shell commands
+
+ Process management: Use --toggle to start/stop via hotkey (bind to a keyboard shortcut),
+ --stop to terminate, or --status to check state.
+
+ Examples:
+
+ Use OpenAI-compatible providers for speech and LLM, with TTS enabled:
+
+
+  agent-cli chat --asr-provider openai --llm-provider openai --tts
+
+
+ Start in background mode (toggle on/off with hotkey):
+
+
+  agent-cli chat --toggle
+
+
+ Use local Ollama LLM with Wyoming ASR:
+
+
+  agent-cli chat --llm-provider ollama
+
 
 ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
 │ --help  -h        Show this message and exit.                                          │
@@ -1616,10 +1811,12 @@ uv tool install "agent-cli[vad]" -p 3.13
 │                             [default: wyoming]                                         │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮
-│ --input-device-index        INTEGER  Index of the audio input device to use.           │
-│ --input-device-name         TEXT     Device name keywords for partial matching.        │
-│ --list-devices                       List available audio input and output devices and │
-│                                      exit.                                             │
+│ --input-device-index        INTEGER  Audio input device index (see --list-devices).    │
+│                                      Uses system default if omitted.                   │
+│ --input-device-name         TEXT     Select input device by name substring (e.g.,      │
+│                                      MacBook or USB).                                  │
+│ --list-devices                       List available audio devices with their indices   │
+│                                      and exit.                                         │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮
 │ --asr-wyoming-ip          TEXT     Wyoming ASR server IP address.                      │
@@ -1676,10 +1873,10 @@ uv tool install "agent-cli[vad]" -p 3.13
 ╭─ Audio Output ─────────────────────────────────────────────────────────────────────────╮
 │ --tts                    --no-tts             Enable text-to-speech for responses.     │
 │                                               [default: no-tts]                        │
-│ --output-device-index                INTEGER  Index of the audio output device to use  │
-│                                               for TTS.                                 │
-│ --output-device-name                 TEXT     Output device name keywords for partial  │
-│                                               matching.                                │
+│ --output-device-index                INTEGER  Audio output device index (see           │
+│                                               --list-devices for available devices).   │
+│ --output-device-name                 TEXT     Partial match on device name (e.g.,      │
+│                                               'speakers', 'headphones').               │
 │ --tts-speed                          FLOAT    Speech speed multiplier (1.0 = normal,   │
 │                                               2.0 = twice as fast, 0.5 = half speed).  │
 │                                               [default: 1.0]                           │
@@ -1697,7 +1894,8 @@ uv tool install "agent-cli[vad]" -p 3.13
 ╭─ Audio Output: OpenAI-compatible ──────────────────────────────────────────────────────╮
 │ --tts-openai-model           TEXT  The OpenAI model to use for TTS.                    │
 │                                    [default: tts-1]                                    │
-│ --tts-openai-voice           TEXT  The voice to use for OpenAI-compatible TTS.         │
+│ --tts-openai-voice           TEXT  Voice for OpenAI TTS (alloy, echo, fable, onyx,     │
+│                                    nova, shimmer).                                     │
 │                                    [default: alloy]                                    │
 │ --tts-openai-base-url        TEXT  Custom base URL for OpenAI-compatible TTS API       │
 │                                    (e.g., http://localhost:8000/v1 for a proxy).       │
@@ -1718,20 +1916,23 @@ uv tool install "agent-cli[vad]" -p 3.13
 │                                 [default: Kore]                                        │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Process Management ───────────────────────────────────────────────────────────────────╮
-│ --stop            Stop any running background process.                                 │
-│ --status          Check if a background process is running.                            │
-│ --toggle          Toggle the background process on/off. If the process is running, it  │
-│                   will be stopped. If the process is not running, it will be started.  │
+│ --stop            Stop any running instance of this command.                           │
+│ --status          Check if an instance is currently running.                           │
+│ --toggle          Start if not running, stop if running. Ideal for hotkey binding.     │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ History Options ──────────────────────────────────────────────────────────────────────╮
-│ --history-dir            PATH     Directory to store conversation history.             │
+│ --history-dir            PATH     Directory for conversation history and long-term     │
+│                                   memory. Both conversation.json and                   │
+│                                   long_term_memory.json are stored here.               │
 │                                   [default: ~/.config/agent-cli/history]               │
-│ --last-n-messages        INTEGER  Number of messages to include in the conversation    │
-│                                   history. Set to 0 to disable history.                │
+│ --last-n-messages        INTEGER  Number of past messages to include as context for    │
+│                                   the LLM. Set to 0 to start fresh each session        │
+│                                   (memory tools still persist).                        │
 │                                   [default: 50]                                        │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ General Options ──────────────────────────────────────────────────────────────────────╮
-│ --save-file           PATH                        Save TTS response audio to WAV file. │
+│ --save-file           PATH                        Save audio to WAV file instead of    │
+│                                                   playing through speakers.            │
 │ --log-level           [debug|info|warning|error]  Set logging level.                   │
 │                                                   [env var: LOG_LEVEL]                 │
 │                                                   [default: info]                      │
@@ -1786,25 +1987,68 @@ uv tool install "agent-cli[vad]" -p 3.13
 
  Usage: agent-cli rag-proxy [OPTIONS]
 
- Start the RAG (Retrieval-Augmented Generation) Proxy Server.
+ Start a RAG proxy server that enables "chat with your documents".
+
+ Watches a folder for documents, indexes them into a vector store, and provides an
+ OpenAI-compatible API at /v1/chat/completions. When you send a chat request, the server
+ retrieves relevant document chunks and injects them as context before forwarding to your
+ LLM backend.
+
+ Quick start:
+
+  • agent-cli rag-proxy — Start with defaults (./rag_docs, OpenAI-compatible API)
+  • agent-cli rag-proxy --docs-folder ~/notes — Index your notes folder
+
+ How it works:
+
+  1 Documents in --docs-folder are chunked, embedded, and stored in ChromaDB
+  2 A file watcher auto-reindexes when files change
+  3 Chat requests trigger a semantic search for relevant chunks
+  4 Retrieved context is injected into the prompt before forwarding to the LLM
+  5 Responses include a rag_sources field listing which documents were used
+
+ Supported file formats:
 
- This server watches a folder for documents, indexes them, and provides an
- OpenAI-compatible API that proxies requests to a backend LLM (like llama.cpp), injecting
- relevant context from the documents.
+ Text: .txt, .md, .json, .py, .js, .ts, .yaml, .toml, .rst, etc. Rich documents (via
+ MarkItDown): .pdf, .docx, .pptx, .xlsx, .html, .csv
+
+ API endpoints:
+
+  • POST /v1/chat/completions — Main chat endpoint (OpenAI-compatible)
+  • GET /health — Health check with configuration info
+  • GET /files — List indexed files with chunk counts
+  • POST /reindex — Trigger manual reindex
+  • All other paths are proxied to the LLM backend
+
+ Per-request overrides (in JSON body):
+
+  • rag_top_k: Override --limit for this request
+  • rag_enable_tools: Override --rag-tools for this request
 
 ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
 │ --help  -h        Show this message and exit.                                          │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ RAG Configuration ────────────────────────────────────────────────────────────────────╮
-│ --docs-folder                      PATH     Folder to watch for documents              │
+│ --docs-folder                      PATH     Folder to watch for documents. Files are   │
+│                                             auto-indexed on startup and when changed.  │
+│                                             Must not overlap with --chroma-path.       │
 │                                             [default: ./rag_docs]                      │
-│ --chroma-path                      PATH     Path to ChromaDB persistence directory     │
+│ --chroma-path                      PATH     ChromaDB storage directory for vector      │
+│                                             embeddings. Must be separate from          │
+│                                             --docs-folder to avoid indexing database   │
+│                                             files.                                     │
 │                                             [default: ./rag_db]                        │
 │ --limit                            INTEGER  Number of document chunks to retrieve per  │
-│                                             query.                                     │
+│                                             query. Higher values provide more context  │
+│                                             but use more tokens. Can be overridden     │
+│                                             per-request via rag_top_k in the JSON      │
+│                                             body.                                      │
 │                                             [default: 3]                               │
-│ --rag-tools      --no-rag-tools             Allow agent to fetch full documents when   │
-│                                             snippets are insufficient.                 │
+│ --rag-tools      --no-rag-tools             Enable read_full_document() tool so the    │
+│                                             LLM can request full document content when │
+│                                             retrieved snippets are insufficient. Can   │
+│                                             be overridden per-request via              │
+│                                             rag_enable_tools in the JSON body.         │
 │                                             [default: rag-tools]                       │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮
@@ -1822,7 +2066,8 @@ uv tool install "agent-cli[vad]" -p 3.13
 ╭─ Server Configuration ─────────────────────────────────────────────────────────────────╮
 │ --host        TEXT     Host/IP to bind API servers to.                                 │
 │                        [default: 0.0.0.0]                                              │
-│ --port        INTEGER  Port to bind to                                                 │
+│ --port        INTEGER  Port for the RAG proxy API (e.g.,                               │
+│                        http://localhost:8000/v1/chat/completions).                     │
 │                        [default: 8000]                                                 │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ General Options ──────────────────────────────────────────────────────────────────────╮
@@ -1912,41 +2157,61 @@ The `memory proxy` command is the core feature—a middleware server that gives
   5 Extracts new facts from the conversation in the background and updates the long-term
     memory store (including handling contradictions).
 
- Use this to give "long-term memory" to any OpenAI-compatible application. Point your
- client's base URL to http://localhost:8100/v1.
+ Example:
+
+
+  # Start proxy pointing to local Ollama
+  agent-cli memory proxy --openai-base-url http://localhost:11434/v1
+
+  # Then configure your chat client to use http://localhost:8100/v1
+  # as its OpenAI base URL. All requests flow through the memory proxy.
+
+
+ Per-request overrides: Clients can include these fields in the request body: memory_id
+ (conversation ID), memory_top_k, memory_recency_weight, memory_score_threshold.
 
 ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
 │ --help  -h        Show this message and exit.                                          │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Memory Configuration ─────────────────────────────────────────────────────────────────╮
-│ --memory-path                               PATH     Path to the memory store (files + │
-│                                                      derived vector index).            │
+│ --memory-path                               PATH     Directory for memory storage.     │
+│                                                      Contains entries/ (Markdown       │
+│                                                      files) and chroma/ (vector        │
+│                                                      index). Created automatically if  │
+│                                                      it doesn't exist.                 │
 │                                                      [default: ./memory_db]            │
-│ --default-top-k                             INTEGER  Number of memory entries to       │
-│                                                      retrieve per query.               │
+│ --default-top-k                             INTEGER  Number of relevant memories to    │
+│                                                      inject into each request. Higher  │
+│                                                      values provide more context but   │
+│                                                      increase token usage.             │
 │                                                      [default: 5]                      │
-│ --max-entries                               INTEGER  Maximum stored memory entries per │
-│                                                      conversation (excluding summary). │
+│ --max-entries                               INTEGER  Maximum entries per conversation  │
+│                                                      before oldest are evicted.        │
+│                                                      Summaries are preserved           │
+│                                                      separately.                       │
 │                                                      [default: 500]                    │
 │ --mmr-lambda                                FLOAT    MMR lambda (0-1): higher favors   │
 │                                                      relevance, lower favors           │
 │                                                      diversity.                        │
 │                                                      [default: 0.7]                    │
-│ --recency-weight                            FLOAT    Recency score weight (0.0-1.0).   │
-│                                                      Controls freshness vs. relevance. │
-│                                                      Default 0.2 (20% recency, 80%     │
-│                                                      semantic relevance).              │
+│ --recency-weight                            FLOAT    Weight for recency vs semantic    │
+│                                                      relevance (0.0-1.0). At 0.2: 20%  │
+│                                                      recency, 80% semantic similarity. │
 │                                                      [default: 0.2]                    │
 │ --score-threshold                           FLOAT    Minimum semantic relevance        │
 │                                                      threshold (0.0-1.0). Memories     │
 │                                                      below this score are discarded to │
 │                                                      reduce noise.                     │
 │                                                      [default: 0.35]                   │
-│ --summarization      --no-summarization              Enable automatic fact extraction  │
-│                                                      and summaries.                    │
+│ --summarization      --no-summarization              Extract facts and generate        │
+│                                                      summaries after each turn using   │
+│                                                      the LLM. Disable to only store    │
+│                                                      raw conversation turns.           │
 │                                                      [default: summarization]          │
-│ --git-versioning     --no-git-versioning             Enable automatic git commit of    │
-│                                                      memory changes.                   │
+│ --git-versioning     --no-git-versioning             Auto-commit memory changes to     │
+│                                                      git. Initializes a repo in        │
+│                                                      --memory-path if needed. Provides │
+│                                                      full history of memory evolution. │
 │                                                      [default: git-versioning]         │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮
@@ -2059,12 +2324,16 @@ agent-cli memory add -c work "Project deadline is Friday"
 │                                                     for stdin. Supports JSON array,    │
 │                                                     JSON object with 'memories' key,   │
 │                                                     or plain text (one per line).      │
-│ --conversation-id  -c                         TEXT  Conversation ID to add memories    │
-│                                                     to.                                │
+│ --conversation-id  -c                         TEXT  Conversation namespace for these   │
+│                                                     memories. Memories are retrieved   │
+│                                                     per-conversation unless shared     │
+│                                                     globally.                          │
 │                                                     [default: default]                 │
-│ --memory-path                                 PATH  Path to the memory store.          │
+│ --memory-path                                 PATH  Directory for memory storage (same │
+│                                                     as memory proxy --memory-path).    │
 │                                                     [default: ./memory_db]             │
-│ --git-versioning       --no-git-versioning          Commit changes to git.             │
+│ --git-versioning       --no-git-versioning          Auto-commit changes to git for     │
+│                                                     version history.                   │
 │                                                     [default: git-versioning]          │
 │ --help             -h                               Show this message and exit.        │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯