{"id":"8635621e-a816-44c4-bbbb-0124a225c072","entityType":"agent","slug":"clawhub-lingmafuture-self-improving-compound","name":"Self Improving Compound","canonicalUrl":"https://www.xpersona.co/agent/clawhub-lingmafuture-self-improving-compound","canonicalPath":"/agent/clawhub-lingmafuture-self-improving-compound","generatedAt":"2026-10-10T08:44:18.555Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T23:49:30.668Z","emptyReason":null},"description":"Agent memory and self-improvement system. Replaces naive file-based agent memory with a structured SQLite learning engine: capture corrections, errors, and r... Skill: Self Improving Compound Owner: lingmafuture Summary: Agent memory and self-improvement system. Replaces naive file-based agent memory with a structured SQLite learning engine: capture corrections, errors, and r... Tags: latest:6.2.5, lifecycle:1.0.5, memory:1.0.5, self-improvement:1.0.5 Version history: v6.2.5 | 2026-05-19T07:53:29.795Z | user Add observable Candidate → Learning → Promotion memory pipeline wit","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.9K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s1795ynq2axpc6ezsahrdzyhrh83h4sk:self-improving-compound","sourceUrl":"https://clawhub.ai/lingmafuture/self-improving-compound","homepage":"https://clawhub.ai/lingmafuture/skills/self-improving-compound","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/lingmafuture/self-improving-compound","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/lingmafuture/skills/self-improving-compound","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":65,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Agent memory and self-improvement system. Replaces naive file-based agent memory with a structured SQLite learning engine: capture corrections, errors, and r..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:49:30.668Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:49:30.668Z","emptyReason":null},"stars":null,"forks":null,"downloads":1869,"packageName":null,"latestVersion":"6.2.5","tractionLabel":"1.9K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:49:30.668Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T23:49:30.668Z","lastCrawledAt":"2026-10-09T23:49:30.668Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T23:49:30.668Z","lastVerifiedAt":null,"highlights":[{"version":"6.2.5","createdAt":"2026-05-19T07:53:29.795Z","changelog":"Add observable Candidate → Learning → Promotion memory pipeline with candidate queue, promotion queue, incremental cursor, and dashboard; update Light Check cron template to scan candidate-first and commit cursor only after successful processing.","fileCount":40,"zipByteSize":111329},{"version":"6.2.4","createdAt":"2026-05-19T06:43:34.655Z","changelog":"Document deterministic Light Check context collector pattern; add SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR; update cron template to report BLOCKED on collector failure and use sessions_history only as verified fallback.","fileCount":38,"zipByteSize":102711},{"version":"6.2.3","createdAt":"2026-05-18T08:50:37.292Z","changelog":"Packaging hygiene release: keep local .reference research artifacts in the canonical working directory while excluding them from GitHub and ClawHub via ignore files; verified ClawHub publish file collection excludes local reference artifacts.","fileCount":38,"zipByteSize":100995},{"version":"6.2.2","createdAt":"2026-05-18T07:37:57.793Z","changelog":"Improve installation experience: clarify that clawhub install only copies files, add full activation flow in SKILL.md covering env vars, learning init, capture gate, cron setup, hooks, optional daily collector, smoke tests, and common install failures.","fileCount":38,"zipByteSize":92980},{"version":"6.2.1","createdAt":"2026-05-18T07:10:28.075Z","changelog":"Clarify the 3+7 model as 3 state directories plus 7 root Markdown control-plane files, add README language links, and tighten Workspace Steward wording for the seven markdown files.","fileCount":38,"zipByteSize":85028},{"version":"6.2.0","createdAt":"2026-05-18T06:59:53.759Z","changelog":"Sync local OpenClaw memory-system hardening: daily factual memory digest guidance, Daily Workspace Steward cron template, portable daily-memory helper, refreshed README/SKILL docs, and sanitized public package.","fileCount":38,"zipByteSize":83575},{"version":"6.1.7","createdAt":"2026-05-17T19:57:46.231Z","changelog":"Added cron installation infrastructure (setup-cron.json + setup-cron-agent.md). Closes the cron audit architecture gap: scripts existed but scheduling was undocumented. SKILL.md now has dedicated Cron installation section.","fileCount":37,"zipByteSize":84168},{"version":"6.1.6","createdAt":"2026-05-17T19:25:34.869Z","changelog":"Added author contact: rockwaychen@gmail.com / GitHub LingmaFuture.","fileCount":33,"zipByteSize":73544}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1795ynq2axpc6ezsahrdzyhrh83h4sk:self-improving-compound","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lingmafuture-self-improving-compound/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lingmafuture-self-improving-compound/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lingmafuture-self-improving-compound/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-lingmafuture-self-improving-compound/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-lingmafuture-self-improving-compound/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-lingmafuture-self-improving-compound/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T08:44:18.548Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lingmafuture-self-improving-compound/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lingmafuture-self-improving-compound/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lingmafuture-self-improving-compound/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lingmafuture-self-improving-compound/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T23:49:30.668Z","emptyReason":null},"readme":"Skill: Self Improving Compound\n\nOwner: lingmafuture\n\nSummary: Agent memory and self-improvement system. Replaces naive file-based agent memory with a structured SQLite learning engine: capture corrections, errors, and r...\n\nTags: latest:6.2.5, lifecycle:1.0.5, memory:1.0.5, self-improvement:1.0.5\n\nVersion history:\n\nv6.2.5 | 2026-05-19T07:53:29.795Z | user\n\nAdd observable Candidate → Learning → Promotion memory pipeline with candidate queue, promotion queue, incremental cursor, and dashboard; update Light Check cron template to scan candidate-first and commit cursor only after successful processing.\n\nv6.2.4 | 2026-05-19T06:43:34.655Z | user\n\nDocument deterministic Light Check context collector pattern; add SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR; update cron template to report BLOCKED on collector failure and use sessions_history only as verified fallback.\n\nv6.2.3 | 2026-05-18T08:50:37.292Z | user\n\nPackaging hygiene release: keep local .reference research artifacts in the canonical working directory while excluding them from GitHub and ClawHub via ignore files; verified ClawHub publish file collection excludes local reference artifacts.\n\nv6.2.2 | 2026-05-18T07:37:57.793Z | user\n\nImprove installation experience: clarify that clawhub install only copies files, add full activation flow in SKILL.md covering env vars, learning init, capture gate, cron setup, hooks, optional daily collector, smoke tests, and common install failures.\n\nv6.2.1 | 2026-05-18T07:10:28.075Z | user\n\nClarify the 3+7 model as 3 state directories plus 7 root Markdown control-plane files, add README language links, and tighten Workspace Steward wording for the seven markdown files.\n\nv6.2.0 | 2026-05-18T06:59:53.759Z | user\n\nSync local OpenClaw memory-system hardening: daily factual memory digest guidance, Daily Workspace Steward cron template, portable daily-memory helper, refreshed README/SKILL docs, and sanitized public package.\n\nv6.1.7 | 2026-05-17T19:57:46.231Z | user\n\nAdded cron installation infrastructure (setup-cron.json + setup-cron-agent.md). Closes the cron audit architecture gap: scripts existed but scheduling was undocumented. SKILL.md now has dedicated Cron installation section.\n\nv6.1.6 | 2026-05-17T19:25:34.869Z | user\n\nAdded author contact: rockwaychen@gmail.com / GitHub LingmaFuture.\n\nv6.1.5 | 2026-05-17T19:21:09.707Z | user\n\nPositioned as agent memory and learning system. Optimized description and intro: three-layer architecture (capture → audit → promotion), 7+3 co-evolution model. Category changed to memory-system.\n\nv6.1.4 | 2026-05-17T19:03:42.307Z | user\n\nPublic staging sync: full 6.1.x stack including SQLite backend, activation hardening with cron enforcement architecture, session-history aware audit, capture gate output routing, and 7+3 co-evolution model.\n\nv6.1.3 | 2026-05-17T18:56:22.299Z | user\n\nAdd capture gate output routing table. Formalize 7+3 continuous-improvement model: memory + learning + skills + AGENTS + TOOLS + MEMORY + HEARTBEAT co-evolve.\n\nv6.1.2 | 2026-05-17T18:10:49.550Z | user\n\nArchitecture upgrade: replace heartbeat-based audit with cron-isolated enforcement (light check every 2h + heavy audit 2x/day). Document session visibility via sessions_history, cron vs heartbeat rationale, and full activation hardening guide.\n\nv6.1.1 | 2026-05-17T17:37:39.654Z | user\n\nAdd activation hardening mechanisms: final-before-reply capture gate, heartbeat learning audit, watchdog/doctor/cron failure log-error routing, daily SQLite export, and helper scripts.\n\nv6.1.0 | 2026-05-17T16:20:20.004Z | user\n\nPublish refreshed README and 6.1.0 self-improving-compound package with SQLite memory-tree architecture, updated references, eval checks, hooks, and CLI workflow documentation.\n\nv6.0.4 | 2026-05-17T04:26:16.740Z | user\n\nFix maintain WARM-to-HOT promotion crash caused by Python helper name shadowing; add regression coverage for the promotion path; keep sanitized public package in sync.\n\nv6.0.3 | 2026-05-16T17:03:29.966Z | user\n\nClean sanitized republish under the original name and slug. Removes public suffix, uses projects staging copy, keeps Daily Memory Digest and learning-routing improvements, and avoids local personal/environment metadata.\n\nv6.0.2 | 2026-05-16T16:56:24.724Z | user\n\nSanitized public release. Keeps Daily Memory Digest and learning-routing improvements, opencode audit hardening, configurable collector paths, and removes local personal/environment metadata from the published package.\n\nv6.0.1-rockway.2 | 2026-05-16T16:46:46.987Z | user\n\nLow-risk hardening after opencode+OmO+Kimi audit: improve daily-memory wrapper help/date validation/python checks, complete index references, clean unused extract-skill variable, and add small hook robustness.\n\nv6.0.1-rockway.1 | 2026-05-16T16:27:16.028Z | user\n\nIntegrate Rockway Daily Memory Digest automation, explicit OpenClaw memory/learning routing, .skill provenance metadata, and local daily-memory wrapper.\n\nv6.0.1 | 2026-05-12T09:35:04.328Z | user\n\nv6.0.1: Fix directory name from learnings/ to learning/ for consistency across all files, hooks, and docs. All tests pass.\n\nv6.0.0 | 2026-05-12T08:22:47.322Z | user\n\nv6.0.0: Migrated from .learnings to learning/ directory, added --area parameter, WARM->HOT reverse promotion, promote/edit commands, daily-memory.sh, hermes-integration reference, improved dedup with SequenceMatcher.\n\nv1.0.5 | 2026-05-10T09:14:53.425Z | user\n\nCorrect emergency republish from isolated skill directory. Includes lifecycle maintenance command, HOT/WARM/COLD memory flow, heartbeat guidance, and tests.\n\nv1.0.4 | 2026-05-10T09:10:36.320Z | user\n\nAdd ivangdavila-inspired memory lifecycle maintenance: maintain dry-run/apply, HOT/WARM/COLD promotion-demotion-archive flow, lifecycle metadata, heartbeat guidance, and tests.\n\nv1.0.3 | 2026-05-09T16:29:03.797Z | user\n\nIntegrate GenericAgent-inspired memory hygiene: action-verified memory guidance, volatile-state protection for learning logs, pointer/index hygiene documentation, and tests.\n\nv1.0.2 | 2026-05-08T22:23:58.979Z | user\n\nClean republish: package only the skill folder and avoid scanner false positives in tests.\n\nv1.0.1 | 2026-05-08T22:22:06.586Z | user\n\nHardening: local timezone IDs, status counts, root compatibility, JSON output, regression tests.\n\nv1.0.0 | 2026-05-08T21:17:23.843Z | user\n\nInitial release: composite self-improving skill absorbing best practices from OpenClaw stock (HOT/WARM/COLD tiers), tristanmanchester (Python toolchains + evals), and pskoett (quantified promotion thresholds + hooks).\n\nArchive index:\n\nArchive v6.2.5: 40 files, 111329 bytes\n\nFiles: _meta.json (142b), CHANGELOG.md (10728b), corrections.md (413b), evals/output-check.md (570b), evals/output-evals.json (2135b), evals/trigger-check.md (492b), evals/trigger-validation.json (967b), heartbeat-state.md (155b), hooks/activator.sh (1211b), hooks/error-detector.sh (1312b), hooks/README.md (459b), index.md (918b), memory.md (1473b), README_zh.md (8341b), README.md (12744b), references/daily-memory-digest.md (2418b), references/entry-formats.md (2096b), references/heartbeat-guidance.md (2761b), references/hermes-integration.md (4871b), references/platform-setup.md (1867b), references/promotion-and-extraction.md (5796b), scripts/daily-memory.sh (2780b), scripts/extract-skill.sh (2754b), scripts/learning-audit.py (4616b), scripts/learning-export.sh (630b), scripts/learnings.py (79485b), scripts/log-system-failures.sh (1553b), scripts/memory-pipeline.py (20668b), scripts/memory/__init__.py (1283b), scripts/memory/chunker.py (8619b), scripts/memory/ingest.py (3320b), scripts/memory/store.py (42938b), scripts/memory/test_memory.py (13959b), scripts/memory/types.py (4495b), scripts/setup-cron-agent.md (3989b), scripts/setup-cron.json (9503b), scripts/test_evals.py (18592b), scripts/test_learnings.py (31407b), skill-card.md (2969b), SKILL.md (35138b)\n\nFile v6.2.5:SKILL.md\n\n---\nname: self-improving-compound\ndescription: \"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.\"\ncompatibility: \"Portable Agent Skills format. Core workflow is agent-agnostic. Bundled helpers require Python 3.8+; hook helpers require bash. No network access is required.\"\nmetadata:\n version: \"6.2.5\"\n original_slug: \"self-improving-compound\"\n category: \"memory-system\"\n author: \"Hybrid adaptation from actual-self-improvement, self-improving-compound, OpenHuman memory-tree, and Hermes Agent architecture | Contact: rockwaychen@gmail.com | GitHub: LingmaFuture\"\n---\n\n# Self-Improving Compound\n\nAn 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.\n\nThe system runs as four layers:\n- **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.\n- **Layer 1 — Real-time capture**: AGENTS.md final-before-reply gate logs corrections, errors, and workarounds to SQLite as they happen.\n- **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).\n- **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.\n- **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.\n\n**Author:** Rockway Chen · [rockwaychen@gmail.com](mailto:rockwaychen@gmail.com) · [GitHub: LingmaFuture](https://github.com/LingmaFuture)\n\n## Installation and activation — `clawhub install` is only step 1\n\nA raw ClawHub install only copies the skill files. It does **not** automatically wire the agent into a self-improving operating loop.\n\nUse this maturity ladder:\n\n| Level | What is configured | Result |\n|---|---|---|\n| 1/5 | `clawhub install self-improving-compound` | Files are present; almost no behavior changes yet. |\n| 2/5 | `learning/` initialized and CLI verified | Manual logging/search works. |\n| 3/5 | Capture gate added to agent instructions | The agent remembers to log lessons before final replies. |\n| 4/5 | Cron jobs installed and delivery configured | Missed lessons, failures, daily memory, and steward checks run automatically. |\n| 5/5 | Hooks/env/collector verified | Activation reminders, error capture, path resolution, and daily factual memory are reliable. |\n\n### Phase 0 — Identify roots\n\nYou must distinguish two roots:\n\n```bash\n# Workspace root: where memory/, learning/, AGENTS.md, etc. live\nexport OPENCLAW_WORKSPACE=\"/path/to/workspace\"\n\n# Optional shared lesson store for multiple workspace roots\n# export SELF_IMPROVING_LEARNING_ROOT=\"$HOME/.openclaw/shared-learning\"\n\n# Skill root: where this skill was installed\nexport SELF_IMPROVING_SKILL_DIR=\"$OPENCLAW_WORKSPACE/skills/self-improving-compound\"\nexport SELF_IMPROVING_LEARNINGS_CLI=\"$SELF_IMPROVING_SKILL_DIR/scripts/learnings.py\"\n```\n\nFor OpenClaw's default workspace this is usually:\n\n```bash\nexport OPENCLAW_WORKSPACE=\"$HOME/.openclaw/workspace\"\nexport SELF_IMPROVING_SKILL_DIR=\"$OPENCLAW_WORKSPACE/skills/self-improving-compound\"\nexport SELF_IMPROVING_LEARNINGS_CLI=\"$SELF_IMPROVING_SKILL_DIR/scripts/learnings.py\"\n```\n\nDo 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.\n\n### Phase 1 — Install files\n\n```bash\nclawhub install self-improving-compound\ncd \"$SELF_IMPROVING_SKILL_DIR\"\nchmod +x scripts/*.py scripts/*.sh hooks/*.sh 2>/dev/null || true\n```\n\nIf the skill is copied manually, set `SELF_IMPROVING_SKILL_DIR` to the copied directory.\n\nThe bundled shell helpers require bash. On POSIX `sh`-only hosts, use the Python CLI directly and skip the `.sh` helpers.\n\n### Phase 2 — Initialize and verify the learning store\n\n```bash\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" init\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" status\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" search \"install smoke test\" --limit 3\n```\n\nExpected result:\n\n- `learning/memory_tree/chunks.db` exists.\n- `status` exits successfully.\n- `search` works even when there are no results.\n\n### Phase 3 — Add the capture gate to agent instructions\n\nAdd a compact rule to the agent's durable instruction file, usually `AGENTS.md`:\n\n```markdown\n## Self-improvement capture gate\n\nBefore 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.\n\nIf yes:\n1. Search existing learnings first:\n `python3 $SELF_IMPROVING_LEARNINGS_CLI --root $OPENCLAW_WORKSPACE search \"\" --limit 5`\n2. If no suitable entry exists, log the durable lesson with `log-correction`, `log-error`, `log-learning`, or `log-feature`.\n3. Keep entries compact, prevention-oriented, and secret-free.\n```\n\nWithout this phase the skill remains mostly passive; the agent will not consistently capture lessons in real time.\n\n### Phase 4 — Install the cron pipeline\n\nCron installation is not automatic. The templates live in `scripts/setup-cron.json`; agent-facing instructions live in `scripts/setup-cron-agent.md`.\n\nRecommended OpenClaw flow:\n\n1. Ask the agent: \"Install the self-improving compound cron jobs using `scripts/setup-cron.json`. Check existing jobs first and update instead of duplicating.\"\n2. Configure delivery for your channel, e.g. Telegram or Feishu.\n3. Verify with `cron list`.\n\nThe pipeline normally includes:\n\n| Job | Purpose |\n|---|---|\n| Self-Improving Light Check | Frequent lightweight scan for missed corrections, errors, and blockers. |\n| Learning Audit Heavy | System/cron failure audit, `learning-audit.py --log`, lifecycle maintenance. |\n| Daily Memory Digest | Writes `memory/YYYY-MM-DD.md` factual continuity notes and extracts reusable lessons. |\n| Daily Workspace Steward | Exports `learning/`, checks `skills/`, and inspects the 7 root Markdown control-plane files. |\n\nImportant cron requirements:\n\n- Set `schedule.tz` to the user's actual timezone.\n- Set or infer `delivery.channel` and `delivery.to`; otherwise reports may not reach the user.\n- Use `cron update` for existing jobs; do not create duplicates.\n- 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.\n\n### Phase 5 — Configure optional hooks\n\nHooks are optional but improve activation. They are runtime-specific.\n\nDry-run the bundled hooks first:\n\n```bash\n\"$SELF_IMPROVING_SKILL_DIR/hooks/activator.sh\" \"install smoke test\" || true\n\"$SELF_IMPROVING_SKILL_DIR/hooks/error-detector.sh\" \"install\" \"smoke test\" || true\n```\n\nIf your client supports command hooks, wire:\n\n- `hooks/activator.sh` as a pre-prompt / prompt-start reminder.\n- `hooks/error-detector.sh` as a post-error / failed-command reminder.\n\nIf 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.\n\n### Phase 6 — Configure the observable memory pipeline\n\nThe 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.\n\n```bash\nexport SELF_IMPROVING_MEMORY_PIPELINE=\"$SELF_IMPROVING_SKILL_DIR/scripts/memory-pipeline.py\"\n# Optional if the OpenClaw session key is ambiguous:\n# export SELF_IMPROVING_MAIN_SESSION_KEY=\"agent:main::direct:\"\npython3 \"$SELF_IMPROVING_MEMORY_PIPELINE\" --base \"$OPENCLAW_WORKSPACE/learning/pipeline\" dashboard\n```\n\nState files:\n\n- `learning/pipeline/candidates.jsonl` — suspected lessons awaiting dedupe/logging.\n- `learning/pipeline/promotion-queue.json` — logged lessons awaiting skill/root-file promotion.\n- `learning/pipeline/cursor.json` — last processed transcript line for incremental cron scans.\n- `learning/pipeline/dashboard.md` and `learning/dashboard.md` — human-readable health view.\n\nCron 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.\n\n### Phase 7 — Configure optional context collectors\n\nFor 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.\n\nLight Check can use a local recent-conversation collector:\n\n```bash\nexport SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR=\"python3 /path/to/recent-context-collector.py --limit 60\"\n```\n\nCollector contract:\n\n- Exit `0` only when context was exported successfully.\n- Print either the output context path or a compact JSON summary containing the path/status.\n- Write a readable Markdown/JSON context file with recent user/assistant visible text.\n- Exit non-zero if the transcript/session cannot be found; the cron job should report `BLOCKED: collector_unavailable` instead of claiming success.\n\n`Daily Memory Digest` can also use a local collector if your runtime has one:\n\n```bash\nexport SELF_IMPROVING_DAILY_COLLECTOR=\"python3 /path/to/collector.py\"\nbash \"$SELF_IMPROVING_SKILL_DIR/scripts/daily-memory.sh\" --root \"$OPENCLAW_WORKSPACE\"\n```\n\nIf no collector is configured, the helper prints the target note contract and the agent must gather context with available runtime tools.\n\n### Phase 8 — End-to-end smoke test\n\nRun this checklist after installation:\n\n```bash\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" log-learning \\\n --summary \"Self-improving install smoke test\" \\\n --details \"Temporary entry to verify logging path; mark resolved or delete if desired.\" \\\n --pattern \"install:smoke-test\" \\\n --area \"domain:setup\"\n\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" search \"install smoke test\" --limit 5\nbash \"$SELF_IMPROVING_SKILL_DIR/scripts/learning-export.sh\"\nbash \"$SELF_IMPROVING_SKILL_DIR/scripts/daily-memory.sh\" --root \"$OPENCLAW_WORKSPACE\" --date \"$(TZ=Asia/Shanghai date +%F)\"\n```\n\nThen verify:\n\n- `learning/memory-export.md` exists.\n- `learning/status.json` exists.\n- `memory/YYYY-MM-DD.md` target is clear if daily memory is enabled.\n- `cron list` shows the expected enabled jobs with `nextRunAtMs`.\n- Delivery target is configured for cron job summaries.\n\n### Common install failures\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| `clawhub install` succeeded but nothing changes | Capture gate and cron not configured | Complete phases 3-4. |\n| 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. |\n| Learnings appear under the skill directory | Wrong `--root` | Set `OPENCLAW_WORKSPACE`; always pass `--root`. |\n| Cron summaries disappear | `delivery` missing channel/recipient | Set `delivery.channel` + `delivery.to`. |\n| Daily memory is generic or empty | No collector/context source | Configure `SELF_IMPROVING_DAILY_COLLECTOR` or improve the cron prompt. |\n| Duplicate cron jobs | Setup re-run without idempotency check | `cron list` first; update by job name. |\n\n## 3+7 co-evolution model\n\nThe **3** state directories are:\n\n- `memory/` — factual daily continuity.\n- `learning/` — SQLite-backed execution lessons.\n- `skills/` — hardened reusable procedures.\n\nThe **7** root Markdown control-plane files are:\n\n- `AGENTS.md` — workspace contract, routing, execution policy, safety boundaries.\n- `HEARTBEAT.md` — lightweight check-in surface; often intentionally empty when cron owns timing.\n- `IDENTITY.md` — compatibility pointer or short identity bridge.\n- `MEMORY.md` — pinned long-term hot context.\n- `SOUL.md` — agent identity/persona.\n- `TOOLS.md` — concrete local environment/tool facts.\n- `USER.md` — durable user profile and collaboration preferences.\n\nThe 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.\n\n## Core idea\n\nUse this system for **durable improvement**, not for every bump in the road.\n\n### Mandatory capture gate\n\nBefore a final reply, run this quick check:\n\n- Did the task include a non-obvious failure, API/tool quirk, or format mismatch?\n- Did a workaround or environment-specific convention make the task succeed?\n- Did the user correct a fact, preference, workflow, or expectation?\n- Would repeating this lesson save time or prevent damage later?\n\nIf yes, **search existing learnings first, then log the lesson before replying**. Do not rely on a “mental note.”\n\nA good entry usually has at least one of these properties:\n- It corrected a wrong assumption.\n- It revealed a project-specific convention.\n- It required real debugging or investigation.\n- It is likely to recur.\n- It should change future workflow, memory, or tooling.\n\nDo **not** log routine noise such as obvious typos, expected validation failures, or errors that were solved immediately with no transferable lesson.\n\n### Capture gate output routing\n\nNot all lessons go to the same place. Route based on type:\n\n| Lesson type | Destination | Example |\n|---|---|---|\n| User facts, preferences, system state | `MEMORY.md` / `memory/YYYY-MM-DD.md` | \"Rockway prefers newspaper theme\" |\n| Execution mistakes, tool gotchas, workarounds | `learning/` SQLite | \"Python shadowing broke promote\" |\n| Stable rules, workflows, anti-patterns discovered | owning `skills//SKILL.md` | \"cron isolation means no session context\" |\n| Behavioral constraints | `AGENTS.md` | \"Don't commit workspace root\" |\n| Environment-specific tool knowledge | `TOOLS.md` | \"Tailscale node name\" |\n\nThe 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.\n\n## Hybrid architecture\n\nThis skill merges three design lineages into one portable package:\n\n| Lineage | Role | What We Kept |\n|---|---|---|\n| **actual-self-improvement** | Execution core | Python CLI (`scripts/learnings.py`), structured logging, JSON evals, search-before-log dedupe |\n| **OpenHuman memory-tree** | Storage core | SQLite chunks, FTS search, entity index, scores, hotness, async jobs, deterministic tree buffers, lifecycle status, idempotent ingest |\n| **self-improving-compound** | Memory architecture | HOT/WARM/COLD lifecycle, workspace-scoped `learning/`, lightweight bootstrap markdown |\n| **self-improving-agent-local** | Promotion & hooks | Quantified promotion thresholds, OpenClaw hook guidance, pattern-key recurrence rules |\n\n### Directory layout under `learning/`\n\n```\nlearning/\n├── memory_tree/chunks.db # SQLite source of truth for durable learnings\n├── index.md # SQLite-generated snapshot (entries, lifecycle, pattern keys)\n├── promotion-queue.json # bounded maintain queue for proven promotion candidates\n├── projects/ # WARM tier (project-specific)\n├── domains/ # WARM tier (domain-specific)\n└── archive/ # COLD tier (inactive)\n```\n\n## Important path model\n\nThere are **two different roots** in this skill:\n\n1. **Skill root** — where bundled resources live:\n - `scripts/...`\n - `references/...`\n - `hooks/...`\n\n2. **Workspace root** — where the project or active workspace lives:\n - `learning/memory_tree/chunks.db`\n - `learning/index.md` (SQLite-generated snapshot)\n - `memory/YYYY-MM-DD.md` factual daily notes, when enabled\n - `learning/projects/`\n - `learning/domains/`\n - `learning/archive/`\n - root agent files such as `AGENTS.md`, `MEMORY.md`, `TOOLS.md`, `USER.md`, `SOUL.md`, `HEARTBEAT.md`, `IDENTITY.md`\n\nWhen `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.\n\nNever write learnings into the installed skill directory. Always target the **workspace root** for project memory and the optional **learning root** for shared lesson storage.\n\n\n## Activation hardening mechanisms\n\nWhen 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:\n\n- **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.\n- **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.\n- **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.\n\n### Architecture decisions (why cron, not heartbeat)\n\n- **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.\n- **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.\n- **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.\n\n### Recommended cron schedule\n\n```text\nCron Schedule (Asia/Shanghai)\n────────────────────────────────────── ──────────────────────\nSelf-Improving Light Check 0 8-22/2 * * * (every 2h during waking hours)\nLearning Audit (Heavy) 0 9,22 * * * (2x/day)\nDaily Memory Digest 50 23 * * * (nightly factual memory)\nDaily Workspace Steward 20 0 * * * (post-digest maintenance)\n```\n\n#### Light Check (every 2h, 08:00-22:00)\n\nA 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.\n\n#### Heavy Audit (09:00, 22:00)\n\nFull 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.\n\n#### Daily Memory Digest (23:50)\n\nRun `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.\n\n#### Daily Workspace Steward (00:20)\n\nRun `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.\n\n### Cron installation (one-time setup)\n\n**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.\n\nThe production-grade cron job definitions are in `scripts/setup-cron.json`. The agent-facing setup guide is `scripts/setup-cron-agent.md`.\n\nQuick setup (run from your OpenClaw main session):\n\n1. **Confirm**: \"I want to install the self-improving compound cron jobs. Use `scripts/setup-cron.json` as reference.\"\n\n2. Your agent will:\n - Read the JSON definitions\n - Resolve placeholder paths (skill root, workspace root)\n - Ask or infer your delivery channel (Telegram / Feishu / etc.)\n - Call `cron add` / `cron update` for each job, avoiding duplicates\n\n3. **Verify**: `cron list` should show enabled jobs with `nextRunAtMs` set.\n\nIf you already have these jobs running, this step is a no-op.\n\n### AGENTS.md capture gate\n\nAdd the following rule to agent instructions (e.g. AGENTS.md):\n\n> 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 search \"\" --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.\n\n### System failure routing\n\nRoute watchdog, doctor, healthcheck, and cron failure signals into `log-error` with stable pattern keys and dedupe:\n\n- Pattern keys: `cron:`, `doctor:`, `watchdog:`, `system:openclaw-audit-failure`\n- Use `scripts/log-system-failures.sh` as an OpenClaw CLI audit wrapper where available.\n- Always search existing entries first to prevent repeated failures from flooding SQLite.\n\n### Guardrails\n\n- Keep entries compact and prevention-oriented.\n- Never log secrets; the CLI redacts tokens, passwords, and API keys automatically.\n- Do not paste full audit exports into chat unless explicitly asked.\n- Treat audit candidates as review prompts rather than automatic truth.\n- Cron runs should reply with one-line summaries or `HEARTBEAT_OK`; do not echo full command output.\n\n## Quick decision table\n\n| Situation | What to do |\n|---|---|\n| User corrects you or updates a fact | Log a **correction** |\n| Non-obvious command / API / tool failure | Log an **error** |\n| User asks for a missing capability | Log a **feature request** |\n| You discover a reusable workaround or convention | Log a **learning** |\n| A pattern keeps recurring | Search related entries, link with `See Also`, and consider promotion |\n| A lesson is broadly applicable or repeated | Promote it into project memory |\n| A resolved, general pattern could help other projects | Extract a new skill |\n\n## Standard workflow\n\n### 0) Optional nightly factual memory\n\nIf the workspace uses daily factual notes, run or schedule:\n\n```bash\nbash scripts/daily-memory.sh --root /absolute/path/to/workspace\n```\n\nThen 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.\n\n### 1) Find the workspace root first\n\nBefore reading or writing `learning/`, determine `WORKSPACE_ROOT`.\n\nGood defaults:\n- the repository root for the current codebase\n- the OpenClaw workspace root (`OPENCLAW_WORKSPACE` env var)\n- the directory containing the files being edited\n\nIf unsure, prefer the directory containing `.git`, `AGENTS.md`, `CLAUDE.md`, or the user's active project files.\n\n### 2) Initialise `learning/` if needed\n\nUse the helper instead of creating files manually:\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace init\n```\n\nThis creates:\n- `learning/memory_tree/chunks.db` (SQLite database)\n- `learning/projects/`\n- `learning/domains/`\n- `learning/archive/`\n\nThe `learning/index.md` snapshot is generated on first write (log, promote, etc.).\n\n### 3) Review existing learnings before risky or familiar work\n\nReview first when:\n- you are returning to an area with prior failures\n- the task touches infra, CI, deployment, auth, data migration, or generated code\n- the user explicitly says \"remember this\", \"we hit this before\", or similar\n\nUse the helper:\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace status\npython3 scripts/learnings.py --root /absolute/path/to/workspace search \"pnpm\" --limit 5\npython3 scripts/learnings.py --root /absolute/path/to/workspace search \"pnpm\" --touch\n\n# --root can also be placed after the subcommand\npython3 scripts/learnings.py status --root /absolute/path/to/workspace --format json\n```\n\nPlain `search` is read-only. Use `--touch` only when the result was actually reused and should increment recurrence metadata.\n\n### 4) Search before logging to avoid duplicates\n\nAlways search for related entries before creating a new one.\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace search \"keyword or pattern\" --limit 10\n```\n\nIf a similar entry already exists:\n- prefer linking with `See Also`\n- reuse or add a stable `Pattern-Key` for recurring issues\n- bump priority only when recurrence justifies it\n- prefer updating the existing pattern story over spraying near-duplicate entries\n\n### 5) Log the right kind of entry\n\n#### Correction\nUse for user corrections and updated facts. Stored in SQLite with a human ID such as `COR-YYYYMMDD-001`.\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace log-correction \\\n --summary \"Used wrong format for Telegram\" \\\n --correct \"Use lists, not tables\" \\\n --pattern chat:telegram-format\n```\n\n#### Learning\nUse for corrections, knowledge gaps, best practices, and durable conventions. Stored in SQLite with a human ID such as `LRN-YYYYMMDD-001`.\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace log-learning \\\n --summary \"Project uses pnpm workspaces, not npm\" \\\n --details \"Attempted npm install. Lockfile and workspace config showed pnpm.\" \\\n --pattern pkg:pnpm-workspace\n```\n\n#### Error\nUse for non-obvious failures, exceptions, or tool/API issues worth remembering. Stored in SQLite with a human ID such as `ERR-YYYYMMDD-001`.\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace log-error \\\n --summary \"Docker build failed on Apple Silicon due to platform mismatch\" \\\n --details \"docker build -t myapp . on Apple Silicon\" \\\n --pattern docker:platform\n```\n\n#### Feature request\nUse 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`.\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace log-feature \\\n --summary \"User needs report export to CSV\" \\\n --details \"Needed for sharing weekly reports with non-technical stakeholders\" \\\n --pattern reports:csv-export\n```\n\n#### Backward-compatible log\nThe old `log` subcommand is preserved for compatibility:\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace log \"Used wrong format\" \\\n --type COR --pattern chat:telegram-format --correct \"Use lists\" --force\n```\n\nTo inspect or share entries, export from SQLite:\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace export\npython3 scripts/learnings.py --root /absolute/path/to/workspace export --format json\n```\n\n### 6) Promote proven lessons into memory\n\nPromote when the learning is broad, repeated, or something any future contributor should know.\n\nCommon targets:\n- `CLAUDE.md` — durable project facts and conventions\n- `AGENTS.md` — workflow rules and automation guidance\n- `.github/copilot-instructions.md` — shared Copilot context\n- `SOUL.md` — behavioural principles in OpenClaw workspaces\n- `TOOLS.md` — tool-specific gotchas in OpenClaw workspaces\n\nWrite promotions as **short prevention rules**, not long incident write-ups.\n\nExample:\n- Bad promotion: \"On 2026-03-12 npm failed because…\"\n- Good promotion: \"Use `pnpm install` in this repo; it is a pnpm workspace.\"\n\nWhen a learning is promoted, update the original entry's status to `promoted` or `promoted_to_skill` and record the destination.\n\n`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.\n\n### 7) Extract a reusable skill when the pattern is real\n\nExtract a new skill when the solution is:\n- resolved and working\n- broadly useful beyond one file or repo\n- non-obvious enough that future agents would benefit\n- recurring enough to justify its own instructions\n\nUse the helper:\n\n```bash\nbash scripts/extract-skill.sh my-skill-name /absolute/path/to/workspace\n```\n\n## Logging rules that matter most\n\n1. **Search first.** Duplicate entries are worse than missing tags.\n2. **Prefer durable lessons.** Only log what should change future behaviour.\n3. **Be specific.** Name the assumption, failure, or convention clearly.\n4. **Include the fix or prevention rule.** An entry without next action is weak.\n5. **Use stable pattern keys for recurring problems.** This lets recurrence compound.\n6. **Promote aggressively once a rule is proven.** The point is fewer repeat mistakes.\n7. **Do not interrupt the user with bookkeeping.** Log silently unless the user asked to see it or you need missing details.\n8. **Never log secrets.** Tokens, passwords, API keys, and private data must be redacted or omitted.\n\n## Memory lifecycle (integrated from ivangdavila/self-improving)\n\nEntries carry metadata (`First-Seen`, `Last-Seen`, `Recurrence-Count`, `Status`, `Area`) so the system can make deterministic lifecycle decisions without guessing.\n\n| Tier | Location | Size guidance | Behavior |\n|------|----------|---------------|----------|\n| HOT | SQLite lifecycle `admitted` | Active working set | Shown by `status`, `search`, and hooks |\n| WARM | SQLite lifecycle `buffered` | 30+ days unused | Retained for context-specific search |\n| COLD | SQLite lifecycle `sealed` | archived/promoted/resolved | Retained for explicit query/export |\n\n### Automatic promotion/demotion\n\nUse `python3 scripts/learnings.py --root maintain` to review:\n\n| Condition | Threshold | Action |\n|---|---|---|\n| HOT -> WARM | 30 days unused | Set lifecycle to `buffered` |\n| WARM -> COLD | 90 days unused | Set lifecycle to `sealed` |\n| Frequent reuse | `Recurrence-Count >= 3` from explicit reuse (`search --touch` or `edit`) | Flag for project-memory promotion |\n| Compaction/export | Human review needed | Export and manually summarize/promote without deleting the SQLite record |\n\n`maintain` defaults to `--dry-run`. Use `--apply` to execute lifecycle status moves. It never deletes content and does not auto-summarize.\n\n### Conflict resolution\n\nWhen patterns contradict:\n1. **More specific wins**: `project` > `domain` > `global`\n2. **More recent wins** at the same specificity level\n3. **Ambiguous conflicts** → ask the user instead of guessing\n\n## Promotion thresholds (from legacy)\n\n| Condition | Threshold | Action |\n|---|---|---|\n| HOT -> WARM | 30 days unused | Mark `buffered` |\n| WARM -> COLD | 90 days unused | Mark `sealed` |\n| Frequent reuse | 3 recorded uses within 7 days | Promote as a short prevention rule |\n| To AGENTS/SOUL/TOOLS | `Recurrence-Count >= 3` + spans 2+ tasks + within 30 days | Promote as short prevention rule |\n| To skill | Proven + broadly applicable | Extract as skill |\n\n## Recommended references\n\nUse these only when needed:\n- `references/entry-formats.md` — full field schemas and manual templates\n- `references/promotion-and-extraction.md` — promotion rules and skill extraction criteria\n- `references/platform-setup.md` — Claude Code, Codex, Copilot, and OpenClaw setup notes\n\n## Hooks\n\nHook helpers are intentionally optional and workspace-root aware.\n\nAvailable hook scripts:\n- `hooks/activator.sh` — lightweight reminder at prompt start\n- `hooks/error-detector.sh` — lightweight error reminder after failed Bash-like commands\n\nHook configuration examples live in `references/platform-setup.md`.\n\n## What \"next-level\" looks like for this skill\n\nA mature use of this skill has a loop:\n\n**capture → dedupe → promote → extract → evaluate**\n\nThat means:\n- entries are created with stable human IDs, content-addressed chunk IDs, and consistent fields\n- repeated issues link to each other instead of fragmenting\n- proven rules move into persistent memory files\n- broadly useful fixes become standalone skills\n- the skill itself is tested with trigger and output evals in `evals/`\n\nFile v6.2.5:hooks/README.md\n\n# Hooks\n\n## activator.sh\nRuns before prompts to surface relevant patterns from memory.\n\n```bash\n./activator.sh [context]\n```\n\n## error-detector.sh\nRuns after errors to log them for later analysis.\n\n```bash\n./error-detector.sh [type] [detail]\n```\n\n## Integration\nFor OpenClaw, add to your configuration:\n- activator.sh as `pre-prompt-hook`\n- error-detector.sh as `post-error-hook`\n\n## Permissions\nEnsure scripts are executable:\n```bash\nchmod +x hooks/*.sh\n```\n\nFile v6.2.5:README.md\n\n# Self-Improving Compound\n\n[中文说明 / Chinese README](README_zh.md)\n\nA portable AgentSkill that turns agent memory from scattered markdown notes into a structured self-improvement system: real-time capture, observable Candidate → Learning → Promotion queues, SQLite-backed learning, cron audits with explicit context collection, daily factual memory, and lightweight workspace stewardship.\n\n## What it does\n\n- **Captures durable lessons** before the final reply after non-trivial work: user corrections, tool/API gotchas, non-obvious failures, workarounds, and missing capabilities.\n- **Stores execution learnings in SQLite** under `learning/memory_tree/chunks.db`, with FTS5 search, deterministic entity indexing, dedupe, lifecycle status, exports, and human-readable snapshots.\n- **Keeps facts separate from lessons**: factual continuity goes to `memory/YYYY-MM-DD.md`; reusable prevention rules go to `learning/`.\n- **Audits itself with cron**: light checks, heavy audits, daily factual memory, and post-digest workspace stewardship. Conversation-aware cron jobs should use deterministic context collectors when available instead of relying on implicit chat visibility.\n- **Makes memory observable** with `Candidate → Learning → Promotion → Done`: candidates, promotion backlog, cursor coverage, and dashboard health are visible under `learning/pipeline/`.\n- **Promotes stable rules** into the right layer: `skills/`, `AGENTS.md`, `TOOLS.md`, `MEMORY.md`, or other root agent state files.\n\n## 3+7 co-evolution model\n\nThis system keeps three durable state directories and seven root Markdown control-plane files aligned:\n\n**3 state directories**\n\n- `memory/` — factual daily continuity: what happened, what changed, decisions, links, follow-ups.\n- `learning/` — SQLite-backed execution lessons: corrections, tool/API gotchas, workflow rules.\n- `skills/` — hardened reusable procedures that future agents can load on demand.\n\n**7 root Markdown files**\n\n- `AGENTS.md` — workspace contract, routing, execution policy, safety boundaries.\n- `HEARTBEAT.md` — lightweight check-in surface; often intentionally empty when cron owns timing.\n- `IDENTITY.md` — compatibility pointer or short identity bridge.\n- `MEMORY.md` — pinned long-term hot context.\n- `SOUL.md` — agent identity/persona.\n- `TOOLS.md` — concrete local environment/tool facts.\n- `USER.md` — durable user profile and collaboration preferences.\n\nThe steward loop should make only small, safe consistency updates across these files. It should not rewrite persona, weaken safety rules, or turn daily facts into root-level bloat.\n\n## Architecture\n\n```text\nObservable Memory Pipeline\n -> collect incremental visible context\n -> add candidates\n -> log confirmed SQLite learnings\n -> queue durable promotions\n -> refresh dashboard\n\nReal-time capture gate\n -> search existing SQLite learnings\n -> log compact correction/error/learning/feature entries\n -> enqueue async memory jobs\n\nMemory job worker\n -> process chunk extraction jobs\n -> update scores, entity index, tree buffers, and tree summaries\n -> run HOT/WARM/COLD lifecycle maintenance\n\nDaily factual memory\n -> write memory/YYYY-MM-DD.md\n -> extract only reusable lessons into learning/\n\nWorkspace stewardship\n -> export learning memory\n -> inspect learning/, skills/, and the 7 root Markdown control-plane files\n -> make only small safe consistency updates\n```\n\n## Install: files are only step 1\n\n`clawhub install` only installs the skill files. A useful setup requires activation.\n\n```bash\nclawhub install self-improving-compound\nexport OPENCLAW_WORKSPACE=\"/path/to/workspace\"\n# Optional: share one learning store across multiple workspace roots.\n# export SELF_IMPROVING_LEARNING_ROOT=\"$HOME/.openclaw/shared-learning\"\nexport SELF_IMPROVING_SKILL_DIR=\"$OPENCLAW_WORKSPACE/skills/self-improving-compound\"\nexport SELF_IMPROVING_LEARNINGS_CLI=\"$SELF_IMPROVING_SKILL_DIR/scripts/learnings.py\"\nchmod +x \"$SELF_IMPROVING_SKILL_DIR\"/scripts/*.py \"$SELF_IMPROVING_SKILL_DIR\"/scripts/*.sh \"$SELF_IMPROVING_SKILL_DIR\"/hooks/*.sh 2>/dev/null || true\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" init\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" status\n```\n\nFull activation checklist:\n\n1. Install files with ClawHub or copy the skill directory.\n2. Set `OPENCLAW_WORKSPACE`, `SELF_IMPROVING_SKILL_DIR`, and optionally `SELF_IMPROVING_LEARNINGS_CLI`.\n Set `SELF_IMPROVING_LEARNING_ROOT` only when multiple workspaces should share the same lesson store.\n3. Initialize `learning/` with `learnings.py init`.\n4. Add the capture gate to `AGENTS.md` or equivalent agent instructions.\n5. Install/update cron jobs from `scripts/setup-cron.json` and configure delivery.\n6. Optionally wire `hooks/activator.sh` and `hooks/error-detector.sh`.\n7. Optionally enable `scripts/memory-pipeline.py` for Candidate → Learning → Promotion visibility.\n8. Optionally configure `SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR` for reliable Light Check context and `SELF_IMPROVING_DAILY_COLLECTOR` for high-quality daily memory.\n9. Run smoke tests: search/log/export/daily-memory helper + `cron list`.\n\nSee `SKILL.md` for the detailed installation and activation flow.\n\nRequirements:\n\n- Python 3.8+\n- bash. The bundled `.sh` helpers intentionally use bash features; POSIX `sh`-only environments are unsupported unless you call the Python CLI directly.\n- No network access required for the local CLI\n\n## Quick start\n\n```bash\n# Initialize learning storage in a workspace\npython3 scripts/learnings.py --root /path/to/workspace init\n\n# Search before logging\npython3 scripts/learnings.py --root /path/to/workspace search \"telegram format\" --limit 5\n\n# Log a correction\npython3 scripts/learnings.py --root /path/to/workspace log-correction \\\n --summary \"Telegram replies should avoid wide tables\" \\\n --correct \"Use compact lists for mobile chat\" \\\n --pattern chat:telegram-format\n\n# Log a reusable learning\npython3 scripts/learnings.py --root /path/to/workspace log-learning \\\n --summary \"Cron jobs that need conversation context should collect it explicitly\" \\\n --details \"Isolated cron sessions do not automatically inherit main chat context; prefer a deterministic transcript/context collector, with sessions_history only as a verified fallback.\" \\\n --pattern cron:explicit-context\n\n# Review and maintain lifecycle\npython3 scripts/learnings.py --root /path/to/workspace status\npython3 scripts/learnings.py --root /path/to/workspace maintain --apply\n# Optional automation: promote high-recurrence lessons into workspace memory files.\npython3 scripts/learnings.py --root /path/to/workspace maintain --apply --auto-promote\n\n# Process async memory jobs once, or keep a local daemon running\npython3 scripts/learnings.py --root /path/to/workspace process-jobs\npython3 scripts/learnings.py --root /path/to/workspace process-jobs --daemon --max-jobs 0\n\n# Export for review\nbash scripts/learning-export.sh\n```\n\n## Optional cron pipeline\n\nThe skill ships with OpenClaw cron templates in `scripts/setup-cron.json` and an agent setup guide in `scripts/setup-cron-agent.md`.\n\nRecommended jobs:\n\n| Job | Default schedule | Purpose |\n|---|---:|---|\n| Self-Improving Light Check | every 2h, 08:00–22:00 | Catch obvious missed corrections and blockers. |\n| Learning Audit Heavy | 09:00 and 22:00 | Audit failures, log missed lessons, maintain lifecycle. |\n| Daily Memory Digest | 23:50 | Write `memory/YYYY-MM-DD.md`, then extract reusable lessons. |\n| Daily Workspace Steward | 00:20 | Export learning memory and lightly inspect `learning/`, `skills/`, and the 7 root Markdown control-plane files. |\n\nFor reliable Light Check context, set an optional collector when your runtime can export recent visible conversation from its local session/transcript store:\n\n```bash\nexport SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR=\"python3 /path/to/recent-context-collector.py --limit 60\"\n```\n\nCollector rule: exit 0 only after writing a readable Markdown/JSON context file; exit non-zero when the target transcript is unavailable so cron can report `BLOCKED: collector_unavailable` instead of a false success.\n\nFor an observable queue and health dashboard, use the bundled pipeline helper:\n\n```bash\nexport SELF_IMPROVING_MEMORY_PIPELINE=\"$SELF_IMPROVING_SKILL_DIR/scripts/memory-pipeline.py\"\npython3 \"$SELF_IMPROVING_MEMORY_PIPELINE\" --base \"$OPENCLAW_WORKSPACE/learning/pipeline\" dashboard\n```\n\nThe helper writes `candidates.jsonl`, `promotion-queue.json`, `cursor.json`, `status.json`, and `dashboard.md` under `learning/pipeline/`; it also writes a convenience `learning/dashboard.md`.\n\nCron installation is not automatic. Ask your OpenClaw agent:\n\n> Install the self-improving compound cron jobs using `scripts/setup-cron.json` as reference. Check existing cron jobs first and update instead of duplicating.\n\n## Path Model\n\nThere are two roots:\n\n1. **Skill root** — this package: `scripts/`, `hooks/`, `references/`, `evals/`.\n2. **Workspace root** — your active agent/project state:\n - `learning/memory_tree/chunks.db`\n - `learning/index.md`\n - `memory/YYYY-MM-DD.md` if daily factual memory is enabled\n - root agent files such as `AGENTS.md`, `MEMORY.md`, `TOOLS.md`, `USER.md`, `SOUL.md`, `HEARTBEAT.md`, `IDENTITY.md`\n\nThe learning store can be split from the workspace root with `--learning-root` or `SELF_IMPROVING_LEARNING_ROOT`. In that mode, SQLite, `index.md`, `heartbeat-state.md`, and `promotion-queue.json` live in the shared learning root, while `promote` and `maintain --auto-promote` still write only under the active workspace root.\n\nNever write durable learnings into the installed skill directory. Always pass `--root /path/to/workspace`; add `--learning-root /path/to/shared-learning` only when sharing lessons across projects.\n\n## Architecture Boundary\n\nThis is a selective OpenHuman memory-tree port for agent lesson management, not a full content-management clone. Implemented pieces include SQLite storage, FTS search with fallback, deterministic entity extraction, scoring, entity hotness, async jobs, lifecycle maintenance, deterministic tree buffers, and a promotion queue. LLM topic routing and full OpenHuman-style content workflows are intentionally out of scope for this Python layer.\n\n## Key commands\n\n```bash\npython3 scripts/learnings.py --root /path/to/workspace init\npython3 scripts/learnings.py --root /path/to/workspace status --format json\npython3 scripts/learnings.py --root /path/to/workspace search \"keyword\" --limit 10\npython3 scripts/learnings.py --root /path/to/workspace search \"pk:tooling:api-client-gen\"\npython3 scripts/learnings.py --root /path/to/workspace search \"entity:path:/repo/openapi.yaml\"\npython3 scripts/learnings.py --root /path/to/workspace search \"keyword\" --touch\npython3 scripts/learnings.py --root /path/to/workspace log-error --summary \"...\" --details \"...\" --pattern area:stable-key\npython3 scripts/learnings.py --root /path/to/workspace log-feature --summary \"...\" --details \"...\" --pattern feature:stable-key\npython3 scripts/learnings.py --root /path/to/workspace process-jobs --format json\npython3 scripts/learnings.py --root /path/to/workspace maintain --apply\npython3 scripts/learnings.py --root /path/to/workspace maintain --apply --auto-promote\npython3 scripts/learnings.py --root /path/to/workspace promote LRN-YYYYMMDD-001 --to AGENTS.md\nbash scripts/daily-memory.sh --root /path/to/workspace\nbash scripts/extract-skill.sh my-new-skill /path/to/workspace\n```\n\n## Guardrails\n\n- Search before logging to avoid duplicates.\n- Keep entries compact, searchable, and prevention-oriented.\n- Do not log secrets, tokens, raw private transcripts, or volatile state.\n- Treat cron audit candidates as review prompts, not automatic truth.\n- Daily Workspace Steward may make small safe markdown updates only; it must not rewrite persona, weaken safety/privacy rules, delete files, or change cron jobs.\n\n## Included references\n\n- `references/entry-formats.md` — schemas and manual templates\n- `references/promotion-and-extraction.md` — promotion thresholds and extraction criteria\n- `references/platform-setup.md` — setup guidance for multiple agent runtimes\n- `references/heartbeat-guidance.md` — when to use heartbeat vs cron\n- `references/daily-memory-digest.md` — daily factual memory quality bar\n- `references/hermes-integration.md` — architecture concepts absorbed from Hermes-style agents\n\n## Credits\n\nHybrid adaptation from actual-self-improvement, self-improving-compound, OpenHuman memory-tree, local self-improving-agent patterns, GenericAgent memory hygiene axioms, and Hermes-style agent architecture.\n\nAuthor/maintainer: Rockway Chen · · \n\nFile v6.2.5:_meta.json\n\n{\n \"ownerId\": \"kn7edxdsvkqkfbxghqy9cqz5p583gz7y\",\n \"slug\": \"self-improving-compound\",\n \"version\": \"6.2.5\",\n \"publishedAt\": 1779177209795\n}\n\nFile v6.2.5:references/daily-memory-digest.md\n\n# Daily Memory Digest Integration\n\nThis reference describes the optional daily factual-memory loop that pairs with the SQLite self-improvement store.\n\n## Purpose\n\n`learning/` captures reusable execution lessons. A daily memory digest captures factual continuity: what happened, what changed, what was decided, and what needs follow-up.\n\nUse both loops together:\n\n- `memory/YYYY-MM-DD.md` — factual timeline, decisions, paths, job IDs, links, risks, follow-ups.\n- `learning/memory_tree/chunks.db` — compact reusable prevention rules: corrections, tool/API gotchas, workflow conventions, recurring failures.\n\nDo not duplicate an entire daily note into `learning/`. Extract only lessons that should alter future behavior.\n\n## Suggested daily note quality bar\n\nWhen the day had meaningful activity, prefer a detailed note that can reconstruct the day without rereading raw chat logs.\n\nRecommended sections:\n\n1. Overview\n2. Key workflows and actions\n3. Important decisions\n4. System/configuration changes\n5. Files/projects changed\n6. External integrations and automations\n7. Problems, risks, and unfinished work\n8. Items to promote into long-term memory/rules\n9. Next-step suggestions\n10. Source notes\n\n## Integration options\n\n### Option A — bring your own collector\n\nIf your runtime has a transcript/session collector, call it first and write its output to a context file. Then have the agent synthesize `memory/YYYY-MM-DD.md` from that context.\n\n`scripts/daily-memory.sh` supports:\n\n```bash\nSELF_IMPROVING_DAILY_COLLECTOR=\"python3 /path/to/collector.py\" \\\n bash scripts/daily-memory.sh --root /path/to/workspace --date YYYY-MM-DD\n```\n\nThe collector may print a context path or summary. The agent should inspect that output before writing the final note.\n\n### Option B — no collector\n\nIf no collector exists, use `scripts/daily-memory.sh` as a contract printer. It validates the date/root and prints the target file plus the required quality bar. The agent must gather context using available runtime tools.\n\n## Self-improvement pass\n\nAfter writing the daily note, run the capture gate:\n\n- User correction / changed preference → `log-correction`\n- Non-obvious failure or API/tool/schema quirk → `log-error`\n- Workflow convention or successful reusable workaround → `log-learning`\n- Missing capability or repeated friction → `log-feature`\n\nKeep learning entries short, searchable, and prevention-oriented.\n\nFile v6.2.5:references/entry-formats.md\n\n# Entry formats\n\nUse the bundled `scripts/learnings.py` when possible. Durable entries are SQLite-backed in `learning/memory_tree/chunks.db`; the markdown examples below are the export format and manual fallback.\n\n## Pattern-Key naming convention\n\nAll Pattern-Keys **must use namespaced format**: `project:key` or `domain:key`.\nThis prevents collisions between unrelated contexts.\n\n| ❌ Avoid | ✅ Use instead |\n|----------|---------------|\n| `migration` | `db:migration` |\n| `rate-limit` | `api:rate-limit` |\n| `layer-cache` | `docker:layer-cache` |\n| `timeout` | `network:timeout` |\n| `auth` | `api:auth-flow` or `project-alpha:auth` |\n\n## Correction entry\n\nStored in SQLite. Exported markdown may look like:\n\n```markdown\n### COR-YYYYMMDD-XXX (YYYY-MM-DD) [Pattern-Key: db:migration]\n- **Type**: COR\n- **Summary**: What I got wrong\n- **Details**: Correct answer and context\n- **Status**: pending\n```\n\n## Learning entry\n\nStored in SQLite. Exported markdown may look like:\n\n```markdown\n### LRN-YYYYMMDD-XXX (YYYY-MM-DD) [Pattern-Key: api:rate-limit]\n- **Type**: LRN\n- **Summary**: One-line summary of the lesson\n- **Details**: What happened, what was wrong or surprising, and what is now known to be true\n```\n\n## Error entry\n\nStored in SQLite. Exported markdown may look like:\n\n```markdown\n### ERR-YYYYMMDD-XXX (YYYY-MM-DD) [Pattern-Key: docker:layer-cache]\n- **Type**: ERR\n- **Summary**: One-line description of the failure\n- **Details**: Command, tool, API, or environment details\n```\n\n## Feature request entry\n\nStored in SQLite. Exported markdown may look like:\n\n```markdown\n### FTR-YYYYMMDD-XXX (YYYY-MM-DD) [Pattern-Key: tooling:csv-export]\n- **Type**: FTR\n- **Summary**: One-line summary of the request\n- **Details**: Why the capability matters and a concrete starting point\n```\n\n## Status guidance\n\n- `pending` — captured, not yet addressed\n- `in_progress` — being worked on now\n- `resolved` — issue fixed or lesson integrated\n- `wont_fix` — intentionally not addressing it\n- `promoted` — distilled into project memory\n- `promoted_to_skill` — extracted into a reusable skill\n\nFile v6.2.5:references/heartbeat-guidance.md\n\n# Heartbeat guidance\n\nThis reference describes how to integrate the self-improving memory lifecycle into a periodic heartbeat without creating noise or destructive churn.\n\n## Design principle\n\nHeartbeat should be **conservative and transparent**. Most runs should do nothing. When they do act, they should only perform safe, reversible moves.\n\n## Recommended heartbeat snippet\n\nAdd this to your workspace `HEARTBEAT.md` or equivalent recurring-check file:\n\n```markdown\n## Self-Improving Memory Check\n\n- Run `python3 scripts/learnings.py --root maintain --dry-run`\n- If the report shows only healthy entries or minor recommendations, return `HEARTBEAT_OK`\n- If the report shows clearly safe moves (e.g., stale HOT entries with unambiguous WARM targets), you may run `maintain --apply` automatically\n- If the report shows ambiguous conflicts, promotion candidates, or missing metadata, log a recommendation and ask the user instead of applying\n- `maintain` updates `learning/heartbeat-state.md` with the last run timestamp and result\n```\n\n## State file template\n\nCreate `learning/heartbeat-state.md` to track heartbeat activity:\n\n```markdown\n# Self-Improving Heartbeat State\n\nlast_heartbeat_started_at: never\nlast_reviewed_change_at: never\nlast_heartbeat_result: never\n\n## Last actions\n- none yet\n```\n\n## Safety rules for heartbeat automation\n\n1. **Prefer `maintain --dry-run`** in automated contexts.\n2. **Only auto-apply** when:\n - The lifecycle update is unambiguous (e.g., an `admitted` entry with `Last-Seen` 60 days ago).\n - No promotion candidates are flagged.\n - No conflicts are detected.\n3. **Never auto-apply** when:\n - Metadata is missing or incomplete.\n - A conflict is detected between namespaces.\n - A promotion candidate has `Recurrence-Count >= 3` (ask user first).\n - The target namespace is unclear.\n4. **Preserve source transparency**: after any promotion/export, the SQLite entry should retain `Status` and `Promoted-To` metadata so future readers can trace the history.\n\n## Minimal example\n\n```bash\n# In heartbeat or cron script\nWORKSPACE=\"${OPENCLAW_WORKSPACE:-$(pwd)}\"\n\n# Dry-run review\nREPORT=$(python3 scripts/learnings.py --root \"$WORKSPACE\" maintain --format json)\nSTALE_COUNT=$(echo \"$REPORT\" | python3 -c \"import sys,json; d=json.load(sys.stdin); print(len(d.get('stale_hot',[])))\")\n\nif [ \"$STALE_COUNT\" -eq 0 ]; then\n echo \"HEARTBEAT_OK\"\nelse\n echo \"HEARTBEAT_RECOMMENDATIONS: $STALE_COUNT stale entries found\"\n echo \"$REPORT\"\nfi\n```\n\n## Integration with OpenClaw\n\nIf your workspace uses an OpenClaw `HEARTBEAT.md`, add the snippet above under a `## Self-Improving Memory Check` heading. The skill will then participate in the existing heartbeat flow without adding new files outside `learning/`.\n\nFile v6.2.5:references/hermes-integration.md\n\n# Hermes Integration Notes\n\nHow the self-improving compound selectively incorporates Hermes Agent architecture\nstrengths while staying lean and SQLite-backed.\n\n## Concepts Absorbed from Hermes Architecture\n\n### 1. Skill Registry & Discovery\n\nHermes has a Skills Hub with unified search across official/builtin/community sources\nand trust levels (builtin > trusted > community). We mirror this with:\n\n- **Pattern-Key index** as lightweight skill pointers — each Pattern-Key is a\n discoverable, searchable SQLite entity that links related entries across lifecycle states\n- **Trust levels**: `confirmed` > `pending` > `experimental`, tracked per-entry\n as status metadata\n- **Auto-discovery** via `learnings.py maintain` scan, which surfaces\n high-recurrence patterns as promotion candidates\n- **`extract-skill.sh`** parallels Hermes's skill authoring workflow — turning\n proven learnings into reusable `SKILL.md` documents\n\n### 2. Context Engine Awareness\n\nHermes has pluggable context engines (compressor, etc.). We keep it explicit\nwith tiered lifecycle loading:\n\n- **HOT tier** (`admitted`) — active context candidates, equivalent to Hermes's\n active context window\n- **WARM tier** (`buffered`) — retained context-specific records\n- **COLD tier** (`sealed`) — archived/promoted/resolved records for explicit query/export\n\nThe `activator.sh` hook mirrors Hermes's context priming by extracting top\nPattern-Keys at session start.\n\n### 3. Achievement-Driven Self-Improvement\n\nHermes has `hermes-achievements` plugin for gamified progress tracking. We\nadopt the concept without the gamification:\n\n- **Recurrence-Count** tracks pattern maturity — equivalent to achievement\n progress tracking\n- **Promotion thresholds** as \"achievement gates\": Recurrence-Count >= 3\n triggers promotion review\n- **Pattern extraction** = skill creation — when a pattern proves itself\n across multiple tasks, it graduates to a reusable skill via\n `extract-skill.sh`\n\n### 4. Provider Abstraction (Kept Lean)\n\nHermes has 8 pluggable memory providers. We keep a single SQLite backend\nbut add abstraction for portability:\n\n- Single-file SQLite backend under `learning/memory_tree/chunks.db`\n- JSON-format export option (`--format json`) for portability between systems\n- `OPENCLAW_WORKSPACE` env var for backend location independence\n\n## What We Intentionally Did NOT Absorb\n\n### Multi-Provider Memory Backend\n\nHermes supports 8 memory providers (honcho, mem0, holographic, retaindb,\nbyterover, supermemory, openviking, hindsight). We keep a single SQLite\nbackend.\n\n**Rationale**: SQLite gives reliable local indexing, scoring, and idempotent\ningest while still requiring zero external services. Markdown export preserves\nhuman review and portability when needed.\n\n### Multi-Platform Gateway\n\nHermes has 10+ platform gateways (Telegram, Discord, Slack, Google Meet,\netc.). We stay platform-agnostic.\n\n**Rationale**: The Portable AgentSkill format (`SKILL.md` frontmatter) works\nwherever the agent works — no gateway abstraction needed. The skill travels\nwith the agent.\n\n### Provider-Agnostic Model Switching\n\nHermes has 109+ model providers with runtime switching. We don't need this.\n\n**Rationale**: Memory management is model-agnostic. Learning capture is about\ncontent and patterns, not about which model executes the task. The\nHOT/WARM/COLD tiering works identically regardless of the underlying LLM.\n\n## Strategic Alignment\n\n| Hermes Concept | Our Implementation | Lean-ness |\n|---|---|---|\n| Skills Hub | Pattern-Key Index + `extract-skill.sh` | Lighter — SQLite-backed, no server |\n| Memory Providers | Single SQLite backend with lifecycle tiers | Lighter — no external services |\n| Achievement System | Recurrence-Count + Promotion thresholds | Lighter — automatic, no gamification UI |\n| Context Engine | HOT/WARM/COLD tiered loading | Lighter — explicit, no compression plugin |\n| Skill Authoring | `SKILL.md` frontmatter + `entry-formats.md` | Equivalent |\n| Cron / Scheduling | `heartbeat-guidance.md` + hooks | Lighter — bash-only, no cron plugin |\n| Plugin Discovery | Workspace directory scan | Lighter — no four-source resolution |\n| Observability | `evals/` JSON quality gates | Lighter — no observability plugin |\n\n## Key Design Philosophy\n\nHermes optimizes for **breadth** — many providers, many platforms, many\nmodels. The self-improving compound optimizes for **depth** — fewer\nmechanisms, but each one is fully integrated into the agent's workflow\n(capture gate, tiered storage, promotion lifecycle, skill extraction).\n\nWe absorb Hermes's **structural ideas** (skill registry, context awareness,\nachievement tracking) while rejecting its **infrastructure complexity**\n(multi-provider backends, platform gateways, model switching). The result is\na system that learns like Hermes but deploys like a single directory of\nMarkdown files.\n\nFile v6.2.5:references/platform-setup.md\n\n# Platform setup\n\nThis skill is portable, but automation differs by environment.\n\n## Manual use (works everywhere)\n\nThe safest baseline is manual activation:\n1. determine the workspace root\n2. run `python3 scripts/learnings.py --root /path/to/workspace `\n3. promote or extract only after the pattern is proven\n\n## Claude Code / Claude-style hook configs\n\nExample prompt-start reminder:\n\n```json\n{\n \"hooks\": {\n \"UserPromptSubmit\": [\n {\n \"matcher\": \"\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"/absolute/path/to/self-improving-compound/hooks/activator.sh\"\n }\n ]\n }\n ]\n }\n}\n```\n\nExample error reminder:\n\n```json\n{\n \"hooks\": {\n \"PostToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"/absolute/path/to/self-improving-compound/hooks/error-detector.sh\"\n }\n ]\n }\n ]\n }\n}\n```\n\n## Codex / other skills-aware CLIs\n\nUse the same manual workflow unless your client supports equivalent command hooks.\n\n## GitHub Copilot\n\nWhen hooks are unavailable, add a compact reminder to `.github/copilot-instructions.md`:\n\n```markdown\n## Self-improvement\nAfter solving non-obvious issues or learning project-specific conventions, consider logging the durable lesson to `learning/` and promoting proven rules into shared memory.\n```\n\n## OpenClaw\n\nOpenClaw-specific notes:\n- Set `OPENCLAW_WORKSPACE` so `--root` is optional.\n- Keep `learning/` in the workspace root by default, not the skill directory.\n- Set `SELF_IMPROVING_LEARNING_ROOT` only when several workspaces should share one lesson store.\n- The `hooks/activator.sh` and `hooks/error-detector.sh` scripts are workspace-root aware.\n- Bundled shell helpers require bash; POSIX `sh`-only hosts should call the Python CLI directly.\n\nFile v6.2.5:references/promotion-and-extraction.md\n\n# Promotion and extraction\n\n## Memory lifecycle maintenance\n\nThe `maintain` subcommand enforces the human-like memory lifecycle integrated from `ivangdavila/self-improving`.\n\n### How `maintain` works\n\n1. **Scan** SQLite chunks in `learning/memory_tree/chunks.db` and read metadata (`First-Seen`, `Last-Seen`, `Recurrence-Count`, `Status`, `Area`, lifecycle status).\n2. **Identify candidates**:\n - `admitted` entries unused for 30+ days → recommend `buffered`\n - `buffered` entries unused for 90+ days → recommend `sealed`\n - Entries with `Recurrence-Count >= 3` or repeated searches → flag for project-memory promotion\n3. **Report** in human-readable text or JSON (`--format json`).\n4. **Queue promotions** in `learning/promotion-queue.json` so automation has a bounded, explicit handoff instead of an invisible growing backlog.\n5. **Apply safe moves** only when `--apply` is passed. `--dry-run` is the default. Use `--auto-promote` with `--apply` only when the deployment explicitly wants high-recurrence lessons written into workspace memory files.\n\n### Safety rules\n\n- **Never delete** without explicit user action; update lifecycle status or export/promote instead.\n- **Never guess** when metadata is insufficient; report recommendations.\n- **Preserve confirmed preferences** during compaction; merge or summarize, do not erase.\n- **Keep operations deterministic** so behavior is testable and reproducible.\n\n### Namespace specificity & conflict resolution\n\nWhen patterns contradict, apply these rules in order:\n\n1. **More specific wins**: `project` > `domain` > `global`\n - A project-specific override takes precedence over a domain rule.\n - A domain rule takes precedence over a global preference.\n2. **More recent wins** at the same specificity level\n - If two project rules conflict, the one with the later `Last-Seen` (or ID date) prevails.\n3. **Ambiguous conflicts require asking the user**\n - If specificity is unclear or dates are identical, do not guess. Log a recommendation and ask.\n\n### Compaction rules\n\nWhen a file exceeds its tier limit:\n\n1. **Merge** similar corrections or learnings into a single, summarized rule.\n2. **Archive** unused patterns to COLD rather than deleting them.\n3. **Summarize** verbose entries while preserving the verified \"what works\" fact.\n4. **Never erase** confirmed preferences or hard-won corrections.\n\n## Promotion rule of thumb\n\nPromote a learning when it is:\n- broadly applicable across multiple files or tasks\n- likely to save future contributors time\n- a stable convention rather than a one-off event\n- better expressed as a short prevention rule than a full incident report\n\n## Promotion targets\n\n| Target | Best for |\n|---|---|\n| `CLAUDE.md` | Project facts, conventions, durable gotchas |\n| `AGENTS.md` | Workflow rules, automation sequences, verification steps |\n| `.github/copilot-instructions.md` | Shared Copilot context |\n| `SOUL.md` | Behavioural rules in OpenClaw workspaces |\n| `TOOLS.md` | Tool-specific gotchas in OpenClaw workspaces |\n\n## Quantified promotion thresholds (legacy)\n\n| Condition | Threshold | Action |\n|---|---|---|\n| HOT -> WARM | 30 days unused | Mark `buffered` |\n| WARM -> COLD | 90 days unused | Mark `sealed` |\n| Frequent reuse | 3 uses within 7 days | Promote as a short prevention rule |\n| To AGENTS/SOUL/TOOLS | `Recurrence-Count >= 3` + spans 2+ tasks + within 30 days | Promote as short prevention rule |\n| To skill | Proven + broadly applicable | Extract as skill |\n\n## Extraction criteria\n\nExtract a reusable skill when most of these are true:\n- the solution is resolved and tested\n- the pattern is not tied to a single file or repo\n- the fix is non-obvious enough to deserve specialised guidance\n- the pattern has recurred or is likely to recur\n- the resulting skill can stand on its own without original chat context\n\n## Memory hygiene (GenericAgent-inspired)\n\nThe following principles are adapted from the GenericAgent memory-management model (MIT licensed). They help keep durable memory clean, accurate, and pointer-like.\n\n### 1. Action-verified memory only\nOnly log a lesson as fact when it is based on an executed and verified observation (e.g. a command that ran, a file that was read, a test that passed). Do not store unverified assumptions, speculative fixes, or \"I think\" statements as durable memory.\n\n> **Rule of thumb**: *No execution, no memory.* If you have not verified it, do not log it as fact.\n\n### 2. No volatile state in durable memory\nAvoid storing ephemeral or session-specific values that change frequently or become stale immediately. Examples to omit:\n- Timestamps, session IDs, process PIDs\n- Absolute temporary paths (`/tmp/...` on a specific machine)\n- Connection handles, one-time tokens, or runtime device info\n- \"Current\" versions or counts that will be wrong on the next run\n\nVolatile context belongs in working memory or session notes, not in `learning/`.\n\n### 3. Index entries are pointers, not duplicates\nThe `index.md` Pattern-Key list and any cross-references should act as minimal pointers. They should tell a future reader *that* a pattern exists and *where* to find it, without duplicating the full details. If the index grows into a copy of the entries, it is too verbose.\n\n### 4. Preserve verified facts during cleanup\nWhen promoting, archiving, or refactoring entries, verified facts and fixes must survive intact. It is fine to compress wording or move an entry to a different tier, but do not drop the accurate \"what was wrong\" and \"what works\" information.\n\n## Before extracting\n\nCheck:\n- Does the new skill solve a real category of task?\n- Can its description say exactly when it should trigger?\n- Can you move detailed docs to `references/`?\n- Can repeated logic be bundled into `scripts/`?\n- Can you add at least a small eval set?\n\nFile v6.2.5:scripts/setup-cron-agent.md\n\n# Cron setup — agent instructions\n\nUse this guide to install the self-improving compound maintenance pipeline in OpenClaw.\n\n## What gets installed\n\n`scripts/setup-cron.json` defines four recommended jobs:\n\n| Job | Default schedule | Purpose |\n|---|---:|---|\n| Self-Improving Light Check | every 2h, 08:00–22:00 | Scan recent main-session history for missed corrections, failures, and reusable lessons. |\n| Learning Audit Heavy | 09:00 and 22:00 | Audit system/cron failures, run `learning-audit.py --log`, and maintain HOT/WARM/COLD lifecycle. |\n| Daily Memory Digest | 23:50 | Write `memory/YYYY-MM-DD.md` factual continuity notes, then extract reusable lessons. |\n| Daily Workspace Steward | 00:20 | Export SQLite learning memory and lightly inspect `learning/`, `skills/`, and the 7 root Markdown control-plane files. |\n\nThe last two jobs are intentionally separated: the digest writes the daily factual record; the steward checks the surrounding operating state after the digest has landed.\n\n## Prerequisites\n\n- This skill is installed and the agent can read `scripts/setup-cron.json`.\n- The agent has access to the OpenClaw `cron` tool.\n- The user explicitly confirms creation or update of persistent cron jobs.\n- Bash is available for the bundled `.sh` helpers. POSIX `sh`-only hosts should run the Python CLI commands directly instead of these helpers.\n\n## Steps for the agent\n\n1. **Read `scripts/setup-cron.json`.**\n If installed via ClawHub, the path is usually:\n `~/.openclaw/workspace/skills/self-improving-compound/scripts/setup-cron.json`\n\n2. **Resolve runtime paths without hard-coding local machine paths:**\n - `OPENCLAW_WORKSPACE` should point to the workspace root.\n - `SELF_IMPROVING_LEARNING_ROOT` may point to a shared learning store used by multiple workspaces.\n - `SELF_IMPROVING_SKILL_DIR` may point to the installed skill directory.\n - `SELF_IMPROVING_LEARNINGS_CLI` may point to an explicit `learnings.py`.\n - `SELF_IMPROVING_MEMORY_PIPELINE` may point to `scripts/memory-pipeline.py` for Candidate → Learning → Promotion queues and dashboard.\n - `SELF_IMPROVING_MAIN_SESSION_KEY` may disambiguate the main conversation session for incremental transcript collection.\n - `SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR` may point to an optional recent-conversation collector command for Light Check.\n - `SELF_IMPROVING_DAILY_COLLECTOR` may point to an optional daily-context collector command.\n\n3. **Configure delivery.**\n The JSON ships with `delivery.bestEffort: true`. Ask or infer the delivery channel and recipient, then set fields such as `delivery.channel` and `delivery.to`.\n\n4. **Check idempotency first.**\n Run `cron list`. If a job with the same name already exists, update it instead of creating a duplicate.\n\n5. **Create/update jobs.**\n Use `cron add` for new jobs or `cron update` for existing jobs. Keep schedules as wall-clock time in `schedule.tz`.\n\n6. **Verify.**\n Run `cron list` again. Each enabled job should have `nextRunAtMs` set and delivery configured as expected.\n\n## Timezone\n\nDefaults use `Asia/Shanghai`. If the user operates in another timezone, adjust `schedule.tz` before creating the jobs. Do not manually convert cron expressions to UTC; cron fields are local wall-clock time in the selected timezone.\n\n## Safety\n\n- These jobs may write local markdown and SQLite state. Ask before installing.\n- The Workspace Steward must only make small, safe, local markdown updates. It must not rewrite persona files, weaken safety/privacy rules, delete files, or change cron jobs.\n- Light Check should prefer the observable memory pipeline when available: collect incrementally, add candidates, log/mark learnings, add promotion items, refresh dashboard, then commit cursor. If a configured collector fails, report `BLOCKED: collector_unavailable` instead of pretending the context was scanned.\n- Daily Memory Digest should not copy raw transcripts into `learning/`; it should extract compact reusable lessons only.\n\nFile v6.2.5:scripts/setup-cron.json\n\n{\n \"description\": \"Ready-to-use OpenClaw cron job definitions for the self-improving compound maintenance pipeline: light checks, heavy audits, optional daily factual memory, and workspace stewardship.\",\n \"jobs\": [\n {\n \"name\": \"Self-Improving Light Check\",\n \"enabled\": true,\n \"schedule\": {\n \"kind\": \"cron\",\n \"expr\": \"0 8-22/2 * * *\",\n \"tz\": \"Asia/Shanghai\"\n },\n \"sessionTarget\": \"isolated\",\n \"payload\": {\n \"kind\": \"agentTurn\",\n \"message\": \"Run the observable Self-Improving Light Check using Candidate → Learning → Promotion when available. Do NOT run the full learning-audit or system-failure scan.\\n\\nEnvironment contract:\\n- WORKSPACE_ROOT=${OPENCLAW_WORKSPACE:-$PWD}\\n- SKILL_DIR=${SELF_IMPROVING_SKILL_DIR:-$WORKSPACE_ROOT/skills/self-improving-compound}\\n- LEARNINGS_CLI=${SELF_IMPROVING_LEARNINGS_CLI:-$SKILL_DIR/scripts/learnings.py}\\n- PIPE=${SELF_IMPROVING_MEMORY_PIPELINE:-$SKILL_DIR/scripts/memory-pipeline.py}\\n- Optional: SELF_IMPROVING_MAIN_SESSION_KEY may disambiguate the main conversation session.\\n- Optional deterministic collector: SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR may point to a command that exports recent visible user/assistant conversation to Markdown or JSON.\\n- If LEARNINGS_CLI is missing, report the missing path instead of continuing silently.\\n\\nPreferred steps when PIPE exists:\\n1. Run: python3 \\\"$PIPE\\\" --base \\\"$WORKSPACE_ROOT/learning/pipeline\\\" collect-incremental\\n - If it exits non-zero because no transcript/session is available, and SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR is configured, run that collector and read its output context instead.\\n - If neither pipeline collection nor configured collector can provide readable context, reply: BLOCKED: collector_unavailable.\\n\\n2. Read the exported context:\\n - Pipeline default: $WORKSPACE_ROOT/learning/pipeline/context/incremental-context.md\\n - Collector output: the Markdown/JSON path printed by the collector or described in its compact JSON summary.\\n If pipeline new_messages is 0, run dashboard and reply HEARTBEAT_OK.\\n\\n3. Candidate-first scan:\\n Scan only recent visible user/assistant text for durable capture-gate signals: user corrections, non-obvious errors, workarounds, tool/API quirks, format mismatches, missing capabilities, or stable workflow rules.\\n Ignore routine status reports, normal successful tool use, and previous cron summaries unless they reveal a new reusable lesson.\\n\\n4. For each hit when PIPE exists:\\n - Add candidate: python3 \\\"$PIPE\\\" --base \\\"$WORKSPACE_ROOT/learning/pipeline\\\" add-candidate ...\\n - Dedupe using both short keywords and stable Pattern-Keys:\\n python3 \\\"$LEARNINGS_CLI\\\" --root \\\"$WORKSPACE_ROOT\\\" search \\\"\\\" --limit 5\\n - If no suitable entry exists, log exactly one concise lesson with log-correction / log-error / log-learning / log-feature.\\n - Mark the candidate learned, duplicate, or resolved.\\n - If it should become a durable rule, add a promotion item.\\n\\n5. Dashboard and cursor:\\n - Run: python3 \\\"$PIPE\\\" --base \\\"$WORKSPACE_ROOT/learning/pipeline\\\" dashboard\\n - Commit cursor only after processing succeeded:\\n python3 \\\"$PIPE\\\" --base \\\"$WORKSPACE_ROOT/learning/pipeline\\\" commit-cursor\\n\\nFallback when PIPE is missing and no collector is configured:\\n- Use sessions_list / sessions_history only after verifying they can access the target session from isolated cron.\\n- If isolated cron cannot access the target session, reply: BLOCKED: session_history_unavailable.\\n\\nReply concisely:\\n- If readable context existed and nothing was found: HEARTBEAT_OK\\n- If something was logged: LOGGED: — ; CANDIDATES: ; PROMOTIONS: \\n- If only duplicate candidates exist: DUPLICATE_ONLY: \\n- If blocked: BLOCKED: \\nDo not paste full output or commands. Do not fabricate context.\",\n \"timeoutSeconds\": 180,\n \"toolsAllow\": [\n \"read\",\n \"exec\",\n \"sessions_list\",\n \"sessions_history\"\n ]\n },\n \"delivery\": {\n \"mode\": \"announce\",\n \"bestEffort\": true\n }\n },\n {\n \"name\": \"Learning Audit Heavy\",\n \"enabled\": true,\n \"schedule\": {\n \"kind\": \"cron\",\n \"expr\": \"0 9,22 * * *\",\n \"tz\": \"Asia/Shanghai\"\n },\n \"sessionTarget\": \"isolated\",\n \"payload\": {\n \"kind\": \"agentTurn\",\n \"message\": \"Run the heavy self-improvement audit.\\n\\nEnvironment contract:\\n- WORKSPACE_ROOT=${OPENCLAW_WORKSPACE:-$PWD}\\n- SKILL_DIR=${SELF_IMPROVING_SKILL_DIR:-$WORKSPACE_ROOT/skills/self-improving-compound}\\n- LEARNINGS_CLI=${SELF_IMPROVING_LEARNINGS_CLI:-$SKILL_DIR/scripts/learnings.py}\\n- If any script is missing or exits non-zero, report that failure instead of continuing silently.\\n\\nSteps:\\n1. System failure audit:\\n \\\"$SKILL_DIR/scripts/log-system-failures.sh\\\"\\n\\n2. Check cron failures:\\n Use cron list (enabled only). For any job where lastRunStatus/lastStatus is not ok, run:\\n python3 \\\"$LEARNINGS_CLI\\\" --root \\\"$WORKSPACE_ROOT\\\" search \\\"\\\" --limit 3\\n If no match, log-error with pattern cron:.\\n\\n3. Learning audit:\\n python3 \\\"$SKILL_DIR/scripts/learning-audit.py\\\" --root \\\"$WORKSPACE_ROOT\\\" --days 2 --log\\n\\n4. Process async memory jobs:\\n python3 \\\"$LEARNINGS_CLI\\\" --root \\\"$WORKSPACE_ROOT\\\" process-jobs --max-jobs 100\\n\\n5. Lifecycle maintain fallback:\\n python3 \\\"$LEARNINGS_CLI\\\" --root \\\"$WORKSPACE_ROOT\\\" maintain --apply\\n This refreshes promotion-queue.json. In fully automated deployments, use maintain --apply --auto-promote only after workspace file writes are approved.\\n\\n6. Reply concisely: system status, cron failures found, audit candidates, queued jobs processed, lifecycle actions taken. Do not expose secrets or paste full logs.\",\n \"timeoutSeconds\": 240,\n \"toolsAllow\": [\n \"exec\",\n \"read\",\n \"cron\"\n ]\n },\n \"delivery\": {\n \"mode\": \"announce\",\n \"bestEffort\": true\n }\n },\n {\n \"name\": \"Daily Memory Digest\",\n \"enabled\": true,\n \"schedule\": {\n \"kind\": \"cron\",\n \"expr\": \"50 23 * * *\",\n \"tz\": \"Asia/Shanghai\"\n },\n \"sessionTarget\": \"isolated\",\n \"payload\": {\n \"kind\": \"agentTurn\",\n \"message\": \"Run the Daily Memory Digest for today.\\n\\nEnvironment contract:\\n- WORKSPACE_ROOT=${OPENCLAW_WORKSPACE:-$PWD}\\n- SKILL_DIR=${SELF_IMPROVING_SKILL_DIR:-$WORKSPACE_ROOT/skills/self-improving-compound}\\n- Optional collector: SELF_IMPROVING_DAILY_COLLECTOR may point to a local context collector command.\\n\\nSteps:\\n1. Run: bash \\\"$SKILL_DIR/scripts/daily-memory.sh\\\" --root \\\"$WORKSPACE_ROOT\\\"\\n2. Gather/read the context indicated by the helper output, or use available runtime tools if no collector is configured.\\n3. Write a detailed factual note to memory/YYYY-MM-DD.md using the helper's required sections.\\n4. Run the self-improvement capture gate on the final note: log only reusable corrections, tool/API gotchas, workflow conventions, or missing capabilities to learning/.\\n5. Reply with date, output path, approximate length, learning entries logged, and blockers. Do not expose secrets or raw transcripts.\",\n \"timeoutSeconds\": 300,\n \"toolsAllow\": [\n \"exec\",\n \"read\",\n \"write\",\n \"memory_search\",\n \"memory_get\"\n ]\n },\n \"delivery\": {\n \"mode\": \"announce\",\n \"bestEffort\": true\n }\n },\n {\n \"name\": \"Daily Workspace Steward\",\n \"enabled\": true,\n \"schedule\": {\n \"kind\": \"cron\",\n \"expr\": \"20 0 * * *\",\n \"tz\": \"Asia/Shanghai\"\n },\n \"sessionTarget\": \"isolated\",\n \"payload\": {\n \"kind\": \"agentTurn\",\n \"message\": \"Run the Daily Workspace Steward maintenance.\\n\\nEnvironment contract:\\n- WORKSPACE_ROOT=${OPENCLAW_WORKSPACE:-$PWD}\\n- SKILL_DIR=${SELF_IMPROVING_SKILL_DIR:-$WORKSPACE_ROOT/skills/self-improving-compound}\\n\\nPurpose: keep durable agent state tidy after the daily memory digest. Make only small, safe, local markdown updates when clearly justified.\\n\\nSteps:\\n1. Export SQLite learning memory: \\\"$SKILL_DIR/scripts/learning-export.sh\\\"\\n2. Inspect learning/: index.md, memory.md, corrections.md, memory-export.md, status.json for stale references, contradictions, missing export freshness, or broken structure.\\n3. Inspect skills/*/SKILL.md for obvious stale workflow rules. Only make minimal factual/procedural edits when the owning skill is clear.\\n4. Inspect the 7 root Markdown control-plane files when present: AGENTS.md, HEARTBEAT.md, IDENTITY.md, MEMORY.md, SOUL.md, TOOLS.md, USER.md.\\n\\nAllowed: fix verified stale local facts, remove clear duplicates/contradictions, add short pointers for stable workflow rules.\\nForbidden: rewrite persona/tone, weaken safety/privacy rules, expose secrets, delete files, or change cron jobs from inside this job.\\n\\nAfter edits, run a small inspection gate (git diff if available, otherwise changed-file summary). Reply with export path/status, skills checked count, root markdown checked count, files changed, and blockers.\",\n \"timeoutSeconds\": 300,\n \"toolsAllow\": [\n \"exec\",\n \"read\",\n \"write\",\n \"edit\",\n \"memory_search\",\n \"memory_get\"\n ]\n },\n \"delivery\": {\n \"mode\": \"announce\",\n \"bestEffort\": true\n }\n }\n ]\n}\n\nArchive v6.2.4: 38 files, 102711 bytes\n\nFiles: _meta.json (142b), CHANGELOG.md (10204b), corrections.md (413b), evals/output-check.md (570b), evals/output-evals.json (2135b), evals/trigger-check.md (492b), evals/trigger-validation.json (967b), heartbeat-state.md (155b), hooks/activator.sh (1211b), hooks/error-detector.sh (1312b), hooks/README.md (459b), index.md (918b), memory.md (1473b), README_zh.md (7866b), README.md (11735b), references/daily-memory-digest.md (2418b), references/entry-formats.md (2096b), references/heartbeat-guidance.md (2761b), references/hermes-integration.md (4871b), references/platform-setup.md (1867b), references/promotion-and-extraction.md (5796b), scripts/daily-memory.sh (2780b), scripts/extract-skill.sh (2754b), scripts/learning-audit.py (4616b), scripts/learning-export.sh (630b), scripts/learnings.py (79485b), scripts/log-system-failures.sh (1553b), scripts/memory/__init__.py (1283b), scripts/memory/chunker.py (8619b), scripts/memory/ingest.py (3320b), scripts/memory/store.py (42938b), scripts/memory/test_memory.py (13959b), scripts/memory/types.py (4495b), scripts/setup-cron-agent.md (3603b), scripts/setup-cron.json (8127b), scripts/test_evals.py (18592b), scripts/test_learnings.py (31407b), SKILL.md (33586b)\n\nFile v6.2.4:SKILL.md\n\n---\nname: self-improving-compound\ndescription: \"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.\"\ncompatibility: \"Portable Agent Skills format. Core workflow is agent-agnostic. Bundled helpers require Python 3.8+; hook helpers require bash. No network access is required.\"\nmetadata:\n version: \"6.2.4\"\n original_slug: \"self-improving-compound\"\n category: \"memory-system\"\n author: \"Hybrid adaptation from actual-self-improvement, self-improving-compound, OpenHuman memory-tree, and Hermes Agent architecture | Contact: rockwaychen@gmail.com | GitHub: LingmaFuture\"\n---\n\n# Self-Improving Compound\n\nAn agent memory and learning system that replaces naive file-based memory with a structured pipeline: real-time capture, automated cron-based audit, and continuous promotion of lessons into skills and agent instructions.\n\nThe system runs as four layers:\n- **Layer 1 — Real-time capture**: AGENTS.md final-before-reply gate logs corrections, errors, and workarounds to SQLite as they happen.\n- **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).\n- **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.\n- **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.\n\n**Author:** Rockway Chen · [rockwaychen@gmail.com](mailto:rockwaychen@gmail.com) · [GitHub: LingmaFuture](https://github.com/LingmaFuture)\n\n## Installation and activation — `clawhub install` is only step 1\n\nA raw ClawHub install only copies the skill files. It does **not** automatically wire the agent into a self-improving operating loop.\n\nUse this maturity ladder:\n\n| Level | What is configured | Result |\n|---|---|---|\n| 1/5 | `clawhub install self-improving-compound` | Files are present; almost no behavior changes yet. |\n| 2/5 | `learning/` initialized and CLI verified | Manual logging/search works. |\n| 3/5 | Capture gate added to agent instructions | The agent remembers to log lessons before final replies. |\n| 4/5 | Cron jobs installed and delivery configured | Missed lessons, failures, daily memory, and steward checks run automatically. |\n| 5/5 | Hooks/env/collector verified | Activation reminders, error capture, path resolution, and daily factual memory are reliable. |\n\n### Phase 0 — Identify roots\n\nYou must distinguish two roots:\n\n```bash\n# Workspace root: where memory/, learning/, AGENTS.md, etc. live\nexport OPENCLAW_WORKSPACE=\"/path/to/workspace\"\n\n# Optional shared lesson store for multiple workspace roots\n# export SELF_IMPROVING_LEARNING_ROOT=\"$HOME/.openclaw/shared-learning\"\n\n# Skill root: where this skill was installed\nexport SELF_IMPROVING_SKILL_DIR=\"$OPENCLAW_WORKSPACE/skills/self-improving-compound\"\nexport SELF_IMPROVING_LEARNINGS_CLI=\"$SELF_IMPROVING_SKILL_DIR/scripts/learnings.py\"\n```\n\nFor OpenClaw's default workspace this is usually:\n\n```bash\nexport OPENCLAW_WORKSPACE=\"$HOME/.openclaw/workspace\"\nexport SELF_IMPROVING_SKILL_DIR=\"$OPENCLAW_WORKSPACE/skills/self-improving-compound\"\nexport SELF_IMPROVING_LEARNINGS_CLI=\"$SELF_IMPROVING_SKILL_DIR/scripts/learnings.py\"\n```\n\nDo 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.\n\n### Phase 1 — Install files\n\n```bash\nclawhub install self-improving-compound\ncd \"$SELF_IMPROVING_SKILL_DIR\"\nchmod +x scripts/*.py scripts/*.sh hooks/*.sh 2>/dev/null || true\n```\n\nIf the skill is copied manually, set `SELF_IMPROVING_SKILL_DIR` to the copied directory.\n\nThe bundled shell helpers require bash. On POSIX `sh`-only hosts, use the Python CLI directly and skip the `.sh` helpers.\n\n### Phase 2 — Initialize and verify the learning store\n\n```bash\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" init\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" status\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" search \"install smoke test\" --limit 3\n```\n\nExpected result:\n\n- `learning/memory_tree/chunks.db` exists.\n- `status` exits successfully.\n- `search` works even when there are no results.\n\n### Phase 3 — Add the capture gate to agent instructions\n\nAdd a compact rule to the agent's durable instruction file, usually `AGENTS.md`:\n\n```markdown\n## Self-improvement capture gate\n\nBefore 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.\n\nIf yes:\n1. Search existing learnings first:\n `python3 $SELF_IMPROVING_LEARNINGS_CLI --root $OPENCLAW_WORKSPACE search \"\" --limit 5`\n2. If no suitable entry exists, log the durable lesson with `log-correction`, `log-error`, `log-learning`, or `log-feature`.\n3. Keep entries compact, prevention-oriented, and secret-free.\n```\n\nWithout this phase the skill remains mostly passive; the agent will not consistently capture lessons in real time.\n\n### Phase 4 — Install the cron pipeline\n\nCron installation is not automatic. The templates live in `scripts/setup-cron.json`; agent-facing instructions live in `scripts/setup-cron-agent.md`.\n\nRecommended OpenClaw flow:\n\n1. Ask the agent: \"Install the self-improving compound cron jobs using `scripts/setup-cron.json`. Check existing jobs first and update instead of duplicating.\"\n2. Configure delivery for your channel, e.g. Telegram or Feishu.\n3. Verify with `cron list`.\n\nThe pipeline normally includes:\n\n| Job | Purpose |\n|---|---|\n| Self-Improving Light Check | Frequent lightweight scan for missed corrections, errors, and blockers. |\n| Learning Audit Heavy | System/cron failure audit, `learning-audit.py --log`, lifecycle maintenance. |\n| Daily Memory Digest | Writes `memory/YYYY-MM-DD.md` factual continuity notes and extracts reusable lessons. |\n| Daily Workspace Steward | Exports `learning/`, checks `skills/`, and inspects the 7 root Markdown control-plane files. |\n\nImportant cron requirements:\n\n- Set `schedule.tz` to the user's actual timezone.\n- Set or infer `delivery.channel` and `delivery.to`; otherwise reports may not reach the user.\n- Use `cron update` for existing jobs; do not create duplicates.\n- 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.\n\n### Phase 5 — Configure optional hooks\n\nHooks are optional but improve activation. They are runtime-specific.\n\nDry-run the bundled hooks first:\n\n```bash\n\"$SELF_IMPROVING_SKILL_DIR/hooks/activator.sh\" \"install smoke test\" || true\n\"$SELF_IMPROVING_SKILL_DIR/hooks/error-detector.sh\" \"install\" \"smoke test\" || true\n```\n\nIf your client supports command hooks, wire:\n\n- `hooks/activator.sh` as a pre-prompt / prompt-start reminder.\n- `hooks/error-detector.sh` as a post-error / failed-command reminder.\n\nIf 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.\n\n### Phase 6 — Configure optional context collectors\n\nFor 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.\n\nLight Check can use a local recent-conversation collector:\n\n```bash\nexport SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR=\"python3 /path/to/recent-context-collector.py --limit 60\"\n```\n\nCollector contract:\n\n- Exit `0` only when context was exported successfully.\n- Print either the output context path or a compact JSON summary containing the path/status.\n- Write a readable Markdown/JSON context file with recent user/assistant visible text.\n- Exit non-zero if the transcript/session cannot be found; the cron job should report `BLOCKED: collector_unavailable` instead of claiming success.\n\n`Daily Memory Digest` can also use a local collector if your runtime has one:\n\n```bash\nexport SELF_IMPROVING_DAILY_COLLECTOR=\"python3 /path/to/collector.py\"\nbash \"$SELF_IMPROVING_SKILL_DIR/scripts/daily-memory.sh\" --root \"$OPENCLAW_WORKSPACE\"\n```\n\nIf no collector is configured, the helper prints the target note contract and the agent must gather context with available runtime tools.\n\n### Phase 7 — End-to-end smoke test\n\nRun this checklist after installation:\n\n```bash\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" log-learning \\\n --summary \"Self-improving install smoke test\" \\\n --details \"Temporary entry to verify logging path; mark resolved or delete if desired.\" \\\n --pattern \"install:smoke-test\" \\\n --area \"domain:setup\"\n\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" search \"install smoke test\" --limit 5\nbash \"$SELF_IMPROVING_SKILL_DIR/scripts/learning-export.sh\"\nbash \"$SELF_IMPROVING_SKILL_DIR/scripts/daily-memory.sh\" --root \"$OPENCLAW_WORKSPACE\" --date \"$(TZ=Asia/Shanghai date +%F)\"\n```\n\nThen verify:\n\n- `learning/memory-export.md` exists.\n- `learning/status.json` exists.\n- `memory/YYYY-MM-DD.md` target is clear if daily memory is enabled.\n- `cron list` shows the expected enabled jobs with `nextRunAtMs`.\n- Delivery target is configured for cron job summaries.\n\n### Common install failures\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| `clawhub install` succeeded but nothing changes | Capture gate and cron not configured | Complete phases 3-4. |\n| 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. |\n| Learnings appear under the skill directory | Wrong `--root` | Set `OPENCLAW_WORKSPACE`; always pass `--root`. |\n| Cron summaries disappear | `delivery` missing channel/recipient | Set `delivery.channel` + `delivery.to`. |\n| Daily memory is generic or empty | No collector/context source | Configure `SELF_IMPROVING_DAILY_COLLECTOR` or improve the cron prompt. |\n| Duplicate cron jobs | Setup re-run without idempotency check | `cron list` first; update by job name. |\n\n## 3+7 co-evolution model\n\nThe **3** state directories are:\n\n- `memory/` — factual daily continuity.\n- `learning/` — SQLite-backed execution lessons.\n- `skills/` — hardened reusable procedures.\n\nThe **7** root Markdown control-plane files are:\n\n- `AGENTS.md` — workspace contract, routing, execution policy, safety boundaries.\n- `HEARTBEAT.md` — lightweight check-in surface; often intentionally empty when cron owns timing.\n- `IDENTITY.md` — compatibility pointer or short identity bridge.\n- `MEMORY.md` — pinned long-term hot context.\n- `SOUL.md` — agent identity/persona.\n- `TOOLS.md` — concrete local environment/tool facts.\n- `USER.md` — durable user profile and collaboration preferences.\n\nThe 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.\n\n## Core idea\n\nUse this system for **durable improvement**, not for every bump in the road.\n\n### Mandatory capture gate\n\nBefore a final reply, run this quick check:\n\n- Did the task include a non-obvious failure, API/tool quirk, or format mismatch?\n- Did a workaround or environment-specific convention make the task succeed?\n- Did the user correct a fact, preference, workflow, or expectation?\n- Would repeating this lesson save time or prevent damage later?\n\nIf yes, **search existing learnings first, then log the lesson before replying**. Do not rely on a “mental note.”\n\nA good entry usually has at least one of these properties:\n- It corrected a wrong assumption.\n- It revealed a project-specific convention.\n- It required real debugging or investigation.\n- It is likely to recur.\n- It should change future workflow, memory, or tooling.\n\nDo **not** log routine noise such as obvious typos, expected validation failures, or errors that were solved immediately with no transferable lesson.\n\n### Capture gate output routing\n\nNot all lessons go to the same place. Route based on type:\n\n| Lesson type | Destination | Example |\n|---|---|---|\n| User facts, preferences, system state | `MEMORY.md` / `memory/YYYY-MM-DD.md` | \"Rockway prefers newspaper theme\" |\n| Execution mistakes, tool gotchas, workarounds | `learning/` SQLite | \"Python shadowing broke promote\" |\n| Stable rules, workflows, anti-patterns discovered | owning `skills//SKILL.md` | \"cron isolation means no session context\" |\n| Behavioral constraints | `AGENTS.md` | \"Don't commit workspace root\" |\n| Environment-specific tool knowledge | `TOOLS.md` | \"Tailscale node name\" |\n\nThe 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.\n\n## Hybrid architecture\n\nThis skill merges three design lineages into one portable package:\n\n| Lineage | Role | What We Kept |\n|---|---|---|\n| **actual-self-improvement** | Execution core | Python CLI (`scripts/learnings.py`), structured logging, JSON evals, search-before-log dedupe |\n| **OpenHuman memory-tree** | Storage core | SQLite chunks, FTS search, entity index, scores, hotness, async jobs, deterministic tree buffers, lifecycle status, idempotent ingest |\n| **self-improving-compound** | Memory architecture | HOT/WARM/COLD lifecycle, workspace-scoped `learning/`, lightweight bootstrap markdown |\n| **self-improving-agent-local** | Promotion & hooks | Quantified promotion thresholds, OpenClaw hook guidance, pattern-key recurrence rules |\n\n### Directory layout under `learning/`\n\n```\nlearning/\n├── memory_tree/chunks.db # SQLite source of truth for durable learnings\n├── index.md # SQLite-generated snapshot (entries, lifecycle, pattern keys)\n├── promotion-queue.json # bounded maintain queue for proven promotion candidates\n├── projects/ # WARM tier (project-specific)\n├── domains/ # WARM tier (domain-specific)\n└── archive/ # COLD tier (inactive)\n```\n\n## Important path model\n\nThere are **two different roots** in this skill:\n\n1. **Skill root** — where bundled resources live:\n - `scripts/...`\n - `references/...`\n - `hooks/...`\n\n2. **Workspace root** — where the project or active workspace lives:\n - `learning/memory_tree/chunks.db`\n - `learning/index.md` (SQLite-generated snapshot)\n - `memory/YYYY-MM-DD.md` factual daily notes, when enabled\n - `learning/projects/`\n - `learning/domains/`\n - `learning/archive/`\n - root agent files such as `AGENTS.md`, `MEMORY.md`, `TOOLS.md`, `USER.md`, `SOUL.md`, `HEARTBEAT.md`, `IDENTITY.md`\n\nWhen `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.\n\nNever write learnings into the installed skill directory. Always target the **workspace root** for project memory and the optional **learning root** for shared lesson storage.\n\n\n## Activation hardening mechanisms\n\nWhen 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:\n\n- **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.\n- **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.\n- **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.\n\n### Architecture decisions (why cron, not heartbeat)\n\n- **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.\n- **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.\n- **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.\n\n### Recommended cron schedule\n\n```text\nCron Schedule (Asia/Shanghai)\n────────────────────────────────────── ──────────────────────\nSelf-Improving Light Check 0 8-22/2 * * * (every 2h during waking hours)\nLearning Audit (Heavy) 0 9,22 * * * (2x/day)\nDaily Memory Digest 50 23 * * * (nightly factual memory)\nDaily Workspace Steward 20 0 * * * (post-digest maintenance)\n```\n\n#### Light Check (every 2h, 08:00-22:00)\n\nA 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.\n\n#### Heavy Audit (09:00, 22:00)\n\nFull 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.\n\n#### Daily Memory Digest (23:50)\n\nRun `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.\n\n#### Daily Workspace Steward (00:20)\n\nRun `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.\n\n### Cron installation (one-time setup)\n\n**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.\n\nThe production-grade cron job definitions are in `scripts/setup-cron.json`. The agent-facing setup guide is `scripts/setup-cron-agent.md`.\n\nQuick setup (run from your OpenClaw main session):\n\n1. **Confirm**: \"I want to install the self-improving compound cron jobs. Use `scripts/setup-cron.json` as reference.\"\n\n2. Your agent will:\n - Read the JSON definitions\n - Resolve placeholder paths (skill root, workspace root)\n - Ask or infer your delivery channel (Telegram / Feishu / etc.)\n - Call `cron add` / `cron update` for each job, avoiding duplicates\n\n3. **Verify**: `cron list` should show enabled jobs with `nextRunAtMs` set.\n\nIf you already have these jobs running, this step is a no-op.\n\n### AGENTS.md capture gate\n\nAdd the following rule to agent instructions (e.g. AGENTS.md):\n\n> 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 search \"\" --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.\n\n### System failure routing\n\nRoute watchdog, doctor, healthcheck, and cron failure signals into `log-error` with stable pattern keys and dedupe:\n\n- Pattern keys: `cron:`, `doctor:`, `watchdog:`, `system:openclaw-audit-failure`\n- Use `scripts/log-system-failures.sh` as an OpenClaw CLI audit wrapper where available.\n- Always search existing entries first to prevent repeated failures from flooding SQLite.\n\n### Guardrails\n\n- Keep entries compact and prevention-oriented.\n- Never log secrets; the CLI redacts tokens, passwords, and API keys automatically.\n- Do not paste full audit exports into chat unless explicitly asked.\n- Treat audit candidates as review prompts rather than automatic truth.\n- Cron runs should reply with one-line summaries or `HEARTBEAT_OK`; do not echo full command output.\n\n## Quick decision table\n\n| Situation | What to do |\n|---|---|\n| User corrects you or updates a fact | Log a **correction** |\n| Non-obvious command / API / tool failure | Log an **error** |\n| User asks for a missing capability | Log a **feature request** |\n| You discover a reusable workaround or convention | Log a **learning** |\n| A pattern keeps recurring | Search related entries, link with `See Also`, and consider promotion |\n| A lesson is broadly applicable or repeated | Promote it into project memory |\n| A resolved, general pattern could help other projects | Extract a new skill |\n\n## Standard workflow\n\n### 0) Optional nightly factual memory\n\nIf the workspace uses daily factual notes, run or schedule:\n\n```bash\nbash scripts/daily-memory.sh --root /absolute/path/to/workspace\n```\n\nThen 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.\n\n### 1) Find the workspace root first\n\nBefore reading or writing `learning/`, determine `WORKSPACE_ROOT`.\n\nGood defaults:\n- the repository root for the current codebase\n- the OpenClaw workspace root (`OPENCLAW_WORKSPACE` env var)\n- the directory containing the files being edited\n\nIf unsure, prefer the directory containing `.git`, `AGENTS.md`, `CLAUDE.md`, or the user's active project files.\n\n### 2) Initialise `learning/` if needed\n\nUse the helper instead of creating files manually:\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace init\n```\n\nThis creates:\n- `learning/memory_tree/chunks.db` (SQLite database)\n- `learning/projects/`\n- `learning/domains/`\n- `learning/archive/`\n\nThe `learning/index.md` snapshot is generated on first write (log, promote, etc.).\n\n### 3) Review existing learnings before risky or familiar work\n\nReview first when:\n- you are returning to an area with prior failures\n- the task touches infra, CI, deployment, auth, data migration, or generated code\n- the user explicitly says \"remember this\", \"we hit this before\", or similar\n\nUse the helper:\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace status\npython3 scripts/learnings.py --root /absolute/path/to/workspace search \"pnpm\" --limit 5\npython3 scripts/learnings.py --root /absolute/path/to/workspace search \"pnpm\" --touch\n\n# --root can also be placed after the subcommand\npython3 scripts/learnings.py status --root /absolute/path/to/workspace --format json\n```\n\nPlain `search` is read-only. Use `--touch` only when the result was actually reused and should increment recurrence metadata.\n\n### 4) Search before logging to avoid duplicates\n\nAlways search for related entries before creating a new one.\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace search \"keyword or pattern\" --limit 10\n```\n\nIf a similar entry already exists:\n- prefer linking with `See Also`\n- reuse or add a stable `Pattern-Key` for recurring issues\n- bump priority only when recurrence justifies it\n- prefer updating the existing pattern story over spraying near-duplicate entries\n\n### 5) Log the right kind of entry\n\n#### Correction\nUse for user corrections and updated facts. Stored in SQLite with a human ID such as `COR-YYYYMMDD-001`.\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace log-correction \\\n --summary \"Used wrong format for Telegram\" \\\n --correct \"Use lists, not tables\" \\\n --pattern chat:telegram-format\n```\n\n#### Learning\nUse for corrections, knowledge gaps, best practices, and durable conventions. Stored in SQLite with a human ID such as `LRN-YYYYMMDD-001`.\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace log-learning \\\n --summary \"Project uses pnpm workspaces, not npm\" \\\n --details \"Attempted npm install. Lockfile and workspace config showed pnpm.\" \\\n --pattern pkg:pnpm-workspace\n```\n\n#### Error\nUse for non-obvious failures, exceptions, or tool/API issues worth remembering. Stored in SQLite with a human ID such as `ERR-YYYYMMDD-001`.\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace log-error \\\n --summary \"Docker build failed on Apple Silicon due to platform mismatch\" \\\n --details \"docker build -t myapp . on Apple Silicon\" \\\n --pattern docker:platform\n```\n\n#### Feature request\nUse 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`.\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace log-feature \\\n --summary \"User needs report export to CSV\" \\\n --details \"Needed for sharing weekly reports with non-technical stakeholders\" \\\n --pattern reports:csv-export\n```\n\n#### Backward-compatible log\nThe old `log` subcommand is preserved for compatibility:\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace log \"Used wrong format\" \\\n --type COR --pattern chat:telegram-format --correct \"Use lists\" --force\n```\n\nTo inspect or share entries, export from SQLite:\n\n```bash\npython3 scripts/learnings.py --root /absolute/path/to/workspace export\npython3 scripts/learnings.py --root /absolute/path/to/workspace export --format json\n```\n\n### 6) Promote proven lessons into memory\n\nPromote when the learning is broad, repeated, or something any future contributor should know.\n\nCommon targets:\n- `CLAUDE.md` — durable project facts and conventions\n- `AGENTS.md` — workflow rules and automation guidance\n- `.github/copilot-instructions.md` — shared Copilot context\n- `SOUL.md` — behavioural principles in OpenClaw workspaces\n- `TOOLS.md` — tool-specific gotchas in OpenClaw workspaces\n\nWrite promotions as **short prevention rules**, not long incident write-ups.\n\nExample:\n- Bad promotion: \"On 2026-03-12 npm failed because…\"\n- Good promotion: \"Use `pnpm install` in this repo; it is a pnpm workspace.\"\n\nWhen a learning is promoted, update the original entry's status to `promoted` or `promoted_to_skill` and record the destination.\n\n`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.\n\n### 7) Extract a reusable skill when the pattern is real\n\nExtract a new skill when the solution is:\n- resolved and working\n- broadly useful beyond one file or repo\n- non-obvious enough that future agents would benefit\n- recurring enough to justify its own instructions\n\nUse the helper:\n\n```bash\nbash scripts/extract-skill.sh my-skill-name /absolute/path/to/workspace\n```\n\n## Logging rules that matter most\n\n1. **Search first.** Duplicate entries are worse than missing tags.\n2. **Prefer durable lessons.** Only log what should change future behaviour.\n3. **Be specific.** Name the assumption, failure, or convention clearly.\n4. **Include the fix or prevention rule.** An entry without next action is weak.\n5. **Use stable pattern keys for recurring problems.** This lets recurrence compound.\n6. **Promote aggressively once a rule is proven.** The point is fewer repeat mistakes.\n7. **Do not interrupt the user with bookkeeping.** Log silently unless the user asked to see it or you need missing details.\n8. **Never log secrets.** Tokens, passwords, API keys, and private data must be redacted or omitted.\n\n## Memory lifecycle (integrated from ivangdavila/self-improving)\n\nEntries carry metadata (`First-Seen`, `Last-Seen`, `Recurrence-Count`, `Status`, `Area`) so the system can make deterministic lifecycle decisions without guessing.\n\n| Tier | Location | Size guidance | Behavior |\n|------|----------|---------------|----------|\n| HOT | SQLite lifecycle `admitted` | Active working set | Shown by `status`, `search`, and hooks |\n| WARM | SQLite lifecycle `buffered` | 30+ days unused | Retained for context-specific search |\n| COLD | SQLite lifecycle `sealed` | archived/promoted/resolved | Retained for explicit query/export |\n\n### Automatic promotion/demotion\n\nUse `python3 scripts/learnings.py --root maintain` to review:\n\n| Condition | Threshold | Action |\n|---|---|---|\n| HOT -> WARM | 30 days unused | Set lifecycle to `buffered` |\n| WARM -> COLD | 90 days unused | Set lifecycle to `sealed` |\n| Frequent reuse | `Recurrence-Count >= 3` from explicit reuse (`search --touch` or `edit`) | Flag for project-memory promotion |\n| Compaction/export | Human review needed | Export and manually summarize/promote without deleting the SQLite record |\n\n`maintain` defaults to `--dry-run`. Use `--apply` to execute lifecycle status moves. It never deletes content and does not auto-summarize.\n\n### Conflict resolution\n\nWhen patterns contradict:\n1. **More specific wins**: `project` > `domain` > `global`\n2. **More recent wins** at the same specificity level\n3. **Ambiguous conflicts** → ask the user instead of guessing\n\n## Promotion thresholds (from legacy)\n\n| Condition | Threshold | Action |\n|---|---|---|\n| HOT -> WARM | 30 days unused | Mark `buffered` |\n| WARM -> COLD | 90 days unused | Mark `sealed` |\n| Frequent reuse | 3 recorded uses within 7 days | Promote as a short prevention rule |\n| To AGENTS/SOUL/TOOLS | `Recurrence-Count >= 3` + spans 2+ tasks + within 30 days | Promote as short prevention rule |\n| To skill | Proven + broadly applicable | Extract as skill |\n\n## Recommended references\n\nUse these only when needed:\n- `references/entry-formats.md` — full field schemas and manual templates\n- `references/promotion-and-extraction.md` — promotion rules and skill extraction criteria\n- `references/platform-setup.md` — Claude Code, Codex, Copilot, and OpenClaw setup notes\n\n## Hooks\n\nHook helpers are intentionally optional and workspace-root aware.\n\nAvailable hook scripts:\n- `hooks/activator.sh` — lightweight reminder at prompt start\n- `hooks/error-detector.sh` — lightweight error reminder after failed Bash-like commands\n\nHook configuration examples live in `references/platform-setup.md`.\n\n## What \"next-level\" looks like for this skill\n\nA mature use of this skill has a loop:\n\n**capture → dedupe → promote → extract → evaluate**\n\nThat means:\n- entries are created with stable human IDs, content-addressed chunk IDs, and consistent fields\n- repeated issues link to each other instead of fragmenting\n- proven rules move into persistent memory files\n- broadly useful fixes become standalone skills\n- the skill itself is tested with trigger and output evals in `evals/`\n\nFile v6.2.4:hooks/README.md\n\n# Hooks\n\n## activator.sh\nRuns before prompts to surface relevant patterns from memory.\n\n```bash\n./activator.sh [context]\n```\n\n## error-detector.sh\nRuns after errors to log them for later analysis.\n\n```bash\n./error-detector.sh [type] [detail]\n```\n\n## Integration\nFor OpenClaw, add to your configuration:\n- activator.sh as `pre-prompt-hook`\n- error-detector.sh as `post-error-hook`\n\n## Permissions\nEnsure scripts are executable:\n```bash\nchmod +x hooks/*.sh\n```\n\nFile v6.2.4:README.md\n\n# Self-Improving Compound\n\n[中文说明 / Chinese README](README_zh.md)\n\nA portable AgentSkill that turns agent memory from scattered markdown notes into a structured self-improvement system: real-time capture, SQLite-backed learning, cron audits with explicit context collection, daily factual memory, and lightweight workspace stewardship.\n\n## What it does\n\n- **Captures durable lessons** before the final reply after non-trivial work: user corrections, tool/API gotchas, non-obvious failures, workarounds, and missing capabilities.\n- **Stores execution learnings in SQLite** under `learning/memory_tree/chunks.db`, with FTS5 search, deterministic entity indexing, dedupe, lifecycle status, exports, and human-readable snapshots.\n- **Keeps facts separate from lessons**: factual continuity goes to `memory/YYYY-MM-DD.md`; reusable prevention rules go to `learning/`.\n- **Audits itself with cron**: light checks, heavy audits, daily factual memory, and post-digest workspace stewardship. Conversation-aware cron jobs should use deterministic context collectors when available instead of relying on implicit chat visibility.\n- **Promotes stable rules** into the right layer: `skills/`, `AGENTS.md`, `TOOLS.md`, `MEMORY.md`, or other root agent state files.\n\n## 3+7 co-evolution model\n\nThis system keeps three durable state directories and seven root Markdown control-plane files aligned:\n\n**3 state directories**\n\n- `memory/` — factual daily continuity: what happened, what changed, decisions, links, follow-ups.\n- `learning/` — SQLite-backed execution lessons: corrections, tool/API gotchas, workflow rules.\n- `skills/` — hardened reusable procedures that future agents can load on demand.\n\n**7 root Markdown files**\n\n- `AGENTS.md` — workspace contract, routing, execution policy, safety boundaries.\n- `HEARTBEAT.md` — lightweight check-in surface; often intentionally empty when cron owns timing.\n- `IDENTITY.md` — compatibility pointer or short identity bridge.\n- `MEMORY.md` — pinned long-term hot context.\n- `SOUL.md` — agent identity/persona.\n- `TOOLS.md` — concrete local environment/tool facts.\n- `USER.md` — durable user profile and collaboration preferences.\n\nThe steward loop should make only small, safe consistency updates across these files. It should not rewrite persona, weaken safety rules, or turn daily facts into root-level bloat.\n\n## Architecture\n\n```text\nReal-time capture gate\n -> search existing SQLite learnings\n -> log compact correction/error/learning/feature entries\n -> enqueue async memory jobs\n\nMemory job worker\n -> process chunk extraction jobs\n -> update scores, entity index, tree buffers, and tree summaries\n -> run HOT/WARM/COLD lifecycle maintenance\n\nDaily factual memory\n -> write memory/YYYY-MM-DD.md\n -> extract only reusable lessons into learning/\n\nWorkspace stewardship\n -> export learning memory\n -> inspect learning/, skills/, and the 7 root Markdown control-plane files\n -> make only small safe consistency updates\n```\n\n## Install: files are only step 1\n\n`clawhub install` only installs the skill files. A useful setup requires activation.\n\n```bash\nclawhub install self-improving-compound\nexport OPENCLAW_WORKSPACE=\"/path/to/workspace\"\n# Optional: share one learning store across multiple workspace roots.\n# export SELF_IMPROVING_LEARNING_ROOT=\"$HOME/.openclaw/shared-learning\"\nexport SELF_IMPROVING_SKILL_DIR=\"$OPENCLAW_WORKSPACE/skills/self-improving-compound\"\nexport SELF_IMPROVING_LEARNINGS_CLI=\"$SELF_IMPROVING_SKILL_DIR/scripts/learnings.py\"\nchmod +x \"$SELF_IMPROVING_SKILL_DIR\"/scripts/*.py \"$SELF_IMPROVING_SKILL_DIR\"/scripts/*.sh \"$SELF_IMPROVING_SKILL_DIR\"/hooks/*.sh 2>/dev/null || true\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" init\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" status\n```\n\nFull activation checklist:\n\n1. Install files with ClawHub or copy the skill directory.\n2. Set `OPENCLAW_WORKSPACE`, `SELF_IMPROVING_SKILL_DIR`, and optionally `SELF_IMPROVING_LEARNINGS_CLI`.\n Set `SELF_IMPROVING_LEARNING_ROOT` only when multiple workspaces should share the same lesson store.\n3. Initialize `learning/` with `learnings.py init`.\n4. Add the capture gate to `AGENTS.md` or equivalent agent instructions.\n5. Install/update cron jobs from `scripts/setup-cron.json` and configure delivery.\n6. Optionally wire `hooks/activator.sh` and `hooks/error-detector.sh`.\n7. Optionally configure `SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR` for reliable Light Check context and `SELF_IMPROVING_DAILY_COLLECTOR` for high-quality daily memory.\n8. Run smoke tests: search/log/export/daily-memory helper + `cron list`.\n\nSee `SKILL.md` for the detailed installation and activation flow.\n\nRequirements:\n\n- Python 3.8+\n- bash. The bundled `.sh` helpers intentionally use bash features; POSIX `sh`-only environments are unsupported unless you call the Python CLI directly.\n- No network access required for the local CLI\n\n## Quick start\n\n```bash\n# Initialize learning storage in a workspace\npython3 scripts/learnings.py --root /path/to/workspace init\n\n# Search before logging\npython3 scripts/learnings.py --root /path/to/workspace search \"telegram format\" --limit 5\n\n# Log a correction\npython3 scripts/learnings.py --root /path/to/workspace log-correction \\\n --summary \"Telegram replies should avoid wide tables\" \\\n --correct \"Use compact lists for mobile chat\" \\\n --pattern chat:telegram-format\n\n# Log a reusable learning\npython3 scripts/learnings.py --root /path/to/workspace log-learning \\\n --summary \"Cron jobs that need conversation context should collect it explicitly\" \\\n --details \"Isolated cron sessions do not automatically inherit main chat context; prefer a deterministic transcript/context collector, with sessions_history only as a verified fallback.\" \\\n --pattern cron:explicit-context\n\n# Review and maintain lifecycle\npython3 scripts/learnings.py --root /path/to/workspace status\npython3 scripts/learnings.py --root /path/to/workspace maintain --apply\n# Optional automation: promote high-recurrence lessons into workspace memory files.\npython3 scripts/learnings.py --root /path/to/workspace maintain --apply --auto-promote\n\n# Process async memory jobs once, or keep a local daemon running\npython3 scripts/learnings.py --root /path/to/workspace process-jobs\npython3 scripts/learnings.py --root /path/to/workspace process-jobs --daemon --max-jobs 0\n\n# Export for review\nbash scripts/learning-export.sh\n```\n\n## Optional cron pipeline\n\nThe skill ships with OpenClaw cron templates in `scripts/setup-cron.json` and an agent setup guide in `scripts/setup-cron-agent.md`.\n\nRecommended jobs:\n\n| Job | Default schedule | Purpose |\n|---|---:|---|\n| Self-Improving Light Check | every 2h, 08:00–22:00 | Catch obvious missed corrections and blockers. |\n| Learning Audit Heavy | 09:00 and 22:00 | Audit failures, log missed lessons, maintain lifecycle. |\n| Daily Memory Digest | 23:50 | Write `memory/YYYY-MM-DD.md`, then extract reusable lessons. |\n| Daily Workspace Steward | 00:20 | Export learning memory and lightly inspect `learning/`, `skills/`, and the 7 root Markdown control-plane files. |\n\nFor reliable Light Check context, set an optional collector when your runtime can export recent visible conversation from its local session/transcript store:\n\n```bash\nexport SELF_IMPROVING_LIGHT_CONTEXT_COLLECTOR=\"python3 /path/to/recent-context-collector.py --limit 60\"\n```\n\nCollector rule: exit 0 only after writing a readable Markdown/JSON context file; exit non-zero when the target transcript is unavailable so cron can report `BLOCKED: collector_unavailable` instead of a false success.\n\nCron installation is not automatic. Ask your OpenClaw agent:\n\n> Install the self-improving compound cron jobs using `scripts/setup-cron.json` as reference. Check existing cron jobs first and update instead of duplicating.\n\n## Path Model\n\nThere are two roots:\n\n1. **Skill root** — this package: `scripts/`, `hooks/`, `references/`, `evals/`.\n2. **Workspace root** — your active agent/project state:\n - `learning/memory_tree/chunks.db`\n - `learning/index.md`\n - `memory/YYYY-MM-DD.md` if daily factual memory is enabled\n - root agent files such as `AGENTS.md`, `MEMORY.md`, `TOOLS.md`, `USER.md`, `SOUL.md`, `HEARTBEAT.md`, `IDENTITY.md`\n\nThe learning store can be split from the workspace root with `--learning-root` or `SELF_IMPROVING_LEARNING_ROOT`. In that mode, SQLite, `index.md`, `heartbeat-state.md`, and `promotion-queue.json` live in the shared learning root, while `promote` and `maintain --auto-promote` still write only under the active workspace root.\n\nNever write durable learnings into the installed skill directory. Always pass `--root /path/to/workspace`; add `--learning-root /path/to/shared-learning` only when sharing lessons across projects.\n\n## Architecture Boundary\n\nThis is a selective OpenHuman memory-tree port for agent lesson management, not a full content-management clone. Implemented pieces include SQLite storage, FTS search with fallback, deterministic entity extraction, scoring, entity hotness, async jobs, lifecycle maintenance, deterministic tree buffers, and a promotion queue. LLM topic routing and full OpenHuman-style content workflows are intentionally out of scope for this Python layer.\n\n## Key commands\n\n```bash\npython3 scripts/learnings.py --root /path/to/workspace init\npython3 scripts/learnings.py --root /path/to/workspace status --format json\npython3 scripts/learnings.py --root /path/to/workspace search \"keyword\" --limit 10\npython3 scripts/learnings.py --root /path/to/workspace search \"pk:tooling:api-client-gen\"\npython3 scripts/learnings.py --root /path/to/workspace search \"entity:path:/repo/openapi.yaml\"\npython3 scripts/learnings.py --root /path/to/workspace search \"keyword\" --touch\npython3 scripts/learnings.py --root /path/to/workspace log-error --summary \"...\" --details \"...\" --pattern area:stable-key\npython3 scripts/learnings.py --root /path/to/workspace log-feature --summary \"...\" --details \"...\" --pattern feature:stable-key\npython3 scripts/learnings.py --root /path/to/workspace process-jobs --format json\npython3 scripts/learnings.py --root /path/to/workspace maintain --apply\npython3 scripts/learnings.py --root /path/to/workspace maintain --apply --auto-promote\npython3 scripts/learnings.py --root /path/to/workspace promote LRN-YYYYMMDD-001 --to AGENTS.md\nbash scripts/daily-memory.sh --root /path/to/workspace\nbash scripts/extract-skill.sh my-new-skill /path/to/workspace\n```\n\n## Guardrails\n\n- Search before logging to avoid duplicates.\n- Keep entries compact, searchable, and prevention-oriented.\n- Do not log secrets, tokens, raw private transcripts, or volatile state.\n- Treat cron audit candidates as review prompts, not automatic truth.\n- Daily Workspace Steward may make small safe markdown updates only; it must not rewrite persona, weaken safety/privacy rules, delete files, or change cron jobs.\n\n## Included references\n\n- `references/entry-formats.md` — schemas and manual templates\n- `references/promotion-and-extraction.md` — promotion thresholds and extraction criteria\n- `references/platform-setup.md` — setup guidance for multiple agent runtimes\n- `references/heartbeat-guidance.md` — when to use heartbeat vs cron\n- `references/daily-memory-digest.md` — daily factual memory quality bar\n- `references/hermes-integration.md` — architecture concepts absorbed from Hermes-style agents\n\n## Credits\n\nHybrid adaptation from actual-self-improvement, self-improving-compound, OpenHuman memory-tree, local self-improving-agent patterns, GenericAgent memory hygiene axioms, and Hermes-style agent architecture.\n\nAuthor/maintainer: Rockway Chen · · \n\nFile v6.2.4:_meta.json\n\n{\n \"ownerId\": \"kn7edxdsvkqkfbxghqy9cqz5p583gz7y\",\n \"slug\": \"self-improving-compound\",\n \"version\": \"6.2.4\",\n \"publishedAt\": 1779173014655\n}\n\nFile v6.2.4:references/daily-memory-digest.md\n\n# Daily Memory Digest Integration\n\nThis reference describes the optional daily factual-memory loop that pairs with the SQLite self-improvement store.\n\n## Purpose\n\n`learning/` captures reusable execution lessons. A daily memory digest captures factual continuity: what happened, what changed, what was decided, and what needs follow-up.\n\nUse both loops together:\n\n- `memory/YYYY-MM-DD.md` — factual timeline, decisions, paths, job IDs, links, risks, follow-ups.\n- `learning/memory_tree/chunks.db` — compact reusable prevention rules: corrections, tool/API gotchas, workflow conventions, recurring failures.\n\nDo not duplicate an entire daily note into `learning/`. Extract only lessons that should alter future behavior.\n\n## Suggested daily note quality bar\n\nWhen the day had meaningful activity, prefer a detailed note that can reconstruct the day without rereading raw chat logs.\n\nRecommended sections:\n\n1. Overview\n2. Key workflows and actions\n3. Important decisions\n4. System/configuration changes\n5. Files/projects changed\n6. External integrations and automations\n7. Problems, risks, and unfinished work\n8. Items to promote into long-term memory/rules\n9. Next-step suggestions\n10. Source notes\n\n## Integration options\n\n### Option A — bring your own collector\n\nIf your runtime has a transcript/session collector, call it first and write its output to a context file. Then have the agent synthesize `memory/YYYY-MM-DD.md` from that context.\n\n`scripts/daily-memory.sh` supports:\n\n```bash\nSELF_IMPROVING_DAILY_COLLECTOR=\"python3 /path/to/collector.py\" \\\n bash scripts/daily-memory.sh --root /path/to/workspace --date YYYY-MM-DD\n```\n\nThe collector may print a context path or summary. The agent should inspect that output before writing the final note.\n\n### Option B — no collector\n\nIf no collector exists, use `scripts/daily-memory.sh` as a contract printer. It validates the date/root and prints the target file plus the required quality bar. The agent must gather context using available runtime tools.\n\n## Self-improvement pass\n\nAfter writing the daily note, run the capture gate:\n\n- User correction / changed preference → `log-correction`\n- Non-obvious failure or API/tool/schema quirk → `log-error`\n- Workflow convention or successful reusable workaround → `log-learning`\n- Missing capability or repeated friction → `log-feature`\n\nKeep learning entries short, searchable, and prevention-oriented.\n\nFile v6.2.4:references/entry-formats.md\n\n# Entry formats\n\nUse the bundled `scripts/learnings.py` when possible. Durable entries are SQLite-backed in `learning/memory_tree/chunks.db`; the markdown examples below are the export format and manual fallback.\n\n## Pattern-Key naming convention\n\nAll Pattern-Keys **must use namespaced format**: `project:key` or `domain:key`.\nThis prevents collisions between unrelated contexts.\n\n| ❌ Avoid | ✅ Use instead |\n|----------|---------------|\n| `migration` | `db:migration` |\n| `rate-limit` | `api:rate-limit` |\n| `layer-cache` | `docker:layer-cache` |\n| `timeout` | `network:timeout` |\n| `auth` | `api:auth-flow` or `project-alpha:auth` |\n\n## Correction entry\n\nStored in SQLite. Exported markdown may look like:\n\n```markdown\n### COR-YYYYMMDD-XXX (YYYY-MM-DD) [Pattern-Key: db:migration]\n- **Type**: COR\n- **Summary**: What I got wrong\n- **Details**: Correct answer and context\n- **Status**: pending\n```\n\n## Learning entry\n\nStored in SQLite. Exported markdown may look like:\n\n```markdown\n### LRN-YYYYMMDD-XXX (YYYY-MM-DD) [Pattern-Key: api:rate-limit]\n- **Type**: LRN\n- **Summary**: One-line summary of the lesson\n- **Details**: What happened, what was wrong or surprising, and what is now known to be true\n```\n\n## Error entry\n\nStored in SQLite. Exported markdown may look like:\n\n```markdown\n### ERR-YYYYMMDD-XXX (YYYY-MM-DD) [Pattern-Key: docker:layer-cache]\n- **Type**: ERR\n- **Summary**: One-line description of the failure\n- **Details**: Command, tool, API, or environment details\n```\n\n## Feature request entry\n\nStored in SQLite. Exported markdown may look like:\n\n```markdown\n### FTR-YYYYMMDD-XXX (YYYY-MM-DD) [Pattern-Key: tooling:csv-export]\n- **Type**: FTR\n- **Summary**: One-line summary of the request\n- **Details**: Why the capability matters and a concrete starting point\n```\n\n## Status guidance\n\n- `pending` — captured, not yet addressed\n- `in_progress` — being worked on now\n- `resolved` — issue fixed or lesson integrated\n- `wont_fix` — intentionally not addressing it\n- `promoted` — distilled into project memory\n- `promoted_to_skill` — extracted into a reusable skill\n\nFile v6.2.4:references/heartbeat-guidance.md\n\n# Heartbeat guidance\n\nThis reference describes how to integrate the self-improving memory lifecycle into a periodic heartbeat without creating noise or destructive churn.\n\n## Design principle\n\nHeartbeat should be **conservative and transparent**. Most runs should do nothing. When they do act, they should only perform safe, reversible moves.\n\n## Recommended heartbeat snippet\n\nAdd this to your workspace `HEARTBEAT.md` or equivalent recurring-check file:\n\n```markdown\n## Self-Improving Memory Check\n\n- Run `python3 scripts/learnings.py --root maintain --dry-run`\n- If the report shows only healthy entries or minor recommendations, return `HEARTBEAT_OK`\n- If the report shows clearly safe moves (e.g., stale HOT entries with unambiguous WARM targets), you may run `maintain --apply` automatically\n- If the report shows ambiguous conflicts, promotion candidates, or missing metadata, log a recommendation and ask the user instead of applying\n- `maintain` updates `learning/heartbeat-state.md` with the last run timestamp and result\n```\n\n## State file template\n\nCreate `learning/heartbeat-state.md` to track heartbeat activity:\n\n```markdown\n# Self-Improving Heartbeat State\n\nlast_heartbeat_started_at: never\nlast_reviewed_change_at: never\nlast_heartbeat_result: never\n\n## Last actions\n- none yet\n```\n\n## Safety rules for heartbeat automation\n\n1. **Prefer `maintain --dry-run`** in automated contexts.\n2. **Only auto-apply** when:\n - The lifecycle update is unambiguous (e.g., an `admitted` entry with `Last-Seen` 60 days ago).\n - No promotion candidates are flagged.\n - No conflicts are detected.\n3. **Never auto-apply** when:\n - Metadata is missing or incomplete.\n - A conflict is detected between namespaces.\n - A promotion candidate has `Recurrence-Count >= 3` (ask user first).\n - The target namespace is unclear.\n4. **Preserve source transparency**: after any promotion/export, the SQLite entry should retain `Status` and `Promoted-To` metadata so future readers can trace the history.\n\n## Minimal example\n\n```bash\n# In heartbeat or cron script\nWORKSPACE=\"${OPENCLAW_WORKSPACE:-$(pwd)}\"\n\n# Dry-run review\nREPORT=$(python3 scripts/learnings.py --root \"$WORKSPACE\" maintain --format json)\nSTALE_COUNT=$(echo \"$REPORT\" | python3 -c \"import sys,json; d=json.load(sys.stdin); print(len(d.get('stale_hot',[])))\")\n\nif [ \"$STALE_COUNT\" -eq 0 ]; then\n echo \"HEARTBEAT_OK\"\nelse\n echo \"HEARTBEAT_RECOMMENDATIONS: $STALE_COUNT stale entries found\"\n echo \"$REPORT\"\nfi\n```\n\n## Integration with OpenClaw\n\nIf your workspace uses an OpenClaw `HEARTBEAT.md`, add the snippet above under a `## Self-Improving Memory Check` heading. The skill will then participate in the existing heartbeat flow without adding new files outside `learning/`.\n\nFile v6.2.4:references/hermes-integration.md\n\n# Hermes Integration Notes\n\nHow the self-improving compound selectively incorporates Hermes Agent architecture\nstrengths while staying lean and SQLite-backed.\n\n## Concepts Absorbed from Hermes Architecture\n\n### 1. Skill Registry & Discovery\n\nHermes has a Skills Hub with unified search across official/builtin/community sources\nand trust levels (builtin > trusted > community). We mirror this with:\n\n- **Pattern-Key index** as lightweight skill pointers — each Pattern-Key is a\n discoverable, searchable SQLite entity that links related entries across lifecycle states\n- **Trust levels**: `confirmed` > `pending` > `experimental`, tracked per-entry\n as status metadata\n- **Auto-discovery** via `learnings.py maintain` scan, which surfaces\n high-recurrence patterns as promotion candidates\n- **`extract-skill.sh`** parallels Hermes's skill authoring workflow — turning\n proven learnings into reusable `SKILL.md` documents\n\n### 2. Context Engine Awareness\n\nHermes has pluggable context engines (compressor, etc.). We keep it explicit\nwith tiered lifecycle loading:\n\n- **HOT tier** (`admitted`) — active context candidates, equivalent to Hermes's\n active context window\n- **WARM tier** (`buffered`) — retained context-specific records\n- **COLD tier** (`sealed`) — archived/promoted/resolved records for explicit query/export\n\nThe `activator.sh` hook mirrors Hermes's context priming by extracting top\nPattern-Keys at session start.\n\n### 3. Achievement-Driven Self-Improvement\n\nHermes has `hermes-achievements` plugin for gamified progress tracking. We\nadopt the concept without the gamification:\n\n- **Recurrence-Count** tracks pattern maturity — equivalent to achievement\n progress tracking\n- **Promotion thresholds** as \"achievement gates\": Recurrence-Count >= 3\n triggers promotion review\n- **Pattern extraction** = skill creation — when a pattern proves itself\n across multiple tasks, it graduates to a reusable skill via\n `extract-skill.sh`\n\n### 4. Provider Abstraction (Kept Lean)\n\nHermes has 8 pluggable memory providers. We keep a single SQLite backend\nbut add abstraction for portability:\n\n- Single-file SQLite backend under `learning/memory_tree/chunks.db`\n- JSON-format export option (`--format json`) for portability between systems\n- `OPENCLAW_WORKSPACE` env var for backend location independence\n\n## What We Intentionally Did NOT Absorb\n\n### Multi-Provider Memory Backend\n\nHermes supports 8 memory providers (honcho, mem0, holographic, retaindb,\nbyterover, supermemory, openviking, hindsight). We keep a single SQLite\nbackend.\n\n**Rationale**: SQLite gives reliable local indexing, scoring, and idempotent\ningest while still requiring zero external services. Markdown export preserves\nhuman review and portability when needed.\n\n### Multi-Platform Gateway\n\nHermes has 10+ platform gateways (Telegram, Discord, Slack, Google Meet,\netc.). We stay platform-agnostic.\n\n**Rationale**: The Portable AgentSkill format (`SKILL.md` frontmatter) works\nwherever the agent works — no gateway abstraction needed. The skill travels\nwith the agent.\n\n### Provider-Agnostic Model Switching\n\nHermes has 109+ model providers with runtime switching. We don't need this.\n\n**Rationale**: Memory management is model-agnostic. Learning capture is about\ncontent and patterns, not about which model executes the task. The\nHOT/WARM/COLD tiering works identically regardless of the underlying LLM.\n\n## Strategic Alignment\n\n| Hermes Concept | Our Implementation | Lean-ness |\n|---|---|---|\n| Skills Hub | Pattern-Key Index + `extract-skill.sh` | Lighter — SQLite-backed, no server |\n| Memory Providers | Single SQLite backend with lifecycle tiers | Lighter — no external services |\n| Achievement System | Recurrence-Count + Promotion thresholds | Lighter — automatic, no gamification UI |\n| Context Engine | HOT/WARM/COLD tiered loading | Lighter — explicit, no compression plugin |\n| Skill Authoring | `SKILL.md` frontmatter + `entry-formats.md` | Equivalent |\n| Cron / Scheduling | `heartbeat-guidance.md` + hooks | Lighter — bash-only, no cron plugin |\n| Plugin Discovery | Workspace directory scan | Lighter — no four-source resolution |\n| Observability | `evals/` JSON quality gates | Lighter — no observability plugin |\n\n## Key Design Philosophy\n\nHermes optimizes for **breadth** — many providers, many platforms, many\nmodels. The self-improving compound optimizes for **depth** — fewer\nmechanisms, but each one is fully integrated into the agent's workflow\n(capture gate, tiered storage, promotion lifecycle, skill extraction).\n\nWe absorb Hermes's **structural ideas** (skill registry, context awareness,\nachievement tracking) while rejecting its **infrastructure complexity**\n(multi-provider backends, platform gateways, model switching). The result is\na system that learns like Hermes but deploys like a single directory of\nMarkdown files.\n\nFile v6.2.4:references/platform-setup.md\n\n# Platform setup\n\nThis skill is portable, but automation differs by environment.\n\n## Manual use (works everywhere)\n\nThe safest baseline is manual activation:\n1. determine the workspace root\n2. run `python3 scripts/learnings.py --root /path/to/workspace `\n3. promote or extract only after the pattern is proven\n\n## Claude Code / Claude-style hook configs\n\nExample prompt-start reminder:\n\n```json\n{\n \"hooks\": {\n \"UserPromptSubmit\": [\n {\n \"matcher\": \"\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"/absolute/path/to/self-improving-compound/hooks/activator.sh\"\n }\n ]\n }\n ]\n }\n}\n```\n\nExample error reminder:\n\n```json\n{\n \"hooks\": {\n \"PostToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"/absolute/path/to/self-improving-compound/hooks/error-detector.sh\"\n }\n ]\n }\n ]\n }\n\n\nArchive v6.2.3: 38 files, 100995 bytes\n\nFiles: _meta.json (142b), CHANGELOG.md (9579b), corrections.md (413b), evals/output-check.md (570b), evals/output-evals.json (2135b), evals/trigger-check.md (492b), evals/trigger-validation.json (967b), heartbeat-state.md (155b), hooks/activator.sh (1211b), hooks/error-detector.sh (1312b), hooks/README.md (459b), index.md (918b), memory.md (1473b), README_zh.md (7129b), README.md (10901b), references/daily-memory-digest.md (2418b), references/entry-formats.md (2096b), references/heartbeat-guidance.md (2761b), references/hermes-integration.md (4871b), references/platform-setup.md (1867b), references/promotion-and-extraction.md (5796b), scripts/daily-memory.sh (2780b), scripts/extract-skill.sh (2754b), scripts/learning-audit.py (4616b), scripts/learning-export.sh (630b), scripts/learnings.py (79485b), scripts/log-system-failures.sh (1553b), scripts/memory/__init__.py (1283b), scripts/memory/chunker.py (8619b), scripts/memory/ingest.py (3320b), scripts/memory/store.py (42938b), scripts/memory/test_memory.py (13959b), scripts/memory/types.py (4495b), scripts/setup-cron-agent.md (3281b), scripts/setup-cron.json (7397b), scripts/test_evals.py (18592b), scripts/test_learnings.py (31407b), SKILL.md (32005b)\n\nArchive v6.2.2: 38 files, 92980 bytes\n\nFiles: _meta.json (142b), CHANGELOG.md (7842b), corrections.md (413b), evals/output-check.md (570b), evals/output-evals.json (2135b), evals/trigger-check.md (492b), evals/trigger-validation.json (967b), heartbeat-state.md (155b), hooks/activator.sh (1211b), hooks/error-detector.sh (1312b), hooks/README.md (459b), index.md (918b), memory.md (1473b), README_zh.md (5955b), README.md (9130b), references/daily-memory-digest.md (2418b), references/entry-formats.md (2096b), references/heartbeat-guidance.md (2761b), references/hermes-integration.md (4871b), references/platform-setup.md (1662b), references/promotion-and-extraction.md (5511b), scripts/daily-memory.sh (2780b), scripts/extract-skill.sh (2754b), scripts/learning-audit.py (4616b), scripts/learning-export.sh (534b), scripts/learnings.py (69699b), scripts/log-system-failures.sh (1457b), scripts/memory/__init__.py (976b), scripts/memory/chunker.py (8619b), scripts/memory/ingest.py (3206b), scripts/memory/store.py (35155b), scripts/memory/test_memory.py (11706b), scripts/memory/types.py (4495b), scripts/setup-cron-agent.md (3036b), scripts/setup-cron.json (7241b), scripts/test_evals.py (18592b), scripts/test_learnings.py (28060b), SKILL.md (30814b)\n\nArchive v6.2.1: 38 files, 85028 bytes\n\nFiles: _meta.json (142b), CHANGELOG.md (7423b), corrections.md (413b), evals/output-check.md (570b), evals/output-evals.json (2135b), evals/trigger-check.md (492b), evals/trigger-validation.json (967b), heartbeat-state.md (155b), hooks/activator.sh (1211b), hooks/error-detector.sh (1312b), hooks/README.md (459b), index.md (918b), memory.md (1473b), README_zh.md (4372b), README.md (7405b), references/daily-memory-digest.md (2418b), references/entry-formats.md (2096b), references/heartbeat-guidance.md (2761b), references/hermes-integration.md (4871b), references/platform-setup.md (1662b), references/promotion-and-extraction.md (5511b), scripts/daily-memory.sh (2780b), scripts/extract-skill.sh (2754b), scripts/learning-audit.py (4616b), scripts/learning-export.sh (534b), scripts/learnings.py (59264b), scripts/log-system-failures.sh (1457b), scripts/memory/__init__.py (976b), scripts/memory/chunker.py (8619b), scripts/memory/ingest.py (3206b), scripts/memory/store.py (30373b), scripts/memory/test_memory.py (11049b), scripts/memory/types.py (4495b), scripts/setup-cron-agent.md (3036b), scripts/setup-cron.json (7090b), scripts/test_evals.py (18592b), scripts/test_learnings.py (23731b), SKILL.md (23318b)\n\nArchive v6.2.0: 38 files, 83575 bytes\n\nFiles: _meta.json (142b), CHANGELOG.md (7011b), corrections.md (413b), evals/output-check.md (570b), evals/output-evals.json (2135b), evals/trigger-check.md (492b), evals/trigger-validation.json (967b), heartbeat-state.md (155b), hooks/activator.sh (1211b), hooks/error-detector.sh (1312b), hooks/README.md (459b), index.md (918b), memory.md (1473b), README_zh.md (3278b), README.md (6204b), references/daily-memory-digest.md (2418b), references/entry-formats.md (2096b), references/heartbeat-guidance.md (2761b), references/hermes-integration.md (4871b), references/platform-setup.md (1662b), references/promotion-and-extraction.md (5511b), scripts/daily-memory.sh (2780b), scripts/extract-skill.sh (2754b), scripts/learning-audit.py (4616b), scripts/learning-export.sh (534b), scripts/learnings.py (59264b), scripts/log-system-failures.sh (1457b), scripts/memory/__init__.py (976b), scripts/memory/chunker.py (8619b), scripts/memory/ingest.py (3206b), scripts/memory/store.py (30373b), scripts/memory/test_memory.py (11049b), scripts/memory/types.py (4495b), scripts/setup-cron-agent.md (3022b), scripts/setup-cron.json (7070b), scripts/test_evals.py (18592b), scripts/test_learnings.py (23731b), SKILL.md (22314b)\n\nArchive v6.1.7: 37 files, 84168 bytes\n\nFiles: _meta.json (142b), CHANGELOG.md (6270b), corrections.md (413b), evals/output-check.md (570b), evals/output-evals.json (2135b), evals/trigger-check.md (492b), evals/trigger-validation.json (967b), heartbeat-state.md (155b), hooks/activator.sh (1211b), hooks/error-detector.sh (1312b), hooks/README.md (459b), index.md (918b), memory.md (1473b), README_zh.md (4421b), README.md (14335b), references/entry-formats.md (2096b), references/heartbeat-guidance.md (2761b), references/hermes-integration.md (4871b), references/platform-setup.md (1662b), references/promotion-and-extraction.md (5511b), scripts/daily-memory.sh (8129b), scripts/extract-skill.sh (2754b), scripts/learning-audit.py (4376b), scripts/learning-export.sh (443b), scripts/learnings.py (59102b), scripts/log-system-failures.sh (1392b), scripts/memory/__init__.py (976b), scripts/memory/chunker.py (8619b), scripts/memory/ingest.py (3206b), scripts/memory/store.py (35472b), scripts/memory/test_memory.py (11049b), scripts/memory/test_store_port.py (13236b), scripts/memory/types.py (4495b), scripts/setup-cron-agent.md (2704b), scripts/setup-cron.json (3923b), scripts/test_learnings.py (23731b), SKILL.md (20764b)\n\nArchive v6.1.6: 33 files, 73544 bytes\n\nFiles: _meta.json (142b), CHANGELOG.md (5883b), corrections.md (413b), evals/output-check.md (570b), evals/output-evals.json (2135b), evals/trigger-check.md (492b), evals/trigger-validation.json (967b), heartbeat-state.md (155b), hooks/activator.sh (1211b), hooks/error-detector.sh (1312b), hooks/README.md (459b), index.md (918b), memory.md (1473b), README.md (13301b), references/entry-formats.md (2096b), references/heartbeat-guidance.md (2761b), references/hermes-integration.md (4871b), references/platform-setup.md (1662b), references/promotion-and-extraction.md (5511b), scripts/daily-memory.sh (8129b), scripts/extract-skill.sh (2754b), scripts/learning-audit.py (4376b), scripts/learning-export.sh (443b), scripts/learnings.py (59102b), scripts/log-system-failures.sh (1392b), scripts/memory/__init__.py (976b), scripts/memory/chunker.py (8619b), scripts/memory/ingest.py (3206b), scripts/memory/store.py (30373b), scripts/memory/test_memory.py (11049b), scripts/memory/types.py (4495b), scripts/test_learnings.py (23731b), SKILL.md (19869b)\n\nArchive v6.1.5: 33 files, 73307 bytes\n\nFiles: _meta.json (142b), CHANGELOG.md (5790b), corrections.md (413b), evals/output-check.md (570b), evals/output-evals.json (2135b), evals/trigger-check.md (492b), evals/trigger-validation.json (967b), heartbeat-state.md (155b), hooks/activator.sh (1211b), hooks/error-detector.sh (1312b), hooks/README.md (459b), index.md (918b), memory.md (1473b), README.md (13159b), references/entry-formats.md (2096b), references/heartbeat-guidance.md (2761b), references/hermes-integration.md (4871b), references/platform-setup.md (1662b), references/promotion-and-extraction.md (5511b), scripts/daily-memory.sh (8129b), scripts/extract-skill.sh (2754b), scripts/learning-audit.py (4376b), scripts/learning-export.sh (443b), scripts/learnings.py (59102b), scripts/log-system-failures.sh (1392b), scripts/memory/__init__.py (976b), scripts/memory/chunker.py (8619b), scripts/memory/ingest.py (3206b), scripts/memory/store.py (30373b), scripts/memory/test_memory.py (11049b), scripts/memory/types.py (4495b), scripts/test_learnings.py (23731b), SKILL.md (19671b)\n\nArchive v6.1.4: 33 files, 72501 bytes\n\nFiles: _meta.json (142b), CHANGELOG.md (5395b), corrections.md (413b), evals/output-check.md (570b), evals/output-evals.json (2135b), evals/trigger-check.md (492b), evals/trigger-validation.json (967b), heartbeat-state.md (155b), hooks/activator.sh (1211b), hooks/error-detector.sh (1312b), hooks/README.md (459b), index.md (918b), memory.md (1473b), README.md (12204b), references/entry-formats.md (2096b), references/heartbeat-guidance.md (2761b), references/hermes-integration.md (4871b), references/platform-setup.md (1662b), references/promotion-and-extraction.md (5511b), scripts/daily-memory.sh (8129b), scripts/extract-skill.sh (2754b), scripts/learning-audit.py (4376b), scripts/learning-export.sh (443b), scripts/learnings.py (59102b), scripts/log-system-failures.sh (1392b), scripts/memory/__init__.py (976b), scripts/memory/chunker.py (8619b), scripts/memory/ingest.py (3206b), scripts/memory/store.py (30373b), scripts/memory/test_memory.py (11049b), scripts/memory/types.py (4495b), scripts/test_learnings.py (23731b), SKILL.md (18964b)","readmeExcerpt":"Skill: Self Improving Compound Owner: lingmafuture Summary: Agent memory and self-improvement system. Replaces naive file-based agent memory with a structured SQLite learning engine: capture corrections, errors, and r... Tags: latest:6.2.5, lifecycle:1.0.5, memory:1.0.5, self-improvement:1.0.5 Version history: v6.2.5 | 2026-05-19T07:53:29.795Z | user Add observable Candidate → Learning → Promotion memory pipeline wit","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# Workspace root: where memory/, learning/, AGENTS.md, etc. live\nexport OPENCLAW_WORKSPACE=\"/path/to/workspace\"\n\n# Optional shared lesson store for multiple workspace roots\n# export SELF_IMPROVING_LEARNING_ROOT=\"$HOME/.openclaw/shared-learning\"\n\n# Skill root: where this skill was installed\nexport SELF_IMPROVING_SKILL_DIR=\"$OPENCLAW_WORKSPACE/skills/self-improving-compound\"\nexport SELF_IMPROVING_LEARNINGS_CLI=\"$SELF_IMPROVING_SKILL_DIR/scripts/learnings.py\""},{"language":"bash","snippet":"export OPENCLAW_WORKSPACE=\"$HOME/.openclaw/workspace\"\nexport SELF_IMPROVING_SKILL_DIR=\"$OPENCLAW_WORKSPACE/skills/self-improving-compound\"\nexport SELF_IMPROVING_LEARNINGS_CLI=\"$SELF_IMPROVING_SKILL_DIR/scripts/learnings.py\""},{"language":"bash","snippet":"clawhub install self-improving-compound\ncd \"$SELF_IMPROVING_SKILL_DIR\"\nchmod +x scripts/*.py scripts/*.sh hooks/*.sh 2>/dev/null || true"},{"language":"bash","snippet":"python3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" init\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" status\npython3 \"$SELF_IMPROVING_LEARNINGS_CLI\" --root \"$OPENCLAW_WORKSPACE\" search \"install smoke test\" --limit 3"},{"language":"markdown","snippet":"## Self-improvement capture gate\n\nBefore 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.\n\nIf yes:\n1. Search existing learnings first:\n `python3 $SELF_IMPROVING_LEARNINGS_CLI --root $OPENCLAW_WORKSPACE search \"\" --limit 5`\n2. If no suitable entry exists, log the durable lesson with `log-correction`, `log-error`, `log-learning`, or `log-feature`.\n3. Keep entries compact, prevention-oriented, and secret-free."},{"language":"bash","snippet":"\"$SELF_IMPROVING_SKILL_DIR/hooks/activator.sh\" \"install smoke test\" || true\n\"$SELF_IMPROVING_SKILL_DIR/hooks/error-detector.sh\" \"install\" \"smoke test\" || true"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: self-improving-compound\ndescription: \"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.\"\ncompatibility: \"Portable Agent Skills format. Core workflow is agent-agnostic. Bundled helpers require Python 3.8+; hook helpers require bash. No network access is required.\"\nmetadata:\n version: \"6.2.5\"\n original_slug: \"self-improving-compound\"\n category: \"memory-system\"\n author: \"Hybrid adaptation from actual-self-improvement, self-improving-compound, OpenHuman memory-tree, and Hermes Agent architecture | Contact: rockwaychen@gmail.com | GitHub: LingmaFuture\"\n---\n\n# Self-Improving Compound\n\nAn 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.\n\nThe system runs as four layers:\n- **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.\n- **Layer 1 — Real-time capture**: AGENTS.md final-before-reply gate logs corrections, errors, and workarounds to SQLite as they happen.\n- **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).\n- **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.\n- **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.\n\n**Author"},{"path":"hooks/README.md","content":"# Hooks\n\n## activator.sh\nRuns before prompts to surface relevant patterns from memory.\n\n```bash\n./activator.sh [context]\n```\n\n## error-detector.sh\nRuns after errors to log them for later analysis.\n\n```bash\n./error-detector.sh [type] [detail]\n```\n\n## Integration\nFor OpenClaw, add to your configuration:\n- activator.sh as `pre-prompt-hook`\n- error-detector.sh as `post-error-hook`\n\n## Permissions\nEnsure scripts are executable:\n```bash\nchmod +x hooks/*.sh\n```"},{"path":"README.md","content":"# Self-Improving Compound\n\n[中文说明 / Chinese README](README_zh.md)\n\nA portable AgentSkill that turns agent memory from scattered markdown notes into a structured self-improvement system: real-time capture, observable Candidate → Learning → Promotion queues, SQLite-backed learning, cron audits with explicit context collection, daily factual memory, and lightweight workspace stewardship.\n\n## What it does\n\n- **Captures durable lessons** before the final reply after non-trivial work: user corrections, tool/API gotchas, non-obvious failures, workarounds, and missing capabilities.\n- **Stores execution learnings in SQLite** under `learning/memory_tree/chunks.db`, with FTS5 search, deterministic entity indexing, dedupe, lifecycle status, exports, and human-readable snapshots.\n- **Keeps facts separate from lessons**: factual continuity goes to `memory/YYYY-MM-DD.md`; reusable prevention rules go to `learning/`.\n- **Audits itself with cron**: light checks, heavy audits, daily factual memory, and post-digest workspace stewardship. Conversation-aware cron jobs should use deterministic context collectors when available instead of relying on implicit chat visibility.\n- **Makes memory observable** with `Candidate → Learning → Promotion → Done`: candidates, promotion backlog, cursor coverage, and dashboard health are visible under `learning/pipeline/`.\n- **Promotes stable rules** into the right layer: `skills/`, `AGENTS.md`, `TOOLS.md`, `MEMORY.md`, or other root agent state files.\n\n## 3+7 co-evolution model\n\nThis system keeps three durable state directories and seven root Markdown control-plane files aligned:\n\n**3 state directories**\n\n- `memory/` — factual daily continuity: what happened, what changed, decisions, links, follow-ups.\n- `learning/` — SQLite-backed execution lessons: corrections, tool/API gotchas, workflow rules.\n- `skills/` — hardened reusable procedures that future agents can load on demand.\n\n**7 root Markdown files**\n\n- `AGENTS.md` — workspace contract, routing, execution policy, safety boundaries.\n- `HEARTBEAT.md` — lightweight check-in surface; often intentionally empty when cron owns timing.\n- `IDENTITY.md` — compatibility pointer or short identity bridge.\n- `MEMORY.md` — pinned long-term hot context.\n- `SOUL.md` — agent identity/persona.\n- `TOOLS.md` — concrete local environment/tool facts.\n- `USER.md` — durable user profile and collaboration preferences.\n\nThe steward loop should make only small, safe consistency updates across these files. It should not rewrite persona, weaken safety rules, or turn daily facts into root-level bloat.\n\n## Architecture\n\n```text\nObservable Memory Pipeline\n -> collect incremental visible context\n -> add candidates\n -> log confirmed SQLite learnings\n -> queue durable promotions\n -> refresh dashboard\n\nReal-time capture gate\n -> search existing SQLite learnings\n -> log compact correction/error/learning/feature entries\n -> enqueue async memory jobs\n\nMemory job worker\n -> process chunk extraction jobs\n -> upd"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7edxdsvkqkfbxghqy9cqz5p583gz7y\",\n \"slug\": \"self-improving-compound\",\n \"version\": \"6.2.5\",\n \"publishedAt\": 1779177209795\n}"},{"path":"references/daily-memory-digest.md","content":"# Daily Memory Digest Integration\n\nThis reference describes the optional daily factual-memory loop that pairs with the SQLite self-improvement store.\n\n## Purpose\n\n`learning/` captures reusable execution lessons. A daily memory digest captures factual continuity: what happened, what changed, what was decided, and what needs follow-up.\n\nUse both loops together:\n\n- `memory/YYYY-MM-DD.md` — factual timeline, decisions, paths, job IDs, links, risks, follow-ups.\n- `learning/memory_tree/chunks.db` — compact reusable prevention rules: corrections, tool/API gotchas, workflow conventions, recurring failures.\n\nDo not duplicate an entire daily note into `learning/`. Extract only lessons that should alter future behavior.\n\n## Suggested daily note quality bar\n\nWhen the day had meaningful activity, prefer a detailed note that can reconstruct the day without rereading raw chat logs.\n\nRecommended sections:\n\n1. Overview\n2. Key workflows and actions\n3. Important decisions\n4. System/configuration changes\n5. Files/projects changed\n6. External integrations and automations\n7. Problems, risks, and unfinished work\n8. Items to promote into long-term memory/rules\n9. Next-step suggestions\n10. Source notes\n\n## Integration options\n\n### Option A — bring your own collector\n\nIf your runtime has a transcript/session collector, call it first and write its output to a context file. Then have the agent synthesize `memory/YYYY-MM-DD.md` from that context.\n\n`scripts/daily-memory.sh` supports:\n\n```bash\nSELF_IMPROVING_DAILY_COLLECTOR=\"python3 /path/to/collector.py\" \\\n bash scripts/daily-memory.sh --root /path/to/workspace --date YYYY-MM-DD\n```\n\nThe collector may print a context path or summary. The agent should inspect that output before writing the final note.\n\n### Option B — no collector\n\nIf no collector exists, use `scripts/daily-memory.sh` as a contract printer. It validates the date/root and prints the target file plus the required quality bar. The agent must gather context using available runtime tools.\n\n## Self-improvement pass\n\nAfter writing the daily note, run the capture gate:\n\n- User correction / changed preference → `log-correction`\n- Non-obvious failure or API/tool/schema quirk → `log-error`\n- Workflow convention or successful reusable workaround → `log-learning`\n- Missing capability or repeated friction → `log-feature`\n\nKeep learning entries short, searchable, and prevention-oriented."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Agent memory and self-improvement system. Replaces naive file-based agent memory with a structured SQLite learning engine: capture corrections, errors, and r... Skill: Self Improving Compound Owner: lingmafuture Summary: Agent memory and self-improvement system. Replaces naive file-based agent memory with a structured SQLite learning engine: capture corrections, errors, and r... Tags: latest:6.2.5, lifecycle:1.0.5, memory:1.0.5, self-improvement:1.0.5 Version history: v6.2.5 | 2026-05-19T07:53:29.795Z | user Add observable Candidate → Learning → Promotion memory pipeline wit","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1535,"uniquenessScore":45,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T23:49:30.668Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T23:49:30.668Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T08:44:18.555Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}