A unified system for continuous improvement: capture corrections, reflect on work, maintain persistent memory across projects and sessions, and extract reusable skills from recurring patterns.
Two tiers: project-local for active work, global for cross-project patterns. Plus a shared channel for cross-session experience exchange.
<project-root>/.learnings/
└── LEARNINGS.md # Corrections, patterns, and errors for this project
Created on first use. Lightweight — one file, simple format.
~/self-improving/
├── memory.md # HOT: ≤100 lines, always loaded — top rules and preferences
├── corrections.md # Last 50 corrections log
├── projects/ # WARM: per-project patterns, loaded on context match
│ └── {project-name}.md
├── domains/ # WARM: domain-specific patterns (code, writing, comms)
│ └── {domain}.md
├── shared/ # Cross-session insights — any session writes, all sessions read
│ └── YYYY-MM-DD-topic.md
├── archive/ # COLD: decayed or long-unused patterns
└── index.md # Topic index for quick lookup
Project-local (create when first logging for a project):
mkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Learnings — %s\n\nCaptured corrections, patterns, and errors.\n\n---\n" "$(basename $(pwd))" > .learnings/LEARNINGS.md
Global (create once):
mkdir -p ~/self-improving/{projects,domains,shared,archive}
[ -f ~/self-improving/memory.md ] || printf "# Global Memory\n\n## Rules\n\n## Preferences\n\n## Patterns\n\n---\n" > ~/self-improving/memory.md
[ -f ~/self-improving/corrections.md ] || printf "# Corrections Log\n\nLast 50 corrections. Oldest auto-pruned.\n\n---\n" > ~/self-improving/corrections.md
[ -f ~/self-improving/index.md ] || printf "# Index\n\nTopic → file mapping for quick lookup.\n\n---\n" > ~/self-improving/index.md
At the beginning of each session, perform a lightweight health check to keep memory from decaying:
~/self-improving/shared/ older than 7 days.memory.md exceeds 100 lines, trigger compaction (see Compaction section).This replaces a heavy heartbeat with a minimal startup sweep. No background processes, no recurring timers — just one pass when the session starts.
Corrections → log immediately:
Errors → log to project-local:
Feature gaps → note for later:
Knowledge gaps → log when you learn something new:
Better approaches → log when you discover improvements:
Keep it lightweight. No heavy metadata — just enough to be useful later.
Append to .learnings/LEARNINGS.md:
### [correction|error|pattern|gap] short summary
**Date**: YYYY-MM-DD
**Context**: what was happening
What went wrong / what was learned:
Description of the situation.
**Rule**: the takeaway (one sentence).
Append to ~/self-improving/corrections.md:
### [date] short summary
**Project**: project-name (or "general")
**Context**: what was happening
**Correction**: what the user said.
**Rule**: the permanent takeaway.
Keep only the last 50 entries — prune oldest when it exceeds that.
Append to ~/self-improving/memory.md under the appropriate section:
- **Rule text** (from: project/area, first noted: date)
After completing significant work, pause and evaluate:
When to self-reflect:
Format:
CONTEXT: [type of task]
REFLECTION: [what I noticed]
LESSON: [what to do differently — log if reusable]
Only persist lessons that are reusable — one-off observations stay in conversation context.
When running multiple sessions in parallel (e.g., different projects, different tasks), use the shared directory as a lightweight message board. No special tools required — just file conventions.
~/self-improving/shared/ is a flat directory that all sessions can read and write. Each shared insight is a small markdown file. Sessions check for new files at natural breakpoints.
When your session discovers something worth sharing with other running sessions:
~/self-improving/shared/YYYY-MM-DD-topic-slug.md:# Topic Title
**From**: project-name / task description
**Date**: YYYY-MM-DD HH:MM
**Relevance**: writing | code | general | project-name
What was learned or discovered:
Brief description.
**Actionable rule**: one sentence the other session can apply.
At natural breakpoints (starting a new task, switching context, after completing work):
# Check for insights from the last 3 days
find ~/self-improving/shared/ -name "*.md" -mtime -3 | sort
Read any relevant files. If an insight applies to your current work, apply it and optionally delete the file (consumed). If not relevant, skip it.
memory.md (HOT) or domains/ (WARM) if the insight proves broadly valuableshared/ accumulate beyond 20 files — prune oldest or promote and delete| Share | Don't Share |
|---|---|
| ------- | ------------ |
| "User prefers concise bullet points over prose for summaries" | "The bug is on line 42 of foo.py" |
| "API X requires auth header format Y" | "I'm debugging the login flow" |
| "This markdown template works well for reports" | One-off file-specific fixes |
| "User corrected: never use Oxford comma" | Internal reasoning or hypotheses |
| Tier | Location | Size Limit | Loaded When |
|---|---|---|---|
| ------ | ---------- | ------------ | ------------- |
| HOT | memory.md | ≤100 lines | Every session |
| WARM | projects/, domains/ | ≤200 lines each | Context matches |
| COLD | archive/ | Unlimited | Explicit query only |
When any file exceeds its size limit:
projects/{name}.mdmemory.md)domains/{domain}.mdGlobal → Domain → Project (outermost is default, innermost overrides)
When a project-local learning is broadly applicable:
CLAUDE.md (project conventions) or relevant project filepromoted| Target | What Goes There |
|---|---|
| -------- | ---------------- |
CLAUDE.md | Project conventions, build commands, gotchas |
~/self-improving/memory.md | Cross-project preferences and behavioral rules |
~/self-improving/projects/{name}.md | Project-specific patterns |
~/self-improving/domains/{domain}.md | Domain patterns (code, writing, comms) |
When a learning becomes a reusable, self-contained capability, extract it as a Skill.
skills/{skill-name}/SKILL.mdname and descriptionpromoted_to_skillmemory.md) for relevant rules.learnings/ for past issues in this area# Count pending learnings in current project
grep -c "^###" .learnings/LEARNINGS.md 2>/dev/null || echo 0
# Count global rules
grep -c "^-" ~/self-improving/memory.md 2>/dev/null || echo 0
# List corrections from last 7 days
grep -A3 "$(date -d '7 days ago' +%Y-%m-%d 2>/dev/null || date -v-7d +%Y-%m-%d)" ~/self-improving/corrections.md
| User says | Action |
|---|---|
| ----------- | -------- |
| "What do you know about X?" | Search all tiers for X |
| "What have you learned?" | Show recent corrections and HOT rules |
| "Show project patterns" | Load projects/{name}.md |
| "Any shared insights?" | List recent files in shared/ |
| "Memory stats" | Report counts per tier (see below) |
| "Forget X" | Search all tiers, confirm before removing |
| "What could be improved?" | Self-reflect on recent work |
Memory Status
HOT (always loaded):
memory.md: X entries
WARM (load on demand):
projects/: X files, X entries total
domains/: X files, X entries total
SHARED (cross-session):
shared/: X files (X new since last check)
COLD (archived):
archive/: X files
Recent activity (7 days):
Corrections logged: X
Promotions to HOT: X
Demotions to WARM: X
Shared insights written: X
Shared insights consumed: X
| Pitfall | Why It Fails | Better Approach |
|---|---|---|
| --------- | ------------- | ----------------- |
| Learning from silence | Creates false rules | Wait for explicit correction or repeated evidence |
| Promoting too fast | Pollutes HOT memory | Keep tentative until pattern repeats 3x |
| Loading everything | Wastes context window | Load HOT + smallest matching WARM files only |
| Deleting entries | Loses trust and history | Demote or archive instead |
| Logging everything | Creates noise | Only log explicit corrections, verified errors, and reusable patterns |
| Hoarding shared insights | Clutters shared/, wastes reads | Consume (delete) after applying, promote valuable ones to WARM/HOT |
| Sharing too specifically | Other sessions can't reuse | Share the rule, not the debugging details |
共 2 个版本