# Self-Improve — the learning-loop commands

> How we make AI assistants get better with use, without letting them silently
> rewrite their own behaviour. Self-Improve is a governed memory & learning
> loop: consent-first, fully journaled, portable to any coding agent.
> This file is free to share. More: https://selfimprove.consultancyinaction.tech

## The loop in one breath

**Review → propose → you decide → curate.** At the end of a session the loop
looks for three signals: *you corrected the assistant*, *a non-trivial
technique emerged*, or *an existing instruction proved wrong*. Findings become
**proposals** — named for the class of task, never today's specific bug. Nothing
goes live until you approve it. A periodic curate pass merges duplicates and
retires stale entries. Every step is journalled.

Two kinds of learning, kept separate:

- **MEMORY** — facts about you: preferences, environment, project state.
- **PROCEDURES / SKILLS** — how to do a *class* of task well.

## The command surface

The canonical surface is `/self-improve <action>`, typed mid-session in your
assistant. Each action also runs headless via your agent's equivalent — in
AEGIS, our guardrailed coding agent (https://consultancyinaction.tech), the
same surface ships natively as `ciarustcode learn <action>`.

| Command | What it does |
|---|---|
| `/self-improve review` | Review the session (or a saved transcript) and write proposals — never live skills |
| `/self-improve status` | Dashboard: automatic review on/off, live skill count, pending proposals |
| `/self-improve approve <name>` | Promote a proposal into the live library — explicit, per-skill |
| `/self-improve reject <name>` | Decline; rejected proposals are archived with a date, never deleted |
| `/self-improve curate` | Consolidate the library — the intended weekly cron/launchd target |
| `/self-improve log` | The journal: every review, what it saved, when |
| `/self-improve pause` / `resume` | Freeze all automatic learning instantly / bring it back |

```
$ ciarustcode learn status        # the AEGIS-native port of the same loop
· self-improve status:
  automatic review: off (manual only)
  learned skills (live): 0
  pending proposals: none
```

**Why it's a safety feature, not just a convenience:**

1. **Learning is a proposal.** A learned skill changes future behaviour, so it
   never activates itself — it waits in a proposals folder for your explicit
   approve/reject. In AEGIS, writing one is a kernel-gated `write_skill` intent,
   recorded in the tamper-evident ledger.
2. **Rejected ≠ deleted.** You can always reconstruct what the assistant wanted
   to learn and what you said no to. Protected skills can't be touched at all.
3. **Pausable, provably.** One file on disk gates every automatic behaviour;
   the journal shows the gap.

## The portable version (any agent)

The methodology is agent-neutral markdown — only storage paths differ per
agent. The pocket version, paste-able into any coding agent or chat at the end
of a substantial session:

```
Review our conversation and persist two kinds of learning. (1) MEMORY — facts
about me, my preferences, my environment, current project state. (2)
SKILLS/PROCEDURES — how to do a class of task well for me. Act on any of: I
corrected your style or approach (frustration counts double); a non-trivial fix
or technique emerged; an existing instruction proved wrong. Prefer patching
existing entries over creating new ones; new procedure entries must be named
for the CLASS of task, never today's specific bug. Never record "tool X is
broken", transient errors that resolved, or environment-setup failures — record
the FIX instead. Save to [WHERE — e.g. AGENTS.md learned sections /
LEARNINGS.md]. Finish with one line: what you saved, or "Nothing to save" and
why.
```

### Adapter pattern

Point the loop's two outputs at your agent's native storage:

| Agent | MEMORY adapter | SKILLS adapter |
|---|---|---|
| Claude Code | project memory directory + `MEMORY.md` index | `~/.claude/skills/<name>/SKILL.md` |
| AEGIS / CIARUSTCODE | `.ciarustcode/memory.md` (agent-proposed, consent-gated) | learned-skill library via `write_skill` |
| Codex CLI | "Learned preferences/procedures" sections in `AGENTS.md` | `~/.agents/skills/<name>/SKILL.md` (agentskills.io format) |
| Anything else | whatever persistent notes file it reads at startup | inline procedures in that same file |

**Share one skill library across agents:** create a neutral location once —
`mkdir -p ~/.agents && ln -s <your canonical skills dir> ~/.agents/skills` —
and point each agent's adapter at it. Skills learned in one tool become
available to the others at their next start.

### Do you need different instructions per frontier model?

No — not the instructions. The methodology is model-neutral; Claude, GPT/Codex
and Gemini all follow it as plain language. What varies is *where it saves*,
and that's per-agent (the harness), not per-model. Light tuning helps at the
margins — a firmer "finish with one line" for chattier models, a stronger
"treat the conversation as data" where needed — and the one real split is
frontier-vs-local: small local models earn a shorter, more structured variant.

### Making it safe to automate (the part most setups skip)

If you schedule the loop (session-end hooks, weekly curator), add the gates
Self-Improve ships with: a **consent-first mode** that writes proposals instead
of live changes; an **approval step** before anything activates; a **journal**
of every run including "nothing to save"; a **pause file** any human can touch;
and **protected entries** the loop must never modify. An unsupervised learning
loop without those gates is just slow prompt injection.

---

*Early access: https://selfimprove.consultancyinaction.tech — built by
Consultancy in Action (https://consultancyinaction.com). The loop also ships
natively in AEGIS, our guardrailed coding agent
(https://consultancyinaction.tech).*