#self-improving #agent-memory #self-improvement #sqlite

Self Improving Compound

Agent memory and self-improvement system. Replaces naive file-based agent memory with a structured SQLite learning engine: capture corrections, errors, and reusable lessons during active work, audit recent conversation context via isolated cron jobs with deterministic collectors when available, and promote proven rules into skills and agent instructions. 3+7 co-evolution model — 3 state directories (memory/, learning/, skills/) plus 7 root Markdown control-plane files (AGENTS.md, HEARTBEAT.md, IDENTITY.md, MEMORY.md, SOUL.md, TOOLS.md, USER.md) improve together. Adds daily factual memory and workspace stewardship loops. Python 3.8+ CLI with bash hooks. Use for: logging non-obvious failures, user corrections, tool/API gotchas, or missing capabilities before the final reply. Use for: setting up automated cron-based audit pipelines that catch what real-time capture misses. Do not use for trivial typos or routine noise.

Rockway@lingmafuture

Install

openclaw skills install @lingmafuture/self-improving-compound

Self-Improving Compound

An agent memory and learning system that replaces naive file-based memory with a structured pipeline: real-time capture, observable Candidate → Learning → Promotion queues, automated cron-based audit, and continuous promotion of lessons into skills and agent instructions.

The system runs as four layers:

Layer 0 — Observable memory pipeline: ambiguous or high-value experience moves through Candidate → Learning → Promotion → Done using scripts/memory-pipeline.py, with learning/pipeline/candidates.jsonl, promotion-queue.json, status.json, and dashboard.md making backlog and coverage visible.
Layer 1 — Real-time capture: AGENTS.md final-before-reply gate logs corrections, errors, and workarounds to SQLite as they happen.
Layer 2 — Cron audit: Isolated background jobs scan recent conversation context. Prefer a deterministic local transcript/context collector; use sessions_history only when it is verified in the runtime. The jobs detect missed lessons and maintain lifecycle (HOT → WARM → COLD).
Layer 3 — Daily factual memory: a nightly memory/YYYY-MM-DD.md digest records decisions, paths, risks, links, and follow-ups; only reusable lessons are extracted into SQLite.
Layer 4 — Promotion + stewardship: proven rules flow from learning/ SQLite → skills/ SKILL.md → the 7 root Markdown control-plane files (AGENTS.md, HEARTBEAT.md, IDENTITY.md, MEMORY.md, SOUL.md, TOOLS.md, USER.md). The full 3+7 system co-evolves.

Author: Rockway Chen · rockwaychen@gmail.com · GitHub: LingmaFuture

Installation and activation — `clawhub install` is only step 1

A raw ClawHub install only copies the skill files. It does not automatically wire the agent into a self-improving operating loop.

Use this maturity ladder:

Level	What is configured	Result
1/5	`clawhub install self-improving-compound`	Files are present; almost no behavior changes yet.
2/5	`learning/` initialized and CLI verified	Manual logging/search works.
3/5	Capture gate added to agent instructions	The agent remembers to log lessons before final replies.
4/5	Cron jobs installed and delivery configured	Missed lessons, failures, daily memory, and steward checks run automatically.
5/5	Hooks/env/collector verified	Activation reminders, error capture, path resolution, and daily factual memory are reliable.

Phase 0 — Identify roots

You must distinguish two roots:

bash

# Workspace root: where memory/, learning/, AGENTS.md, etc. live
export OPENCLAW_WORKSPACE="/path/to/workspace"

# Optional shared lesson store for multiple workspace roots
# export SELF_IMPROVING_LEARNING_ROOT="$HOME/.openclaw/shared-learning"

# Skill root: where this skill was installed
export SELF_IMPROVING_SKILL_DIR="$OPENCLAW_WORKSPACE/skills/self-improving-compound"
export SELF_IMPROVING_LEARNINGS_CLI="$SELF_IMPROVING_SKILL_DIR/scripts/learnings.py"

For OpenClaw's default workspace this is usually:

bash

export OPENCLAW_WORKSPACE="$HOME/.openclaw/workspace"
export SELF_IMPROVING_SKILL_DIR="$OPENCLAW_WORKSPACE/skills/self-improving-compound"
export SELF_IMPROVING_LEARNINGS_CLI="$SELF_IMPROVING_SKILL_DIR/scripts/learnings.py"

Do not write durable learnings into the skill directory. By default learning/ belongs under the workspace root; use SELF_IMPROVING_LEARNING_ROOT or --learning-root only when several workspaces should share one lesson store.

Phase 1 — Install files

bash

clawhub install self-improving-compound
cd "$SELF_IMPROVING_SKILL_DIR"
chmod +x scripts/*.py scripts/*.sh hooks/*.sh 2>/dev/null || true

If the skill is copied manually, set SELF_IMPROVING_SKILL_DIR to the copied directory.

The bundled shell helpers require bash. On POSIX sh-only hosts, use the Python CLI directly and skip the .sh helpers.

Phase 2 — Initialize and verify the learning store

bash

python3 "$SELF_IMPROVING_LEARNINGS_CLI" --root "$OPENCLAW_WORKSPACE" init
python3 "$SELF_IMPROVING_LEARNINGS_CLI" --root "$OPENCLAW_WORKSPACE" status
python3 "$SELF_IMPROVING_LEARNINGS_CLI" --root "$OPENCLAW_WORKSPACE" search "install smoke test" --limit 3

Expected result:

learning/memory_tree/chunks.db exists.
status exits successfully.
search works even when there are no results.

Phase 3 — Add the capture gate to agent instructions

Add a compact rule to the agent's durable instruction file, usually AGENTS.md:

markdown

## Self-improvement capture gate

Before the final reply after any non-trivial task, check whether the work involved a user correction, non-obvious failure, tool/API quirk, workaround, format mismatch, missing capability, or reusable convention.

If yes:
1. Search existing learnings first:
   `python3 $SELF_IMPROVING_LEARNINGS_CLI --root $OPENCLAW_WORKSPACE search "<keywords>" --limit 5`
2. If no suitable entry exists, log the durable lesson with `log-correction`, `log-error`, `log-learning`, or `log-feature`.
3. Keep entries compact, prevention-oriented, and secret-free.

Without this phase the skill remains mostly passive; the agent will not consistently capture lessons in real time.

Phase 4 — Install the cron pipeline

Cron installation is not automatic. The templates live in scripts/setup-cron.json; agent-facing instructions live in scripts/setup-cron-agent.md.

Recommended OpenClaw flow:

Ask the agent: "Install the self-improving compound cron jobs using scripts/setup-cron.json. Check existing jobs first and update instead of duplicating."
Configure delivery for your channel, e.g. Telegram or Feishu.
Verify with cron list.

The pipeline normally includes:

Job	Purpose
Self-Improving Light Check	Frequent lightweight scan for missed corrections, errors, and blockers.
Learning Audit Heavy	System/cron failure audit, `learning-audit.py --log`, lifecycle maintenance.
Daily Memory Digest	Writes `memory/YYYY-MM-DD.md` factual continuity notes and extracts reusable lessons.
Daily Workspace Steward	Exports `learning/`, checks `skills/`, and inspects the 7 root Markdown control-plane files.

Important cron requirements:

Set schedule.tz to the user's actual timezone.
Set or infer delivery.channel and delivery.to; otherwise reports may not reach the user.
Use cron update for existing jobs; do not create duplicates.
Isolated cron sessions do not inherit main chat context. Jobs that need conversation context should prefer an explicit collector that exports recent visible conversation to a file. Use sessions_list / sessions_history only after verifying those tools can access the target session from isolated cron.

Phase 5 — Configure optional hooks

Hooks are optional but improve activation. They are runtime-specific.

Dry-run the bundled hooks first:

bash

"$SELF_IMPROVING_SKILL_DIR/hooks/activator.sh" "install smoke test" || true
"$SELF_IMPROVING_SKILL_DIR/hooks/error-detector.sh" "install" "smoke test" || true

If your client supports command hooks, wire:

hooks/activator.sh as a pre-prompt / prompt-start reminder.
hooks/error-detector.sh as a post-error / failed-command reminder.

If your runtime has no hook system, skip this phase and rely on the capture gate plus cron. Do not invent config keys; use your runtime's documented hook mechanism.

Phase 6 — Configure the observable memory pipeline

The bundled scripts/memory-pipeline.py adds an explicit queue and dashboard around cron/context scanning. It is optional for tiny installs but recommended for reliable systems.

bash

export SELF_IMPROVING_MEMORY_PIPELINE="$SELF_IMPROVING_SKILL_DIR/scripts/memory-pipeline.py"
# Optional if the OpenClaw session key is ambiguous:
# export SELF_IMPROVING_MAIN_SESSION_KEY="agent:main:<channel>:direct:<id>"
python3 "$SELF_IMPROVING_MEMORY_PIPELINE" --base "$OPENCLAW_WORKSPACE/learning/pipeline" dashboard

State files:

learning/pipeline/candidates.jsonl — suspected lessons awaiting dedupe/logging.
learning/pipeline/promotion-queue.json — logged lessons awaiting skill/root-file promotion.
learning/pipeline/cursor.json — last processed transcript line for incremental cron scans.
learning/pipeline/dashboard.md and learning/dashboard.md — human-readable health view.

Cron Light Check should prefer this flow: collect-incremental → add/mark candidates → log learnings → add/mark promotions → dashboard → commit-cursor. Commit the cursor only after successful processing.

Phase 7 — Configure optional context collectors

For reliable cron audits, prefer deterministic collectors over implicit chat context. A collector is a local command that reads the runtime's session/transcript store and writes recent visible user/assistant text to a Markdown or JSON file. It should skip tool outputs, hidden thinking, secrets, and raw long transcripts.

Light Check can use a local recent-conversation collector:

bash

export SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR="python3 /path/to/recent-context-collector.py --limit 60"

Collector contract:

Exit 0 only when context was exported successfully.
Print either the output context path or a compact JSON summary containing the path/status.
Write a readable Markdown/JSON context file with recent user/assistant visible text.
Exit non-zero if the transcript/session cannot be found; the cron job should report BLOCKED: collector_unavailable instead of claiming success.

Daily Memory Digest can also use a local collector if your runtime has one:

bash

export SELF_IMPROVING_DAILY_COLLECTOR="python3 /path/to/collector.py"
bash "$SELF_IMPROVING_SKILL_DIR/scripts/daily-memory.sh" --root "$OPENCLAW_WORKSPACE"

If no collector is configured, the helper prints the target note contract and the agent must gather context with available runtime tools.

Phase 8 — End-to-end smoke test

Run this checklist after installation:

bash

python3 "$SELF_IMPROVING_LEARNINGS_CLI" --root "$OPENCLAW_WORKSPACE" log-learning \
  --summary "Self-improving install smoke test" \
  --details "Temporary entry to verify logging path; mark resolved or delete if desired." \
  --pattern "install:smoke-test" \
  --area "domain:setup"

python3 "$SELF_IMPROVING_LEARNINGS_CLI" --root "$OPENCLAW_WORKSPACE" search "install smoke test" --limit 5
bash "$SELF_IMPROVING_SKILL_DIR/scripts/learning-export.sh"
bash "$SELF_IMPROVING_SKILL_DIR/scripts/daily-memory.sh" --root "$OPENCLAW_WORKSPACE" --date "$(TZ=Asia/Shanghai date +%F)"

Then verify:

learning/memory-export.md exists.
learning/status.json exists.
memory/YYYY-MM-DD.md target is clear if daily memory is enabled.
cron list shows the expected enabled jobs with nextRunAtMs.
Delivery target is configured for cron job summaries.

Common install failures

Symptom	Likely cause	Fix
`clawhub install` succeeded but nothing changes	Capture gate and cron not configured	Complete phases 3-4.
Cron runs but finds no conversation context	Isolated session has no main history or `sessions_history` is restricted	Configure `SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR`; use `sessions_history` only as a verified fallback.
Learnings appear under the skill directory	Wrong `--root`	Set `OPENCLAW_WORKSPACE`; always pass `--root`.
Cron summaries disappear	`delivery` missing channel/recipient	Set `delivery.channel` + `delivery.to`.
Daily memory is generic or empty	No collector/context source	Configure `SELF_IMPROVING_DAILY_COLLECTOR` or improve the cron prompt.
Duplicate cron jobs	Setup re-run without idempotency check	`cron list` first; update by job name.

3+7 co-evolution model

The 3 state directories are:

memory/ — factual daily continuity.
learning/ — SQLite-backed execution lessons.
skills/ — hardened reusable procedures.

The 7 root Markdown control-plane files are:

AGENTS.md — workspace contract, routing, execution policy, safety boundaries.
HEARTBEAT.md — lightweight check-in surface; often intentionally empty when cron owns timing.
IDENTITY.md — compatibility pointer or short identity bridge.
MEMORY.md — pinned long-term hot context.
SOUL.md — agent identity/persona.
TOOLS.md — concrete local environment/tool facts.
USER.md — durable user profile and collaboration preferences.

The steward loop should keep these layers aligned with small, safe edits only. It must not rewrite persona, weaken safety/privacy rules, or promote volatile daily facts into root-level bloat.

Core idea

Use this system for durable improvement, not for every bump in the road.

Mandatory capture gate

Before a final reply, run this quick check:

Did the task include a non-obvious failure, API/tool quirk, or format mismatch?
Did a workaround or environment-specific convention make the task succeed?
Did the user correct a fact, preference, workflow, or expectation?
Would repeating this lesson save time or prevent damage later?

If yes, search existing learnings first, then log the lesson before replying. Do not rely on a “mental note.”

A good entry usually has at least one of these properties:

It corrected a wrong assumption.
It revealed a project-specific convention.
It required real debugging or investigation.
It is likely to recur.
It should change future workflow, memory, or tooling.

Do not log routine noise such as obvious typos, expected validation failures, or errors that were solved immediately with no transferable lesson.

Capture gate output routing

Not all lessons go to the same place. Route based on type:

Lesson type	Destination	Example
User facts, preferences, system state	`MEMORY.md` / `memory/YYYY-MM-DD.md`	"Rockway prefers newspaper theme"
Execution mistakes, tool gotchas, workarounds	`learning/` SQLite	"Python shadowing broke promote"
Stable rules, workflows, anti-patterns discovered	owning `skills/<skill>/SKILL.md`	"cron isolation means no session context"
Behavioral constraints	`AGENTS.md`	"Don't commit workspace root"
Environment-specific tool knowledge	`TOOLS.md`	"Tailscale node name"

The full 3+7 system co-evolves: fixing one layer while leaving another stale is half-done work. When a lesson reveals a skill is stale, upgrade it immediately and bump its version.

Hybrid architecture

This skill merges three design lineages into one portable package:

Lineage	Role	What We Kept
actual-self-improvement	Execution core	Python CLI (`scripts/learnings.py`), structured logging, JSON evals, search-before-log dedupe
OpenHuman memory-tree	Storage core	SQLite chunks, FTS search, entity index, scores, hotness, async jobs, deterministic tree buffers, lifecycle status, idempotent ingest
self-improving-compound	Memory architecture	HOT/WARM/COLD lifecycle, workspace-scoped `learning/`, lightweight bootstrap markdown
self-improving-agent-local	Promotion & hooks	Quantified promotion thresholds, OpenClaw hook guidance, pattern-key recurrence rules

Directory layout under `learning/`

text

learning/
├── memory_tree/chunks.db  # SQLite source of truth for durable learnings
├── index.md               # SQLite-generated snapshot (entries, lifecycle, pattern keys)
├── promotion-queue.json   # bounded maintain queue for proven promotion candidates
├── projects/              # WARM tier (project-specific)
├── domains/               # WARM tier (domain-specific)
└── archive/               # COLD tier (inactive)

Important path model

There are two different roots in this skill:

Skill root — where bundled resources live:
- scripts/...
- references/...
- hooks/...
Workspace root — where the project or active workspace lives:
- learning/memory_tree/chunks.db
- learning/index.md (SQLite-generated snapshot)
- memory/YYYY-MM-DD.md factual daily notes, when enabled
- learning/projects/
- learning/domains/
- learning/archive/
- root agent files such as AGENTS.md, MEMORY.md, TOOLS.md, USER.md, SOUL.md, HEARTBEAT.md, IDENTITY.md

When SELF_IMPROVING_LEARNING_ROOT or --learning-root is set, the learning/* files above live in that shared learning root instead. Promotions still target the active workspace root, so a shared store can feed multiple projects without writing AGENTS/TOOLS files into the wrong workspace.

Never write learnings into the installed skill directory. Always target the workspace root for project memory and the optional learning root for shared lesson storage.

Activation hardening mechanisms

When this skill is installed in a persistent agent runtime, self-improvement must be enforced by the system rather than left to memory. The recommended architecture uses three enforcement loops:

Capture gate: an agent instruction requiring search + log before every final reply after a non-trivial task. This catches lessons in real-time during active work.
Cron enforcement: isolated background jobs that audit recent session history, scan for system failures, maintain lifecycle, and export SQLite for review. Cron runs in isolated sessions that do not consume the main conversation context.
Daily stewardship: a factual daily digest plus a post-digest workspace steward keep memory/, learning/, skills/, and the 7 root Markdown control-plane files aligned without broad rewrites.

Architecture decisions (why cron, not heartbeat)

Cron is isolated. sessionTarget: "isolated" creates a fresh ephemeral session that does not pollute the main agent's context window or bust prompt-cache warmth.
Cron context must be explicit. An isolated cron job does not automatically see the main chat. Prefer a deterministic collector that reads the runtime's local session/transcript store and exports recent user/assistant visible text to a file. sessions_list / sessions_history can be used only when you have verified they work from isolated cron; otherwise they create false confidence.
Heartbeat runs in the main session by default. Its role should be limited to lightweight check-ins and urgent reminders. Do not embed audit execution commands in HEARTBEAT.md; keep that file minimal so heartbeat returns HEARTBEAT_OK quickly unless an urgent decision is needed.

Recommended cron schedule

text

Cron                                     Schedule (Asia/Shanghai)
──────────────────────────────────────   ──────────────────────
Self-Improving Light Check               0 8-22/2 * * *    (every 2h during waking hours)
Learning Audit (Heavy)                   0 9,22 * * *      (2x/day)
Daily Memory Digest                      50 23 * * *       (nightly factual memory)
Daily Workspace Steward                  20 0 * * *        (post-digest maintenance)

Light Check (every 2h, 08:00-22:00)

A quick in-between scan that reads recent conversation context and checks whether any user correction, non-obvious error, workaround, or tool/API quirk has been missed by the SQLite learning store. Preferred path: run SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR, read its exported Markdown/JSON, then dedupe with learnings.py search. Fallback path: use sessions_list / sessions_history only if verified from isolated cron. Tools: exec, read; optionally sessions_list, sessions_history for the fallback. Timeout: 120-180s.

Heavy Audit (09:00, 22:00)

Full audit: system-failure check, cron-failure scan, learning-audit.py --log, and learnings.py maintain --apply for lifecycle promotion/demotion. Tools: exec, read, cron. Timeout: 240s.

Daily Memory Digest (23:50)

Run scripts/daily-memory.sh, gather or read the daily context, write memory/YYYY-MM-DD.md, then run the capture gate on the final note. Facts stay in memory/; compact reusable lessons go to SQLite. See references/daily-memory-digest.md. Timeout: 300s.

Daily Workspace Steward (00:20)

Run scripts/learning-export.sh, inspect learning/, skills/*/SKILL.md, and root agent markdown files for small safe consistency updates. It may fix verified stale facts or clear contradictions, but must not rewrite persona, weaken safety/privacy rules, delete files, or change cron jobs. Timeout: 300s.

Cron installation (one-time setup)

The cron jobs described above are NOT created automatically when you install this skill. You must run the setup once to create them in your OpenClaw instance.

The production-grade cron job definitions are in scripts/setup-cron.json. The agent-facing setup guide is scripts/setup-cron-agent.md.

Quick setup (run from your OpenClaw main session):

Confirm: "I want to install the self-improving compound cron jobs. Use scripts/setup-cron.json as reference."
Your agent will:
- Read the JSON definitions
- Resolve placeholder paths (skill root, workspace root)
- Ask or infer your delivery channel (Telegram / Feishu / etc.)
- Call cron add / cron update for each job, avoiding duplicates
Verify: cron list should show enabled jobs with nextRunAtMs set.

If you already have these jobs running, this step is a no-op.

AGENTS.md capture gate

Add the following rule to agent instructions (e.g. AGENTS.md):

Before every final reply after a non-trivial task: if the task involved a user correction, non-obvious failure, API/tool quirk, workaround, format mismatch, missing capability, or reusable convention, search existing SQLite learning first with scripts/learnings.py --root <workspace> search "<keywords>" --limit 5. If no suitable entry exists, log the durable lesson before replying. Never rely on a mental note; learning/memory_tree/chunks.db is the execution-learning source of truth.

System failure routing

Route watchdog, doctor, healthcheck, and cron failure signals into log-error with stable pattern keys and dedupe:

Pattern keys: cron:<job-name>, doctor:<check-name>, watchdog:<component>, system:openclaw-audit-failure
Use scripts/log-system-failures.sh as an OpenClaw CLI audit wrapper where available.
Always search existing entries first to prevent repeated failures from flooding SQLite.

Guardrails

Keep entries compact and prevention-oriented.
Never log secrets; the CLI redacts tokens, passwords, and API keys automatically.
Do not paste full audit exports into chat unless explicitly asked.
Treat audit candidates as review prompts rather than automatic truth.
Cron runs should reply with one-line summaries or HEARTBEAT_OK; do not echo full command output.

Quick decision table

Situation	What to do
User corrects you or updates a fact	Log a correction
Non-obvious command / API / tool failure	Log an error
User asks for a missing capability	Log a feature request
You discover a reusable workaround or convention	Log a learning
A pattern keeps recurring	Search related entries, link with `See Also`, and consider promotion
A lesson is broadly applicable or repeated	Promote it into project memory
A resolved, general pattern could help other projects	Extract a new skill

Standard workflow

0) Optional nightly factual memory

If the workspace uses daily factual notes, run or schedule:

bash

bash scripts/daily-memory.sh --root /absolute/path/to/workspace

Then write memory/YYYY-MM-DD.md from the gathered context and run the capture gate on that note. Use references/daily-memory-digest.md for the quality bar. Do not copy the diary into SQLite; extract only reusable prevention rules.

1) Find the workspace root first

Before reading or writing learning/, determine WORKSPACE_ROOT.

Good defaults:

the repository root for the current codebase
the OpenClaw workspace root (OPENCLAW_WORKSPACE env var)
the directory containing the files being edited

If unsure, prefer the directory containing .git, AGENTS.md, CLAUDE.md, or the user's active project files.

2) Initialise `learning/` if needed

Use the helper instead of creating files manually:

bash

python3 scripts/learnings.py --root /absolute/path/to/workspace init

This creates:

learning/memory_tree/chunks.db (SQLite database)
learning/projects/
learning/domains/
learning/archive/

The learning/index.md snapshot is generated on first write (log, promote, etc.).

3) Review existing learnings before risky or familiar work

Review first when:

you are returning to an area with prior failures
the task touches infra, CI, deployment, auth, data migration, or generated code
the user explicitly says "remember this", "we hit this before", or similar

Use the helper:

bash

python3 scripts/learnings.py --root /absolute/path/to/workspace status
python3 scripts/learnings.py --root /absolute/path/to/workspace search "pnpm" --limit 5
python3 scripts/learnings.py --root /absolute/path/to/workspace search "pnpm" --touch

# --root can also be placed after the subcommand
python3 scripts/learnings.py status --root /absolute/path/to/workspace --format json

Plain search is read-only. Use --touch only when the result was actually reused and should increment recurrence metadata.

4) Search before logging to avoid duplicates

Always search for related entries before creating a new one.

bash

python3 scripts/learnings.py --root /absolute/path/to/workspace search "keyword or pattern" --limit 10

If a similar entry already exists:

prefer linking with See Also
reuse or add a stable Pattern-Key for recurring issues
bump priority only when recurrence justifies it
prefer updating the existing pattern story over spraying near-duplicate entries

5) Log the right kind of entry

Correction

Use for user corrections and updated facts. Stored in SQLite with a human ID such as COR-YYYYMMDD-001.

bash

python3 scripts/learnings.py --root /absolute/path/to/workspace log-correction \
  --summary "Used wrong format for Telegram" \
  --correct "Use lists, not tables" \
  --pattern chat:telegram-format

Learning

Use for corrections, knowledge gaps, best practices, and durable conventions. Stored in SQLite with a human ID such as LRN-YYYYMMDD-001.

bash

python3 scripts/learnings.py --root /absolute/path/to/workspace log-learning \
  --summary "Project uses pnpm workspaces, not npm" \
  --details "Attempted npm install. Lockfile and workspace config showed pnpm." \
  --pattern pkg:pnpm-workspace

Error

Use for non-obvious failures, exceptions, or tool/API issues worth remembering. Stored in SQLite with a human ID such as ERR-YYYYMMDD-001.

bash

python3 scripts/learnings.py --root /absolute/path/to/workspace log-error \
  --summary "Docker build failed on Apple Silicon due to platform mismatch" \
  --details "docker build -t myapp . on Apple Silicon" \
  --pattern docker:platform

Feature request

Use when the user wants a missing capability or a recurring friction point should become a feature. Stored in SQLite with a human ID such as FTR-YYYYMMDD-001.

bash

python3 scripts/learnings.py --root /absolute/path/to/workspace log-feature \
  --summary "User needs report export to CSV" \
  --details "Needed for sharing weekly reports with non-technical stakeholders" \
  --pattern reports:csv-export

Backward-compatible log

The old log subcommand is preserved for compatibility:

bash

python3 scripts/learnings.py --root /absolute/path/to/workspace log "Used wrong format" \
  --type COR --pattern chat:telegram-format --correct "Use lists" --force

To inspect or share entries, export from SQLite:

bash

python3 scripts/learnings.py --root /absolute/path/to/workspace export
python3 scripts/learnings.py --root /absolute/path/to/workspace export --format json

6) Promote proven lessons into memory

Promote when the learning is broad, repeated, or something any future contributor should know.

Common targets:

CLAUDE.md — durable project facts and conventions
AGENTS.md — workflow rules and automation guidance
.github/copilot-instructions.md — shared Copilot context
SOUL.md — behavioural principles in OpenClaw workspaces
TOOLS.md — tool-specific gotchas in OpenClaw workspaces

Write promotions as short prevention rules, not long incident write-ups.

Example:

Bad promotion: "On 2026-03-12 npm failed because…"
Good promotion: "Use pnpm install in this repo; it is a pnpm workspace."

When a learning is promoted, update the original entry's status to promoted or promoted_to_skill and record the destination.

maintain writes high-recurrence candidates to learning/promotion-queue.json. For fully automated deployments, maintain --apply --auto-promote promotes those candidates into the active workspace root while keeping the shared learning store separate when --learning-root is used.

7) Extract a reusable skill when the pattern is real

Extract a new skill when the solution is:

resolved and working
broadly useful beyond one file or repo
non-obvious enough that future agents would benefit
recurring enough to justify its own instructions

Use the helper:

bash

bash scripts/extract-skill.sh my-skill-name /absolute/path/to/workspace

Logging rules that matter most

Search first. Duplicate entries are worse than missing tags.
Prefer durable lessons. Only log what should change future behaviour.
Be specific. Name the assumption, failure, or convention clearly.
Include the fix or prevention rule. An entry without next action is weak.
Use stable pattern keys for recurring problems. This lets recurrence compound.
Promote aggressively once a rule is proven. The point is fewer repeat mistakes.
Do not interrupt the user with bookkeeping. Log silently unless the user asked to see it or you need missing details.
Never log secrets. Tokens, passwords, API keys, and private data must be redacted or omitted.

Memory lifecycle (integrated from ivangdavila/self-improving)

Entries carry metadata (First-Seen, Last-Seen, Recurrence-Count, Status, Area) so the system can make deterministic lifecycle decisions without guessing.

Tier	Location	Size guidance	Behavior
HOT	SQLite lifecycle `admitted`	Active working set	Shown by `status`, `search`, and hooks
WARM	SQLite lifecycle `buffered`	30+ days unused	Retained for context-specific search
COLD	SQLite lifecycle `sealed`	archived/promoted/resolved	Retained for explicit query/export

Automatic promotion/demotion

Use python3 scripts/learnings.py --root <workspace> maintain to review:

Condition	Threshold	Action
HOT -> WARM	30 days unused	Set lifecycle to `buffered`
WARM -> COLD	90 days unused	Set lifecycle to `sealed`
Frequent reuse	`Recurrence-Count >= 3` from explicit reuse (`search --touch` or `edit`)	Flag for project-memory promotion
Compaction/export	Human review needed	Export and manually summarize/promote without deleting the SQLite record

maintain defaults to --dry-run. Use --apply to execute lifecycle status moves. It never deletes content and does not auto-summarize.

Conflict resolution

When patterns contradict:

More specific wins: project > domain > global
More recent wins at the same specificity level
Ambiguous conflicts → ask the user instead of guessing

Promotion thresholds (from legacy)

Condition	Threshold	Action
HOT -> WARM	30 days unused	Mark `buffered`
WARM -> COLD	90 days unused	Mark `sealed`
Frequent reuse	3 recorded uses within 7 days	Promote as a short prevention rule
To AGENTS/SOUL/TOOLS	`Recurrence-Count >= 3` + spans 2+ tasks + within 30 days	Promote as short prevention rule
To skill	Proven + broadly applicable	Extract as skill

Recommended references

Use these only when needed:

references/entry-formats.md — full field schemas and manual templates
references/promotion-and-extraction.md — promotion rules and skill extraction criteria
references/platform-setup.md — Claude Code, Codex, Copilot, and OpenClaw setup notes

Hooks

Hook helpers are intentionally optional and workspace-root aware.

Available hook scripts:

hooks/activator.sh — lightweight reminder at prompt start
hooks/error-detector.sh — lightweight error reminder after failed Bash-like commands

Hook configuration examples live in references/platform-setup.md.

What "next-level" looks like for this skill

A mature use of this skill has a loop:

capture → dedupe → promote → extract → evaluate

That means:

entries are created with stable human IDs, content-addressed chunk IDs, and consistent fields
repeated issues link to each other instead of fragmenting
proven rules move into persistent memory files
broadly useful fixes become standalone skills
the skill itself is tested with trigger and output evals in evals/

Self Improving Compound

Install

Self-Improving Compound

Installation and activation — clawhub install is only step 1

Phase 0 — Identify roots

Phase 1 — Install files

Phase 2 — Initialize and verify the learning store

Phase 3 — Add the capture gate to agent instructions

Phase 4 — Install the cron pipeline

Phase 5 — Configure optional hooks

Phase 6 — Configure the observable memory pipeline

Phase 7 — Configure optional context collectors

Phase 8 — End-to-end smoke test

Common install failures

3+7 co-evolution model

Core idea

Mandatory capture gate

Capture gate output routing

Hybrid architecture

Directory layout under learning/

Important path model

Activation hardening mechanisms

Architecture decisions (why cron, not heartbeat)

Recommended cron schedule

Light Check (every 2h, 08:00-22:00)

Heavy Audit (09:00, 22:00)

Daily Memory Digest (23:50)

Daily Workspace Steward (00:20)

Cron installation (one-time setup)

AGENTS.md capture gate

System failure routing

Guardrails

Quick decision table

Standard workflow

0) Optional nightly factual memory

1) Find the workspace root first

2) Initialise learning/ if needed

3) Review existing learnings before risky or familiar work

4) Search before logging to avoid duplicates

5) Log the right kind of entry

Correction

Learning

Error

Feature request

Backward-compatible log

6) Promote proven lessons into memory

7) Extract a reusable skill when the pattern is real

Logging rules that matter most

Memory lifecycle (integrated from ivangdavila/self-improving)

Automatic promotion/demotion

Conflict resolution

Promotion thresholds (from legacy)

Recommended references

Hooks

What "next-level" looks like for this skill

Related skills

Installation and activation — `clawhub install` is only step 1

Directory layout under `learning/`

2) Initialise `learning/` if needed