wicked-brain 0.1.2 → 0.3.1

package/skills/wicked-brain-query/SKILL.md

@@ -31,13 +31,70 @@ Server: http://localhost:{port}/api
 
 Question: "{question}"
 
+## Step 0: Decompose query
+
+Before searching, extract 3-5 keyword search terms from the question.
+These should be noun phrases, named entities, and technical terms — not
+full sentences or common words.
+
+Example:
+  Question: "What was the reasoning behind choosing PostgreSQL over SQLite?"
+  Key terms: ["PostgreSQL", "SQLite", "database decision", "API layer"]
+
+### Check learned synonyms first
+
+Before generating synonyms, check if `{brain_path}/_meta/synonyms.json` exists.
+If it does, read it. Format:
+
+```json
+{
+  "testing": ["unit-test", "integration-test", "test-coverage"],
+  "auth": ["authentication", "jwt", "session"],
+  "bootcamp": ["pod-exercises", "hands-on-lab"]
+}
+```
+
+For each key term, look it up in the synonym map. Use learned synonyms first,
+then supplement with LLM-generated synonyms for terms not in the map.
+Learned synonyms are more reliable — they come from actual brain usage.
+
+### LLM synonym expansion
+
+For terms not covered by the learned synonym map, generate 1-2 synonyms or related terms:
+- "auth" → also search "authentication", "credentials"
+- "DB" → also search "database", "datastore"
+- "K8s" → also search "kubernetes", "container-orchestration"
+
+Run searches for both the original key terms AND the expanded terms.
+Deduplicate results before proceeding to Step 1.
+
+Example:
+  Question: "How does our auth system handle sessions?"
+  Key terms: ["auth", "sessions"]
+  Expanded: ["authentication", "credentials", "session-management", "tokens"]
+  Search queries: ["auth", "sessions", "authentication", "credentials", "session-management", "tokens"]
+
+Use the key terms for FTS search queries (Step 1).
+Use the full original question for synthesis context (Step 4).
+Run multiple searches if key terms suggest different angles.
+
 ## Step 1: Search
 
 Search the brain for relevant content:
 ```bash
 curl -s -X POST http://localhost:{port}/api \
   -H "Content-Type: application/json" \
-  -d '{"action":"search","params":{"query":"{question}","limit":10}}'
+  -d '{"action":"search","params":{"query":"{term}","limit":10,"session_id":"{session_id}"}}'
+```
+
+Pass a session_id with every search call. This enables access tracking for
+consolidation. Use a consistent session_id for the entire conversation.
+
+If the question implies recency ("recently", "this week", "latest"), add a `since` parameter to the search with an ISO 8601 timestamp. For example, for "this week" use the date 7 days ago:
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"search","params":{"query":"{term}","limit":10,"session_id":"{session_id}","since":"{iso8601_date}"}}'
 ```
 
 Also search with grep for exact phrases:
@@ -45,6 +102,18 @@ Also search with grep for exact phrases:
 grep -rl "{key_terms}" {brain_path}/chunks/ {brain_path}/wiki/ 2>/dev/null | head -10
 ```
 
+### Log synonym effectiveness
+
+For each synonym-expanded search term, log whether it produced results:
+
+If the expansion returned results that the user accessed (appeared in final answer):
+Append to `{brain_path}/_meta/log.jsonl`:
+{"ts":"{ISO}","op":"synonym_hit","original":"{original term}","expansion":"{expanded term}","results_found":{count},"author":"agent:query"}
+
+If the expansion returned 0 results:
+Append to `{brain_path}/_meta/log.jsonl`:
+{"ts":"{ISO}","op":"synonym_miss","original":"{original term}","expansion":"{expanded term}","results_found":0,"author":"agent:query"}
+
 ## Step 2: Progressive read
 
 Read the top 3-5 results at depth 1 first (just frontmatter + summary).
@@ -82,4 +151,12 @@ Answer the question directly, then list sources:
 Sources:
 - {path}: {one-line description of what it contributed}
 - {path}: {one-line description}
+
+## Step 5: Log search effectiveness
+
+If evidence was insufficient to answer the question fully, append a
+search-miss event to the brain's log:
+
+Append this line to {brain_path}/_meta/log.jsonl:
+{"ts":"{ISO}","op":"search_miss","query":"{original question}","key_terms":[{extracted terms}],"results_found":{count},"author":"agent:query"}
 ```

package/skills/wicked-brain-retag/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: wicked-brain:retag
+description: |
+  Backfill synonym-expanded tags on chunks and memories that have fewer than
+  5 tags. Run periodically or as part of consolidation.
+
+  Use when: "retag the brain", "expand tags", "backfill synonyms",
+  "brain retag", "improve tagging".
+---
+
+# wicked-brain:retag
+
+Scan chunks and memories with thin tagging and expand their `contains:` with synonyms and related terms.
+
+## Cross-Platform Notes
+
+- Uses Glob tool for file discovery (not shell `find`)
+- Uses Read tool for frontmatter parsing (not shell `head`)
+- Uses Edit tool for frontmatter updates (not shell `sed`)
+- No shell commands required — fully agent-native
+
+## Config
+
+Read `_meta/config.json` for brain path and server port.
+If it doesn't exist, trigger wicked-brain:init.
+
+## Parameters
+
+- **dry_run** (optional, default false): if true, report what would change without writing
+- **min_tags** (optional, default 5): threshold — only retag docs with fewer tags than this
+
+## Process
+
+### Step 1: Find under-tagged documents
+
+Use Glob to find all markdown files:
+
+```
+{brain_path}/chunks/**/*.md
+{brain_path}/memory/**/*.md
+```
+
+### Step 2: Read frontmatter at depth 0
+
+For each file, read the YAML frontmatter between `---` lines. Parse the `contains:` array. Filter to files with fewer than {min_tags} tags.
+
+### Step 3: Expand tags
+
+For each under-tagged document, read at depth 1 (first ~10 lines of content after frontmatter). Generate expanded tags:
+
+#### Check learned synonyms
+
+Before LLM expansion, check if `{brain_path}/_meta/synonyms.json` exists.
+For each existing tag, look it up in the synonym map. Learned expansions take
+priority over LLM-generated ones. Supplement with LLM expansions for tags
+not in the map.
+
+- For each existing tag, add 1-3 synonyms or related terms
+- Extract additional keywords from the content summary
+- Apply the same expansion rules as wicked-brain:memory store:
+  - Abbreviations: JWT → "json-web-token"
+  - Synonyms: "auth" → "authentication"
+  - Related concepts: "JWT" → "tokens", "session", "security"
+  - Domain hierarchy: "PostgreSQL" → "database", "RDBMS"
+- Deduplicate and cap at 15 tags total
+
+### Step 4: Update or report
+
+If **dry_run**: report the file path, current tag count, and proposed new tags.
+
+If not dry_run: update the `contains:` field in the YAML frontmatter in-place using the Edit tool. The server's file watcher will detect the change and re-index.
+
+### Step 5: Summary
+
+Report:
+- Total files scanned
+- Files under threshold
+- Files updated (or would-be-updated in dry run)
+- Sample of expanded tags for verification

package/skills/wicked-brain-search/SKILL.md

@@ -75,16 +75,8 @@ curl -s -X POST http://localhost:{port}/api \
 
 Parse the JSON response to get results.
 
-## Step 2: File search (catches what FTS might miss)
+## Step 2: Return results
 
-Search for exact phrases or patterns that FTS tokenization might split.
-Use your Grep tool (preferred) or shell fallback:
-- macOS/Linux: `grep -rl "{query}" {brain_path}/chunks/ {brain_path}/wiki/ 2>/dev/null | head -20`
-- Windows: `findstr /s /m "{query}" {brain_path}\chunks\*.md {brain_path}\wiki\*.md 2>nul`
-
-## Step 3: Merge and return
-
-Combine FTS results and grep matches. Deduplicate by path.
 For each result, read the first line of the file to get the title/summary.
 
 Return in this format:
@@ -95,7 +87,7 @@ RESULTS:
 TOTAL: {count}
 ```
 
-### Step 4: Merge results from all subagents
+### Step 3: Merge results from all subagents
 
 After all subagents return:
 1. Collect all results
@@ -103,7 +95,7 @@ After all subagents return:
 3. Sort by score descending
 4. Tag each result with its brain origin
 
-### Step 5: Return at requested depth
+### Step 4: Return at requested depth
 
 **Depth 0 (default):**
 ```

package/skills/wicked-brain-status/SKILL.md

@@ -67,6 +67,13 @@ Check parent/link accessibility by using the Read tool on
 Depth 0 plus:
 - Use the Read tool on `_meta/log.jsonl` (last 50 lines) to identify topic distribution from recent tag events.
   Shell fallback: `tail -50 {brain_path}/_meta/log.jsonl` (macOS/Linux) or `Get-Content "{brain_path}\_meta\log.jsonl" -Tail 50` (Windows PowerShell)
+- Show topic distribution for the last 7 days by searching with a `since` filter:
+  ```bash
+  curl -s -X POST http://localhost:{port}/api \
+    -H "Content-Type: application/json" \
+    -d '{"action":"search","params":{"query":"*","limit":100,"since":"{iso8601_7_days_ago}"}}'
+  ```
+  Group results by path prefix (e.g., `chunks/extracted/`, `wiki/`) to show recent activity distribution.
 - List the top 10 most common tags
 - Flag any staleness warnings (sources modified after last ingest)
 

package/skills/wicked-brain-update/SKILL.md

@@ -70,6 +70,10 @@ This re-runs the installer with the latest version, updating all skills across d
 
 ### Step 5: Restart server if running
 
+**IMPORTANT:** After updating, any running brain server must be restarted to pick up
+new server code (schema migrations, new actions, updated search scoring). Failing to
+restart means the old code serves requests even though skills expect new features.
+
 Check if a brain server is running and restart it to pick up changes.
 
 Find running server PIDs by searching for `server.pid` files under `_meta/` directories
@@ -97,12 +101,27 @@ For each pid file found:
 5. Restart: `npx wicked-brain-server --brain "{brain_dir}" --port {port}`
    On Windows: `Start-Process npx -ArgumentList "wicked-brain-server","--brain","{brain_dir}","--port","{port}" -NoNewWindow`
 
-### Step 6: Report
+### Step 6: Verify migration
+
+After server restart, verify the server started successfully and migrations ran:
+
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"health"}'
+```
+
+If health check fails, check server logs for migration errors. The server runs
+numbered schema migrations on startup — each new version may add tables or columns
+to the SQLite database. Migrations are automatic and idempotent.
+
+### Step 7: Report
 
 Tell the user what was updated:
 - Server: v{old} -> v{new}
 - Skills: updated in {N} CLIs
 - Running servers: {N} restarted
+- Schema: migrated to version {N} (check via health endpoint)
 
 ## Version check without updating