🧠 aprende

Turn every conversation into durable knowledge.

A community skill for Claude Code and Codex that helps your agent learn from its mistakes — and never repeat them.

🌎  Read in Español →

Install · Usage · How it works · FAQ · Contributing · tododeia.com

⚡ 30-second pitch

You correct your agent. The session ends. Next week, you correct
it again on the exact same thing. aprende fixes that. Type /aprende
at the end of a session — it scans the conversation, surfaces every
correction worth preserving, asks you which to keep, and writes them
where your agent will find them next time. Reflexion-style anti-patterns,
confirmation-first writes, cross-tool (Claude Code + Codex), bilingual.

You:  /aprende

aprende:
  Found 3 candidate learnings from this conversation.

   1. [project-doc] Use pnpm, not npm — user said "this repo uses pnpm"  (high)
   2. [lesson]      localStorage fails in purchase WebView — use IndexedDB  (high)
   3. [memory]      User prefers explicit error messages in tests  (medium)

  >

You:  1,2

aprende:
  ✓ project  → ./CLAUDE.md + ./AGENTS.md  (## Commands)
  ✓ lesson   → ~/.claude/projects/.../lesson_webview-localstorage.md
  Captured 2 learnings. Run /aprende --review next month to prune.

Why this exists

Coding agents repeat the same mistakes across sessions. The
corrections you make in one chat — "no, this repo uses pnpm", "always
add using and with check to RLS policies" — evaporate when the
session ends. You correct the agent. Next week, you correct it again. And
again. aprende fixes that. After each session, you run /aprende. It
surfaces what was worth learning. You pick what to keep. It writes it
where the agent will find it next time.

The four categories

The lesson category is the one that compounds. Following the Reflexion
paper, every lesson must answer four
questions:

**What happened:** ...
**Why it happened:** ...
**How to avoid:** ...
**Detection signal:** ...

Install

Option 1 — Plugin (recommended)

From inside Claude Code:

/plugin marketplace add Hainrixz/aprende-skill
/plugin install aprende@aprende-skill

That's it. The skill and its hooks are wired up automatically. Hooks are
on by default (see disclosure below).

Option 2 — Manual

Clone the repo and copy the skill folder:

git clone https://github.com/Hainrixz/aprende-skill.git
cp -r aprende-skill/skills/aprende ~/.claude/skills/
cp -r aprende-skill/skills/learn ~/.claude/skills/   # English alias (optional)

To enable the hooks (optional):

# Copy the handlers somewhere stable:
mkdir -p ~/.claude/aprende-hooks
cp aprende-skill/hooks-handlers/*.sh ~/.claude/aprende-hooks/
chmod +x ~/.claude/aprende-hooks/*.sh

Then in a Claude Code session, run /aprende-enable-hooks — it will
splice the hook entries into ~/.claude/settings.json. You'll need to
replace ${CLAUDE_PLUGIN_ROOT} with ~/.claude/aprende-hooks in those
entries since manual install doesn't set that env var. The README walks
through the exact JSON to paste.

Usage

Example session

You:  /aprende

aprende:
  Found 3 candidate learnings from this conversation.

  Reply with: numbers, "all", "none", or "edit N: <text>" / "drop low" / "skip N".

   1. [project-doc] Use pnpm, not npm — user said "this repo uses pnpm"  (high)
   2. [lesson]      localStorage fails in purchase WebView — use IndexedDB  (high)
   3. [memory]      User prefers explicit error messages in tests  (medium)

  >

You:  1,2

aprende:
  ✓ project  → ./CLAUDE.md + ./AGENTS.md  (## Commands)
  ✓ lesson   → ~/.claude/projects/.../lesson_webview-localstorage.md  (+MEMORY.md)

  Captured 2 learnings. Run /aprende --review next month to prune.

Hooks (ON by default) — disclosure

When installed via the plugin, two hooks are active from the
moment you install:

• PostToolUse — after every Bash / Edit / Write tool call, a small
  bash script (capture-signal.sh) inspects the result. If it sees a
  non-zero exit code, an error message, or the same file edited 3+ times,
  it appends a one-line record to
  ~/.claude/projects/<slug>/.aprende-signals.md. It never writes a
  learning. It only accumulates signals for /aprende to read later.
• Stop — at session end, if signals were captured and you didn't
  run /aprende, a small bash script (stop-suggest.sh) emits a
  one-line reminder asking you to run it. It also never writes a
  learning.

Both hooks are bilingual in their messages, run in <50ms, and exit cleanly
on any error so they never block your work.

To disable: /aprende-disable-hooks (removes the entries from
~/.claude/settings.json — keeps a backup).

Cross-tool: Claude Code + Codex

aprende is designed to work in both ecosystems:

• project-doc writes always dual-write to CLAUDE.md and
  AGENTS.md. Same content both files. Claude Code reads the first,
  Codex reads the second.
• For lessons and memories, use /aprende --portable to also mirror
  to ./.aprende/lessons/ in the project root, with a flat
  ./.aprende/index.md that Codex can read via a one-line directive
  auto-added to AGENTS.md.
• The skill itself is plain Markdown + YAML — any agent that
  understands the agentskills.io convention can
  invoke it.

Storage map

~/.claude/
├── projects/
│   └── -Users-you-path-to-project/
│       └── memory/
│           ├── MEMORY.md                    # index
│           ├── feedback_pnpm-over-npm.md    # type: feedback
│           ├── project_supabase-rls.md      # type: project
│           ├── lesson_webview-storage.md    # type: lesson (Reflexion-style)
│           └── ...
├── skills/
│   ├── aprende/        # the skill (workflow)
│   ├── learn/          # English alias
│   └── ...             # any skills /aprende drafted as stubs
└── settings.json       # hook config (after /aprende-enable-hooks)

<your-project>/
├── CLAUDE.md           # for Claude Code
├── AGENTS.md           # for Codex (dual-written, same content)
└── .aprende/           # only if --portable was used
    ├── index.md
    └── lessons/
        └── ...

Design principles

1. Confirmation-first. Nothing writes to disk until you say which
   items to keep. The skill repeats this rule three times internally.
2. Prefer false negatives. A wrong rule locked into memory is worse
   than repeating a correction three times. Confidence labels are
   mandatory.
3. Annotate overlaps, don't drop. When a candidate looks like a
   duplicate, the skill flags it [overlaps with: ...] and lets you
   decide.
4. Retire, don't delete. Outdated lessons get status: retired,
   not rm. Audit trail matters.
5. Reflexion over logging. Lessons capture why a mistake happened,
   not just what. That's where the +20% lift
   comes from.
6. Hooks are advisory, not authoritative. Hooks only accumulate
   signals and remind you. They never write learnings.
7. Hard cap at 15 candidates per run. Forces focus.

FAQ

Q: Won't my memory folder fill with junk?
A: Three guardrails prevent it: (a) confidence labels make you filter,
(b) dedup annotates overlaps before showing the list, (c) /aprende --review lets you prune monthly.

Q: Does this work with Codex?
A: Yes. project-doc writes go to both CLAUDE.md and AGENTS.md. For
lessons, use /aprende --portable to mirror them into ./.aprende/.

Q: Can the agent learn automatically without me running /aprende?
A: No. By design. Automatic capture is the failure mode that locks in
false positives. The hooks remind you to run /aprende but never write
on their own.

Q: How is this different from claude-mem / claude-reflect?
A: aprende is intentionally simpler: no SQLite, no embeddings, no MCP
server. Plain Markdown + bilingual workflow + Reflexion-style lesson
format. It plugs into the user's existing memory folder convention
instead of standing up a parallel store. If you need embeddings/vector
search, use claude-mem —
it's the most battle-hardened in that space.

Contributing

Issues, PRs, and lesson contributions welcome. Especially:

• Better signal patterns in signal-patterns.md (any language).
• Real lessons from your sessions — anonymized examples that show
  the four-section format working well.
• Bug reports — specifically, false positives that slipped past
  confirmation (those are the hardest to catch).

See CONTRIBUTING.md for the full guide.

Credits

Built on patterns from:

• Reflexion (Shinn et al., 2023) —
  the "linguistic post-mortem" pattern.
• Hermes Agent (Nous Research) —
  the "synthesize skills from recurring workflows" idea.
• claude-reflect —
  confidence scoring against false positives.
• claude-mem —
  hook-driven capture pattern.
• The Claude Code memory system — aprende extends the existing
  per-project memory convention rather than replacing it.

Mascot and hero art generated with Higgsfield
(Nano Banana Pro) from a pixel-art reference designed for this project.

License

MIT — see LICENSE.