Capture Learning

Capture Learning (v2 — Memory Graph)

When to invoke

• Bug resolved with non-obvious root cause
• Pattern discovered that applies beyond this one case
• User corrected your approach
• Solution took 2+ attempts to get right
• Framework or library quirk discovered

Do NOT invoke for: typos, missing imports, obvious variable errors, one-off config.

Protocol

Step 1 — Choose memory type

Step 2 — Choose associated skill

Step 3 — Validate before saving

Before writing, verify ALL of these:

1. context is filled: "In [technology/version], when [specific situation]..."
2. problem describes what went wrong or was unclear
3. solution is at least 10 words and actionable (no absolute file paths)
4. reason explains WHY (not just restates the solution)
5. tags has between 2 and 5 lowercase kebab-case items
6. If type: AntiPattern then confidence should start at 1

Step 4 — Save to Memory Graph

Use the memory_add MCP tool:

memory_add({
  type: "Pattern",
  context: "In Next.js 15 App Router with next-intl, when configuring i18n...",
  problem: "Middleware ordering caused locale not to be detected",
  solution: "Place next-intl middleware before auth middleware in the chain...",
  reason: "next-intl needs to extract locale from URL before auth redirects happen",
  tags: ["next-intl", "middleware", "i18n", "next-js"],
  confidence: 1,
  importance: 5,
  scope: "global",
  skill: "next-best-practices",
  repo: "skillbrain"
})

The tool automatically:

• Generates a unique ID (e.g., M-pattern-a1b2c3d4e5f6)
• Populates full-text search index
• Detects potential contradictions with existing memories

Step 5 — Handle contradictions

If memory_add reports contradictions:

⚠️ Potential contradiction with M-bugfix-xxx: "In Next.js..."

Surface to the user:

CONFLICT DETECTED
New:      "{summary}" [tags: ...]
Existing: M-xxx "{summary}" — confidence: N

A) New supersedes old → create Updates edge
B) Both valid with different scope → keep both
C) Cancel new memory

If the user chooses A:

memory_add_edge({
  sourceId: "M-new-xxx",
  targetId: "M-old-xxx",
  type: "Updates",
  reason: "New approach replaces previous solution"
})

Step 6 — Confirm

✅ Memory captured: M-{type}-{id}
   Type: {type} | Confidence: 1 | Scope: {scope}
   Tags: {tags}
   Stored in: Memory Graph (SQLite)

Step 7 — Create edges (optional but valuable)

If the new memory relates to existing ones:

memory_add_edge({sourceId: "M-new", targetId: "M-related", type: "RelatedTo"})
memory_add_edge({sourceId: "M-new", targetId: "M-cause", type: "CausedBy"})
memory_add_edge({sourceId: "M-new", targetId: "M-parent", type: "PartOf"})

Edge Types

Multi-agent safety

If running as a subagent, write to temp file instead:

/path/.agents/skills/_pending/learning-{date}-{random}.yml

The parent agent or post-session-review will merge these via memory_add at session end.

Legacy compatibility

Old learnings.md files have been migrated to the Memory Graph via:

node packages/codegraph/dist/cli.js migrate-learnings .

The markdown files remain as read-only backups. All new learnings go to SQLite.