wicked-brain 0.1.2 → 0.3.2

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

@@ -0,0 +1,99 @@
+---
+name: wicked-brain-configure
+description: Read brain state and write contextual instructions into the active CLI's agent config file. Run after onboarding, major ingests, or consolidation.
+---
+
+# wicked-brain:configure
+
+Writes a contextual `## wicked-brain` section into the active CLI/IDE's agent config file.
+
+## Config
+
+Read `_meta/config.json` for brain path and server port.
+If it doesn't exist, trigger wicked-brain:init.
+
+## Process
+
+### Step 1: Gather brain state
+
+1. Call server stats:
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"stats"}'
+```
+
+2. Search for top topics — run a broad search to identify dominant tags:
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"search","params":{"query":"*","limit":50}}'
+```
+Read frontmatter of top results, count `contains:` tag frequency. Top 10 tags = brain expertise.
+
+3. Read `{brain_path}/brain.json` for brain identity and linked brains.
+
+4. Read `{brain_path}/_meta/log.jsonl` (last 50 lines) for recent `search_miss` entries — these are knowledge gaps.
+
+5. List available agents by reading `skills/wicked-brain-agent/agents/` at depth 0.
+
+### Step 2: Detect CLI/IDE
+
+Check for these signals in order (first match wins):
+
+| Signal | Platform | Config File |
+|--------|----------|------------|
+| `CLAUDE_CODE` env var or `.claude/` exists | Claude Code | `CLAUDE.md` |
+| `CODEX_CLI` env var or `.codex/` exists | Codex | `.codex/instructions.md` |
+| `.kiro/` exists | Kiro | `KIRO.md` |
+| `GEMINI_CLI` env var or `.gemini/` exists | Gemini CLI | `GEMINI.md` |
+| `COPILOT_CLI` env var or `.github/` exists | Copilot CLI | `.github/copilot-instructions.md` |
+| `.cursor/` exists | Cursor | `.cursor/rules/wicked-brain.md` |
+| `.antigravity/` exists | Antigravity | `.antigravity/rules/wicked-brain.md` |
+| None | Fallback | `CLAUDE.md` |
+
+### Step 3: Write config section
+
+Read the target config file. Find the `## wicked-brain` section (if it exists, replace it). If it doesn't exist, append it.
+
+Write a section like this (adapt content to actual brain state):
+
+```markdown
+## wicked-brain
+
+Digital brain: {brain_id} | {total} indexed items | {chunks} chunks, {wiki} wiki articles, {memory} memories
+
+**Domain expertise:** {top 10 tags from step 1}
+
+**Knowledge gaps:** {recent search_miss topics, if any}
+
+**Linked brains:** {list from brain.json, or "none"}
+
+### How to use
+
+- **Before responding**: call `wicked-brain:agent` (context) to surface relevant knowledge
+- **Capture learnings**: call `wicked-brain:agent` (session-teardown) at session end
+- **Store a decision/pattern/gotcha**: call `wicked-brain:memory` (store mode)
+- **Ask the brain**: call `wicked-brain:query` for cited answers
+- **Available agents**: consolidate, context, session-teardown, onboard (via `wicked-brain:agent`)
+
+### Rules
+
+- Do NOT read brain files directly — use skills and agents
+- Always pass session_id with search calls for access tracking
+- Capture non-obvious decisions and gotchas as memories
+```
+
+### Step 4: Confirm
+
+Report what was written and where:
+- Config file: {path}
+- Brain stats: {total} items, {expertise summary}
+- Gaps noted: {N} search misses
+
+## Cross-Platform Notes
+
+- Uses Bash to check for env vars and directories
+- Uses Read/Edit tools for config file management
+- All paths use forward slashes
+- On Windows, check `%USERPROFILE%` equivalents for home directory paths

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

@@ -49,6 +49,13 @@ curl -s -X POST http://localhost:{port}/api \
   -d '{"action":"stats","params":{}}'
 ```
 
+Read _meta/log.jsonl. Look for:
+1. op: "search_miss" entries — these are topics users searched for but
+   couldn't find. Prioritize these as highest-value gaps.
+2. Low-frequency tags in chunks (existing approach) — secondary signal.
+
+Group search misses by topic and address the most frequent ones first.
+
 Search for thin areas — topics mentioned in existing chunks but with few entries.
 Use your Grep tool on `{brain_path}/chunks/` to find all `contains:` fields and
 count occurrences. Shell fallback:
@@ -62,6 +69,18 @@ Based on existing content, reason about:
 - Connections between concepts that exist but aren't documented
 - Questions the brain can't currently answer
 
+## Source Material Rules (CRITICAL)
+
+ONLY read from `chunks/extracted/` as source material for new inferences. Never base
+inferences on content from `chunks/inferred/` — that would be inference-of-inference,
+which causes confidence laundering (inferred content cites inferred content, making
+unreliable chains appear well-sourced).
+
+- If you find relevant content in `chunks/inferred/`, you may note it as background
+  context but do NOT cite it as a `source_chunk` or use it as evidence for new inferences.
+- Every entry in `source_chunks` in your output MUST start with `chunks/extracted/`.
+- If a gap cannot be filled using only extracted chunks as evidence, skip it.
+
 ## Step 3: Write inferred chunks
 
 For each gap, write a new chunk to `{brain_path}/chunks/inferred/{topic}/chunk-NNN.md`:

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

@@ -108,6 +108,21 @@ narrative_theme: {the "so what" in 8 words or fewer}
 
 {Extracted content in markdown format}
 
+## Tag Expansion
+
+After generating the initial `contains:` tags, expand each keyword with 1-3 synonyms or related terms:
+
+- **Abbreviations**: JWT → "json-web-token", K8s → "kubernetes", API → "application-programming-interface"
+- **Synonyms**: "auth" → "authentication", "DB" → "database", "config" → "configuration"
+- **Related concepts**: "JWT" → "tokens", "session", "security"; "PostgreSQL" → "database", "RDBMS"
+- **Domain hierarchy**: specific terms get their general category added
+
+Add expanded tags to `contains:` alongside originals. Deduplicate. Cap total tags at 15 per chunk.
+
+Example:
+  Original tags: ["jwt", "session", "expiry"]
+  After expansion: ["jwt", "json-web-token", "tokens", "security", "session", "session-management", "expiry", "timeout", "ttl"]
+
 ## After writing chunks, index them in the server:
 
 curl -s -X POST http://localhost:{port}/api \
@@ -240,10 +255,34 @@ function splitText(text) {
   return chunks.length > 0 ? chunks : [text];
 }
 
+async function removeOldChunks(name) {
+  const chunkDir = join(BRAIN, "chunks", "extracted", name);
+  if (!existsSync(chunkDir)) return;
+  const ts = Math.floor(Date.now() / 1000);
+  // Remove each chunk from the search index before archiving
+  for (const f of readdirSync(chunkDir).filter(f => f.endsWith(".md"))) {
+    const id = `chunks/extracted/${name}/${f}`;
+    try {
+      await fetch(`http://localhost:${PORT}/api`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ action: "remove", params: { id } }),
+      });
+    } catch (e) {
+      console.error(`  Failed to remove ${id}: ${e.message}`);
+    }
+  }
+  // Archive the old directory
+  const { renameSync } = await import("node:fs");
+  renameSync(chunkDir, `${chunkDir}.archived-${ts}`);
+  console.log(`  Archived old chunks: ${name}`);
+}
+
 async function ingestFile(filePath) {
   const ext = extname(filePath).toLowerCase();
   const rel = relative(SOURCE_DIR, filePath);
   const name = safeName(rel);
+  await removeOldChunks(name);
   const chunkDir = join(BRAIN, "chunks", "extracted", name);
   mkdirSync(chunkDir, { recursive: true });
 
@@ -254,7 +293,22 @@ async function ingestFile(filePath) {
     const chunkId = `${name}/chunk-${String(i + 1).padStart(3, "0")}`;
     const chunkPath = `chunks/extracted/${chunkId}.md`;
     const ts = new Date().toISOString();
-    const keywords = [...new Set(chunks[i].toLowerCase().replace(/[^a-z0-9\s-]/g,"").split(/\s+/).filter(w => w.length > 5))].slice(0, 10);
+    const STOP = new Set([
+      "should","would","could","their","about","which","these","those",
+      "there","where","other","after","before","during","while","being",
+      "having","because","through","between","without","against","itself",
+      "become","becomes","another","however","already","always","around"
+    ]);
+
+    // Note: These keywords are for FTS indexing. The LLM-based ingest
+    // generates richer synonym-expanded tags in the contains: field.
+    // This batch script extracts basic keywords only.
+    const keywords = [...new Set(
+      chunks[i].toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, "")
+        .split(/\s+/)
+        .filter(w => w.length > 5 && !STOP.has(w))
+    )].slice(0, 10);
 
     const frontmatter = [
       "---",
@@ -318,10 +372,19 @@ This pattern should be used **whenever more than 5 files need processing**. It:
 
 ### Step 4: Archive on re-ingest
 
-If previous chunks exist for a source, archive them first.
-Use the agent's native move/rename capability, or shell equivalents:
-- macOS/Linux: `mv "{brain_path}/chunks/extracted/{safe_name}" "{brain_path}/chunks/extracted/{safe_name}.archived-$(date +%s)"`
-- Windows: `Rename-Item "{brain_path}\chunks\extracted\{safe_name}" "{safe_name}.archived-{timestamp}"`
+If previous chunks exist for a source, **remove them from the search index before archiving**.
+Archived files are invisible to the file watcher, so the server won't clean them up automatically.
+
+1. List all .md files in `{brain_path}/chunks/extracted/{safe_name}/`
+2. For each file, call the server to remove it from the index:
+   ```bash
+   curl -s -X POST http://localhost:{port}/api \
+     -H "Content-Type: application/json" \
+     -d '{"action":"remove","params":{"id":"chunks/extracted/{safe_name}/chunk-NNN.md"}}'
+   ```
+3. Then rename the directory to archive it:
+   - macOS/Linux: `mv "{brain_path}/chunks/extracted/{safe_name}" "{brain_path}/chunks/extracted/{safe_name}.archived-$(date +%s)"`
+   - Windows: `Rename-Item "{brain_path}\chunks\extracted\{safe_name}" "{safe_name}.archived-{timestamp}"`
 
 ### Step 5: Report to user
 

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

@@ -69,6 +69,12 @@ Shell fallback:
 ### Stale entries
 Compare source file modification times with chunk creation times.
 
+### Stale wiki articles
+For each wiki article with source_hashes in frontmatter:
+- Read each source chunk
+- Compare its current content hash prefix against the stored hash
+- If any hash mismatches or chunk is missing: flag as stale
+
 ### Missing frontmatter
 Check each chunk has required frontmatter fields (source, chunk_id, confidence, indexed_at).
 
@@ -77,6 +83,14 @@ Check each chunk has required frontmatter fields (source, chunk_id, confidence,
 Read a sample of chunks and wiki articles. Check:
 - Are tags consistent? (same concept tagged differently in different chunks)
 - Are there factual contradictions between articles?
+- Check for `contradicts` typed links — query the server:
+  ```bash
+  curl -s -X POST http://localhost:{port}/api \
+    -H "Content-Type: application/json" \
+    -d '{"action":"contradictions","params":{}}'
+  ```
+  For each contradiction link, read both the source and target to determine
+  if the contradiction is resolved. Flag unresolved contradictions as warnings.
 - Are there implicit connections that should be explicit [[links]]?
 - What topics have chunks but no wiki article? (coverage gaps)
 

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

@@ -0,0 +1,172 @@
+---
+name: wicked-brain:lsp
+description: |
+  Universal code intelligence via LSP. Queries language servers for definitions,
+  references, symbols, call hierarchies, hover info, and diagnostics. Auto-installs
+  language servers when missing.
+
+  Use when: "where is X defined", "who uses X", "what type is X",
+  "list symbols in", "find symbol", "who calls X", "blast radius",
+  "architecture map", "code diagnostics", "lsp health".
+---
+
+# wicked-brain:lsp
+
+Universal code intelligence for any CLI/IDE via the brain's LSP client layer.
+
+## Cross-Platform Notes
+
+Commands in this skill work on macOS, Linux, and Windows. When a command has
+platform differences, alternatives are shown. Your native tools (Read, Write,
+Grep, Glob) work everywhere — prefer them over shell commands when possible.
+
+For the brain path default:
+- macOS/Linux: ~/.wicked-brain
+- Windows: %USERPROFILE%\.wicked-brain
+
+- `curl` works on macOS, Linux, and Windows 10+
+- File paths must be absolute
+- On Windows, use forward slashes in JSON: `"file":"C:/Users/me/project/file.ts"`
+- Language server install commands assume the package manager is in PATH
+- For Windows PowerShell without npm/pip in PATH, guide the user to install manually
+
+## Config
+
+Read `_meta/config.json` for brain path and server port.
+If it doesn't exist, trigger wicked-brain:init.
+
+## When to Use
+
+| You want to... | Action | Example |
+|----------------|--------|---------|
+| Find where something is defined | `lsp-definition` | "Where is UserService defined?" |
+| Find all usages of something | `lsp-references` | "Who uses the validateCredentials function?" |
+| See what type something is | `lsp-hover` | "What's the type of this variable?" |
+| List symbols in a file | `lsp-symbols` | "What classes and functions are in auth/login.ts?" |
+| Find a symbol by name | `lsp-workspace-symbols` | "Find the class PaymentService" |
+| See what implements an interface | `lsp-implementation` | "What classes implement AuthProvider?" |
+| Find who calls a function | `lsp-call-hierarchy-in` | "Who calls processPayment?" |
+| See what a function calls | `lsp-call-hierarchy-out` | "What does processPayment call?" |
+| Check for errors | `lsp-diagnostics` | "Any type errors in this project?" |
+| Analyze blast radius | `lsp-call-hierarchy-in` (recursive) | "What breaks if I change handleRequest?" |
+| Map architecture | `lsp-workspace-symbols` + `lsp-symbols` | "Give me an overview of this codebase" |
+| Check server status | `lsp-health` | "Are language servers running?" |
+
+## Process
+
+### Step 1: Identify the action
+
+Based on what the user/agent needs, pick the appropriate action from the table above.
+
+### Step 2: Call the server
+
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"{action}","params":{params}}'
+```
+
+**Position-based actions** (definition, references, hover, implementation, call-hierarchy):
+```json
+{"action":"lsp-definition","params":{"file":"/absolute/path/to/file.ts","line":15,"col":10}}
+```
+Note: `line` and `col` are 0-indexed.
+
+**File-based actions** (symbols):
+```json
+{"action":"lsp-symbols","params":{"file":"/absolute/path/to/file.ts"}}
+```
+
+**Query-based actions** (workspace-symbols):
+```json
+{"action":"lsp-workspace-symbols","params":{"query":"PaymentService"}}
+```
+
+**No-params actions** (health, diagnostics without file):
+```json
+{"action":"lsp-health"}
+{"action":"lsp-diagnostics"}
+```
+
+### Step 3: Handle errors — auto-install
+
+If the response contains `"error": "language_server_not_found"`, the language server isn't installed. The response includes install instructions:
+
+```json
+{"error":"language_server_not_found","language":"typescript","install":{"method":"npm","package":"typescript-language-server typescript"}}
+```
+
+Attempt installation based on the method:
+
+| Method | Command |
+|--------|---------|
+| npm | `npm install -g {package}` |
+| pip | `pip install {package} 2>/dev/null \|\| pip3 install {package}` |
+| cargo | `cargo install {package}` |
+| gem | `gem install {package}` |
+| go | `go install {package}@latest` |
+| brew | `brew install {package}` |
+| dotnet | `dotnet tool install -g {package}` |
+| rustup | `rustup component add {package}` |
+| manual | Tell the user: "Install {package} manually" |
+
+After installation, retry the original LSP request.
+
+If installation fails, report to the user:
+"Could not auto-install {language} language server. Install manually: {instructions}"
+
+### Step 4: Handle other errors
+
+| Error | What to do |
+|-------|-----------|
+| `language_server_crashed` | The server crashed 3 times. Report to user, suggest checking the language server logs. |
+| `unsupported_language` | No known language server for this file extension. |
+| `lsp_timeout` | The language server took too long. May be initializing a large project. Retry once. |
+| `file_outside_workspace` | The file isn't in a registered project. Use `wicked-brain:onboard` to register the project first. |
+
+### Step 5: Use results
+
+**Definitions/References/Implementation** return locations:
+```json
+{"locations":[{"file":"/path/to/file.ts","line":15,"col":2}]}
+```
+Read the file at that location to show the user the relevant code.
+
+**Symbols** return a hierarchy:
+```json
+{"symbols":[{"name":"UserService","kind":"class","line":15,"endLine":45,"children":[...]}]}
+```
+Useful for understanding file structure.
+
+**Hover** returns type info:
+```json
+{"content":"(method) UserService.validate(token: string): boolean","language":"typescript"}
+```
+
+**Call hierarchy** returns call chains:
+```json
+{"calls":[{"from":{"name":"handleLogin","file":"/path/auth.ts","line":30}}]}
+```
+
+**Diagnostics** return errors/warnings:
+```json
+{"diagnostics":[{"line":23,"col":5,"severity":"error","message":"Type 'string' is not assignable to type 'number'"}],"errors":1,"warnings":0}
+```
+
+## Blast Radius Analysis
+
+To analyze the blast radius of changing a function:
+
+1. Call `lsp-call-hierarchy-in` for the function → get direct callers
+2. For each caller, call `lsp-call-hierarchy-in` again → get indirect callers
+3. Continue until the chain stabilizes (usually 2-3 levels)
+4. Report the full call chain with file locations
+
+## Architecture Mapping
+
+To map a codebase's architecture:
+
+1. Call `lsp-workspace-symbols` with query="" to get all symbols
+2. For key files (entry points, main modules), call `lsp-symbols` for detailed hierarchies
+3. Combine with brain's existing wikilinks and backlinks for a complete picture
+4. Use `wicked-brain:compile` to synthesize into a wiki article

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

@@ -0,0 +1,144 @@
+---
+name: wicked-brain:memory
+description: |
+  Store and recall experiential learnings (decisions, patterns, preferences,
+  gotchas, discoveries) in the brain's memory system.
+
+  Use when: "remember this", "store this decision", "recall what we decided",
+  "what do I know about", "brain memory".
+---
+
+# wicked-brain:memory
+
+Store and recall experiential learnings in the brain's memory system.
+
+## Cross-Platform Notes
+
+- Uses `curl` for server API calls (available on Windows 10+, macOS, Linux)
+- File writes use agent-native tools (Write/Edit), not shell commands
+- Path separator: always use forward slashes in `contains:` and `path` fields
+- Brain path default: `~/.wicked-brain` (macOS/Linux), `%USERPROFILE%\.wicked-brain` (Windows)
+
+## Config
+
+Read `_meta/config.json` for brain path and server port.
+If it doesn't exist, trigger wicked-brain:init.
+
+## Parameters
+
+- **mode** (required): `store` or `recall`
+- **content** (store mode): the memory content to store
+- **type** (store mode, optional): `decision`, `pattern`, `preference`, `gotcha`, or `discovery`. Auto-detected if omitted.
+- **ttl_days** (store mode, optional): number of days before this memory expires. Defaults by type.
+- **query** (recall mode): search term for finding memories
+- **filter_type** (recall mode, optional): filter by memory type
+- **filter_tier** (recall mode, optional): filter by tier (`working`, `episodic`, `semantic`)
+
+## Store Mode
+
+### Step 1: Detect type
+
+If type is not provided, classify the content:
+- Contains "decided", "chose", "will use", "going with" → `decision`
+- Contains "pattern", "always", "tends to", "convention" → `pattern`
+- Contains "prefer", "like", "want", "should always" → `preference`
+- Contains "watch out", "careful", "gotcha", "trap", "bug" → `gotcha`
+- Otherwise → `discovery`
+
+### Step 2: Apply type defaults
+
+| Type | Default importance | Default ttl_days |
+|------|-------------------|-----------------|
+| decision | 7 | null (permanent) |
+| pattern | 6 | null (permanent) |
+| preference | 6 | null (permanent) |
+| gotcha | 5 | 30 |
+| discovery | 4 | 14 |
+
+Agent-provided overrides take precedence.
+
+### Step 3: Generate tags with synonym expansion
+
+Extract 5-10 keyword tags from the content. For each tag, add 1-3 synonyms:
+- Abbreviations: JWT → "json-web-token", K8s → "kubernetes"
+- Synonyms: "auth" → "authentication", "DB" → "database"
+- Related concepts: "JWT" → "tokens", "session", "security"
+- Domain hierarchy: specific terms get their general category added
+
+Cap total tags at 15. Deduplicate.
+
+### Step 4: Generate safe filename
+
+Slugify a summary of the content:
+- Lowercase, replace spaces with hyphens, remove special chars
+- Max 60 characters
+- Example: "Decided to use JWT with 15-min expiry" → `jwt-15min-expiry-decision.md`
+
+### Step 5: Write memory file
+
+Write to `{brain_path}/memory/{safe_name}.md`:
+
+```yaml
+---
+type: {detected or provided type}
+tier: working
+confidence: 0.5
+importance: {from type defaults or override}
+ttl_days: {from type defaults or override, null if permanent}
+session_origin: "{current session identifier or ISO timestamp}"
+contains:
+  - {tag1}
+  - {tag2}
+  - {synonym-expanded tags...}
+entities:
+  people: [{if mentioned}]
+  systems: [{if mentioned}]
+indexed_at: "{ISO 8601 timestamp}"
+---
+
+{memory content}
+```
+
+The server's file watcher will auto-index this file.
+
+### Step 6: Log the store event
+
+Append to `{brain_path}/_meta/log.jsonl`:
+
+```json
+{"ts":"{ISO}","op":"memory_store","path":"memory/{safe_name}.md","type":"{type}","tier":"working","author":"agent:memory"}
+```
+
+## Recall Mode
+
+### Progressive loading
+
+- **Depth 0**: frontmatter only — type, tier, confidence, importance, contains tags
+- **Depth 1**: + first 3 lines of content (summary)
+- **Depth 2**: full content
+
+### Step 1: Search
+
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"search","params":{"query":"{query}","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.
+
+### Step 2: Filter results
+
+Filter to paths starting with `memory/`. If filter_type or filter_tier provided, read frontmatter and filter accordingly.
+
+### Step 3: Apply tier weighting
+
+Re-rank results by applying tier multipliers:
+- `semantic`: score x 1.3
+- `episodic`: score x 1.0
+- `working`: score x 0.8
+
+### Step 4: Return at requested depth
+
+Return results at the requested depth level. Default to depth 0.