@automagik/genie-brain 0.260404.8

package/skills/brain-learn/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: brain-learn
+description: Manage agent learnings -- ingest, search, classify, and forget knowledge memories
+---
+
+# /brain-learn — Agent Learning Management
+
+Manage the agent's learning memory -- ingest feedback, discover patterns, store preferences, and recall relevant learnings. Supports classification by type, enforcement flags for mandatory rules, and soft-delete for forgetting without permanent loss.
+
+## When to Use
+
+- Agent receives a correction or feedback from a human
+- Agent discovers a recurring pattern worth remembering
+- Agent needs to store a user preference or communication style
+- Agent needs to recall previous learnings before taking action
+- Cleaning up outdated or incorrect learnings
+
+## Prerequisites
+
+- Brain must exist (`genie brain status`)
+- Brain should have a `memory/` directory (created automatically on first learn ingest)
+
+## Flow
+
+1. **Classify** -- determine the learning type (feedback, project, user, reference)
+2. **Ingest** -- store the learning with metadata and optional enforcement
+3. **Index** -- learning is indexed for search (automatic after ingest)
+4. **Recall** -- search learnings when context is needed for a task
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `genie brain learn ingest "content" --brain <id>` | Ingest a learning -- auto-classifies type |
+| `genie brain learn ingest "content" --brain <id> --learning-type feedback` | Ingest with explicit type |
+| `genie brain learn ingest "content" --brain <id> --name "name"` | Ingest with a human-readable name |
+| `genie brain learn ingest "content" --brain <id> --reason "why"` | Ingest with rationale explaining why this matters |
+| `genie brain learn ingest "content" --brain <id> --enforce` | Mark as enforced rule -- mandatory compliance |
+| `genie brain learn search "query" --brain <id>` | Search across all learnings |
+| `genie brain learn search "query" --brain <id> --enforce` | Search only enforced (mandatory) learnings |
+| `genie brain learn search "query" --brain <id> --learning-type feedback` | Search filtered by learning type |
+| `genie brain learn list --brain <id>` | List all active learnings |
+| `genie brain learn list --brain <id> --learning-type user` | List learnings filtered by type |
+| `genie brain learn list --brain <id> --all` | List all learnings including forgotten ones |
+| `genie brain learn forget <path\|#docid> --brain <id>` | Soft-delete a learning (recoverable) |
+| `genie brain learn classify --brain <id>` | Auto-classify unclassified learnings |
+
+## Learning Types
+
+| Type | When to Use | Examples |
+|------|-------------|---------|
+| `feedback` | Corrections, directives, behavioral rules | "Never use pip, always use uv", "Always create PRs to dev" |
+| `project` | Architecture, design decisions, how systems work | "The brain uses RRF for search fusion", "Embeddings are in Postgres" |
+| `user` | Preferences, communication style, personal patterns | "User prefers concise responses", "Use Brazilian Portuguese for chat" |
+| `reference` | General knowledge, facts, documentation | "API rate limit is 100/min", "Deploy process uses GitHub Actions" |
+
+## Enforce Flag
+
+The `--enforce` flag marks a learning as a mandatory rule:
+
+- Enforced learnings appear in `--enforce` filtered searches
+- Future hook support will automatically check enforced learnings before actions
+- Use sparingly -- only for strong corrections and non-negotiable rules
+- Enforced learnings are highlighted differently in list output
+
+**When to enforce:**
+- Human says "never do X" or "always do Y"
+- A mistake was made and the correction is absolute
+- A policy or rule must be followed without exception
+
+**When NOT to enforce:**
+- Soft preferences ("I usually prefer...")
+- Context-dependent patterns ("In this project, we tend to...")
+- Reference information (facts, docs, architecture notes)
+
+## Rules
+
+- Let the auto-classifier choose the type unless you are certain of the correct classification
+- Use `--enforce` only for strong corrections and non-negotiable directives
+- Include `--reason` to explain why a learning matters -- aids future recall and context
+- Include `--name` for important learnings to make them easy to find in lists
+- `forget` is a soft-delete -- the learning is hidden but recoverable with `--all`
+- Search learnings before starting tasks that might be affected by past feedback
+- Do not duplicate learnings -- search first to check if a similar learning already exists
+- Periodically review learnings with `list` and `forget` outdated ones
+
+## Composition
+
+- Chains with **/brain-search** -- recall learnings alongside factual knowledge base searches
+- Chains with **/brain-analyze** -- synthesize patterns across multiple learnings
+- Chains with **/brain-health** -- learning memory health is part of overall brain quality

package/skills/brain-observe/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: brain-observe
+description: Monitor brain performance — gap analysis, strategy tuning, cost analysis, and trace review
+---
+
+# /brain-observe — Brain Observability
+
+Monitor and tune brain search performance. Review query traces, identify knowledge gaps, tune strategy routing, and analyze costs. Essential for maintaining retrieval quality in production.
+
+## When to Use
+
+- Search quality has degraded or users report irrelevant results
+- Need to identify knowledge gaps (queries that return poor results)
+- Tuning strategy routing for specific query patterns
+- Analyzing costs for CAG/embedding operations
+- Periodic brain maintenance and optimization
+
+## Prerequisites
+
+- Brain must exist and have query traces (`genie brain traces`)
+- Brain should have been used for searches (traces are recorded automatically)
+
+## Flow
+
+### Gap Analysis
+1. `genie brain traces --brain <id> --failed` — find queries with low confidence
+2. Analyze patterns — which topics have gaps?
+3. Use **/brain-ingest** to fill identified gaps
+4. Re-test gap queries with `genie brain search`
+
+### Strategy Tuning
+1. `genie brain traces --brain <id> --limit 50` — review recent traces
+2. Identify query patterns that underperform with default strategy
+3. `genie brain strategy set "<pattern>" cag --brain <id>` — route pattern to CAG
+4. Re-test to verify improvement
+
+### Cost Analysis
+1. `genie brain cache --estimate --brain <id>` — estimate CAG cache costs
+2. Review trace latencies for strategy optimization decisions
+3. Consider switching high-cost patterns from CAG to RAG if quality is sufficient
+
+### Conflict Resolution
+1. `genie brain conflicts --brain <id>` — detect contradictory documents
+2. `genie brain link --brain <id> --detect-conflicts` — link + conflict detection
+3. Resolve conflicts by updating source documents or forgetting outdated ones
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `genie brain traces --brain <id>` | List recent query traces |
+| `genie brain traces --brain <id> --limit 50` | More traces |
+| `genie brain traces --brain <id> --failed` | Only failed/low-confidence queries |
+| `genie brain traces --brain <id> --strategy cag` | Filter by strategy |
+| `genie brain traces --brain <id> --purge --older-than 90` | Clean old traces |
+| `genie brain strategy --brain <id>` | List strategy configs |
+| `genie brain strategy set "<pattern>" <strategy> --brain <id>` | Set routing rule |
+| `genie brain strategy set "<pattern>" <strategy> --brain <id> --reason "why"` | With rationale |
+| `genie brain strategy rm "<pattern>" --brain <id>` | Remove routing rule |
+| `genie brain cache --estimate --brain <id>` | Estimate CAG costs |
+| `genie brain conflicts --brain <id>` | Detect contradictions |
+| `genie brain status` | Brain dashboard with stats |
+
+## Rules
+
+- Review traces weekly for production brains
+- Purge traces older than 90 days to keep the database lean
+- Always include `--reason` when setting strategy configs — future you will thank you
+- Fix knowledge gaps before tuning strategies — missing content causes more issues than wrong strategies
+- Use `--failed` filter to focus on actual problems, not noise
+
+## Composition
+
+- Chains with **/brain-search** for re-testing after tuning
+- Chains with **/brain-ingest** to fill knowledge gaps identified by traces
+- Chains with **/brain-health** for comprehensive quality assessment
+- Follow-up to **/brain-build** Phase 5 (ongoing tuning)

package/skills/brain-search/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: brain-search
+description: Search a brain knowledge base with confidence scoring and strategy selection
+---
+
+# /brain-search — Knowledge Base Search
+
+Search a brain knowledge base using hybrid retrieval strategies, evaluate result confidence, and cite sources with appropriate authority levels. Supports both quick RAG lookups and deep CAG reasoning for complex queries.
+
+## When to Use
+
+- Agent needs to find information from the knowledge base
+- Agent needs to verify facts or claims against stored knowledge
+- Agent needs to locate specific documents, entities, or references
+- Agent needs to answer a question using brain content as ground truth
+
+## Prerequisites
+
+- Brain must exist (`genie brain status`)
+- Brain must be indexed (`genie brain update`) so chunks and embeddings are available
+- For CAG strategy, rlmx must be reachable (uses LLM reasoning over full documents)
+
+## Flow
+
+1. **Intent detection** -- determine what the user is really asking
+2. **Strategy selection** -- pick RAG (general) or CAG (complex reasoning) based on query type
+3. **Search execution** -- run the query against the indexed brain
+4. **Confidence evaluation** -- score results and decide citation authority
+5. **Citation** -- present findings with the appropriate confidence framing
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `genie brain search "<query>" --brain <id>` | Main search -- auto-selects strategy |
+| `genie brain search "<query>" --brain <id> --strategy rag` | Force RAG strategy (BM25 + Trigram + Vector via RRF) |
+| `genie brain search "<query>" --brain <id> --strategy cag` | Force CAG strategy (RAG then full doc retrieval then rlmx reasoning) |
+| `genie brain search "<query>" --brain <id> --limit 20` | Return more results (default varies by strategy) |
+| `genie brain search "<query>" --brain <id> --min-confidence 0.7` | Filter out results below confidence threshold |
+| `genie brain analyze "<query>" --brain <id>` | Deep analysis via rlmx -- synthesizes across multiple documents |
+| `genie brain analyze "<query>" --brain <id> --mode synthesize` | Synthesis mode -- combines information from multiple sources |
+| `genie brain get <path\|#docid> --brain <id>` | Retrieve the full content of a specific document by path or doc ID |
+
+## Strategy Guide
+
+| Strategy | Method | Best For |
+|----------|--------|----------|
+| `rag` (default) | Fuses BM25 + Trigram + Vector search via Reciprocal Rank Fusion | General queries, factual lookups, keyword-heavy searches |
+| `cag` | RAG results then full document retrieval then rlmx reasoning | Complex questions needing synthesis, "why" and "how" questions, multi-hop reasoning |
+| Auto (no flag) | Auto-selects based on query type using strategy config or default RAG | Most cases -- let the system decide |
+
+**When to force a strategy:**
+
+- Force `--strategy rag` when you need fast, precise lookups and the query is straightforward
+- Force `--strategy cag` when the answer requires reasoning across multiple documents or the question is analytical
+- Leave strategy unset for most queries and let the system auto-select
+
+## Confidence Decision Tree
+
+| Level | Threshold | How to Cite |
+|-------|-----------|-------------|
+| **FULL** | >= 0.80 | Cite with authority. "According to [doc]..." |
+| **HIGH** | >= 0.70 | Cite with confidence. "The brain indicates..." |
+| **PARTIAL** | >= 0.50 | Cite with caveat. "Based on available information..." |
+| **LOW** | >= 0.30 | Mention uncertainty. "I found limited information suggesting..." |
+| **NONE** | < 0.30 | Do not fabricate. "No relevant information found in the brain." |
+
+## Rules
+
+- NEVER fabricate information that is not present in search results
+- ALWAYS include the confidence level when citing brain content
+- Prefer CAG for "why" and "how" questions that require reasoning
+- Use `--min-confidence` to filter noise in brains with lots of low-relevance content
+- When confidence is NONE, say so explicitly -- do not guess or hallucinate an answer
+- Use `genie brain get` to retrieve the full document when a chunk looks relevant but incomplete
+- For ambiguous queries, run a broad search first then refine with tighter terms
+
+## Composition
+
+- Chains with **/brain-analyze** -- escalate to deep analysis when RAG results are insufficient
+- Chains with **/brain-ingest** -- if search reveals knowledge gaps, ingest new content to fill them
+- Chains with **/brain-learn** -- recall agent learnings and preferences alongside factual search