From 7a7fe08ebdab7a544b6d25f32171753c5ce094df Mon Sep 17 00:00:00 2001
From: Cu7ious <garkusha.sergio@gmail.com>
Date: Fri, 1 May 2026 19:16:26 -0700
Subject: [PATCH 1/2] feat(setup): add --help/-h flag with synopsis and usage
 examples

---
 setup.sh | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/setup.sh b/setup.sh
index bad76a2..ae02ced 100755
--- a/setup.sh
+++ b/setup.sh
@@ -12,6 +12,41 @@
 # 7. Verifies everything works
 set -euo pipefail
 
+usage() {
+  cat <<EOF
+Usage: ./setup.sh [OPTIONS]
+
+Set up OpenExp — Q-learning memory for Claude Code.
+
+Steps performed:
+  1. Check prerequisites (Python 3.11+, Docker, jq, Claude Code CLI)
+  2. Create Python venv and install dependencies
+  3. Start Qdrant vector database (Docker)
+  4. Create Qdrant collection
+  5. Copy .env.example → .env
+  6. Register MCP server + hooks in Claude Code settings
+  7. Verify installation
+
+Options:
+  -h, --help    Show this help message and exit
+
+Environment variables:
+  QDRANT_API_KEY    Optional. Passed to Qdrant container for auth.
+
+After setup:
+  claude                                         Start Claude Code (hooks activate automatically)
+  .venv/bin/python3 -m openexp.cli ingest        Ingest observations into Qdrant
+  .venv/bin/python3 -m openexp.cli search -q ''  Search memories
+  .venv/bin/python3 -m openexp.cli stats         Show memory stats
+EOF
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    -h|--help) usage; exit 0 ;;
+  esac
+done
+
 OPENEXP_DIR="$(cd "$(dirname "$0")" && pwd)"
 CLAUDE_SETTINGS="$HOME/.claude/settings.local.json"
 COLLECTION="openexp_memories"

From bd7428b2668f516b92f8b2770f17a4f50cbd426d Mon Sep 17 00:00:00 2001
From: Cu7ious <garkusha.sergio@gmail.com>
Date: Fri, 1 May 2026 22:13:43 -0700
Subject: [PATCH 2/2] docs(setup): expand --help with env vars, hooks, MCP
 tools, all CLI commands

Drop stale Q-learning framing. Add missing env vars, hook descriptions,
MCP tool list, experience profiles, and per-project override note.
---
 setup.sh | 44 ++++++++++++++++++++++++++++++++++++--------
 1 file changed, 36 insertions(+), 8 deletions(-)

diff --git a/setup.sh b/setup.sh
index 7ef612a..8cc7d43 100755
--- a/setup.sh
+++ b/setup.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
-# OpenExp Setup — Q-learning memory for Claude Code
-# Usage: ./setup.sh
+# OpenExp Setup — persistent memory layer for Claude Code
+# Usage: ./setup.sh [-h|--help]
 #
 # This script:
 # 1. Creates Python venv + installs deps
@@ -16,7 +16,7 @@ usage() {
   cat <<EOF
 Usage: ./setup.sh [OPTIONS]
 
-Set up OpenExp — Q-learning memory for Claude Code.
+Set up OpenExp — persistent memory layer for Claude Code.
 
 Steps performed:
   1. Check prerequisites (Python 3.11+, Docker, jq, Claude Code CLI)
@@ -31,13 +31,41 @@ Options:
   -h, --help    Show this help message and exit
 
 Environment variables:
-  QDRANT_API_KEY    Optional. Passed to Qdrant container for auth.
+  QDRANT_API_KEY          Optional. Auth key passed to Qdrant container.
+  OPENEXP_DATA_DIR        Override default data directory (~/.openexp/data).
+  OPENEXP_EXPERIENCE      Active experience profile (default: "default").
+  OPENEXP_COLLECTION      Qdrant collection name (default: "openexp_memories").
+
+Hooks registered (auto-activate on every claude session):
+  SessionStart       Inject top-10 relevant memories as context
+  UserPromptSubmit   Recall top-5 memories per message; auto-detect experience
+  PostToolUse        Capture observations from Write/Edit/Bash tool calls
+  SessionEnd         Extract decisions + ingest full transcript (background)
+
+MCP tools available inside Claude Code:
+  search_memory      Hybrid vector+BM25 search with Q-reranking
+  add_memory         Store a memory with embedding
+  log_prediction     Record a prediction grounded to an experience pack step
+  log_outcome        Resolve a prediction with observed facts (active feedback loop)
+  memory_stats       System health: point counts, pending predictions
 
 After setup:
-  claude                                         Start Claude Code (hooks activate automatically)
-  .venv/bin/python3 -m openexp.cli ingest        Ingest observations into Qdrant
-  .venv/bin/python3 -m openexp.cli search -q ''  Search memories
-  .venv/bin/python3 -m openexp.cli stats         Show memory stats
+  claude                                                   Start Claude Code
+  openexp search -q 'your query'                          Search memories
+  openexp ingest                                           Ingest past Claude sessions
+  openexp stats                                            Memory system health
+  openexp experience list                                  List experience profiles
+  openexp experience create                                Interactive experience wizard
+  openexp retrospective daily                              Run daily analysis
+  openexp viz                                              Generate HTML dashboard
+  openexp compact                                          Merge similar memories
+
+Experience profiles (auto-detected from project keywords):
+  default     Software engineering (commits, PRs, deploys)
+  sales       Sales & outreach (leads, proposals, deals)
+  dealflow    Deal pipeline (NDA, invoice, payment)
+
+Per-project experience override: add .openexp.yaml to project root.
 EOF
 }