Skip to main content
skill CX Codex

capy-cortex — Claude Code skill: agent memory that learns from errors

capy-cortex keeps a local base of rules, anti-patterns and preferences, then feeds the matching ones into context through hooks. Useful when an agent keeps repeating the same mistakes.

MIT ★ 138 updated 2026-09-03

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add happycapy-ai/Happycapy-skills --skill capy-cortex -a claude-code
Open on GitHub

What capy-cortex does

Under the hood it is a local SQLite file with an FTS5 index plus a TF-IDF model built with sklearn. Hooks read from it without being asked: session start brings in anti-patterns, preferences and principles, and each prompt pulls rules that match the current task.

Learning happens while you work. A failed tool call is filed as an anti-pattern, the Stop hook mines the conversation for corrections and preferences, reflect.py goes through session transcripts, consolidate.py clusters similar rules into principles, decay fades the ones nobody reinforced. The PreToolUse(Bash) hook also blocks bash commands it has been taught to treat as dangerous, which changes agent behaviour beyond memory alone.

Everything runs through python3, and the database sits at ~/.claude/skills/capy-cortex/cortex.db. Clustering depends on sklearn, so that library has to be present in the same Python environment or consolidate.py fails. Hooks fire on their own; calling them by hand is not part of the flow.

What it helps with

  • stop the agent from repeating a command that already failed
  • pull stack-specific rules before starting a task
  • turn scattered user corrections into general principles
  • block a bash command the agent has broken things with
  • inspect what the knowledge base has collected so far

Example prompts for the agent

  • Show me which rules you already have for React and TypeScript
  • Add an anti-pattern: never force push to main
  • Run consolidation and list the principles it produced

How to install capy-cortex

1Skills CLI (Vercel)

npx skills add happycapy-ai/Happycapy-skills --skill capy-cortex -a claude-code

2Manually: put the files in place

~/.claude/skills/capy-cortex/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/capy-cortex/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about capy-cortex

How do I install capy-cortex in Claude Code?

Run npx skills add happycapy-ai/Happycapy-skills --skill capy-cortex -a claude-code. The skill then sits at ~/.claude/skills/capy-cortex/SKILL.md.

What does capy-cortex do?

It stores rules, preferences and anti-patterns in SQLite and loads the relevant ones through hooks. Errors and corrections from the conversation end up in that store too.

What does rule consolidation need?

consolidate.py clusters entries with sklearn, so the library must live in the same Python environment as the other scripts. Without it the consolidation step does not run.

Source text

SKILL.md · MIT
---
name: capy-cortex
description: "Autonomous learning system - learns from mistakes, reflects on sessions, and gets smarter over time. The AI brain."
---

# Capy Cortex - Autonomous Learning System

You have a persistent learning brain powered by SQLite + FTS5 + sklearn TF-IDF.
Knowledge is automatically loaded via hooks. This file describes manual operations.

## Architecture

- **Database**: `~/.claude/skills/capy-cortex/cortex.db` (SQLite + FTS5 + WAL)
- **Hooks** (automatic, never call manually):
  - SessionStart: Loads anti-patterns, preferences, principles
  - UserPromptSubmit: Retrieves task-relevant rules via FTS5
  - PreToolUse(Bash): Blocks known dangerous commands
  - PostToolUseFailure: Records errors as anti-patterns
  - Stop: Extracts corrections and preferences from conversation
- **Scripts** (for manual/scheduled use):
  - `cortex.py`: Core engine (retrieve, add rules, stats)
  - `reflect.py`: Deep session analysis
  - `consolidate.py`: Cluster rules into principles (sklearn)
  - `bootstrap.py`: Mine historical sessions

## Manual Commands

```bash
# Check system health
python3 ~/.claude/skills/capy-cortex/scripts/cortex.py stats

# Retrieve rules for a topic
python3 ~/.claude/skills/capy-cortex/scripts/cortex.py retrieve "react typescript"

# Add a rule manually
python3 ~/.claude/skills/capy-cortex/scripts/cortex.py add-rule "Always use TypeScript strict mode" "best_practice"

# Add an anti-pattern
python3 ~/.claude/skills/capy-cortex/scripts/cortex.py add-ap "Never force push to main" "critical"

# Add a preference
python3 ~/.claude/skills/capy-cortex/scripts/cortex.py add-pref "User prefers functional components over class components"

# Run consolidation (clusters rules into principles)
python3 ~/.claude/skills/capy-cortex/scripts/consolidate.py

# Retrain TF-IDF model
python3 ~/.claude/skills/capy-cortex/scripts/cortex.py retrain

# Apply confidence decay
python3 ~/.claude/skills/capy-cortex/scripts/cortex.py decay
```

## How It Learns

1. **Automatic** (via hooks): Errors are captured, corrections noted, preferences extracted
2. **Reflection**: Deep analysis of session transcripts extracts patterns
3. **Consolidation**: sklearn clustering groups similar rules into principles
4. **Decay**: Old, unreinforced rules fade; validated rules strengthen
5. **Retrieval**: Two-stage FTS5 + TF-IDF returns only relevant knowledge (O(1) context)

© happycapy-ai · MIT · happycapy-ai/Happycapy-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set41

The whole set →
video-frames video-frames pulls frames and thumbnails from video files using ffmpeg. It helps Claude Code inspect video contents or grab screenshots at specific timestamps. CX Codex +1 ★ 138repo stars weather Fetches current conditions and forecasts for a city or airport. It works for quick answers and JSON-based weather requests. CX Codex +1 ★ 138repo stars oss-contributor-swarm oss-contributor-swarm deploys an autonomous 9-agent swarm to discover simple GitHub issues, write fixes, and submit pull requests. CX Codex +1 ★ 138repo stars llm-council llm-council is a Claude Code skill that sends one prompt to several AI models and displays their replies side by side, with shared-answer synthesis and anonymous voting. CX Codex +1 ★ 138repo stars happycapy-skill-creator happycapy-skill-creator adapts existing skills from anthropics/skills for HappyCapy environments. It strips Docker dependencies and bundles the result into a .skill archive. CX Codex +1 ★ 138repo stars youtube-music Search YouTube Music by track or artist, then open a result in the default browser. It needs an API key and MCP configuration. CX Codex +1 ★ 138repo stars agent-4-code-writer agent-4-code-writer — a Claude Code subagent that implements fixes or features within an open-source contributor swarm using an existing issue plan and codebase map. CX Codex ★ 138repo stars agent-3-codebase-explorer agent-3-codebase-explorer explores a repository before a fix or feature, locating relevant files and documenting the project structure for the next agents. CX Codex ★ 138repo stars

Project sponsors

Companies that keep this analytics open