Help us improve
Share bugs, ideas, or general feedback.
From lavra
Captures solved problems as structured JSONL knowledge entries for fast recall in future sessions. Automatically activates after bug fixes or when a solution should be preserved.
npx claudepluginhub roberto-mello/lavra --plugin lavraHow this skill is triggered — by the user, by Claude, or both
Slash command
/lavra:lavra-knowledgeThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Purpose:** Capture solved problems as structured JSONL entries in `.lavra/memory/knowledge.jsonl` and as bead comments, building a searchable knowledge base that auto-recall injects into future sessions.
Capture knowledge — solutions, context docs, learnings, and principles. Use after fixing non-trivial bugs, creating context for AI, or discovering patterns worth preserving. Triggers: compound, document solution, capture fix, save solution, knowledge compound, document this, save this fix, context, create context, update context, build context, learn, save learning, remember this.
Extracts patterns, quirks, and decisions from conversations; persists to Markdown files in knowledge/learnings/. Use /learn for quick or /learn --deep for thorough analysis.
Use when completing any meaningful task - distill patterns, lessons, and insights from the interaction and persist them for future sessions
Share bugs, ideas, or general feedback.
Purpose: Capture solved problems as structured JSONL entries in .lavra/memory/knowledge.jsonl and as bead comments, building a searchable knowledge base that auto-recall injects into future sessions.
Captures problem solutions immediately after confirmation, creating structured knowledge entries stored in .lavra/memory/knowledge.jsonl for auto-recall search and logged as bead comments for traceability. Uses the five knowledge prefixes: LEARNED, DECISION, FACT, PATTERN, INVESTIGATION.
Organization: Append-only JSONL file. Each solved problem produces one or more entries. The auto-recall hook (auto-recall.sh) searches by keyword and injects relevant entries at session start.
<project_root>
All .lavra/ paths are relative to the project root. If you cd into a subdirectory during work, resolve the project root first:
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")
Then prefix all .lavra/ paths with "$PROJECT_ROOT/" when invoking them via Bash.
</project_root>
<critical_sequence name="knowledge-capture" enforce_order="strict">
Auto-invoke after phrases:
OR manual invocation.
Non-trivial problems only: multiple investigation attempts, tricky debugging, non-obvious solution, or future sessions would benefit.
Skip for: simple typos, obvious syntax errors, trivial fixes.
### Step 2: Gather ContextExtract from conversation history:
Required:
BLOCKING REQUIREMENT: If critical context is missing (area, exact error, or resolution steps), ask and WAIT before proceeding to Step 3:
I need a few details to document this properly:
1. Which area/module had this issue?
2. What was the exact error message or symptom?
3. What fixed it?
[Continue after user provides details]
### Step 3: Check Existing Knowledge
Search knowledge.jsonl for similar issues:
# Search by error message keywords
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")
grep "exact error phrase" "$PROJECT_ROOT/.lavra/memory/knowledge.jsonl"
# Search using recall script if available
"$PROJECT_ROOT/.lavra/memory/recall.sh" "keyword1 keyword2"
IF similar knowledge found:
Present decision options:
Found similar knowledge entry:
[key]: [content summary]
What's next?
1. Create new entries anyway (recommended if different root cause)
2. Skip (this is a duplicate)
3. Create new entries with cross-reference
Choose (1-3): _
WAIT for user response.
ELSE (no similar knowledge found):
Proceed directly to Step 4.
### Step 4: Determine Knowledge TypeClassify the solution into one or more knowledge prefixes:
| Prefix | Use When | Example |
|---|---|---|
| LEARNED | Discovered something non-obvious through debugging | "LEARNED: OAuth redirect URI must match exactly including trailing slash" |
| DECISION | Made an architectural or implementation choice | "DECISION: Use connection pooling instead of per-request connections because..." |
| FACT | Confirmed a factual constraint or requirement | "FACT: PostgreSQL JSONB columns require explicit casting for array operations" |
| PATTERN | Identified a recurring pattern (good or bad) | "PATTERN: Always check for nil before accessing nested hash keys in API responses" |
| INVESTIGATION | Documented an investigation path for future reference | "INVESTIGATION: Debugged memory leak - profiler showed retained objects from..." |
Most solved problems produce 1-3 entries. A complex debugging session might produce 1 LEARNED (key insight), 1 PATTERN (prevention rule), 1 INVESTIGATION (debugging path for future reference).
### Step 5: Validate JSONL EntryCRITICAL: All knowledge entries must conform to the JSONL schema.
<validation_gate name="jsonl-schema" blocking="true">
Required fields for each entry:
{
"key": "lowercase-hyphen-separated-unique-key",
"type": "learned|decision|fact|pattern|investigation",
"content": "Clear, specific description of the knowledge",
"source": "user|agent|subagent",
"tags": ["tag1", "tag2"],
"ts": 1706918400,
"bead": "BD-001"
}
Validation rules:
learned-oauth-redirect-must-match-exactly)learned, decision, fact, pattern, investigationuser, agent, or subagentAuto-tagging: Extract keywords from content matching known domains:
BLOCK if validation fails:
JSONL validation failed:
Errors:
- key: must be lowercase-hyphen-separated, got "MyKey"
- type: must be one of [learned, decision, fact, pattern, investigation], got "bug"
- content: too vague - must be specific and searchable
Please provide corrected values.
GATE ENFORCEMENT: Do not proceed to Step 6 until all entries pass validation.
</validation_gate>
### Step 6: Write Knowledge EntriesAppend entries to knowledge.jsonl:
# Append each validated entry as a single JSON line
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")
echo '{"key":"learned-oauth-redirect-must-match","type":"learned","content":"OAuth redirect URI must match exactly including trailing slash","source":"agent","tags":["auth","oauth","security"],"ts":1706918400,"bead":"BD-001"}' >> "$PROJECT_ROOT/.lavra/memory/knowledge.jsonl"
Log as bead comments (if bead ID available):
For each entry, log a bead comment using the appropriate prefix:
bd comments add BD-001 "LEARNED: OAuth redirect URI must match exactly including trailing slash"
bd comments add BD-001 "PATTERN: Always verify OAuth redirect URIs match exactly, including protocol and trailing slash"
Rotation: If knowledge.jsonl exceeds 1000 lines after appending, move first 500 lines to knowledge.archive.jsonl and keep remaining lines as new knowledge.jsonl.
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")
LINE_COUNT=$(wc -l < "$PROJECT_ROOT/.lavra/memory/knowledge.jsonl")
if [ "$LINE_COUNT" -gt 1000 ]; then
head -500 "$PROJECT_ROOT/.lavra/memory/knowledge.jsonl" >> "$PROJECT_ROOT/.lavra/memory/knowledge.archive.jsonl"
tail -n +501 "$PROJECT_ROOT/.lavra/memory/knowledge.jsonl" > "$PROJECT_ROOT/.lavra/memory/knowledge.jsonl.tmp"
mv "$PROJECT_ROOT/.lavra/memory/knowledge.jsonl.tmp" "$PROJECT_ROOT/.lavra/memory/knowledge.jsonl"
fi
### Step 7: Cross-Reference & Pattern Detection
If similar knowledge found in Step 3:
Add cross-reference tag: include the key of the related entry in the tags array (e.g., "tags": ["auth", "see-also:learned-oauth-token-expiry"]).
Detect recurring patterns: if 3+ entries share the same tags or describe similar issues, suggest creating a PATTERN entry that synthesizes the recurring theme:
Detected recurring pattern: 3 entries related to "auth" + "redirect"
Suggest creating a PATTERN entry?
1. Yes - create synthesized pattern entry
2. No - entries are distinct enough
Choose (1-2): _
</critical_sequence>
<decision_gate name="post-capture" wait_for_user="true">
After successful capture, present options and WAIT for user response:
Knowledge captured successfully.
Entries added:
- [key1]: [content summary]
- [key2]: [content summary]
Bead comments logged: [Yes/No - BD-XXX]
What's next?
1. Continue workflow (recommended)
2. View captured entries
3. Search related knowledge
4. Add more entries for this solution
5. Other
Handle responses:
Option 1: Return to calling skill/workflow. Capture is complete.
Option 2: Display the JSONL entries written. Present menu again.
Option 3: Run recall search with the new entry tags. Display related knowledge. Present menu again.
Option 4: Return to Step 4 to classify additional knowledge. Useful when the solution reveals multiple insights.
Option 5: Ask what they'd like to do.
</decision_gate>
<integration_protocol>
Invoked by: manual invocation after solution confirmed, confirmation phrases ("that worked", "it's fixed"), or called from /lavra-work and /lavra-review workflows.
Works with:
auto-recall.sh — reads knowledge.jsonl at session startmemory-capture.sh — captures knowledge from bd comments add commandsrecall.sh — manual searchData flow:
.lavra/memory/knowledge.jsonlbd comments add (triggers memory-capture.sh)auto-recall.sh searches and injects relevant entries</integration_protocol>
<success_criteria>
Capture is successful when ALL of the following are true:
.lavra/memory/knowledge.jsonlbd comments add (if bead ID available)</success_criteria>
Missing context: ask for missing details. Do not proceed until critical info is provided.
JSONL validation failure: show specific errors, present retry with corrected values. BLOCK until valid.
Missing bead ID: knowledge can still be captured to knowledge.jsonl. Skip bd comments add. Warn: "No active bead - knowledge saved to JSONL only, not linked to a bead."
knowledge.jsonl doesn't exist: create it with touch .lavra/memory/knowledge.jsonl and continue.
MUST do:
bd comments add with knowledge prefixes when bead ID is availableMUST NOT do:
docs/solutions/ (this is not compound-docs)Good entries have: specific, searchable content (exact error messages, specific techniques); appropriate type classification; relevant tags; clear cause-and-effect; prevention guidance where applicable.
Avoid: vague content ("something was wrong with auth"), missing technical details ("fixed the code"), overly broad tags ("code", "bug"), duplicate content across entries.
User: "That worked! The N+1 query is fixed."
Skill activates:
.includes(:items) on Order model{"key":"learned-n-plus-one-order-items-eager-load","type":"learned","content":"Order listing N+1 query fixed by adding .includes(:items) to Order model scope. Missing eager loading caused separate DB query per order item, taking >5 seconds for 100+ orders.","source":"agent","tags":["database","performance","n-plus-one","eager-loading"],"ts":1706918400,"bead":"BD-042"}
{"key":"pattern-always-check-eager-loading-on-associations","type":"pattern","content":"When listing parent records that display child data, always use .includes() for associations. Check with bullet gem or query logs. Without eager loading, N records = N+1 queries.","source":"agent","tags":["database","performance","n-plus-one","eager-loading","prevention"],"ts":1706918401,"bead":"BD-042"}
Valid..lavra/memory/knowledge.jsonlbd comments add BD-042 "LEARNED: Order listing N+1 query fixed by adding .includes(:items). Missing eager loading caused separate DB query per order item."
bd comments add BD-042 "PATTERN: When listing parent records that display child data, always use .includes() for associations. Check with bullet gem or query logs."
Output:
Knowledge captured successfully.
Entries added:
- learned-n-plus-one-order-items-eager-load: Order listing N+1 query fixed by adding .includes(:items)...
- pattern-always-check-eager-loading-on-associations: When listing parent records...
Bead comments logged: Yes - BD-042
What's next?
1. Continue workflow (recommended)
2. View captured entries
3. Search related knowledge
4. Add more entries for this solution
5. Other