learned-behavior
Self-improving memory for AI coding agents (Claude Code, Codex, Copilot).
Observes what your agent does, distills recurring patterns into lessons, surfaces the relevant ones before each task, and auto-promotes rules that keep proving themselves while decaying stale ones.
No self-report. No LLM in the loop. Pure behavioral signal mined from agent hook events.
What it isn't
- Not a coding-style linter — it doesn't read your code, only your agent's tool calls.
- Not a context-window manager or summarizer — lessons are short rules, not session memory.
- Not cloud-hosted — all storage and processing is local SQLite. Nothing leaves your machine.
What it captures
- Repeated failures — same error pattern recurring across sessions
- Skill bypasses — raw
aws logs when a casino-logs skill is available, raw kubectl when a k3s skill is available, etc. (project-configurable)
- Repeated Edit self-corrections — the agent keeps writing
X and replacing it with Y; the rule should be "write Y directly next time"
- PreToolUse blocks — every time a guard denies a command, we record it. Recurring blocks surface training gaps.
What it produces
A durable, project-scoped list of rules your agents see before their next task:
$ learned-behavior advice --workspace "$PWD"
1. laravelphp/vapor image has no bash — use `sh -c`, not `bash -lc`
2. After composer install on a new worktree, run `php artisan package:discover`
3. Never --force-push to production/staging — use --force-with-lease on feature branches only
How it improves itself
Every lesson has a confidence score and a status (candidate → approved → dormant).
- Promotion: candidates with ≥ N observations over ≥ M days with no contradicting signal graduate to
approved.
- Decay: approved lessons whose pattern hasn't been seen in X days lose confidence, eventually going
dormant and dropping out of advice.
- Reinforcement: when a lesson is surfaced and the warned-about pattern doesn't recur in that session, confidence ticks up.
Run learned-behavior promote and learned-behavior decay nightly (or via a cron/Stop hook) and the corpus gets better without human curation.
Requirements
- Python 3.10+ (uses PEP 604 union syntax and built-in generic type parameters)
- SQLite 3 (ships with Python's
sqlite3 module)
- No third-party runtime dependencies
Privacy
- No network calls. The plugin never reaches out to any server — no telemetry, no analytics, no phone-home, no auto-update check.
- No data leaves your machine. Everything is stored in one local SQLite file at
~/.local/share/learned-behavior/learning.db (or $LEARNED_BEHAVIOR_HOME).
- No third parties. Zero runtime dependencies; nothing to ship your data to even if it tried.
- You own the data. Delete the SQLite file at any time and the plugin starts fresh. See Disable / uninstall.
There is no separate privacy policy because there is nothing to disclose beyond the above. Full technical detail of every file touched and every hook registered is in the next section.
Side effects & permissions
Full disclosure of everything the plugin touches on your machine:
- Hooks registered:
SessionStart, UserPromptSubmit, PostToolUse *, Stop, SessionEnd — all invoke python3 ${CLAUDE_PLUGIN_ROOT}/learning.py <subcommand>. Each call has a short timeout (3–5s) and fails open.
- Files written: one SQLite DB at
~/.local/share/learned-behavior/learning.db (or $LEARNED_BEHAVIOR_HOME if set). Nothing else is created or modified outside that directory.
- Network: none. No telemetry, no outbound requests, no phone-home. All processing is local.
- Execution surface: the CLI reads stdin/argv, queries/writes the SQLite DB, prints JSON or text to stdout. It does not spawn subprocesses, shell out, or touch files outside its own data dir.
- Destructive subcommands:
promote, decay, reinforce, maintain default to dry-run. They only mutate the DB when you pass --write.
- Trust boundary:
observe records hook payloads into SQLite verbatim. If you don't want a particular command or path recorded, don't run it while hooks are active.
Disable / uninstall
