@lavralabs/lavra 0.7.0

package/plugins/lavra/tests/build-index.sh

@@ -0,0 +1,116 @@
+#!/bin/bash
+#
+# Build SQLite FTS5 index from knowledge.jsonl
+#
+# Usage: build-index.sh /path/to/knowledge.jsonl /path/to/output.db
+#
+# Creates a SQLite database with:
+# - knowledge table with all fields
+# - knowledge_fts FTS5 virtual table for full-text search
+#
+
+KNOWLEDGE_FILE="$1"
+DB_FILE="$2"
+
+if [[ -z "$KNOWLEDGE_FILE" ]] || [[ -z "$DB_FILE" ]]; then
+  echo "Usage: build-index.sh /path/to/knowledge.jsonl /path/to/output.db" >&2
+  exit 1
+fi
+
+if [[ ! -f "$KNOWLEDGE_FILE" ]]; then
+  echo "File not found: $KNOWLEDGE_FILE" >&2
+  exit 1
+fi
+
+if ! command -v python3 &>/dev/null; then
+  echo "Required: python3" >&2
+  exit 1
+fi
+
+# Remove existing db to start fresh
+rm -f "$DB_FILE"
+
+# Use Python for proper parameterized SQL (no escaping issues)
+python3 - "$KNOWLEDGE_FILE" "$DB_FILE" <<'PYEOF'
+import json
+import sqlite3
+import sys
+
+knowledge_file = sys.argv[1]
+db_file = sys.argv[2]
+
+conn = sqlite3.connect(db_file)
+cur = conn.cursor()
+
+cur.executescript("""
+CREATE TABLE knowledge(
+  key TEXT PRIMARY KEY,
+  type TEXT,
+  content TEXT,
+  source TEXT,
+  tags_text TEXT,
+  ts INTEGER,
+  bead TEXT
+);
+
+CREATE VIRTUAL TABLE knowledge_fts USING fts5(
+  content, tags_text, type, key,
+  content=knowledge,
+  content_rowid=rowid,
+  tokenize='porter unicode61'
+);
+
+CREATE TRIGGER knowledge_ai AFTER INSERT ON knowledge BEGIN
+  INSERT INTO knowledge_fts(rowid, content, tags_text, type, key)
+  VALUES (new.rowid, new.content, new.tags_text, new.type, new.key);
+END;
+""")
+
+inserted = 0
+skipped = 0
+
+with open(knowledge_file, encoding="utf-8") as f:
+    for line in f:
+        line = line.strip()
+        if not line:
+            continue
+
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError:
+            skipped += 1
+            continue
+
+        key = entry.get("key", "")
+        if not key:
+            skipped += 1
+            continue
+
+        tags = entry.get("tags", [])
+        tags_text = " ".join(tags) if isinstance(tags, list) else str(tags)
+
+        try:
+            cur.execute(
+                "INSERT OR IGNORE INTO knowledge(key, type, content, source, tags_text, ts, bead) VALUES(?, ?, ?, ?, ?, ?, ?)",
+                (
+                    key,
+                    entry.get("type", ""),
+                    entry.get("content", ""),
+                    entry.get("source", ""),
+                    tags_text,
+                    entry.get("ts", 0),
+                    entry.get("bead", ""),
+                ),
+            )
+            inserted += 1
+        except Exception as e:
+            print(f"  Warning: skipped {key}: {e}", file=sys.stderr)
+            skipped += 1
+
+conn.commit()
+conn.close()
+
+print(f"Built FTS5 index: {db_file}")
+print(f"  Entries indexed: {inserted}")
+print(f"  Entries skipped: {skipped}")
+PYEOF

package/plugins/lavra/tests/recall-bench.sh

@@ -0,0 +1,224 @@
+#!/bin/bash
+#
+# Memory Recall Benchmark - compare grep vs FTS5 search quality
+#
+# Usage: recall-bench.sh /path/to/knowledge.jsonl
+#
+# Runs curated test queries against both grep and FTS5 backends,
+# scores results against human-judged relevance labels, and outputs
+# a comparison report with precision@5, recall@5, and MRR.
+#
+
+set -euo pipefail
+
+KNOWLEDGE_FILE="$1"
+
+if [[ -z "$KNOWLEDGE_FILE" ]]; then
+  echo "Usage: recall-bench.sh /path/to/knowledge.jsonl" >&2
+  exit 1
+fi
+
+if [[ ! -f "$KNOWLEDGE_FILE" ]]; then
+  echo "File not found: $KNOWLEDGE_FILE" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TEST_QUERIES="$SCRIPT_DIR/test-queries.jsonl"
+GREP_SEARCH="$SCRIPT_DIR/search-grep.sh"
+FTS5_SEARCH="$SCRIPT_DIR/search-fts5.sh"
+BUILD_INDEX="$SCRIPT_DIR/build-index.sh"
+
+TOP_K=5
+DB_FILE=$(mktemp /tmp/recall-bench-XXXXXX.db)
+trap 'rm -f "$DB_FILE"' EXIT
+
+# Verify dependencies
+for FILE in "$TEST_QUERIES" "$GREP_SEARCH" "$FTS5_SEARCH" "$BUILD_INDEX"; do
+  if [[ ! -f "$FILE" ]]; then
+    echo "Missing: $FILE" >&2
+    exit 1
+  fi
+done
+
+for CMD in sqlite3 jq; do
+  if ! command -v "$CMD" &>/dev/null; then
+    echo "Required: $CMD" >&2
+    exit 1
+  fi
+done
+
+# Build FTS5 index
+echo "Building FTS5 index..."
+bash "$BUILD_INDEX" "$KNOWLEDGE_FILE" "$DB_FILE"
+echo ""
+
+# Scoring functions using awk for floating point
+calc_precision() {
+  local hits="$1"
+  local returned="$2"
+  if [[ "$returned" -eq 0 ]]; then
+    echo "0.000"
+  else
+    awk "BEGIN { printf \"%.3f\", $hits / $returned }"
+  fi
+}
+
+calc_recall() {
+  local hits="$1"
+  local total_relevant="$2"
+  if [[ "$total_relevant" -eq 0 ]]; then
+    echo "1.000"
+  else
+    awk "BEGIN { printf \"%.3f\", $hits / $total_relevant }"
+  fi
+}
+
+calc_rr() {
+  # Reciprocal rank: 1/rank of first relevant result, 0 if none
+  local rank="$1"
+  if [[ "$rank" -eq 0 ]]; then
+    echo "0.000"
+  else
+    awk "BEGIN { printf \"%.3f\", 1.0 / $rank }"
+  fi
+}
+
+# Run benchmark
+TOTAL_QUERIES=0
+GREP_P_SUM=0
+GREP_R_SUM=0
+GREP_RR_SUM=0
+FTS5_P_SUM=0
+FTS5_R_SUM=0
+FTS5_RR_SUM=0
+
+# Header
+printf "%-45s | %-17s | %-17s | %-17s\n" "" "Precision@$TOP_K" "Recall@$TOP_K" "MRR"
+printf "%-45s | %-8s %-8s | %-8s %-8s | %-8s %-8s\n" "Query" "grep" "fts5" "grep" "fts5" "grep" "fts5"
+printf "%s\n" "$(printf '%.0s-' {1..120})"
+
+while IFS= read -r QUERY_LINE; do
+  [[ -z "$QUERY_LINE" ]] && continue
+
+  QUERY=$(echo "$QUERY_LINE" | jq -r '.query')
+  RELEVANT_KEYS=$(echo "$QUERY_LINE" | jq -r '.relevant_keys[]')
+  TOTAL_RELEVANT=$(echo "$QUERY_LINE" | jq -r '.relevant_keys | length')
+
+  # Run grep search
+  GREP_RESULTS=$(bash "$GREP_SEARCH" "$QUERY" "$KNOWLEDGE_FILE" "$TOP_K" 2>/dev/null || true)
+
+  # Run FTS5 search
+  FTS5_RESULTS=$(bash "$FTS5_SEARCH" "$QUERY" "$DB_FILE" "$TOP_K" 2>/dev/null || true)
+
+  # Score grep results
+  GREP_HITS=0
+  GREP_FIRST_RANK=0
+  GREP_RANK=0
+  GREP_RETURNED=0
+
+  while IFS= read -r RESULT_KEY; do
+    [[ -z "$RESULT_KEY" ]] && continue
+    GREP_RETURNED=$((GREP_RETURNED + 1))
+    GREP_RANK=$((GREP_RANK + 1))
+
+    IS_RELEVANT=false
+    while IFS= read -r REL_KEY; do
+      if [[ "$RESULT_KEY" == "$REL_KEY" ]]; then
+        IS_RELEVANT=true
+        break
+      fi
+    done <<< "$RELEVANT_KEYS"
+
+    if $IS_RELEVANT; then
+      GREP_HITS=$((GREP_HITS + 1))
+      if [[ "$GREP_FIRST_RANK" -eq 0 ]]; then
+        GREP_FIRST_RANK=$GREP_RANK
+      fi
+    fi
+  done <<< "$GREP_RESULTS"
+
+  # Score FTS5 results
+  FTS5_HITS=0
+  FTS5_FIRST_RANK=0
+  FTS5_RANK=0
+  FTS5_RETURNED=0
+
+  while IFS= read -r RESULT_KEY; do
+    [[ -z "$RESULT_KEY" ]] && continue
+    FTS5_RETURNED=$((FTS5_RETURNED + 1))
+    FTS5_RANK=$((FTS5_RANK + 1))
+
+    IS_RELEVANT=false
+    while IFS= read -r REL_KEY; do
+      if [[ "$RESULT_KEY" == "$REL_KEY" ]]; then
+        IS_RELEVANT=true
+        break
+      fi
+    done <<< "$RELEVANT_KEYS"
+
+    if $IS_RELEVANT; then
+      FTS5_HITS=$((FTS5_HITS + 1))
+      if [[ "$FTS5_FIRST_RANK" -eq 0 ]]; then
+        FTS5_FIRST_RANK=$FTS5_RANK
+      fi
+    fi
+  done <<< "$FTS5_RESULTS"
+
+  # Compute metrics
+  G_P=$(calc_precision $GREP_HITS $GREP_RETURNED)
+  G_R=$(calc_recall $GREP_HITS $TOTAL_RELEVANT)
+  G_RR=$(calc_rr $GREP_FIRST_RANK)
+
+  F_P=$(calc_precision $FTS5_HITS $FTS5_RETURNED)
+  F_R=$(calc_recall $FTS5_HITS $TOTAL_RELEVANT)
+  F_RR=$(calc_rr $FTS5_FIRST_RANK)
+
+  # Print row
+  QUERY_DISPLAY="$QUERY"
+  if [[ ${#QUERY_DISPLAY} -gt 43 ]]; then
+    QUERY_DISPLAY="${QUERY_DISPLAY:0:40}..."
+  fi
+  printf "%-45s | %-8s %-8s | %-8s %-8s | %-8s %-8s\n" "$QUERY_DISPLAY" "$G_P" "$F_P" "$G_R" "$F_R" "$G_RR" "$F_RR"
+
+  # Accumulate for averages
+  GREP_P_SUM=$(awk "BEGIN { print $GREP_P_SUM + $G_P }")
+  GREP_R_SUM=$(awk "BEGIN { print $GREP_R_SUM + $G_R }")
+  GREP_RR_SUM=$(awk "BEGIN { print $GREP_RR_SUM + $G_RR }")
+  FTS5_P_SUM=$(awk "BEGIN { print $FTS5_P_SUM + $F_P }")
+  FTS5_R_SUM=$(awk "BEGIN { print $FTS5_R_SUM + $F_R }")
+  FTS5_RR_SUM=$(awk "BEGIN { print $FTS5_RR_SUM + $F_RR }")
+  TOTAL_QUERIES=$((TOTAL_QUERIES + 1))
+
+done < "$TEST_QUERIES"
+
+# Summary
+printf "%s\n" "$(printf '%.0s-' {1..120})"
+
+if [[ $TOTAL_QUERIES -gt 0 ]]; then
+  AVG_GP=$(awk "BEGIN { printf \"%.3f\", $GREP_P_SUM / $TOTAL_QUERIES }")
+  AVG_GR=$(awk "BEGIN { printf \"%.3f\", $GREP_R_SUM / $TOTAL_QUERIES }")
+  AVG_GRR=$(awk "BEGIN { printf \"%.3f\", $GREP_RR_SUM / $TOTAL_QUERIES }")
+  AVG_FP=$(awk "BEGIN { printf \"%.3f\", $FTS5_P_SUM / $TOTAL_QUERIES }")
+  AVG_FR=$(awk "BEGIN { printf \"%.3f\", $FTS5_R_SUM / $TOTAL_QUERIES }")
+  AVG_FRR=$(awk "BEGIN { printf \"%.3f\", $FTS5_RR_SUM / $TOTAL_QUERIES }")
+
+  printf "%-45s | %-8s %-8s | %-8s %-8s | %-8s %-8s\n" "AVERAGE ($TOTAL_QUERIES queries)" "$AVG_GP" "$AVG_FP" "$AVG_GR" "$AVG_FR" "$AVG_GRR" "$AVG_FRR"
+
+  echo ""
+  echo "Legend:"
+  echo "  Precision@$TOP_K = relevant results / returned results (higher = less noise)"
+  echo "  Recall@$TOP_K    = relevant results / total relevant (higher = more complete)"
+  echo "  MRR           = 1/rank of first relevant result (higher = faster to find)"
+
+  # Delta summary
+  DELTA_P=$(awk "BEGIN { printf \"%+.3f\", $AVG_FP - $AVG_GP }")
+  DELTA_R=$(awk "BEGIN { printf \"%+.3f\", $AVG_FR - $AVG_GR }")
+  DELTA_RR=$(awk "BEGIN { printf \"%+.3f\", $AVG_FRR - $AVG_GRR }")
+
+  echo ""
+  echo "FTS5 vs grep delta:"
+  echo "  Precision: $DELTA_P"
+  echo "  Recall:    $DELTA_R"
+  echo "  MRR:       $DELTA_RR"
+fi

package/plugins/lavra/tests/search-fts5.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+#
+# FTS5 search backend - SQLite full-text search with BM25 ranking
+#
+# Usage: search-fts5.sh "query string" /path/to/knowledge.db [N]
+#
+# Runs FTS5 MATCH query with BM25 ranking, returns top N keys ordered by relevance.
+#
+
+QUERY="$1"
+DB_FILE="$2"
+TOP_N="${3:-5}"
+
+if [[ -z "$QUERY" ]] || [[ -z "$DB_FILE" ]]; then
+  echo "Usage: search-fts5.sh \"query\" /path/to/knowledge.db [N]" >&2
+  exit 1
+fi
+
+if [[ ! -f "$DB_FILE" ]]; then
+  echo "Database not found: $DB_FILE" >&2
+  exit 1
+fi
+
+# Use Python for proper FTS5 query construction and parameterized execution
+python3 - "$QUERY" "$DB_FILE" "$TOP_N" <<'PYEOF'
+import sqlite3
+import re
+import sys
+
+query = sys.argv[1]
+db_file = sys.argv[2]
+top_n = int(sys.argv[3])
+
+# Extract terms (2+ alphanumeric chars)
+terms = re.findall(r'\b[a-zA-Z0-9_.]{2,}\b', query.lower())
+
+if not terms:
+    sys.exit(0)
+
+# Build FTS5 query: join with OR
+# Quote each term to handle special chars
+fts_query = " OR ".join(f'"{t}"' for t in terms)
+
+conn = sqlite3.connect(db_file)
+cur = conn.cursor()
+
+# BM25 weights: content=10, tags_text=5, type=2, key=1
+try:
+    cur.execute("""
+        SELECT k.key
+        FROM knowledge_fts fts
+        JOIN knowledge k ON k.rowid = fts.rowid
+        WHERE knowledge_fts MATCH ?
+        ORDER BY bm25(knowledge_fts, -10.0, -5.0, -2.0, -1.0)
+        LIMIT ?
+    """, (fts_query, top_n))
+
+    for row in cur.fetchall():
+        print(row[0])
+
+except Exception:
+    pass
+
+conn.close()
+PYEOF

package/plugins/lavra/tests/search-grep.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+#
+# Grep search backend - mirrors the current recall.sh/auto-recall.sh logic
+#
+# Usage: search-grep.sh "query string" /path/to/knowledge.jsonl [N]
+#
+# Splits query into terms, greps each, deduplicates by key, returns top N keys.
+#
+
+QUERY="$1"
+KNOWLEDGE_FILE="$2"
+TOP_N="${3:-5}"
+
+if [[ -z "$QUERY" ]] || [[ -z "$KNOWLEDGE_FILE" ]]; then
+  echo "Usage: search-grep.sh \"query\" /path/to/knowledge.jsonl [N]" >&2
+  exit 1
+fi
+
+if [[ ! -f "$KNOWLEDGE_FILE" ]]; then
+  echo "File not found: $KNOWLEDGE_FILE" >&2
+  exit 1
+fi
+
+# Split query into terms (matching auto-recall.sh approach)
+TERMS=$(echo "$QUERY" | tr '[:upper:]' '[:lower:]' | grep -oE '\b[a-zA-Z0-9_.]{2,}\b')
+
+SEEN_KEYS=""
+RESULT_KEYS=""
+COUNT=0
+
+for TERM in $TERMS; do
+  [[ $COUNT -ge $TOP_N ]] && break
+
+  # grep -i for case-insensitive matching (mirrors recall.sh line 96)
+  MATCHES=$(grep -i "$TERM" "$KNOWLEDGE_FILE" 2>/dev/null)
+
+  while IFS= read -r LINE; do
+    [[ -z "$LINE" ]] && continue
+    [[ $COUNT -ge $TOP_N ]] && break
+
+    KEY=$(echo "$LINE" | jq -r '.key // empty' 2>/dev/null)
+    [[ -z "$KEY" ]] && continue
+
+    # Deduplicate
+    if [[ "$SEEN_KEYS" != *"|$KEY|"* ]]; then
+      SEEN_KEYS="${SEEN_KEYS}|${KEY}|"
+      RESULT_KEYS="${RESULT_KEYS}${KEY}"$'\n'
+      COUNT=$((COUNT + 1))
+    fi
+  done <<< "$MATCHES"
+done
+
+# Output keys, one per line, trimming trailing newline
+echo "$RESULT_KEYS" | sed '/^$/d'

package/plugins/lavra/tests/test-queries.jsonl

@@ -0,0 +1,25 @@
+{"query": "ViaCEP", "description": "Exact match - find entries about ViaCEP API", "relevant_keys": ["learned-fact-viacep-api-returns-400-bad-request-when-street-city-co", "fact-brasilapi-open-cep-service-does-not-return-ibge-city-codes"]}
+{"query": "E0014", "description": "Exact match - government NFSe error code", "relevant_keys": ["learned-government-nfse-api-e0014-rejects-any-resubmission-of-same-d", "fact-nfse-government-api-error-e0014-rejects-any-dps-with-same-se"]}
+{"query": "pynfse-nacional", "description": "Exact match - the NFSe library name", "relevant_keys": ["learned-pynfse-nacional-0-4-0-had-bug-xml-element-subst1-should-b", "decision-client-code-medsimples-generates-dps-numero-not-the-libra"]}
+{"query": "db commit RLS reset", "description": "Partial terms - find entries about RLS context lost after commit", "relevant_keys": ["investigation-postgresql-set-session-variables-app-is-superadmin-app-org", "pattern-whenever-a-background-task-or-service-method-calls-db-commit", "learned-rls-session-variables-app-org-id-app-is-superadmin-reset", "pattern-in-substitute-nfse-use-db-flush-instead-of-db-commit-be", "pattern-in-routers-that-create-records-and-need-to-re-query-with-rel"]}
+{"query": "payment methods Brazil", "description": "Partial terms - find Stripe/PIX/Boleto payment entries", "relevant_keys": ["decision-payment-method-priority-for-brazil-implementation-1-primary", "fact-stripe-connect-brazil-regulatory-restrictions-platforms-ou", "learned-stripe-payment-methods-in-brazil-require-proper-portuguese-a", "investigation-iof-tax-currency-considerations-iof-imposto-sobre-opera", "pattern-python-sdk-paymentintent-implementation-create-paymentinte"]}
+{"query": "how to avoid data loss in phone migration", "description": "Conceptual - migration safety for phone number changes", "relevant_keys": ["fact-common-migration-pitfalls-1-data-loss-from-aggressive-no", "pattern-migration-from-single-field-to-country-code-split-1-add", "learned-always-analyze-production-data-before-writing-migration-stra", "decision-created-phone-migration-strategy-md-and-pre-migration-phone", "investigation-production-database-analysis-completed-results-1-country"]}
+{"query": "query returns null after saving", "description": "Conceptual - cache/flush issues after database writes", "relevant_keys": ["investigation-root-cause-is-missing-clearapicache-call-after-cachedaxios", "pattern-in-routers-that-create-records-and-need-to-re-query-with-rel", "investigation-post-api-visits-rxvisits-returned-200-but-pydantic-serializ", "learned-pydantic-with-from-attributes-true-only-serializes-fields-ex"]}
+{"query": "Stripe Brazil restrictions", "description": "Multi-word - Stripe platform limitations in Brazil", "relevant_keys": ["fact-stripe-connect-brazil-regulatory-restrictions-platforms-ou", "decision-payment-method-priority-for-brazil-implementation-1-primary", "learned-stripe-payment-methods-in-brazil-require-proper-portuguese-a", "investigation-iof-tax-currency-considerations-iof-imposto-sobre-opera"]}
+{"query": "phone number validation", "description": "Multi-word - phone validation across frontend and backend", "relevant_keys": ["learned-backend-phone-validation-tests-now-comprehensive-added-tes", "learned-phoneinput-accessibility-requires-consistent-errorid-across", "learned-pydantic-field-validator-with-validationinfo-allows-accessin", "investigation-e-164-format-is-itu-t-international-phone-standard-structur", "fact-brazil-55-has-special-validation-rules-for-whatsapp-braz", "decision-added-phone-number-max-length-validation-in-format-phone-e16", "pattern-best-practices-for-e-164-normalization-before-whatsapp-api-c"]}
+{"query": "RLS", "description": "Abbreviation - row level security entries", "relevant_keys": ["investigation-postgresql-set-session-variables-app-is-superadmin-app-org", "pattern-whenever-a-background-task-or-service-method-calls-db-commit", "learned-rls-session-variables-app-org-id-app-is-superadmin-reset", "fact-rls-policy-on-rx-visits-rx-visits-tenant-isolation-checks", "fact-rls-context-is-set-by-require-clinical-access-via-get-curren", "pattern-in-substitute-nfse-use-db-flush-instead-of-db-commit-be"]}
+{"query": "NFSe fiscal invoice", "description": "Abbreviation + related terms - fiscal document issuance", "relevant_keys": ["investigation-nfse-error-e0240-cep-nao-existe-ou-nao-pertence-ao-municip", "learned-government-nfse-api-e0014-rejects-any-resubmission-of-same-d", "fact-nfse-substitution-has-35-day-limit-calculated-using-brazilia", "fact-nfse-government-api-error-e0014-rejects-any-dps-with-same-se", "fact-nfse-service-description-now-includes-visit-date-in-format", "decision-allow-retry-of-stuck-processing-issuances-by-removing-the-ha", "learned-pynfse-nacional-0-4-0-had-bug-xml-element-subst1-should-b"]}
+{"query": "cursor pointer text selection", "description": "UI pattern - specific CSS interaction issue", "relevant_keys": ["pattern-cursor-pointer-on-tablerow-elements-prevents-text-selection"]}
+{"query": "Portuguese accents i18n", "description": "UI pattern - accent/internationalization issues", "relevant_keys": ["pattern-portuguese-accents-missing-in-several-ui-strings-check-for", "learned-stripe-payment-methods-in-brazil-require-proper-portuguese-a"]}
+{"query": "webhook secret authentication", "description": "Cross-domain - service-to-service auth", "relevant_keys": ["learned-cognitest-assignment-uses-x-webhook-secret-header-for-servic", "decision-unify-on-one-shared-secret-cognitest-webhook-secret-with-o", "pattern-service-to-service-webhook-pattern-graceful-degradation-on", "pattern-service-to-service-endpoints-post-api-cognitest-resource"]}
+{"query": "security phone masking XSS", "description": "Cross-domain - security across different features", "relevant_keys": ["fact-security-considerations-phone-numbers-are-injection-vector", "learned-phone-masking-implementation-verified-with-unit-tests-all-r", "learned-security-through-defense-in-depth-is-more-practical-than-sin", "pattern-pii-in-audit-logs-requires-balancing-privacy-with-operationa"]}
+{"query": "Pydantic serialization validation", "description": "Technical - Pydantic-specific issues", "relevant_keys": ["learned-pydantic-with-from-attributes-true-only-serializes-fields-ex", "investigation-post-api-visits-rxvisits-returned-200-but-pydantic-serializ", "learned-pydantic-field-validator-with-validationinfo-allows-accessin", "learned-pydantic-v2-field-validator-order-can-be-controlled-with-mod"]}
+{"query": "flush instead of commit", "description": "Specific pattern - db.flush vs db.commit", "relevant_keys": ["pattern-in-substitute-nfse-use-db-flush-instead-of-db-commit-be", "pattern-in-routers-that-create-records-and-need-to-re-query-with-rel", "pattern-atomic-onboarding-transaction-pattern-use-db-flush-betwe", "learned-rls-session-variables-app-org-id-app-is-superadmin-reset"]}
+{"query": "GDPR LGPD data retention", "description": "Compliance - privacy regulation entries", "relevant_keys": ["learned-gdpr-lgpd-medical-records-deletion-requires-1-response-wit", "fact-brazilian-lgpd-requires-20-year-minimum-retention-for-medica", "fact-gdpr-article-20-requires-data-portability-in-structured-com", "pattern-gdpr-compliance-requires-multi-phase-implementation-phase-1", "pattern-gdpr-audit-logs-must-contain-metadata-without-pii-log-requ", "investigation-no-deletion-endpoints-exist-currently-patients-and-doctors"]}
+{"query": "CEP address lookup", "description": "Feature-specific - postal code validation", "relevant_keys": ["learned-fact-viacep-api-returns-400-bad-request-when-street-city-co", "investigation-nfse-error-e0240-cep-nao-existe-ou-nao-pertence-ao-municip", "fact-brasilapi-open-cep-service-does-not-return-ibge-city-codes", "pattern-cep-validation-uses-sync-wrapper-validate-cep-sync-that-ru"]}
+{"query": "structured logging event names", "description": "Logging patterns - event naming conventions", "relevant_keys": ["pattern-event-names-use-snake-case-past-tense-domain-prefix-when-h", "pattern-migrate-logging-with-event-names-snake-case-past-tense-do", "pattern-use-logger-bind-for-request-scoped-context-with-entity-ids", "learned-structured-logging-epic-pattern-wave-1-deps-config-prin", "decision-downgrade-router-inclusion-and-static-file-discovery-logs-to"]}
+{"query": "CogniTest credits free", "description": "Feature - credits system and free tier", "relevant_keys": ["fact-free-credits-system-is-broken-new-orgs-registered-via-meds", "learned-frontend-credits-widget-complete-created-creditswidget-svel", "learned-backend-integration-complete-modified-create-session-endpoi", "learned-cognitest-pricing-uses-lazy-initialization-call-post-api"]}
+{"query": "environment variables production deploy", "description": "DevOps - env var configuration for deployment", "relevant_keys": ["fact-for-prod-builds-set-env-inline-vite-cognitest-api-url-http", "pattern-vite-bakes-vite-env-vars-into-the-js-bundle-at-build-time", "decision-used-env-production-as-single-source-of-truth-for-prod-fron", "learned-fastapi-s-pydantic-settings-are-loaded-at-startup-changing", "fact-vite-api-url-is-only-used-in-vite-config-ts-dev-proxy-not-i", "pattern-when-one-frontend-needs-to-call-another-service-s-api-both"]}
+{"query": "React useCallback re-render", "description": "React-specific performance pattern", "relevant_keys": ["learned-functions-created-during-render-cause-unnecessary-re-renders", "learned-controlled-components-should-not-maintain-internal-state-for", "learned-react-keys-must-be-unique-across-all-items-in-a-list-not-ju"]}
+{"query": "Alembic migration model columns", "description": "Database migration patterns", "relevant_keys": ["learned-when-adding-columns-via-alembic-migration-must-also-add-cor", "pattern-backend-schema-changes-require-1-model-update-2-alembic", "decision-added-phone-and-phone-country-columns-to-user-model-at-lines", "decision-converted-cognitest-from-varchar-36-to-native-postgresql-uu"]}
+{"query": "WhatsApp E.164 format", "description": "Integration - WhatsApp phone formatting requirements", "relevant_keys": ["investigation-whatsapp-business-api-requires-e-164-format-for-all-phone-nu", "investigation-e-164-format-is-itu-t-international-phone-standard-structur", "fact-whatsapp-api-excludes-certain-countries-from-messaging-crim", "pattern-best-practices-for-e-164-normalization-before-whatsapp-api-c", "learned-e-164-formatting-should-happen-at-validation-time-not-at-ap"]}