Setup — Self-Improving Agent

First-Time Setup

1. Create Memory Structure

mkdir -p ~/self-improving/{projects,domains,archive}

2. Initialize Core Files

Create ~/self-improving/memory.md using memory-template.md:

Copy the structure from `memory-template.md` into `~/self-improving/memory.md`.

Memory file baseline:

# Memory (HOT Tier)

## Preferences

## Patterns

## Rules

Create ~/self-improving/corrections.md:

# Corrections Log

| Date | What I Got Wrong | Correct Answer | Status |
|------|-----------------|----------------|--------|

Create ~/self-improving/index.md:

# Memory Index

| File | Lines | Last Updated |
|------|-------|--------------|
| memory.md | 0 | — |
| corrections.md | 0 | — |

3. Choose Operating Mode

Add to your AGENTS.md or workspace config:

## Self-Improving Mode

Current mode: Passive

Available modes:
- Passive: Only learn from explicit corrections
- Active: Suggest patterns after 3x repetition
- Strict: Require confirmation for every entry

4. Add SOUL.md Steering

Add this section to your SOUL.md:

**Self-Improving**
Compounding execution quality is part of the job.
Before non-trivial work, load `~/self-improving/memory.md` and only the smallest relevant domain or project files.
After corrections, failed attempts, or reusable lessons, write one concise entry to the correct self-improving file immediately.
Prefer learned rules when relevant, but keep self-inferred rules revisable.
Do not skip retrieval just because the task feels familiar.

5. Refine AGENTS.md Memory Section (Non-Destructive)

Update AGENTS.md by complementing the existing ## Memory section. Do not replace the whole section and do not remove existing lines.

If your ## Memory block differs from the default template, insert the same additions in equivalent places so existing information is preserved.

Add this line in the continuity list (next to Daily notes and Long-term):

- **Self-improving:** `~/self-improving/` (via `self-improving` skill) — execution-improvement memory (preferences, workflows, style patterns, what improved/worsened outcomes)

Right after the sentence "Capture what matters...", add:

Use `memory/YYYY-MM-DD.md` and `MEMORY.md` for factual continuity (events, context, decisions).
Use `~/self-improving/` for compounding execution quality across tasks.
For compounding quality, read `~/self-improving/memory.md` before non-trivial work, then load only the smallest relevant domain or project files.
If in doubt, store factual history in `memory/YYYY-MM-DD.md` / `MEMORY.md`, and store reusable performance lessons in `~/self-improving/` (tentative until human validation).

Before the "Write It Down" subsection, add:

Before any non-trivial task:
- Read `~/self-improving/memory.md`
- List available files first:
  ```bash
  for d in ~/self-improving/domains ~/self-improving/projects; do
    [ -d "$d" ] && find "$d" -maxdepth 1 -type f -name "*.md"
  done | sort

Read up to 3 matching files from ~/self-improving/domains/
If a project is clearly active, also read ~/self-improving/projects/<project>.md
Do not read unrelated domains "just in case"

If inferring a new rule, keep it tentative until human validation.


Inside the "Write It Down" bullets, refine the behavior (non-destructive):
- Keep existing intent, but route execution-improvement content to `~/self-improving/`.
- If the exact bullets exist, replace only these lines; if wording differs, apply equivalent edits without removing unrelated guidance.

Use this target wording:

```markdown
- When someone says "remember this" → if it's factual context/event, update `memory/YYYY-MM-DD.md`; if it's a correction, preference, workflow/style choice, or performance lesson, log it in `~/self-improving/`
- Explicit user correction → append to `~/self-improving/corrections.md` immediately
- Reusable global rule or preference → append to `~/self-improving/memory.md`
- Domain-specific lesson → append to `~/self-improving/domains/<domain>.md`
- Project-only override → append to `~/self-improving/projects/<project>.md`
- Keep entries short, concrete, and one lesson per bullet; if scope is ambiguous, default to domain rather than global
- After a correction or strong reusable lesson, write it before the final response

Verification

Run "memory stats" to confirm setup:

📊 Self-Improving Memory

🔥 HOT (always loaded):
   memory.md: 0 entries

🌡️ WARM (load on demand):
   projects/: 0 files
   domains/: 0 files

❄️ COLD (archived):
   archive/: 0 files

⚙️ Mode: Passive

Optional: Heartbeat Integration

Add to HEARTBEAT.md for automatic maintenance:

## Self-Improving Check

- [ ] Review corrections.md for patterns ready to graduate
- [ ] Check memory.md line count (should be ≤100)
- [ ] Archive patterns unused >90 days

4.9 KiB Executable File Raw Permalink Blame History