sage-self-learning

# Self-Learning Learn from mistakes. Don't repeat them. Captures what went wrong, what was non-obvious, and what the agent should do differently. Every learning includes a **prevention rule** — a forward-looking instruction that changes future behavior. **Part of the unified knowledge system.** Self-learning stores through sage-memory (or files) with the `self-learning` tag / `learning` type. During recall, learnings surface as warnings alongside regular knowledge. ## Capabilities by Backend | Capability | MCP | Files | |------------|-----|-------| | Store learnings | ✅ `sage_memory_store` | ✅ `.sage-memory/lrn-*.md` files | | Search learnings | ✅ BM25 + `filter_tags` | ⚠️ scan `lrn-` files by name | | Update learnings | ✅ `sage_memory_update` | ✅ edit file | | Delete learnings | ✅ `sage_memory_delete` | ✅ delete file | | Browse by type | ✅ `sage_memory_list` | ✅ scan `lrn-` files | | Link to entities | ✅ `sage_memory_link` | ⚠️ `relations:` frontmatter (see sage-ontology skill) | | Multi-hop graph recall | ✅ `sage_memory_graph` | ❌ single-hop scan only | | Namespace isolation | ✅ `filter_tags` | ✅ `lrn-` filename prefix | **How to detect backend:** At session start, call `sage_memory_set_project` with the project root. If it responds, use MCP. If not, use `.sage-memory/` files. ## Recall: Search Before You Work At task start, search for learnings relevant to the current task. ### With MCP **Basic recall (keyword):** ``` sage_memory_search( query: "<task-relevant keywords>", filter_tags: ["self-learning"], limit: 5 ) ``` Always include `filter_tags: ["self-learning"]` — this excludes all non-learning entries. **Targeted recall (graph-based):** When you know the current task's ontology entity ID: ``` sage_memory_graph( id: "<task_entity_memory_id>", relation: "applies_to", direction: "inbound", depth: 1 ) ``` Returns learnings explicitly linked to this task — more precise than keyword search. **Hot spot detection:** ``` sage_memory_graph( id: "<module_entity_id>", relation: "applies_to", direction: "inbound", depth: 1 ) ``` If 5+ linked learnings → flag the area as mistake-prone. ### With Files Scan `.sage-memory/` for `lrn-` prefixed files. Read filenames and identify those relevant to the current task. Read matching files for their prevention rules. For a broad search: list all `lrn-*.md` files and scan names. For a focused search: look for keywords in filenames like `lrn-stripe-webhook-*.md` when working on Stripe webhooks. ### Reporting When learnings are found, report the **prevention rule**, not the incident. Say: "Before working with Stripe webhooks, verify that body parsing middleware is skipped for the webhook route." When nothing is found, say nothing. ## Capture: Detect and Store ### Five Learning Types | Type | Trigger | |------|---------| | `gotcha` | Non-obvious behavior discovered through debugging | | `correction` | User corrected the agent | | `convention` | Undocumented project/team pattern discovered | | `api-drift` | API/library behaves differently than expected | | `error-fix` | Recurring error with a known solution | ### How to Store **Title:** `[LRN:<type>] <specific description>` **Content:** Four-part structure: 1. **What happened** — the symptom 2. **Why it was wrong** — root cause 3. **What's correct** — the right approach 4. **Prevention** — what to check BEFORE this happens again **With MCP:** ``` sage_memory_store( title: "[LRN:gotcha] Stripe webhook requires raw body before JSON parsing", content: "What happened: Webhook signature verification failed with 400. Why: Express body parser replaced raw body with parsed JSON. What's correct: Use express.raw() for the webhook route. Prevention: Before implementing any webhook handler that verifies signatures, check whether the SDK requires the raw request body.", tags: ["self-learning", "gotcha", "stripe", "webhooks"], entities: [ {name: "Stripe", type: "TECHNOLOGY"}, {name: "Express", type: "TECHNOLOGY"} ], scope: "project" ) ``` **Extract Before Store (0.9+).** Pass an `entities` array naming the technologies, services, or modules the learning is about. The Prevention line in particular should usually reference a real entity (library, service, module) so future graph traversal from that entity surfaces this learning. Optional `relations` array if the learning connects two entities (e.g., `{from: "Express", to: "Stripe", rel: "contradicts"}` for a body-parser/signature-verification conflict). **With files:** ``` File: .sage-memory/lrn-stripe-webhook-raw-body.md --- tags: [self-learning, gotcha, stripe, webhooks] type: learning scope: project created: 2026-03-20 --- [LRN:gotcha] Stripe webhook requires raw body before JSON parsing What happened: Webhook signature verification failed with 400 "No signatures found matching the expected signature." Why: Express body parser replaced raw body with parsed JSON before the Stripe SDK could verify the signature. What's correct: Use express.raw({type: 'application/json'}) middleware for the webhook route, before the global body parser. Prevention: Before implementing any webhook handler that verifies signatures (Stripe, GitHub, Twilio), check whether the SDK requires the raw request body. If yes, ensure body parsing middleware is skipped or deferred for that route. ``` ### Link to Ontology Entities (MCP only) After storing a learning, link it to the relevant entity: ``` sage_memory_link( source_id: "<learning_memory_id>", target_id: "<task_or_module_entity_id>", relation: "applies_to" ) ``` **With files:** Skip linking. Mention the related entity in the content if the connection is important: "Related entity: task_a1b2 (Fix payment timeout)." ### Link to Code Symbols (0.11+ Codebase Scan) When a learning applies to a SPECIFIC function or class — not just "the payment system" but `PaymentOrchestrator.charge` on line 47 — link it to the actual symbol so the recall surfaces during code work on that exact symbol. **Detect availability:** if `sage-memory scan-codebase --help` exits 0 and a recent scan has run, code-symbol memories exist in the project DB. **Workflow:** 1. **Find the symbol's memory id:** ``` sage_memory_search( query: "PaymentOrchestrator.charge", filter_tags: ["codebase"], limit: 3 ) ``` The file-memory result's `id` field is the parent for all symbols in that file. For symbol-level linkage, query `code_symbols` directly via the MCP search (filter on the qualified name in tags or content), or accept the file-level link as the v1 granularity. 2. **Link the learning to the file memory:** ``` sage_memory_link( source_id: "<learning_memory_id>", target_id: "<file_memory_id>", relation: "applies_to" ) ``` 3. **Future recall:** when an agent works on the same file, the graph channel surfaces this learning even if the query doesn't mention the file by name — entity-mediated proximity at work. **Why bother:** "show me past mistakes on `PaymentOrchestrator`" is the single most valuable self-learning query, and it ONLY works when learnings are linked to the code structure, not just to free-text file paths that drift when files move. **With files:** Skip — relative paths in prose go stale; the file-memory id is stable across renames as long as content_hash doesn't change. Without MCP, document the path in the content and re-find the file each session. ### When a Learning Causes a Bug When you follow a stored self-learning entry and it leads to incorrect behavior (wrong library, outdated pattern, contradicted convention): 1. **Store a NEW learning** (type: `correction`) describing what the original said, why it's now wrong, and what the correct approach is. 2. **Invalidate the original:** ``` sage_memory_update(id: "<original_id>", status: "invalidated") ``` 3. **Link the correction to the original:** ``` sage_memory_link( source_id: "<correction_id>", target_id: "<original_id>", relation: "corrects" ) ``` The original learning will never appear in search again. The correction replaces it as active knowledge. The graph edge preserves the audit trail. **With files:** Rename the original file to `lrn-INVALID-<name>.md` and add `status: invalidated` to its frontmatter. Create the correction as a new file. ### When a memory is a paraphrase of an older one (0.12.0+) When `sage_memory_store` returns a `suggested_links` entry with `confidence: "near_duplicate"`, the new content is a semantic paraphrase of an existing memory (cosine similarity ≥ 0.95 against the existing memory's embedding). Decide one of: - **Link via `supersedes`** if the new wording is more accurate or current: ``` sage_memory_link( source_id: "<new_id>", target_id: "<older_id>", relation: "supersedes" ) ``` Future `sage_memory_search` results will surface the older memory with `superseded_by: <new_id>` so agents can prefer the newer one. The older memory is NOT filtered or down-ranked — transparency over silent hiding. - **Merge content** if the old phrasing carries useful detail the new one lost: `sage_memory_update(id: "<older_id>", content: "<merged_text>")` then `sage_memory_delete(id: "<new_id>")`. - **Keep both** if they cover meaningfully different angles (rare at cosine ≥ 0.95). No action needed; both stay active. **`supersedes` vs `corrects` — pick the right one:** - `corrects` + `status: invalidated` (see "When a Learning Causes a Bug" above) is for memories that are *factually wrong* — outdated library names, broken patterns, contradicted conventions. The original is hidden from future search. - `supersedes` is for *semantic paraphrase* where both versions are valid but the newer is preferred. Both stay visible; the older carries a pointer to the newer. ### Search Before Store (Semantic Reinforcement) Before creating a new learning, check for existing similar learnings: 1. Search with the new learning's core content: ``` sage_memory_search( query: "<what_happened + prevention_rule>", filter_tags: ["self-learning"], limit: 3 ) ``` 2. If the top result describes the **same root cause and same prevention**: - Do NOT create a new entry - Update the existing entry with any new details: ``` sage_memory_update(id: "<existing_id>", content: "<merged content>") ``` - The access_count bump from the search already signals reinforcement 3. If no strong match → store as new. Why: Three entries saying "check middleware order" waste search slots. One entry that gets richer over time is more useful. **With files:** Scan `lrn-*.md` filenames for similar topics. If a match exists, edit that file instead of creating a new one. ### When NOT to Store Ask: "Would this change how I approach a future task?" - **No** → don't store - **Yes** → store **Budget:** 2-5 learnings per significant task. ## Review: Curate and Improve Triggered by "sage review" or "review learnings." ### With MCP 1. **Inventory** — `sage_memory_list(tags: ["self-learning"])` → all learnings 2. **By type** — `sage_memory_list(tags: ["self-learning", "gotcha"])` etc. 3. **Stale check** — flag learnings about changed code or outdated APIs 4. **Consolidate** — merge 3+ similar → store consolidated → link to same entities → delete originals 5. **Promote** — identify learnings for scope escalation 6. **Hot spots** — `sage_memory_graph` on key entities → count inbound `applies_to` edges → report most mistake-prone areas ### With Files 1. **Inventory** — list all `lrn-*.md` files 2. **By type** — read frontmatter to group by type tag 3. **Stale check** — check creation dates, read content for outdated refs 4. **Consolidate** — manually merge file contents → create new file → delete originals 5. **Promote** — identify candidates, create global-scope copy 6. **Hot spots** — count `lrn-*.md` files by domain keyword in filename ## Promote: Scope Escalation **Project → Global:** Learning applies beyond this codebase. Store a context-independent version at global scope. **With MCP:** `sage_memory_store(..., scope: "global")` **With files:** Copy to `~/.sage-memory/` (global directory), remove project-specific details. **Global → Team:** Export to a shared file in the repo. **Read:** `references/team-sharing.md`. **Read:** `references/promotion-rules.md` for criteria. ## Quality Principles **Prevention over documentation.** Every learning answers: "What should I check before this happens again?" **Specificity retrieves.** `[LRN:gotcha] Stripe webhook requires raw body` retrieves. `[LRN:gotcha] API issue` does not. **Freshness matters.** Update or delete when code changes make a learning obsolete. **Learnings are not memories.** "Billing uses saga pattern" is a memory. "Agent assumed REST, broke the compensation chain" is a learning. ## References - `references/capture-patterns.md` — Triggers, examples, prevention rules - `references/storage-conventions.md` — Format conventions - `references/promotion-rules.md` — Scope escalation criteria - `references/team-sharing.md` — Export formats for teams - `references/review-workflow.md` — Curation process - `references/examples.md` — End-to-end scenarios - `references/ontology-integration.md` — Graph integration