{"id":"047dc5d7-014b-4673-9bd5-1c435540b263","entityType":"agent","slug":"clawhub-jd2005l-opencortex","name":"OpenCortex","canonicalUrl":"https://xpersona.co/agent/clawhub-jd2005l-opencortex","canonicalPath":"/agent/clawhub-jd2005l-opencortex","generatedAt":"2026-04-17T06:03:27.103Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"description":"Self-improving memory architecture for OpenClaw agents. Structured memory files, nightly distillation, weekly synthesis, enforced principles (P0 for custom,...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 648 downloads reported by the source. Last updated 4/15/2026.","installCommand":"clawhub skill install kn7e5n3qxtp49kdnhne6vr3wzd81n3sc:opencortex","sourceUrl":"https://clawhub.ai/JD2005L/opencortex","homepage":"https://clawhub.ai/JD2005L/opencortex","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/JD2005L/opencortex","kind":"source"}],"safetyScore":84,"overallRank":62,"popularityScore":56,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"OpenCortex technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","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-04-15T00:45:39.800Z","emptyReason":null},"stars":null,"forks":null,"downloads":648,"packageName":null,"latestVersion":"3.5.18","tractionLabel":"648 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-03-01T03:33:02.514Z","emptyReason":null},"lastUpdatedAt":"2026-04-15T00:45:39.800Z","lastCrawledAt":"2026-03-01T03:33:02.514Z","lastIndexedAt":null,"nextCrawlAt":"2026-03-02T03:33:02.514Z","lastVerifiedAt":null,"highlights":[{"version":"3.5.18","createdAt":"2026-02-28T18:25:57.357Z","changelog":"Use --model default to clear cron model overrides (empty string silently ignored by OpenClaw CLI)","fileCount":12,"zipByteSize":60983},{"version":"3.5.17","createdAt":"2026-02-28T18:18:14.620Z","changelog":"Clear cron model overrides to gateway default via cron edit, skip updates when message and model already correct, model-agnostic for all providers","fileCount":12,"zipByteSize":60985},{"version":"3.5.15","createdAt":"2026-02-28T18:09:06.643Z","changelog":"Git backup now scrubs all non-binary files by default instead of only known extensions. Fixes silent backup failures when secrets appear in unlisted file types.","fileCount":null,"zipByteSize":null},{"version":"3.5.14","createdAt":"2026-02-28T08:02:05.493Z","changelog":"Memory search index shown as optional info, not a warning. OpenCortex works without embeddings configured.","fileCount":null,"zipByteSize":null},{"version":"3.5.13","createdAt":"2026-02-28T07:55:44.329Z","changelog":"Remove cron model override detection from update.sh to reduce script size for scanner analysis, verify.sh handles model override warnings","fileCount":null,"zipByteSize":null},{"version":"3.5.12","createdAt":"2026-02-28T07:52:47.596Z","changelog":"Fix crash after subsection extraction from missing error guards on grep and tail pipelines under set -e","fileCount":null,"zipByteSize":null},{"version":"3.5.11","createdAt":"2026-02-28T07:48:47.109Z","changelog":"Fix subsection extraction crash from special characters in headers, use fixed-string grep matching, add error guards for set -e compatibility","fileCount":null,"zipByteSize":null},{"version":"3.5.10","createdAt":"2026-02-28T07:43:59.610Z","changelog":"Detect cron model overrides and provide manual TUI instructions, revert automated cron deletion for scanner compliance","fileCount":null,"zipByteSize":null}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install kn7e5n3qxtp49kdnhne6vr3wzd81n3sc:opencortex","setupComplexity":"low","setupSteps":["Install using `clawhub skill install kn7e5n3qxtp49kdnhne6vr3wzd81n3sc:opencortex` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/JD2005L/opencortex before using production credentials."],"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://xpersona.co/api/v1/agents/clawhub-jd2005l-opencortex/snapshot","contractUrl":"https://xpersona.co/api/v1/agents/clawhub-jd2005l-opencortex/contract","trustUrl":"https://xpersona.co/api/v1/agents/clawhub-jd2005l-opencortex/trust"},"curlExamples":["curl -s \"https://xpersona.co/api/v1/agents/clawhub-jd2005l-opencortex/snapshot\"","curl -s \"https://xpersona.co/api/v1/agents/clawhub-jd2005l-opencortex/contract\"","curl -s \"https://xpersona.co/api/v1/agents/clawhub-jd2005l-opencortex/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-04-17T06:03:27.098Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://xpersona.co/api/v1/agents/clawhub-jd2005l-opencortex/dossier","snapshotUrl":"https://xpersona.co/api/v1/agents/clawhub-jd2005l-opencortex/snapshot","contractUrl":"https://xpersona.co/api/v1/agents/clawhub-jd2005l-opencortex/contract","trustUrl":"https://xpersona.co/api/v1/agents/clawhub-jd2005l-opencortex/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":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"readme":"Skill: OpenCortex\n\nOwner: JD2005L\n\nSummary: Self-improving memory architecture for OpenClaw agents. Structured memory files, nightly distillation, weekly synthesis, enforced principles (P0 for custom,...\n\nTags: architecture:1.6.0, latest:3.5.18, memory:1.6.0, self-improving:1.6.0, voice:1.2.1\n\nVersion history:\n\nv3.5.18 | 2026-02-28T18:25:57.357Z | user\n\nUse --model default to clear cron model overrides (empty string silently ignored by OpenClaw CLI)\n\nv3.5.17 | 2026-02-28T18:18:14.620Z | user\n\nClear cron model overrides to gateway default via cron edit, skip updates when message and model already correct, model-agnostic for all providers\n\nv3.5.15 | 2026-02-28T18:09:06.643Z | user\n\nGit backup now scrubs all non-binary files by default instead of only known extensions. Fixes silent backup failures when secrets appear in unlisted file types.\n\nv3.5.14 | 2026-02-28T08:02:05.493Z | user\n\nMemory search index shown as optional info, not a warning. OpenCortex works without embeddings configured.\n\nv3.5.13 | 2026-02-28T07:55:44.329Z | user\n\nRemove cron model override detection from update.sh to reduce script size for scanner analysis, verify.sh handles model override warnings\n\nv3.5.12 | 2026-02-28T07:52:47.596Z | user\n\nFix crash after subsection extraction from missing error guards on grep and tail pipelines under set -e\n\nv3.5.11 | 2026-02-28T07:48:47.109Z | user\n\nFix subsection extraction crash from special characters in headers, use fixed-string grep matching, add error guards for set -e compatibility\n\nv3.5.10 | 2026-02-28T07:43:59.610Z | user\n\nDetect cron model overrides and provide manual TUI instructions, revert automated cron deletion for scanner compliance\n\nv3.5.9 | 2026-02-28T07:40:06.489Z | user\n\nDetect cron model overrides and provide manual TUI instructions, revert automated cron deletion for scanner compliance\n\nv3.5.7 | 2026-02-28T07:36:06.952Z | user\n\nFix cron model overrides via delete and recreate (no --clear-model CLI support), extract bloated MEMORY.md subsections to dedicated files, memory search health check with provider setup guidance\n\nv3.5.4 | 2026-02-28T07:22:12.297Z | user\n\nStructural cleanup engine: detect/resolve duplicate and orphan principles (title + body hash comparison), move non-standard MEMORY.md sections to dedicated memory files, clear cron model overrides, memory search health check, weekly retrieval quality testing with remediation chain, fix interactive prompts reading from /dev/tty to prevent stdin hijack in loops\n\nv3.5.3 | 2026-02-28T07:11:43.662Z | user\n\nStructural cleanup engine: detect and resolve duplicate/orphan principles beyond P0-P8 (title + body comparison), migrate unique orphans to P0 sub-principles, clear cron model overrides, flag MEMORY.md bloat and non-standard sections, memory search health check in verify.sh, weekly retrieval quality testing with remediation chain, fix stdin hijack in heredoc loops (read from /dev/tty)\n\nv3.5.0 | 2026-02-28T06:52:06.221Z | user\n\nStructural cleanup: detect and resolve duplicate/orphan principles beyond P0-P8, clear cron model overrides, flag MEMORY.md bloat and non-standard sections\n\nv3.4.18 | 2026-02-28T05:16:28.370Z | user\n\nDocumentation sweep: README update matrix and architecture.md updated with all v3.4.x features including cron dedup, AGENTS.md merge, memory health monitoring, and retrieval quality testing\n\nv3.4.16 | 2026-02-28T05:06:26.313Z | user\n\nverify.sh checks memory search index health, file count, and MEMORY.md boot size. Weekly synthesis now tests retrieval quality with real queries and logs gaps.\n\nv3.4.15 | 2026-02-28T04:22:13.468Z | user\n\nRemove --model default from cron job edits and creation — OpenClaw gateway interprets it as literal model name, causing cron failures\n\nv3.4.14 | 2026-02-28T04:03:12.546Z | user\n\nFix cron existence detection: use truncation-safe match strings for openclaw cron list output\n\nUpdater deduplicates Daily Memory Distillation and Weekly Synthesis cron jobs, removing extras created by prior truncation detection bug\n\nv3.4.12 | 2026-02-28T03:57:01.189Z | user\n\nStrict y/n input validation with retry loop across all prompts in install.sh and update.sh\n\nv3.4.10 | 2026-02-28T03:40:02.184Z | user\n\nUpdater recreates missing Daily Memory Distillation and Weekly Synthesis cron jobs with timezone auto-detection instead of deferring to manual install\n\nv3.4.9 | 2026-02-28T03:28:52.261Z | user\n\nSelf-healing updater: AGENTS.md and BOOTSTRAP.md merge custom sections during regeneration. Weekly structural integrity audit ensures information is in the correct file and section. Timezone auto-detection. Safety and Formatting standard AGENTS.md sections.\n\nv3.4.6 | 2026-02-28T03:13:29.515Z | user\n\nAuto-detect timezone during install instead of defaulting to UTC. Weekly synthesis now reorganizes memory files for accessibility. Daily distillation flags stale projects and syncs cron job table.\n\nv3.4.5 | 2026-02-28T02:59:10.449Z | user\n\nUpdater regenerates AGENTS.md and BOOTSTRAP.md directly with backup instead of deferring to install.sh\n\nv3.4.4 | 2026-02-28T02:49:06.564Z | user\n\nShow version number in update.sh output header\n\nv3.4.3 | 2026-02-28T02:39:51.820Z | user\n\nComprehensive update coverage: checks and creates SOUL.md, USER.md, .gitignore sensitive entries, offers AGENTS.md and BOOTSTRAP.md backup and regeneration when outdated, verifies cron job existence, model-agnostic P1 delegation, P0 custom principles with migration from P1-P8 customizations, hash-based principle comparison, reference doc sync, full MEMORY.md structure verification\n\nv3.4.0 | 2026-02-28T02:19:50.848Z | user\n\nCustom principle migration: updater detects additions to P1-P8, shows them, and offers to move them to P0 sub-principles (P0-A, P0-B, etc.) before replacing with the standard version. Auto-creates P0 section for older installs. Model-agnostic P1 delegation tiers.\n\nv3.2.5 | 2026-02-28T01:48:40.938Z | user\n\nUpdater now shows full side-by-side content (current vs new) in a boxed format before asking to update each principle. Users can see exactly what's changing before saying yes.\n\nv3.2.4 | 2026-02-28T01:39:52.551Z | user\n\nAdded update matrix table to README documenting exactly what the updater touches and how. Changelog: \"README now includes update behavior matrix showing what content is updated, how, and whether user data is safe\"\n\nv3.2.3 | 2026-02-28T01:25:26.979Z | user\n\nComprehensive updater: reference docs auto-updated, principle body changes detected via hash comparison, AGENTS.md and BOOTSTRAP.md content gap checks added\n\nv3.2.1 | 2026-02-28T01:15:22.521Z | user\n\n- Added mention of \"write-ahead durability\" to the memory architecture features.\n- No code or functional changes; documentation only.\n\nv3.2.0 | 2026-02-28T00:59:26.540Z | user\n\nAdded write-before-respond discipline to P2 (Write It Down). When the user states a preference, makes a decision, gives a deadline, or corrects you, the agent now writes it to memory before composing a response. Prevents context loss if the session ends or compacts between responding and saving. Inspired by Write-Ahead Log patterns used in database systems.\n\nAdded corresponding \"Write Before Responding\" section to the AGENTS.md template with a clear two-step protocol.\n\nv3.1.5 | 2026-02-27T04:55:35.737Z | user\n\nFixed install on existing OpenClaw instances where MEMORY.md already exists but has no PRINCIPLES section. Previously the installer would skip the file entirely. Now it detects the missing section and injects principles after the first heading line, preserving all existing content.\n\nFixed verify.sh \"integer expression expected\" error when counting principles. The grep output could contain newline characters that broke the comparison. Output is now sanitized to digits only.\n\nCleared hardcoded model overrides from cron jobs during updates (uses gateway default).\n\nv3.1.3 | 2026-02-26T00:56:18.827Z | user\n\nverify.sh now warns about hardcoded model overrides in crons.\n\nv3.1.2 | 2026-02-25T07:10:03.585Z | user\n\nUpdate script clears hardcoded model overrides from crons\n\n• update.sh now passes --model default when updating cron messages, clearing any stale hardcoded model (e.g. haiku, sonnet) so crons use the gateway default\n• Fresh installs already didn't hardcode models — this fixes existing installs that had them set from earlier versions\n\nv3.1.1 | 2026-02-25T07:05:34.215Z | user\n\nUpdate script clears hardcoded model overrides from crons\n\n• update.sh now passes --model default when updating cron messages, clearing any stale hardcoded model (e.g. haiku, sonnet) so crons use the gateway default\n• Fresh installs already didn't hardcode models — this fixes existing installs that had them set from earlier versions\n\nv3.1.0 | 2026-02-25T06:41:31.853Z | user\n\n1. Cron messages now reference instruction files instead of inline ~5KB — saves tokens every run\n2. Install asks Eager vs Lazy loading strategy\n3. verify.sh warns if MEMORY.md exceeds 3KB budget\n\nv3.0.7 | 2026-02-25T02:15:11.834Z | user\n\nFixes the install.sh line 573 error (nested double quotes). Also fixes verify.sh principle counting. Upload to ClawHub when ready.\n\nv3.0.5 | 2026-02-25T01:50:32.633Z | user\n\nPrinciple updates now ask before replacing. Shows current vs new title, warns about custom content loss, asks y/N per principle. No user data silently overwritten.\n\nv3.0.1 | 2026-02-25T01:08:33.221Z | user\n\nFull documentation sweep. Fixed: README directories list, AGENTS.md template, metrics knowledge count, update.sh cron messages (were completely stale), architecture.md reference. Everything now consistently references contacts/workflows/preferences.\n\nv3.0.0 | 2026-02-25T00:59:50.502Z | user\n\nContacts, Workflows, and Preferences. Full pipeline: auto-capture from conversation → nightly distillation routing → weekly review → metrics tracking. P4 and P5 extended with enforcement. All scanner-safe.\n\nv2.8.9 | 2026-02-24T20:02:46.981Z | user\n\nOpt-in security model, metrics tracking, streamlined installer. Voice profiling and infra collection now require env vars (off by default). Git backup uses isolated copy — workspace files never touched. Removed python3 dependency. Cron jobs use gateway default model. Install script detects existing installs with Update/Reconfigure menu. Daily metrics tracking with growth charts and compound scoring.\n\nv2.8.7 | 2026-02-24T18:55:13.307Z | user\n\nUpdate instructions in SKILL.md and README now point to install.sh instead of update.sh separately. One command to update.\n\nv2.8.5 | 2026-02-24T18:42:02.410Z | user\n\nRemoved git-scrub-secrets.sh and git-restore-secrets.sh entirely. Scanner flagged them as contradicting the \"isolated copy\" claim. git-backup.sh already has its own inline scrub logic. Should resolve the Instruction Scope concern.\n\nv2.8.4 | 2026-02-24T18:38:30.047Z | user\n\nInstall detects existing installs without version file — checks for MEMORY.md with PRINCIPLES section, not just .opencortex-version. Shows \"version unknown\" and offers Update/Reinstall/Cancel\n• Update path offers new optional features — when updating, update.sh now asks about features you don't have yet (e.g., metrics tracking) instead of silently skipping them\n• Metrics script auto-refreshed on update — if you already have metrics enabled, update.sh copies the latest metrics.sh to your workspace\n• Normal user flow works end-to-end — clawhub install --force → bash install.sh → detects install → offers Update → asks about new features → done\n\nv2.8.3 | 2026-02-24T18:33:20.086Z | user\n\nInstall script now detects existing version and offers Update/Reinstall/Cancel. Also includes v2.8.2 scanner fixes (no python3, file binary declared, restore-secrets clarified).\n\nv2.8.1 | 2026-02-24T18:24:00.451Z | user\n\nVersion bump only to correct display name.\n\nv2.8.0 | 2026-02-24T18:20:09.860Z | user\n\nMetrics tracking: opt-in daily snapshots tracking knowledge growth, decisions, tools, runbooks, failures, debriefs. ASCII growth charts and 0-100 compound score. Read-only, no network, no sensitive data. Weekly synthesis includes metrics if enabled.\n\nv2.7.0 | 2026-02-24T17:55:10.157Z | user\n\nv2.7.0: Opt-in security model — voice profiling and infra collection now require explicit env vars, both off by default. Git backup rewritten with isolated copy approach (workspace files never modified). Documentation overhauled with threat model, default state table, cron scope details, pre-install checklist.\n\nv2.6.0 | 2026-02-24T17:32:20.902Z | user\n\nNew update.sh script for upgrading existing installs — updates cron job messages, adds missing principles, copies new scripts. Non-destructive, never overwrites user content. Supports --dry-run. Agents now know how to self-update and verify when asked.\n\nv2.5.2 | 2026-02-24T17:22:01.715Z | user\n\nAdd verify.sh for post-install health checks (read-only). Agent self-verification — users can ask their bot \"is OpenCortex working?\" Install instructions corrected to run from workspace root.\n\nv2.5.1 | 2026-02-24T17:10:53.508Z | user\n\nFix install instructions — must run from workspace root, not from inside skill folder. Files were being created in wrong location.\n\nv2.5.0 | 2026-02-24T17:01:14.993Z | user\n\nMajor security tightening — git-backup commits locally only (push requires explicit --push flag), vault blocks file-based passphrase by default (requires system keyring), scrub limited to known text extensions by default. All three scanner concerns directly addressed.\n\nv2.4.5 | 2026-02-24T16:53:07.147Z | user\n\nRemove npm install commands from docs, added note that installer makes no network calls.\n\nv2.4.4 | 2026-02-24T16:46:30.081Z | user\n\nComprehensive install prerequisites (npm, openclaw, clawhub CLI), visible GitHub link on skill page, plain language throughout, cron time fix.\n\nv2.4.3 | 2026-02-24T07:38:39.958Z | user\n\nFix cron time mismatch (installer now matches documented 3AM/5AM schedules), add P8 to SKILL.md principles table, clarify install prerequisites and workspace context, remove duplicate vault functions, replace jargon with plain language throughout.\n\nv2.4.2 | 2026-02-24T07:24:44.596Z | user\n\nRemove duplicate function definitions in vault.sh flagged by scanner as code quality issue.\n\nv2.4.1 | 2026-02-24T07:17:31.153Z | user\n\nFix install instructions — was openclaw skill install (broken command), now clawhub install opencortex + bash scripts/install.sh. Added clear note that install.sh must be run after clawhub install.\n\nv2.4.0 | 2026-02-24T06:30:43.231Z | user\n\nNew principle P8: Check the Shed First — agents must consult TOOLS.md, INFRA.md, and memory before deferring work to the user or claiming they can't do something. Nightly audit catches unnecessary deferrals. Full documentation updated.\n\nv2.3.4 | 2026-02-24T05:36:09.027Z | user\n\nFix display name\n\nv2.3.3 | 2026-02-24T05:33:04.651Z | user\n\nGPG passphrase now passed via file descriptor (fd3) instead of command line argv — no longer visible in process lists. Registry metadata moved to proper single-line JSON format per AgentSkills spec, declaring all env vars, sensitive files, required bins, and network access.\n\nv2.3.2 | 2026-02-24T05:29:14.069Z | user\n\nDeclare all env vars, sensitive local files, required/optional binaries, and network access in SKILL.md registry metadata. Addresses scanner concern about undeclared credentials and backends.\n\nv2.3.1 | 2026-02-24T05:27:02.795Z | user\n\nSelf-improving memory architecture for OpenClaw agents. Structured memory, nightly knowledge distillation, weekly synthesis, encrypted vault with system keyring support, closed-loop principle enforcement, voice profiling, and git backup with secret scrubbing.\n\nv2.3.0 | 2026-02-24T05:05:10.172Z | user\n\nVault passphrase now stored in system keyring (secret-tool, macOS Keychain, keyctl) when available. File-based storage is fallback only. New commands: vault.sh migrate, vault.sh backend.\n\nv2.2.3 | 2026-02-24T04:26:15.655Z | user\n\nAddress instruction scope concern: document that workspace isolation is enforced by OpenClaw platform (isolated sessions), not by individual skills. All cron instructions use workspace-relative paths only, no external filesystem or network access.\n\nv2.2.2 | 2026-02-24T04:21:12.683Z | user\n\nSecurity hardening: git-backup now aborts if .vault/ or .secrets-map not in .gitignore, scrub/restore operates on ALL tracked text files (not just specific extensions), installer always ensures sensitive paths are gitignored regardless of feature selection\n\nv2.2.1 | 2026-02-24T04:18:14.665Z | user\n\nClosed-loop principle enforcement: nightly audits for tool documentation, decision capture, sub-agent debriefs, and failure root cause. Weekly runbook auto-detection and principle health checks. Clarified agent-driven cron execution model in documentation.\n\nv2.2.0 | 2026-02-24T04:11:17.246Z | user\n\ntest\n\nv2.1.0 | 2026-02-23T04:17:10.012Z | user\n\nVault passphrase rotation + key validation, pre-push scrub verification, cron lockfile safety, runbook auto-detection, dry-run mode\n\nv2.0.2 | 2026-02-23T03:04:05.132Z | user\n\nAdd P4 enforcement line + Tool Shed Audit to distillation cron; fix display name to OpenCortex\n\nv2.0.1 | 2026-02-23T02:47:07.954Z | user\n\nFix audit findings: declare required/optional binaries, fix vault passphrase-on-disk claim, add pre-flight dependency checks in installer\n\nv2.0.0 | 2026-02-23T02:33:10.664Z | user\n\nAdded AES-256 encrypted vault for sensitive data. Secure mode default.\n\nv1.6.1 | 2026-02-23T01:57:03.971Z | user\n\nBundled inspectable git scripts, manual-only self-update.\n\nv1.6.0 | 2026-02-23T01:31:05.940Z | user\n\nRemoved supply chain risk: self-update manual-only, git scripts generated at install not bundled, zero network ops.\n\nv1.5.1 | 2026-02-22T23:05:14.442Z | user\n\nComprehensive security documentation addressing every scanner category.\n\nv1.5.0 | 2026-02-22T22:30:17.382Z | user\n\nGit scripts now bundled as inspectable files (not generated at runtime). All credential references removed from cron instructions and metadata. No /root default paths.\n\nv1.4.0 | 2026-02-22T22:24:12.559Z | user\n\nSecurity hardening: voice profiling and self-update now opt-in during install, workspace defaults to cwd not /root, removed credential references from distillation routing, added homepage for provenance.\n\nv1.3.0 | 2026-02-22T18:33:01.851Z | user\n\nAdded P7: Log Failures\n\nv1.2.1 | 2026-02-22T18:23:08.035Z | user\n\nFix display name to OpenCortex.\n\nv1.2.0 | 2026-02-22T18:19:10.833Z | user\n\nComprehensive security transparency section, self-update runs first, voice profiling documented as optional/removable, no API key requirements.\n\nv1.0.0 | 2026-02-22T18:07:06.018Z | user\n\nSelf-improving memory architecture with voice profiling for OpenClaw agents.\n\nArchive index:\n\nArchive v3.5.18: 12 files, 60983 bytes\n\nFiles: README.md (21251b), references/architecture.md (6173b), references/distillation.md (6064b), references/weekly-synthesis.md (5425b), scripts/git-backup.sh (4591b), scripts/install.sh (39165b), scripts/metrics.sh (14441b), scripts/update.sh (67014b), scripts/vault.sh (10359b), scripts/verify.sh (6524b), SKILL.md (10486b), _meta.json (130b)\n\nFile v3.5.18:SKILL.md\n\n---\nname: OpenCortex\nhomepage: https://github.com/JD2005L/opencortex\ndescription: >\n  Self-improving memory architecture for OpenClaw agents. Structured memory files,\n  nightly distillation, weekly synthesis, enforced principles (P0 for custom, P1-P8 managed),\n  write-ahead durability, and model-agnostic delegation — so your agent\n  compounds knowledge instead of forgetting it. Includes opt-in metrics tracking with\n  growth charts and compound scoring to measure effectiveness over time. All sensitive features (voice profiling,\n  infrastructure auto-collection, git push) are OFF by default and require explicit\n  opt-in via environment variable or flag. Safe to install: no network calls during\n  setup, fully auditable bash scripts, isolated cron sessions scoped to workspace only.\n  Use when: (1) setting up a new OpenClaw instance, (2) user asks to improve/organize\n  memory, (3) user wants the agent to stop forgetting things, (4) bootstrapping a fresh\n  agent with best practices. NOT for: runtime memory_search queries (use built-in memory\n  tools). Triggers: \"set up memory\", \"organize yourself\", \"stop forgetting\", \"memory\n  architecture\", \"self-improving\", \"cortex\", \"bootstrap memory\", \"memory optimization\".\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"grep\",\"sed\",\"find\"],\"optionalBins\":[\"git\",\"gpg\",\"openssl\",\"openclaw\",\"secret-tool\",\"keyctl\",\"file\"]},\"env\":{\"CLAWD_WORKSPACE\":{\"description\":\"Workspace directory (defaults to cwd)\",\"required\":false},\"CLAWD_TZ\":{\"description\":\"Timezone for cron scheduling (defaults to UTC)\",\"required\":false},\"OPENCORTEX_VAULT_PASS\":{\"description\":\"Vault passphrase via env var. Prefer system keyring.\",\"required\":false,\"sensitive\":true},\"OPENCORTEX_VOICE_PROFILE\":{\"description\":\"Set to 1 to enable voice profiling in the nightly distillation cron. Off by default.\",\"required\":false,\"sensitive\":false},\"OPENCORTEX_INFRA_COLLECT\":{\"description\":\"Set to 1 to enable infrastructure auto-collection in the nightly distillation cron. Off by default.\",\"required\":false,\"sensitive\":false},\"OPENCORTEX_SCRUB_ALL\":{\"description\":\"Set to 1 to scrub all tracked files (not just known text types) during git backup. Off by default.\",\"required\":false,\"sensitive\":false},\"OPENCORTEX_ALLOW_FILE_PASSPHRASE\":{\"description\":\"Set to 1 to allow vault passphrase stored in a file (.vault/.passphrase). Off by default; prefer system keyring.\",\"required\":false,\"sensitive\":false}},\"sensitiveFiles\":[\".secrets-map\",\".vault/.passphrase\"],\"networkAccess\":\"Optional git push only (off by default, requires --push flag)\"}}\n---\n\n# OpenCortex — Self-Improving Memory Architecture\n\nTransform a default OpenClaw agent into one that compounds knowledge daily.\n\n📦 [Full source on GitHub](https://github.com/JD2005L/opencortex) — review the code, file issues, or contribute.\n\n## What This Does\n\n1. **Structures memory** into purpose-specific files instead of one flat dump\n2. **Installs nightly maintenance** that distills daily work into permanent knowledge\n3. **Installs weekly synthesis** that catches patterns across days\n4. **Establishes principles** that enforce good memory habits — and backs them up with nightly audits that verify tool documentation, decision capture, sub-agent debriefs, failure analysis, and unnecessary deferrals to the user. Nothing slips through the cracks.\n6. **Builds a voice profile** of your human from daily conversations for authentic ghostwriting (opt-in, requires `OPENCORTEX_VOICE_PROFILE=1`)\n7. **Encrypts sensitive data** in an AES-256 vault with key-only references in docs; supports passphrase rotation (`vault.sh rotate`) and validates key names on `vault.sh set`\n8. **Enables safe git backup** with secret scrubbing (secrets never modified in your live workspace — scrubbed in an isolated copy only)\n9. **Tracks growth over time** *(opt-in)* — daily metrics snapshots with compound scoring and ASCII growth charts\n\n## Installation\n\n**Prerequisites** (install these separately if you don't have them):\n- [OpenClaw](https://github.com/openclaw/openclaw) 2026.2.x+\n- [ClawHub CLI](https://clawhub.com)\n\n```bash\n# 1. Download the skill from your OpenClaw workspace directory\ncd ~/clawd    # or wherever your workspace is\nclawhub install opencortex\n\n# 2. Run the installer FROM YOUR WORKSPACE DIRECTORY (not from inside the skill folder)\nbash skills/opencortex/scripts/install.sh\n\n# Optional: preview what would be created without changing anything\nbash skills/opencortex/scripts/install.sh --dry-run\n```\n\nThe installer will ask about optional features (encrypted vault, voice profiling, infrastructure collection, git backup). It's safe to re-run — it skips anything that already exists. The installer itself makes no network calls — it only creates local files and registers cron jobs.\n\n```bash\n# 3. Verify everything is working (read-only — checks files and cron jobs, changes nothing)\nbash skills/opencortex/scripts/verify.sh\n```\n\nYou can also ask your OpenClaw agent \"is OpenCortex working?\" — it knows how to run the verification and share results.\n\nThe script will:\n- Create the file hierarchy (non-destructively — won't overwrite existing files)\n- Create directory structure\n- Set up cron jobs (daily distillation, weekly synthesis)\n- Optionally set up git backup with secret scrubbing\n\nAfter install, review and customize:\n- `SOUL.md` — personality and identity (make it yours)\n- `USER.md` — info about your human\n- `MEMORY.md` — principles (add/remove as needed)\n- `.secrets-map` — add your actual secrets for git scrubbing\n\n## Updating\n\n```bash\n# 1. Download the latest version (run from workspace root)\nclawhub install opencortex --force\n\n# 2. Re-run the installer — it detects your existing install and offers to update\nbash skills/opencortex/scripts/install.sh\n```\n\nThe installer detects your existing version and offers three options: Update (recommended), Full reinstall, or Cancel. The update path is non-destructive — it adds missing content, refreshes cron messages, and offers any new optional features without overwriting your customized files.\n\n## Architecture\n\n```\nSOUL.md          ← Identity, personality, boundaries\nAGENTS.md        ← Operating protocol, delegation rules\nMEMORY.md        ← Principles + memory index (< 3KB, loaded every session)\nTOOLS.md         ← Tool shed: APIs, scripts, and access methods with abilities descriptions\nINFRA.md         ← Infrastructure atlas: hosts, IPs, services, network\nUSER.md          ← Human's preferences, projects, communication style\nBOOTSTRAP.md     ← First-run checklist for new sessions\n\nmemory/\n  projects/      ← One file per project (distilled, not raw)\n  contacts/      ← One file per person/org (role, context, preferences)\n  workflows/     ← One file per workflow/pipeline (services, steps, issues)\n  runbooks/      ← Step-by-step procedures (delegatable to sub-agents)\n  preferences.md ← Cross-cutting user preferences by category\n  archive/       ← Archived daily logs + weekly summaries\n  YYYY-MM-DD.md  ← Today's working log (distilled nightly)\n```\n\n## Principles (installed by default)\n\n| # | Name | Purpose |\n|---|------|---------|\n| P1 | Delegate First | Assess tasks for sub-agent delegation; stay available |\n| P2 | Write It Down | Commit to files, not mental notes |\n| P3 | Ask Before External | Confirm before emails, public posts, destructive ops |\n| P4 | Tool Shed & Workflows | Document tools and workflows; enforced by nightly audit |\n| P5 | Capture Decisions & Preferences | Record decisions and preferences; enforced by nightly + weekly audit |\n| P6 | Sub-agent Debrief | Delegated work feeds back to daily log; orphans recovered by distillation |\n| P7 | Log Failures | Tag failures/corrections; root cause analysis enforced by nightly audit |\n| P8 | Check the Shed First | Consult TOOLS.md/INFRA.md/memory before deferring work to user; enforced by nightly audit |\n\n## Cron Jobs (installed)\n\n| Schedule | Name | What it does |\n|----------|------|-------------|\n| Daily 3 AM (local) | Distillation | Reads daily logs → distills into project/tools/infra files → audits tools/decisions/debriefs/failures → optimizes → archives |\n| Weekly Sunday 5 AM | Synthesis | Reviews week for patterns, recurring problems, unfinished threads, decisions; auto-creates runbooks from repeated procedures |\n\nBoth jobs use a shared lockfile (`/tmp/opencortex-distill.lock`) to prevent conflicts when daily and weekly runs overlap.\n\nCustomize times by editing cron jobs: `openclaw cron list` then `openclaw cron edit <id> --cron \"...\"`.\n\n## Git Backup (optional)\n\nIf enabled during install, creates:\n- `scripts/git-backup.sh` — auto-commit every 6 hours, scrubs secrets in an isolated temp copy (workspace files never modified)\n- `.secrets-map` — maps secrets to placeholders (gitignored, 600 perms)\n\nAdd secrets to `.secrets-map` in format: `actual_secret|{{PLACEHOLDER_NAME}}`\n\nBefore each push, `git-backup.sh` verifies no raw secrets remain in the scrubbed copy. If any are found, the backup is aborted — nothing reaches the remote.\n\n## Customization\n\n**Adding a project:** Create `memory/projects/my-project.md`, add to MEMORY.md index.\n\n**Adding a contact:** Create `memory/contacts/name.md`. Distillation auto-creates contacts from conversations.\n\n**Adding a workflow:** Create `memory/workflows/my-pipeline.md`. Distillation auto-creates workflows when described.\n\n**Adding a preference:** Append to `memory/preferences.md` under the right category. Distillation auto-captures from conversation.\n\n**Adding a principle:** Append to MEMORY.md under 🔴 PRINCIPLES. Keep it short.\n\n**Adding a runbook:** Create `memory/runbooks/my-procedure.md`. Sub-agents can follow these directly.\n\n**Adding a tool:** Add to TOOLS.md with: what it is, how to access it, and a goal-oriented abilities description (so future intent-based lookup matches).\n\n## How It Compounds\n\n```\nDaily work → daily log\n  → nightly distill → routes to project/tools/infra/principles files\n                     → optimization pass (dedup, prune stale, condense)\n  → weekly synthesis → patterns, recurring problems, unfinished threads → auto-creates runbooks from repeated procedures → `memory/runbooks/`\nSub-agent work → debrief (P6) → daily log → same pipeline\nDecisions → captured with reasoning (P5) → never re-asked\nNew tools → documented with abilities (P4) → findable by intent\n```\n\nEach day the agent wakes up slightly more knowledgeable and better organized.\n\nFile v3.5.18:README.md\n\n# 🧠 OpenCortex\n\n**Self-improving memory architecture for [OpenClaw](https://github.com/openclaw/openclaw) agents.**\n\nStop forgetting. Start compounding.\n\n---\n\n## The Problem\n\nOut of the box, OpenClaw agents dump everything into a flat `MEMORY.md`. Context fills up, compaction loses information, and the agent forgets what it learned last week. It's like having a brilliant employee with amnesia who takes notes on napkins.\n\n## The Solution\n\nOpenCortex transforms your agent into one that **gets smarter every day** through:\n\n- **Structured memory** — Purpose-specific files instead of one flat dump\n- **Nightly distillation** — Daily work automatically distilled into permanent knowledge\n- **Weekly synthesis** — Pattern detection across days catches recurring problems and unfinished threads\n- **Enforced principles** — Habits that prevent knowledge loss (decision capture, tool documentation, sub-agent debriefs)\n- **Write-ahead durability** — Agent writes decisions and preferences to memory before responding, so nothing is lost if the session ends or compacts mid-conversation\n- **Encrypted vault** — AES-256 encrypted secret storage with system keyring support\n- **Voice profiling** *(opt-in)* — Learns how your human communicates for authentic ghostwriting\n- **Infrastructure collection** *(opt-in)* — Auto-routes infrastructure details from daily logs to INFRA.md\n- **Safe git backup** *(opt-in)* — Automatic secret scrubbing in an isolated copy — workspace files are never modified\n\n## Quick Start\n\n**Prerequisites:** [OpenClaw](https://github.com/openclaw/openclaw) 2026.2.x+ and [ClawHub CLI](https://clawhub.com)\n\n```bash\n# From your OpenClaw workspace directory (e.g. ~/clawd)\nclawhub install opencortex\nbash skills/opencortex/scripts/install.sh\n\n# Preview without changing anything:\nbash skills/opencortex/scripts/install.sh --dry-run\n\n# Verify everything is working (read-only):\nbash skills/opencortex/scripts/verify.sh\n```\n\n**Important:** Run the installer from your workspace root, NOT from inside the skill folder.\n\nThe installer asks about optional features, creates files (won't overwrite existing ones), and registers cron jobs. It makes zero network calls.\n\nAfter install, customize:\n1. `SOUL.md` — personality and identity\n2. `USER.md` — info about your human\n3. `MEMORY.md` — principles and project index\n4. `TOOLS.md` — tools and APIs as you discover them\n5. `INFRA.md` — infrastructure reference\n6. `.secrets-map` — secrets for git scrubbing (if using git backup)\n\n### From Source\n\n```bash\ngit clone https://github.com/JD2005L/opencortex.git\ncd opencortex && bash scripts/install.sh\n```\n\n## Updating\n\n```bash\nclawhub install opencortex --force         # Download latest\nbash skills/opencortex/scripts/install.sh  # Detects existing install, offers Update\n```\n\nThe installer detects your existing version and offers: **1) Update** (recommended), **2) Full reinstall**, **3) Cancel.** It never overwrites files you've customized.\n\n### What the updater does\n\n| Content | Update method | User data safe? |\n|---------|--------------|-----------------|\n| Principles (P1-P8) | Hash comparison, asks before replacing | ✅ Asks y/N per principle |\n| P0 (Custom Principles) | Never touched | ✅ Your custom principles are always safe |\n| Helper scripts (verify, vault, metrics, git-backup) | Checksum comparison, auto-replaced | ✅ These aren't user-edited |\n| Reference docs (distillation, weekly-synthesis, architecture) | Checksum comparison, auto-replaced | ✅ These aren't user-edited |\n| Cron job messages | Always updated to latest template | ✅ Only the message text changes |\n| Cron model overrides | Cleared on every update | ✅ Gateway uses its configured default |\n| Cron deduplication | Detects and removes duplicate crons from prior bugs | ✅ Keeps the first, deletes extras |\n| Extra principles (P9+) | Detects duplicates and orphans, offers remove/migrate to P0 | ✅ Asks per principle |\n| MEMORY.md bloat | Warns if >5KB, flags non-standard sections | ✅ Suggests what to move |\n| Missing cron jobs | Offers to recreate with timezone auto-detection | ✅ Asks before creating |\n| MEMORY.md structure (## Identity, ## Memory Index) | Adds missing core sections | ✅ Existing sections untouched |\n| MEMORY.md index (### Infrastructure through ### Daily Logs) | Adds all 8 missing sub-sections | ✅ Existing sections untouched |\n| preferences.md | Created if missing | ✅ Existing file untouched |\n| New directories (contacts, workflows) | Created if missing | ✅ |\n| AGENTS.md | Merges: regenerates standard sections, preserves custom sections | ✅ Custom sections appended |\n| BOOTSTRAP.md | Merges: regenerates standard sections, preserves custom sections | ✅ Custom sections appended |\n| SOUL.md | Created if missing | ✅ Existing file untouched |\n| USER.md | Created if missing | ✅ Existing file untouched |\n| .gitignore | Adds missing sensitive entries (.vault/, .secrets-map, etc.) | ✅ Existing entries untouched |\n\n---\n\n## Architecture\n\n```\nSOUL.md          ← Identity & personality\nAGENTS.md        ← Operating protocol & delegation rules\nMEMORY.md        ← Principles + index (< 3KB, loaded every session)\nTOOLS.md         ← Tool shed: APIs, scripts with abilities descriptions\nINFRA.md         ← Infrastructure atlas: hosts, IPs, services\nUSER.md          ← Your human's preferences\nBOOTSTRAP.md     ← Session startup checklist\n\nmemory/\n  projects/      ← One file per project (distilled, not raw)\n  contacts/      ← One file per person/org (role, context, preferences)\n  workflows/     ← One file per workflow/pipeline (services, steps, issues)\n  runbooks/      ← Step-by-step procedures (delegatable to sub-agents)\n  preferences.md ← Cross-cutting user preferences by category\n  archive/       ← Archived daily logs + weekly summaries\n  YYYY-MM-DD.md  ← Today's working log (distilled nightly)\n```\n\n## Principles (P0–P8)\n\n| # | Principle | What It Does | Enforcement |\n|---|-----------|-------------|-------------|\n| P0 | Custom Principles | Your own principles (P0-A, P0-B, etc.) | Never modified by updates |\n| P1 | Delegate First | Model-agnostic sub-agent delegation (Light/Medium/Heavy) | Agent protocol |\n| P2 | Write It Down | Write-ahead durability: save before responding | Agent protocol |\n| P3 | Ask Before External | Confirm before public/destructive actions | Agent protocol |\n| P4 | Tool Shed & Workflows | Document tools and workflows | Nightly audit scans for undocumented tools and workflows |\n| P5 | Capture Decisions & Preferences | Record decisions and preferences | Nightly + weekly audit for uncaptured decisions and preferences |\n| P6 | Sub-agent Debrief | Delegated work feeds back to daily log | Nightly audit recovers orphaned debriefs |\n| P7 | Log Failures | Tag failures with root cause analysis | Nightly audit checks for missing root causes |\n| P8 | Check the Shed First | Use documented tools before deferring to user | Nightly audit flags unnecessary deferrals |\n\n## How It Compounds\n\n```\nWeek 1:  Agent knows basics, asks lots of questions\nWeek 4:  Agent has project history, knows tools, follows decisions\nWeek 12: Agent has deep institutional knowledge, patterns, runbooks\nWeek 52: Agent knows more about your setup than you remember\n```\n\n---\n\n## Security Model\n\n### Threat Model Summary\n\nOpenCortex is a **workspace-scoped memory skill**. It creates files, registers cron jobs that run as isolated OpenClaw agent sessions, and optionally manages an encrypted vault. The primary risk surface is:\n\n1. **Autonomous cron jobs** that read/write workspace files without human interaction\n2. **Optional features** that collect sensitive data (voice patterns, infrastructure details)\n3. **Optional git backup** that handles secret scrubbing before commits\n\nOpenCortex contains **zero network operations** — no telemetry, no phone-home, no external endpoints. Every script is plain bash. [Full source is public.](https://github.com/JD2005L/opencortex)\n\n### Default State: What's On and Off\n\n| Feature | Default | Opt-In Required | What It Accesses | How to Disable |\n|---------|---------|----------------|-----------------|----------------|\n| Structured memory files | ✅ ON | — | Creates markdown files in workspace | Delete unwanted files |\n| Daily distillation cron | ✅ ON | — | Reads/writes `memory/`, `MEMORY.md`, `TOOLS.md`, `USER.md` | `openclaw cron delete <id>` |\n| Weekly synthesis cron | ✅ ON | — | Reads `memory/archive/`, writes summaries + runbooks | `openclaw cron delete <id>` |\n| Principle enforcement audits | ✅ ON | — | Part of distillation — audits within workspace | Remove audit sections from cron message |\n| Encrypted vault | Asked at install | Choose \"direct\" mode to skip | `.vault/` directory, system keyring | Don't init vault; delete `.vault/` |\n| Voice profiling | ❌ OFF | `OPENCORTEX_VOICE_PROFILE=1` | Reads workspace conversation logs → `memory/VOICE.md` | Unset env var; delete `memory/VOICE.md` |\n| Infrastructure collection | ❌ OFF | `OPENCORTEX_INFRA_COLLECT=1` | Routes infra mentions from daily logs → `INFRA.md` | Unset env var |\n| Git backup | ❌ OFF | Say \"yes\" at install | Commits workspace to git (local only by default) | Remove from crontab; delete scripts |\n| Git push to remote | ❌ OFF | `--push` flag on each run | Pushes scrubbed commits to remote | Don't pass `--push` |\n| Daily metrics tracking | ❌ OFF | Say \"yes\" at install | Read-only file counts → `memory/metrics.log` | Remove from crontab; delete `metrics.log` |\n| Broad file scrubbing | ❌ OFF | `OPENCORTEX_SCRUB_ALL=1` | Scrubs all tracked files (not just known text types) | Unset env var |\n| File-based vault passphrase | ❌ OFF | `OPENCORTEX_ALLOW_FILE_PASSPHRASE=1` | Stores passphrase at `.vault/.passphrase` | Unset env var; use system keyring |\n\n### What Runs Autonomously\n\nTwo cron jobs, both running as **isolated OpenClaw agent sessions** scoped to the workspace:\n\n| Job | Schedule | Reads | Writes | Network Access |\n|-----|----------|-------|--------|----------------|\n| Daily Distillation | Daily 3 AM (local) | `memory/*.md`, workspace `*.md` | `memory/projects/`, `memory/contacts/`, `memory/workflows/`, `memory/preferences.md`, `MEMORY.md`, `TOOLS.md`, `USER.md`, daily log audit outputs | **None** |\n| Weekly Synthesis | Sunday 5 AM (local) | `memory/archive/*.md`, `memory/projects/*.md`, `memory/contacts/*.md`, `memory/workflows/*.md`, `memory/preferences.md` | `memory/archive/weekly-*.md`, project/contact/workflow/preference files, `memory/runbooks/` | **None** |\n\nBoth jobs:\n- Use a shared lockfile (`/tmp/opencortex-distill.lock`) to prevent conflicts\n- Contain **no** `rm`, system modifications, network calls, or external API access\n- Reference **only** workspace-relative paths (`memory/`, `MEMORY.md`, `TOOLS.md`, etc.)\n- Are fully inspectable: `openclaw cron list`\n- Are fully removable: `openclaw cron delete <id>`\n\n**How cron jobs work:** OpenCortex does not bundle standalone distillation scripts. Instead, the installer registers OpenClaw cron jobs (`openclaw cron add`) with detailed task instructions. At runtime, OpenClaw spawns an isolated agent session that follows those instructions to read, synthesize, and write workspace files. The LLM agent is the executor — it's far better at knowledge synthesis than any bash script could be. The cron job messages *are* the implementation, fully viewable and editable via `openclaw cron list` / `openclaw cron edit`.\n\n**On workspace isolation:** The cron instructions themselves don't enforce sandboxing — that's the **OpenClaw platform's** responsibility. OpenClaw cron jobs run in isolated sessions scoped to the workspace directory by the runtime, the same way a Dockerfile doesn't implement kernel isolation — the container runtime does. OpenCortex's cron instructions contain no references to external filesystems, network calls, or system commands beyond `openclaw cron list` and `crontab -l` (for self-auditing cron health).\n\n### Git Backup Security\n\nGit backup (when enabled) uses an **isolated copy approach** — your workspace files are never modified during scrubbing:\n\n1. All files to commit are copied to a temp directory\n2. Secrets are scrubbed in the copy only (using `.secrets-map` replacements)\n3. The scrubbed copy is verified — if any raw secrets remain, the backup aborts immediately\n4. A git commit is built from the scrubbed copy using git plumbing (`hash-object`, `update-index`, `write-tree`, `commit-tree`)\n5. The temp directory is cleaned up\n6. Your original workspace files are **untouched throughout the entire process**\n\nAdditional safeguards:\n- `.secrets-map` and `.vault/` are always gitignored (enforced at install)\n- Pre-backup check aborts if either exists but isn't gitignored\n- Push requires explicit `--push` flag — local-only by default\n- `.secrets-map` has 600 permissions (owner-only read/write)\n\n**Recommendation:** Test in a disposable repo first. Run the backup, inspect the commit diff, and confirm scrubbing works before pointing at a real remote.\n\n### Vault Security\n\nThe encrypted vault stores secrets at rest via GPG symmetric encryption (AES-256). Passphrase storage uses the **best available backend** (auto-detected):\n\n| Priority | Backend | Passphrase Location | On Disk? |\n|----------|---------|-------------------|----------|\n| 1 | secret-tool (Linux keyring) | GNOME/KDE keyring | No |\n| 2 | macOS Keychain | Native macOS keystore | No |\n| 3 | keyctl (Linux kernel keyring) | Kernel memory | No |\n| 4 | Environment variable | `OPENCORTEX_VAULT_PASS` | No |\n| 5 | File fallback | `.vault/.passphrase` (mode 600) | Yes — requires `OPENCORTEX_ALLOW_FILE_PASSPHRASE=1` |\n\nCommands: `vault.sh init`, `vault.sh set <key> <value>`, `vault.sh get <key>`, `vault.sh rotate`, `vault.sh migrate`, `vault.sh backend`\n\nKey names are validated on set (alphanumeric + underscores only).\n\n### Install Mechanism\n\nThe installer (`scripts/install.sh`) is a single bash script that:\n- Creates markdown files (only if they don't already exist)\n- Creates directories (`memory/projects/`, `memory/contacts/`, `memory/workflows/`, `memory/runbooks/`, `memory/archive/`)\n- Registers OpenClaw cron jobs via `openclaw cron add`\n- Optionally copies bundled `git-backup.sh` and `vault.sh` scripts to the workspace\n\n**No external downloads.** No package installs. No network calls. No binaries. All code is plain bash + markdown, bundled in the skill package and fully auditable.\n\n### Credentials\n\nOpenCortex declares **no required API keys or environment variables**. The cron jobs use your gateway's default model — OpenCortex never sees or handles model provider keys. Any model capable of reading and writing markdown files will work.\n\nOptional environment variables (all off by default):\n\n| Variable | Purpose | Sensitive |\n|----------|---------|-----------|\n| `CLAWD_WORKSPACE` | Override workspace directory (defaults to cwd) | No |\n| `CLAWD_TZ` | Timezone for cron scheduling (defaults to UTC) | No |\n| `OPENCORTEX_VAULT_PASS` | Vault passphrase via env var (prefer keyring) | Yes |\n| `OPENCORTEX_VOICE_PROFILE` | Enable voice profiling in distillation | No |\n| `OPENCORTEX_INFRA_COLLECT` | Enable infrastructure auto-collection | No |\n| `OPENCORTEX_SCRUB_ALL` | Scrub all tracked files during git backup | No |\n| `OPENCORTEX_ALLOW_FILE_PASSPHRASE` | Allow file-based vault passphrase | No |\n\n---\n\n## What to Review Before Installing\n\n1. **Read the scripts.** They're bundled plain bash — `install.sh`, `update.sh`, `vault.sh`, `git-backup.sh`, `verify.sh`, `metrics.sh`. You can read every line before running anything. Required binaries: `grep`, `sed`, `find`. Optional: `git`, `gpg`, `openssl`, `openclaw`, `secret-tool`, `keyctl`, `file` (for binary detection during scrubbing).\n2. **Confirm workspace isolation.** OpenCortex delegates sandbox enforcement to the OpenClaw platform. Verify your OpenClaw instance enforces workspace-only behavior for cron sessions. If isolation is misconfigured, a cron session could theoretically access files outside the workspace.\n3. **Inspect cron messages after install.** Run `openclaw cron list` to see the exact instructions registered. These are the actual implementation — edit or remove them freely.\n4. **Prefer system keyring for vault.** Use `secret-tool`, macOS Keychain, or `keyctl` over file-based passphrase storage. Set `OPENCORTEX_ALLOW_FILE_PASSPHRASE=1` only if no keyring is available and you accept the risk.\n5. **Test git backup in a disposable repo.** Verify `.secrets-map` entries scrub correctly before using on a real remote.\n6. **Opt-in features are off by default.** Voice profiling, infrastructure collection, broad scrubbing, and git push all require explicit activation. Only enable what you need.\n7. **Consider disabling voice profiling** if you're uncomfortable with the agent building a persistent behavioral profile from conversations.\n\n---\n\n## Metrics & Growth Tracking\n\nIf enabled during install, OpenCortex tracks your agent's knowledge growth over time. A daily system cron (11:30 PM local) snapshots file counts, decision captures, tool documentation, and more into `memory/metrics.log`. No sensitive data is collected — only counts and pattern matches.\n\n### What's Tracked\n\n| Metric | What It Measures |\n|--------|-----------------|\n| Knowledge files | Total files in `memory/projects/`, `memory/contacts/`, `memory/workflows/`, `memory/runbooks/`, and `memory/` |\n| Knowledge size (KB) | Total size of knowledge files |\n| Decisions captured | `**Decision:**` entries across all memory files |\n| Preferences captured | `**Preference:**` entries in `memory/preferences.md` |\n| Contacts | People/orgs documented in `memory/contacts/` |\n| Workflows | Pipelines/automations in `memory/workflows/` |\n| Runbooks | Reusable procedures in `memory/runbooks/` |\n| Tools documented | Entries in `TOOLS.md` |\n| Failures logged | `❌ FAILURE:` and `🔧 CORRECTION:` entries |\n| Debriefs | Sub-agent debrief entries in daily logs |\n| Projects | Files in `memory/projects/` |\n| Archive files | Distilled daily logs in `memory/archive/` |\n\n### Commands\n\n```bash\n# Snapshot today's metrics\nbash scripts/metrics.sh --collect\n\n# Show trends with ASCII growth charts + compound score\nbash scripts/metrics.sh --report\n\n# Last 4 weeks only\nbash scripts/metrics.sh --report --weeks 4\n\n# JSON output (for integrations)\nbash scripts/metrics.sh --json\n```\n\nOr just ask your agent: *\"How is OpenCortex doing?\"* or *\"Show me OpenCortex metrics.\"*\n\n### Compound Score\n\nThe report includes a 0–100 compound score reflecting knowledge depth, growth rate, and tracking consistency:\n\n| Score | Rating |\n|-------|--------|\n| 80–100 | Thriving — deep knowledge, steady growth |\n| 60–79 | Growing — good foundation, building momentum |\n| 40–59 | Developing — basics in place, room to grow |\n| 20–39 | Getting started — early days |\n| 0–19 | Just installed — give it time |\n\nA healthy OpenCortex installation trends upward over weeks. Flat or declining scores highlight specific areas to focus on.\n\n### Weekly Summary\n\nIf metrics tracking is enabled, the weekly synthesis cron automatically includes a metrics report in its output — showing 4-week trends and flagging areas that need attention.\n\n### Security\n\nThe metrics script (`scripts/metrics.sh`) is **read-only** — it only counts files and greps for patterns. It writes only to `memory/metrics.log` (append-only in `--collect` mode). No network access, no sensitive data captured (counts, never content), no system modifications.\n\n---\n\n## Customization\n\n**Add a project:** Create `memory/projects/my-project.md`, add to MEMORY.md index. Nightly distillation routes relevant daily log entries to it.\n\n**Add a contact:** Create `memory/contacts/name.md` with: name, role/relationship, context, communication preferences. Distillation auto-creates contacts mentioned in conversation.\n\n**Add a workflow:** Create `memory/workflows/my-pipeline.md` with: what it does, services involved, how to operate it. Distillation auto-creates workflows when described.\n\n**Add a preference:** Append to `memory/preferences.md` under the right category. Format: `**Preference:** [what] — [context] (date)`. Distillation auto-captures preferences stated in conversation.\n\n**Add a principle:** Append to MEMORY.md under 🔴 PRINCIPLES. Keep it short.\n\n**Add a runbook:** Create `memory/runbooks/my-procedure.md` with step-by-step instructions. Sub-agents follow these directly.\n\n**Add a tool:** Add to TOOLS.md with: what it is, how to access it, goal-oriented abilities description.\n\n**Change cron schedule:** `openclaw cron list` then `openclaw cron edit <id> --cron \"...\"`.\n\n**Run fully air-gapped:** Decline all optional features during install. No voice profiling, no infrastructure collection, no git backup. The core memory architecture and distillation work entirely offline.\n\n## Requirements\n\n- [OpenClaw](https://github.com/openclaw/openclaw) 2026.2.x+\n- **Required:** `grep`, `sed`, `find` (standard on most systems)\n- **Optional:** `git` (for backup), `gpg` (for vault), `openssl` (for passphrase generation)\n\n## License\n\nMIT\n\n## Credits\n\nCreated by [JD2005L](https://github.com/JD2005L)\n\nFile v3.5.18:_meta.json\n\n{\n  \"ownerId\": \"kn7e5n3qxtp49kdnhne6vr3wzd81n3sc\",\n  \"slug\": \"opencortex\",\n  \"version\": \"3.5.18\",\n  \"publishedAt\": 1772303157357\n}\n\nFile v3.5.18:references/architecture.md\n\n# OpenCortex Architecture Reference\n\n## Why This Exists\n\nDefault OpenClaw memory is a flat MEMORY.md that grows unbounded. Context fills up, compaction loses information, the agent forgets what it learned. OpenCortex solves this with:\n\n1. **Separation of concerns** — different files for different purposes\n2. **Nightly distillation** — raw daily logs → permanent structured knowledge\n3. **Weekly synthesis** — pattern detection across days\n4. **Principles** — enforced habits that prevent knowledge loss (P0 for custom, P1-P8 managed)\n5. **Sub-agent debrief loop** — delegated work feeds back into memory\n\n## File Purposes\n\n| File | Loaded at boot? | Purpose | Size target |\n|------|-----------------|---------|-------------|\n| MEMORY.md | Yes | Principles + index only | < 3KB |\n| TOOLS.md | Yes | Tool/API catalog with abilities | Grows with tools |\n| INFRA.md | Yes | Infrastructure reference | Grows with infra |\n| SOUL.md | Yes | Identity, personality | < 1KB |\n| AGENTS.md | Yes | Operating protocol | < 1KB |\n| USER.md | Yes | Human's preferences | < 1KB |\n| BOOTSTRAP.md | Yes | Session startup checklist | < 0.5KB |\n| memory/projects/*.md | On demand | Per-project knowledge | Any |\n| memory/contacts/*.md | On demand | Per-person/org knowledge | Any |\n| memory/workflows/*.md | On demand | Per-workflow/pipeline knowledge | Any |\n| memory/preferences.md | On demand | Cross-cutting user preferences by category | Any |\n| memory/runbooks/*.md | On demand | Procedures for sub-agents | Any |\n| memory/YYYY-MM-DD.md | Current day | Working log | Any |\n| memory/archive/*.md | Via search | Historical logs | Any |\n\n## Distillation Routes\n\nThe nightly cron reads daily logs and routes each piece of information:\n\n| Information type | Destination |\n|-----------------|-------------|\n| Project work, features, bugs | memory/projects/{project}.md |\n| New tool descriptions and capabilities | TOOLS.md (sensitive values → vault) |\n| Infrastructure changes | INFRA.md (if OPENCORTEX_INFRA_COLLECT=1) |\n| People and organizations mentioned | memory/contacts/{name}.md |\n| Workflows and pipelines described | memory/workflows/{name}.md |\n| Stated preferences and opinions | memory/preferences.md (categorized) |\n| Decisions and architectural directions | Relevant project file or MEMORY.md |\n| New principles, lessons | MEMORY.md |\n| User info and communication style | USER.md |\n| Scheduled job changes | MEMORY.md jobs table |\n| Repeatable procedures | memory/runbooks/ |\n\n## Preference Categories\n\nPreferences in `memory/preferences.md` are organized by category:\n\n| Category | Examples |\n|----------|---------|\n| Communication | \"No verbose explanations\", \"Direct messages only\" |\n| Code & Technical | \"Detailed commit messages\", \"Prefer TypeScript\" |\n| Workflow & Process | \"Check for messages before pushing\", \"Batch commits\" |\n| Scheduling & Time | \"Don't schedule before 9 AM\", \"Prefer async\" |\n| Tools & Services | \"Use VS Code over Vim\", \"Prefer Brave over Chrome\" |\n| Content & Media | \"720p minimum\", \"No dubbed content\" |\n| Environment & Setup | \"Dark mode everywhere\", \"Dual monitor layout\" |\n\nFormat: `**Preference:** [what] — [context/reasoning] (date)`\n\nPreferences are auto-captured from conversation when the user says \"I prefer\", \"always do\", \"I don't like\", etc. Contradicted preferences are updated (not duplicated).\n\n## Compounding Effect\n\n```\nWeek 1:  Agent knows basics, asks lots of questions\nWeek 4:  Agent has project history, knows tools, follows decisions, remembers preferences\nWeek 12: Agent has deep institutional knowledge, patterns, runbooks, contact history\nWeek 52: Agent knows more about the setup than most humans would remember\n```\n\nThe key insight: **daily distillation + weekly synthesis + decision/preference capture** means the agent gets better at a rate proportional to how much it's used. Unlike raw log accumulation which just fills context, structured knowledge compounds.\n\n## Common Customizations\n\n### Adding delegation tiers\nEdit MEMORY.md P1 to adjust which capability tier (Light/Medium/Heavy) handles what complexity. P1 is model-agnostic and works with whatever models you have configured.\n\n### Changing distillation schedule\n`openclaw cron edit <id> --cron \"0 10 * * *\" --tz \"Your/Timezone\"`\n\n### Adding custom principles\nAll custom principles go in P0 as sub-principles (P0-A, P0-B, P0-C, etc.). P1-P8 are managed by OpenCortex updates and should not be modified directly. The agent is instructed to:\n- Route all new principle requests to P0, even if the user asks for P9 or beyond\n- Check for conflicts with P1-P8 before adding\n- Assess whether the request is truly a principle (persistent behavioral rule) or would be better suited as a preference, decision, runbook, or agent rule\n\n### Write-ahead durability (P2)\nWhen the user states a preference, makes a decision, gives a deadline, or corrects the agent, the agent writes it to the relevant memory file before composing a response. This prevents context loss if the session ends or compacts mid-conversation.\n\n### Memory health monitoring\nThe weekly synthesis includes automated checks that maintain memory quality over time:\n- **Structural integrity audit** — verifies information is in the correct file (preferences in preferences.md, tools in TOOLS.md, etc.) and moves misplaced content.\n- **Memory file reorganization** — merges duplicates, groups related info, restructures growing files while preserving all detail.\n- **Retrieval quality testing** — runs test queries against memory_search and verifies results are relevant. Diagnoses failures (file too large, content misplaced, stale index), fixes what it can, escalates what it can't, and tracks gaps across weeks.\n- **Stale content cleanup** — flags completed projects for archival, syncs MEMORY.md cron table against actual cron jobs.\n\nThe verify.sh script also checks memory search index health, file count, and MEMORY.md boot size.\n\n### Multi-bot setups\nEach bot gets its own OpenCortex install. Share knowledge via:\n- Common git repo (read-only for non-primary bots)\n- SSH-based management (primary bot propagates changes)\n- Shared NFS/SMB mount for common reference docs\n\nFile v3.5.18:references/distillation.md\n\n# Daily Memory Distillation — Instructions\n\nYou are an AI assistant. Daily memory maintenance task.\n\n**IMPORTANT:** Before writing to any file, check for /tmp/opencortex-distill.lock. If it exists and was created less than 10 minutes ago, wait 30 seconds and retry (up to 3 times). Before starting work, create this lockfile. Remove it when done. This prevents daily and weekly jobs from conflicting.\n\n## Part 1: Distillation\n\n1. Check memory/ for daily log files (YYYY-MM-DD.md, not in archive/).\n2. Distill ALL useful information into the right file:\n   - Project work → memory/projects/ (create new files if needed)\n   - New tool descriptions and capabilities → TOOLS.md (names, URLs, what they do)\n   - **IMPORTANT:** Never write passwords, tokens, or secrets into any file. For sensitive values, instruct the user to run: scripts/vault.sh set <key> <value>. Reference in docs as: vault:<key>\n   - Infrastructure changes → INFRA.md (ONLY if OPENCORTEX_INFRA_COLLECT=1 is set in the environment — otherwise skip infrastructure routing entirely)\n   - Contacts mentioned → memory/contacts/ (one file per person/org. Include: name, role/relationship, context, communication preferences, key interactions. Create new file if first mention, update existing if already known.)\n   - Workflows described → memory/workflows/ (one file per workflow/pipeline. Include: what it does, services involved, how to operate it, known issues. Create new file if first description.)\n   - Preferences stated → memory/preferences.md (append under the matching category: Communication, Code & Technical, Workflow & Process, Scheduling & Time, Tools & Services, Content & Media, Environment & Setup. Format: **Preference:** [what] — [context/reasoning] (date). Do NOT duplicate existing preferences — update them if the user changes their mind.)\n   - Decisions → relevant project file or MEMORY.md. Format: **Decision:** [what] — [why] (date)\n   - Principles, lessons → MEMORY.md\n   - Scheduled jobs → MEMORY.md jobs table\n   - User info and communication style → USER.md\n3. Synthesize, do not copy. Extract decisions, architecture, lessons, issues, capabilities, contacts, workflows, preferences.\n4. Move distilled logs to memory/archive/\n5. Update MEMORY.md index if new files created.\n\n## Part 2: Voice Profile\n\nONLY perform this section if OPENCORTEX_VOICE_PROFILE=1 is set in the environment. If not set, skip this section entirely.\n\n6. Read memory/VOICE.md. Review today's conversations for new patterns:\n   - New vocabulary, slang, shorthand the user uses\n   - How they phrase requests, decisions, reactions\n   - Tone shifts in different contexts\n   Append new observations to VOICE.md. Do not duplicate existing entries.\n\n## Optimization\n\n- Review memory/projects/ for duplicates, stale info, verbose sections. Fix directly.\n- Review memory/contacts/ — merge duplicates, update stale info, add missing context.\n- Review memory/workflows/ — verify accuracy, update if services or steps changed.\n- Review memory/preferences.md — remove contradicted preferences (user changed mind), merge duplicates, ensure categories are correct.\n- Review MEMORY.md: verify index accuracy, principles concise, jobs table current.\n- Review TOOLS.md and (if OPENCORTEX_INFRA_COLLECT=1) INFRA.md: remove stale entries, verify descriptions.\n\n## Stale Content Cleanup\n\n- Check memory/projects/ for projects marked \"Complete\" more than 30 days ago with no recent daily log mentions. Flag for archival in the summary (do not delete — the user decides).\n- Check MEMORY.md scheduled jobs table against actual cron jobs (openclaw cron list + crontab -l). Remove entries for crons that no longer exist. Add entries for crons not yet documented.\n\n## Tool Shed Audit (P4 Enforcement)\n\n- Read TOOLS.md. Scan today's daily logs for any CLI tools, APIs, or services that were USED but are NOT documented in TOOLS.md. Add missing entries with: what it is, how to access it, what it can do.\n- For tools already in TOOLS.md, check if today's logs reveal gotchas, failure modes, or usage notes not yet captured. Update existing entries.\n\n## Decision & Preference Audit (P5 Enforcement)\n\n- Scan today's daily logs for any decisions stated by the user that are NOT captured in project files, MEMORY.md, or USER.md.\n- For each uncaptured decision, write it to the appropriate file. Format: **Decision:** [what] — [why] (date)\n- Scan today's daily logs for any stated preferences NOT in memory/preferences.md. Phrases like 'I prefer', 'always do', 'I don't like', 'I want', 'don't ever' signal preferences.\n- For each uncaptured preference, append to memory/preferences.md under the right category. Format: **Preference:** [what] — [context/reasoning] (date). If contradicts existing, UPDATE existing.\n\n## Contact Audit\n\n- Scan today's daily logs for any people or organizations mentioned. For each, check if a file exists in memory/contacts/. If not and relevant, create one.\n- For existing contacts, update with new information from today's logs.\n\n## Workflow Audit\n\n- Scan today's daily logs for any workflows, pipelines, or multi-service processes. For each, check if a file exists in memory/workflows/. If not, create one.\n- For existing workflows, update if today's logs reveal changes or issues.\n\n## Debrief Recovery (P6 Enforcement)\n\n- Check today's daily logs for any sub-agent delegations. For each, verify a debrief entry exists. If missing, write a recovery debrief.\n\n## Shed Deferral Audit (P8 Enforcement)\n\n- Scan today's daily logs for instances where the agent deferred to the user. Cross-reference with TOOLS.md, INFRA.md, and memory/. Flag unnecessary deferrals.\n\n## Failure Root Cause (P7 Enforcement)\n\n- Scan today's daily logs for ❌ FAILURE: or 🔧 CORRECTION: entries. Verify root cause analysis exists. If missing, add it.\n\n## Cron Health\n\n- Run openclaw cron list and crontab -l. Verify no two jobs within 15 minutes. Fix MEMORY.md jobs table if out of sync.\n\n---\n\nBefore completing, append debrief to memory/YYYY-MM-DD.md.\nReply with brief summary.\n\nFile v3.5.18:references/weekly-synthesis.md\n\n# Weekly Synthesis — Instructions\n\nYou are an AI assistant. Weekly synthesis — higher-altitude review.\n\n**IMPORTANT:** Before writing to any file, check for /tmp/opencortex-distill.lock. If it exists and was created less than 10 minutes ago, wait 30 seconds and retry (up to 3 times). Before starting work, create this lockfile. Remove it when done. This prevents daily and weekly jobs from conflicting.\n\n1. Read archived daily logs from past 7 days (memory/archive/).\n2. Read all project files (memory/projects/), contact files (memory/contacts/), workflow files (memory/workflows/), and preferences (memory/preferences.md).\n3. Identify and act on:\n   a. Recurring problems → add to project Known Issues\n   b. Unfinished threads → add to Pending with last-touched date\n   c. Cross-project connections → add cross-references\n   d. Decisions this week → ensure captured with reasoning\n   e. New capabilities → verify in TOOLS.md with abilities (P4)\n   f. **Runbook detection** — identify any multi-step procedure (3+ steps) performed more than once this week, or likely to recur. Check if a runbook exists in memory/runbooks/. If not, create one with clear steps a sub-agent could follow. Update MEMORY.md runbooks index.\n   g. **Principle health** — read MEMORY.md principles section. Verify each principle has: clear intent, enforcement mechanism, and that the enforcement is actually reflected in the distillation cron. Flag any principle without enforcement.\n   h. **Contact review** — check memory/contacts/ for stale entries, missing contacts, or contacts that should be merged.\n   i. **Workflow review** — check memory/workflows/ for outdated descriptions or new workflows.\n   j. **Preference review** — read memory/preferences.md. Check for contradictions, stale preferences, and organization.\n   k. **Memory file reorganization** — review all memory files (projects, contacts, workflows, preferences, TOOLS.md) for organization quality. For files that have grown large or disorganized: merge duplicate entries, group related information together, ensure consistent formatting, and restructure sections when it would improve accessibility. Preserve ALL detail during reorganization — this is restructuring, not summarizing. Prioritize files that have had the most additions this week.\n   l. **Structural integrity audit** — verify information is in the correct file and section:\n      - Preferences in memory/preferences.md, NOT scattered across project files or MEMORY.md\n      - Decisions in the relevant project file, NOT in preferences.md or daily logs\n      - Tool/API documentation in TOOLS.md, NOT in project files or MEMORY.md\n      - Infrastructure details in INFRA.md (if it exists), NOT in TOOLS.md or project files\n      - Contact information in memory/contacts/, NOT embedded in project files\n      - Workflow/pipeline docs in memory/workflows/, NOT in project files or TOOLS.md\n      - Repeatable procedures (3+ steps) in memory/runbooks/, NOT left as inline notes\n      - MEMORY.md contains ONLY principles and the index — no project details, no tool docs, no preferences\n      - AGENTS.md contains ONLY operating protocol — no project-specific rules or preferences\n      - If anything is misplaced, move it to the correct location. Preserve all detail during the move.\n   m. **Retrieval quality check** — test memory_search with 3-5 queries based on this week's work (project names, key decisions, people mentioned). For each query, verify the top results are actually relevant. If retrieval misses information you know exists:\n      1. **Diagnose** — determine the cause: file too large (>50KB, needs splitting), information in the wrong file (structural integrity issue, move it), duplicate/scattered content (needs consolidation), or embeddings not configured/stale.\n      2. **Fix automatically** — for issues within the agent's control: split oversized files into focused sub-files, move misplaced content to the correct file (per item l), consolidate scattered duplicates, update MEMORY.md index to reflect new files.\n      3. **Escalate to user** — for issues requiring user action: embeddings not configured (suggest setup steps), persistent retrieval failures after restructuring (may need QMD backend or manual review).\n      4. **Track** — log each retrieval gap and its resolution in the weekly summary under a \"Retrieval Health\" section. If the same gap appears two weeks in a row without resolution, flag it prominently to the user.\n      5. **Verify** — re-test previously failed queries to confirm fixes worked. Note improvements or regressions.\n4. Write weekly summary to memory/archive/weekly-YYYY-MM-DD.md.\n\n## Runbook Detection\n\n- Review this week's daily logs for any multi-step procedure (3+ steps) that was performed more than once, or is likely to recur.\n- For each candidate: check if a runbook already exists in memory/runbooks/.\n- If not, create one with clear step-by-step instructions that a sub-agent could follow independently.\n- Update MEMORY.md runbooks index if new runbooks created.\n\n## Metrics Summary (if enabled)\n\n- If scripts/metrics.sh exists, run: bash scripts/metrics.sh --report --weeks 4\n- Include the output in your weekly summary.\n- If the compound score is declining or flat, note specific areas that need attention.\n\n---\n\nBefore completing, append debrief to memory/YYYY-MM-DD.md.\nReply with weekly summary.\n\nArchive v3.5.17: 12 files, 60985 bytes\n\nFiles: README.md (21251b), references/architecture.md (6173b), references/distillation.md (6064b), references/weekly-synthesis.md (5425b), scripts/git-backup.sh (4591b), scripts/install.sh (39165b), scripts/metrics.sh (14441b), scripts/update.sh (67000b), scripts/vault.sh (10359b), scripts/verify.sh (6524b), SKILL.md (10486b), _meta.json (130b)\n\nFile v3.5.17:SKILL.md\n\n---\nname: OpenCortex\nhomepage: https://github.com/JD2005L/opencortex\ndescription: >\n  Self-improving memory architecture for OpenClaw agents. Structured memory files,\n  nightly distillation, weekly synthesis, enforced principles (P0 for custom, P1-P8 managed),\n  write-ahead durability, and model-agnostic delegation — so your agent\n  compounds knowledge instead of forgetting it. Includes opt-in metrics tracking with\n  growth charts and compound scoring to measure effectiveness over time. All sensitive features (voice profiling,\n  infrastructure auto-collection, git push) are OFF by default and require explicit\n  opt-in via environment variable or flag. Safe to install: no network calls during\n  setup, fully auditable bash scripts, isolated cron sessions scoped to workspace only.\n  Use when: (1) setting up a new OpenClaw instance, (2) user asks to improve/organize\n  memory, (3) user wants the agent to stop forgetting things, (4) bootstrapping a fresh\n  agent with best practices. NOT for: runtime memory_search queries (use built-in memory\n  tools). Triggers: \"set up memory\", \"organize yourself\", \"stop forgetting\", \"memory\n  architecture\", \"self-improving\", \"cortex\", \"bootstrap memory\", \"memory optimization\".\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"grep\",\"sed\",\"find\"],\"optionalBins\":[\"git\",\"gpg\",\"openssl\",\"openclaw\",\"secret-tool\",\"keyctl\",\"file\"]},\"env\":{\"CLAWD_WORKSPACE\":{\"description\":\"Workspace directory (defaults to cwd)\",\"required\":false},\"CLAWD_TZ\":{\"description\":\"Timezone for cron scheduling (defaults to UTC)\",\"required\":false},\"OPENCORTEX_VAULT_PASS\":{\"description\":\"Vault passphrase via env var. Prefer system keyring.\",\"required\":false,\"sensitive\":true},\"OPENCORTEX_VOICE_PROFILE\":{\"description\":\"Set to 1 to enable voice profiling in the nightly distillation cron. Off by default.\",\"required\":false,\"sensitive\":false},\"OPENCORTEX_INFRA_COLLECT\":{\"description\":\"Set to 1 to enable infrastructure auto-collection in the nightly distillation cron. Off by default.\",\"required\":false,\"sensitive\":false},\"OPENCORTEX_SCRUB_ALL\":{\"description\":\"Set to 1 to scrub all tracked files (not just known text types) during git backup. Off by default.\",\"required\":false,\"sensitive\":false},\"OPENCORTEX_ALLOW_FILE_PASSPHRASE\":{\"description\":\"Set to 1 to allow vault passphrase stored in a file (.vault/.passphrase). Off by default; prefer system keyring.\",\"required\":false,\"sensitive\":false}},\"sensitiveFiles\":[\".secrets-map\",\".vault/.passphrase\"],\"networkAccess\":\"Optional git push only (off by default, requires --push flag)\"}}\n---\n\n# OpenCortex — Self-Improving Memory Architecture\n\nTransform a default OpenClaw agent into one that compounds knowledge daily.\n\n📦 [Full source on GitHub](https://github.com/JD2005L/opencortex) — review the code, file issues, or contribute.\n\n## What This Does\n\n1. **Structures memory** into purpose-specific files instead of one flat dump\n2. **Installs nightly maintenance** that distills daily work into permanent knowledge\n3. **Installs weekly synthesis** that catches patterns across days\n4. **Establishes principles** that enforce good memory habits — and backs them up with nightly audits that verify tool documentation, decision capture, sub-agent debriefs, failure analysis, and unnecessary deferrals to the user. Nothing slips through the cracks.\n6. **Builds a voice profile** of your human from daily conversations for authentic ghostwriting (opt-in, requires `OPENCORTEX_VOICE_PROFILE=1`)\n7. **Encrypts sensitive data** in an AES-256 vault with key-only references in docs; supports passphrase rotation (`vault.sh rotate`) and validates key names on `vault.sh set`\n8. **Enables safe git backup** with secret scrubbing (secrets never modified in your live workspace — scrubbed in an isolated copy only)\n9. **Tracks growth over time** *(opt-in)* — daily metrics snapshots with compound scoring and ASCII growth charts\n\n## Installation\n\n**Prerequisites** (install these separately if you don't have them):\n- [OpenClaw](https://github.com/openclaw/openclaw) 2026.2.x+\n- [ClawHub CLI](https://clawhub.com)\n\n```bash\n# 1. Download the skill from your OpenClaw workspace directory\ncd ~/clawd    # or wherever your workspace is\nclawhub install opencortex\n\n# 2. Run the installer FROM YOUR WORKSPACE DIRECTORY (not from inside the skill folder)\nbash skills/opencortex/scripts/install.sh\n\n# Optional: preview what would be created without changing anything\nbash skills/opencortex/scripts/install.sh --dry-run\n```\n\nThe installer will ask about optional features (encrypted vault, voice profiling, infrastructure collection, git backup). It's safe to re-run — it skips anything that already exists. The installer itself makes no network calls — it only creates local files and registers cron jobs.\n\n```bash\n# 3. Verify everything is working (read-only — checks files and cron jobs, changes nothing)\nbash skills/opencortex/scripts/verify.sh\n```\n\nYou can also ask your OpenClaw agent \"is OpenCortex working?\" — it knows how to run the verification and share results.\n\nThe script will:\n- Create the file hierarchy (non-destructively — won't overwrite existing files)\n- Create directory structure\n- Set up cron jobs (daily distillation, weekly synthesis)\n- Optionally set up git backup with secret scrubbing\n\nAfter install, review and customize:\n- `SOUL.md` — personality and identity (make it yours)\n- `USER.md` — info about your human\n- `MEMORY.md` — principles (add/remove as needed)\n- `.secrets-map` — add your actual secrets for git scrubbing\n\n## Updating\n\n```bash\n# 1. Download the latest version (run from workspace root)\nclawhub install opencortex --force\n\n# 2. Re-run the installer — it detects your existing install and offers to update\nbash skills/opencortex/scripts/install.sh\n```\n\nThe installer detects your existing version and offers three options: Update (recommended), Full reinstall, or Cancel. The update path is non-destructive — it adds missing content, refreshes cron messages, and offers any new optional features without overwriting your customized files.\n\n## Architecture\n\n```\nSOUL.md          ← Identity, personality, boundaries\nAGENTS.md        ← Operating protocol, delegation rules\nMEMORY.md        ← Principles + memory index (< 3KB, loaded every session)\nTOOLS.md         ← Tool shed: APIs, scripts, and access methods with abilities descriptions\nINFRA.md         ← Infrastructure atlas: hosts, IPs, services, network\nUSER.md          ← Human's preferences, projects, communication style\nBOOTSTRAP.md     ← First-run checklist for new sessions\n\nmemory/\n  projects/      ← One file per project (distilled, not raw)\n  contacts/      ← One file per person/org (role, context, preferences)\n  workflows/     ← One file per workflow/pipeline (services, steps, issues)\n  runbooks/      ← Step-by-step procedures (delegatable to sub-agents)\n  preferences.md ← Cross-cutting user preferences by category\n  archive/       ← Archived daily logs + weekly summaries\n  YYYY-MM-DD.md  ← Today's working log (distilled nightly)\n```\n\n## Principles (installed by default)\n\n| # | Name | Purpose |\n|---|------|---------|\n| P1 | Delegate First | Assess tasks for sub-agent delegation; stay available |\n| P2 | Write It Down | Commit to files, not mental notes |\n| P3 | Ask Before External | Confirm before emails, public posts, destructive ops |\n| P4 | Tool Shed & Workflows | Document tools and workflows; enforced by nightly audit |\n| P5 | Capture Decisions & Preferences | Record decisions and preferences; enforced by nightly + weekly audit |\n| P6 | Sub-agent Debrief | Delegated work feeds back to daily log; orphans recovered by distillation |\n| P7 | Log Failures | Tag failures/corrections; root cause analysis enforced by nightly audit |\n| P8 | Check the Shed First | Consult TOOLS.md/INFRA.md/memory before deferring work to user; enforced by nightly audit |\n\n## Cron Jobs (installed)\n\n| Schedule | Name | What it does |\n|----------|------|-------------|\n| Daily 3 AM (local) | Distillation | Reads daily logs → distills into project/tools/infra files → audits tools/decisions/debriefs/failures → optimizes → archives |\n| Weekly Sunday 5 AM | Synthesis | Reviews week for patterns, recurring problems, unfinished threads, decisions; auto-creates runbooks from repeated procedures |\n\nBoth jobs use a shared lockfile (`/tmp/opencortex-distill.lock`) to prevent conflicts when daily and weekly runs overlap.\n\nCustomize times by editing cron jobs: `openclaw cron list` then `openclaw cron edit <id> --cron \"...\"`.\n\n## Git Backup (optional)\n\nIf enabled during install, creates:\n- `scripts/git-backup.sh` — auto-commit every 6 hours, scrubs secrets in an isolated temp copy (workspace files never modified)\n- `.secrets-map` — maps secrets to placeholders (gitignored, 600 perms)\n\nAdd secrets to `.secrets-map` in format: `actual_secret|{{PLACEHOLDER_NAME}}`\n\nBefore each push, `git-backup.sh` verifies no raw secrets remain in the scrubbed copy. If any are found, the backup is aborted — nothing reaches the remote.\n\n## Customization\n\n**Adding a project:** Create `memory/projects/my-project.md`, add to MEMORY.md index.\n\n**Adding a contact:** Create `memory/contacts/name.md`. Distillation auto-creates contacts from conversations.\n\n**Adding a workflow:** Create `memory/workflows/my-pipeline.md`. Distillation auto-creates workflows when described.\n\n**Adding a preference:** Append to `memory/preferences.md` under the right category. Distillation auto-captures from conversation.\n\n**Adding a principle:** Append to MEMORY.md under 🔴 PRINCIPLES. Keep it short.\n\n**Adding a runbook:** Create `memory/runbooks/my-procedure.md`. Sub-agents can follow these directly.\n\n**Adding a tool:** Add to TOOLS.md with: what it is, how to access it, and a goal-oriented abilities description (so future intent-based lookup matches).\n\n## How It Compounds\n\n```\nDaily work → daily log\n  → nightly distill → routes to project/tools/infra/principles files\n                     → optimization pass (dedup, prune stale, condense)\n  → weekly synthesis → patterns, recurring problems, unfinished threads → auto-creates runbooks from repeated procedures → `memory/runbooks/`\nSub-agent work → debrief (P6) → daily log → same pipeline\nDecisions → captured with reasoning (P5) → never re-asked\nNew tools → documented with abilities (P4) → findable by intent\n```\n\nEach day the agent wakes up slightly more knowledgeable and better organized.\n\nFile v3.5.17:README.md\n\n# 🧠 OpenCortex\n\n**Self-improving memory architecture for [OpenClaw](https://github.com/openclaw/openclaw) agents.**\n\nStop forgetting. Start compounding.\n\n---\n\n## The Problem\n\nOut of the box, OpenClaw agents dump everything into a flat `MEMORY.md`. Context fills up, compaction loses information, and the agent forgets what it learned last week. It's like having a brilliant employee with amnesia who takes notes on napkins.\n\n## The Solution\n\nOpenCortex transforms your agent into one that **gets smarter every day** through:\n\n- **Structured memory** — Purpose-specific files instead of one flat dump\n- **Nightly distillation** — Daily work automatically distilled into permanent knowledge\n- **Weekly synthesis** — Pattern detection across days catches recurring problems and unfinished threads\n- **Enforced principles** — Habits that prevent knowledge loss (decision capture, tool documentation, sub-agent debriefs)\n- **Write-ahead durability** — Agent writes decisions and preferences to memory before responding, so nothing is lost if the session ends or compacts mid-conversation\n- **Encrypted vault** — AES-256 encrypted secret storage with system keyring support\n- **Voice profiling** *(opt-in)* — Learns how your human communicates for authentic ghostwriting\n- **Infrastructure collection** *(opt-in)* — Auto-routes infrastructure details from daily logs to INFRA.md\n- **Safe git backup** *(opt-in)* — Automatic secret scrubbing in an isolated copy — workspace files are never modified\n\n## Quick Start\n\n**Prerequisites:** [OpenClaw](https://github.com/openclaw/openclaw) 2026.2.x+ and [ClawHub CLI](https://clawhub.com)\n\n```bash\n# From your OpenClaw workspace directory (e.g. ~/clawd)\nclawhub install opencortex\nbash skills/opencortex/scripts/install.sh\n\n# Preview without changing anything:\nbash skills/opencortex/scripts/install.sh --dry-run\n\n# Verify everything is working (read-only):\nbash skills/opencortex/scripts/verify.sh\n```\n\n**Important:** Run the installer from your workspace root, NOT from inside the skill folder.\n\nThe installer asks about optional features, creates files (won't overwrite existing ones), and registers cron jobs. It makes zero network calls.\n\nAfter install, customize:\n1. `SOUL.md` — personality and identity\n2. `USER.md` — info about your human\n3. `MEMORY.md` — principles and project index\n4. `TOOLS.md` — tools and APIs as you discover them\n5. `INFRA.md` — infrastructure reference\n6. `.secrets-map` — secrets for git scrubbing (if using git backup)\n\n### From Source\n\n```bash\ngit clone https://github.com/JD2005L/opencortex.git\ncd opencortex && bash scripts/install.sh\n```\n\n## Updating\n\n```bash\nclawhub install opencortex --force         # Download latest\nbash skills/opencortex/scripts/install.sh  # Detects existing install, offers Update\n```\n\nThe installer detects your existing version and offers: **1) Update** (recommended), **2) Full reinstall**, **3) Cancel.** It never overwrites files you've customized.\n\n### What the updater does\n\n| Content | Update method | User data safe? |\n|---------|--------------|-----------------|\n| Principles (P1-P8) | Hash comparison, asks before replacing | ✅ Asks y/N per principle |\n| P0 (Custom Principles) | Never touched | ✅ Your custom principles are always safe |\n| Helper scripts (verify, vault, metrics, git-backup) | Checksum comparison, auto-replaced | ✅ These aren't user-edited |\n| Reference docs (distillation, weekly-synthesis, architecture) | Checksum comparison, auto-replaced | ✅ These aren't user-edited |\n| Cron job messages | Always updated to latest template | ✅ Only the message text changes |\n| Cron model overrides | Cleared on every update | ✅ Gateway uses its configured default |\n| Cron deduplication | Detects and removes duplicate crons from prior bugs | ✅ Keeps the first, deletes extras |\n| Extra principles (P9+) | Detects duplicates and orphans, offers remove/migrate to P0 | ✅ Asks per principle |\n| MEMORY.md bloat | Warns if >5KB, flags non-standard sections | ✅ Suggests what to move |\n| Missing cron jobs | Offers to recreate with timezone auto-detection | ✅ Asks before creating |\n| MEMORY.md structure (## Identity, ## Memory Index) | Adds missing core sections | ✅ Existing sections untouched |\n| MEMORY.md index (### Infrastructure through ### Daily Logs) | Adds all 8 missing sub-sections | ✅ Existing sections untouched |\n| preferences.md | Created if missing | ✅ Existing file untouched |\n| New directories (contacts, workflows) | Created if missing | ✅ |\n| AGENTS.md | Merges: regenerates standard sections, preserves custom sections | ✅ Custom sections appended |\n| BOOTSTRAP.md | Merges: regenerates standard sections, preserves custom sections | ✅ Custom sections appended |\n| SOUL.md | Created if missing | ✅ Existing file untouched |\n| USER.md | Created if missing | ✅ Existing file untouched |\n| .gitignore | Adds missing sensitive entries (.vault/, .secrets-map, etc.) | ✅ Existing entries untouched |\n\n---\n\n## Architecture\n\n```\nSOUL.md          ← Identity & personality\nAGENTS.md        ← Operating protocol & delegation rules\nMEMORY.md        ← Principles + index (< 3KB, loaded every session)\nTOOLS.md         ← Tool shed: APIs, scripts with abilities descriptions\nINFRA.md         ← Infrastructure atlas: hosts, IPs, services\nUSER.md          ← Your human's preferences\nBOOTSTRAP.md     ← Session startup checklist\n\nmemory/\n  projects/      ← One file per project (distilled, not raw)\n  contacts/      ← One file per person/org (role, context, preferences)\n  workflows/     ← One file per workflow/pipeline (services, steps, issues)\n  runbooks/      ← Step-by-step procedures (delegatable to sub-agents)\n  preferences.md ← Cross-cutting user preferences by category\n  archive/       ← Archived daily logs + weekly summaries\n  YYYY-MM-DD.md  ← Today's working log (distilled nightly)\n```\n\n## Principles (P0–P8)\n\n| # | Principle | What It Does | Enforcement |\n|---|-----------|-------------|-------------|\n| P0 | Custom Principles | Your own principles (P0-A, P0-B, etc.) | Never modified by updates |\n| P1 | Delegate First | Model-agnostic sub-agent delegation (Light/Medium/Heavy) | Agent protocol |\n| P2 | Write It Down | Write-ahead durability: save before responding | Agent protocol |\n| P3 | Ask Before External | Confirm before public/destructive actions | Agent protocol |\n| P4 | Tool Shed & Workflows | Document tools and workflows | Nightly audit scans for undocumented tools and workflows |\n| P5 | Capture Decisions & Preferences | Record decisions and preferences | Nightly + weekly audit for uncaptured decisions and preferences |\n| P6 | Sub-agent Debrief | Delegated work feeds back to daily log | Nightly audit recovers orphaned debriefs |\n| P7 | Log Failures | Tag failures with root cause analysis | Nightly audit checks for missing root causes |\n| P8 | Check the Shed First | Use documented tools before deferring to user | Nightly audit flags unnecessary deferrals |\n\n## How It Compounds\n\n```\nWeek 1:  Agent knows basics, asks lots of questions\nWeek 4:  Agent has project history, knows tools, follows decisions\nWeek 12: Agent has deep institutional knowledge, patterns, runbooks\nWeek 52: Agent knows more about your setup than you remember\n```\n\n---\n\n## Security Model\n\n### Threat Model Summary\n\nOpenCortex is a **workspace-scoped memory skill**. It creates files, registers cron jobs that run as isolated OpenClaw agent sessions, and optionally manages an encrypted vault. The primary risk surface is:\n\n1. **Autonomous cron jobs** that read/write workspace files without human interaction\n2. **Optional features** that collect sensitive data (voice patterns, infrastructure details)\n3. **Optional git backup** that handles secret scrubbing before commits\n\nOpenCortex contains **zero network operations** — no telemetry, no phone-home, no external endpoints. Every script is plain bash. [Full source is public.](https://github.com/JD2005L/opencortex)\n\n### Default State: What's On and Off\n\n| Feature | Default | Opt-In Required | What It Accesses | How to Disable |\n|---------|---------|----------------|-----------------|----------------|\n| Structured memory files | ✅ ON | — | Creates markdown files in workspace | Delete unwanted files |\n| Daily distillation cron | ✅ ON | — | Reads/writes `memory/`, `MEMORY.md`, `TOOLS.md`, `USER.md` | `openclaw cron delete <id>` |\n| Weekly synthesis cron | ✅ ON | — | Reads `memory/archive/`, writes summaries + runbooks | `openclaw cron delete <id>` |\n| Principle enforcement audits | ✅ ON | — | Part of distillation — audits within workspace | Remove audit sections from cron message |\n| Encrypted vault | Asked at install | Choose \"direct\" mode to skip | `.vault/` directory, system keyring | Don't init vault; delete `.vault/` |\n| Voice profiling | ❌ OFF | `OPENCORTEX_VOICE_PROFILE=1` | Reads workspace conversation logs → `memory/VOICE.md` | Unset env var; delete `memory/VOICE.md` |\n| Infrastructure collection | ❌ OFF | `OPENCORTEX_INFRA_COLLECT=1` | Routes infra mentions from daily logs → `INFRA.md` | Unset env var |\n| Git backup | ❌ OFF | Say \"yes\" at install | Commits workspace to git (local only by default) | Remove from crontab; delete scripts |\n| Git push to remote | ❌ OFF | `--push` flag on each run | Pushes scrubbed commits to remote | Don't pass `--push` |\n| Daily metrics tracking | ❌ OFF | Say \"yes\" at install | Read-only file counts → `memory/metrics.log` | Remove from crontab; delete `metrics.log` |\n| Broad file scrubbing | ❌ OFF | `OPENCORTEX_SCRUB_ALL=1` | Scrubs all tracked files (not just known text types) | Unset env var |\n| File-based vault passphrase | ❌ OFF | `OPENCORTEX_ALLOW_FILE_PASSPHRASE=1` | Stores passphrase at `.vault/.passphrase` | Unset env var; use system keyring |\n\n### What Runs Autonomously\n\nTwo cron jobs, both running as **isolated OpenClaw agent sessions** scoped to the workspace:\n\n| Job | Schedule | Reads | Writes | Network Access |\n|-----|----------|-------|--------|----------------|\n| Daily Distillation | Daily 3 AM (local) | `memory/*.md`, workspace `*.md` | `memory/projects/`, `memory/contacts/`, `memory/workflows/`, `memory/preferences.md`, `MEMORY.md`, `TOOLS.md`, `USER.md`, daily log audit outputs | **None** |\n| Weekly Synthesis | Sunday 5 AM (local) | `memory/archive/*.md`, `memory/projects/*.md`, `memory/contacts/*.md`, `memory/workflows/*.md`, `memory/preferences.md` | `memory/archive/weekly-*.md`, project/contact/workflow/preference files, `memory/runbooks/` | **None** |\n\nBoth jobs:\n- Use a shared lockfile (`/tmp/opencortex-distill.lock`) to prevent conflicts\n- Contain **no** `rm`, system modifications, network calls, or external API access\n- Reference **only** workspace-relative paths (`memory/`, `MEMORY.md`, `TOOLS.md`, etc.)\n- Are fully inspectable: `openclaw cron list`\n- Are fully removable: `openclaw cron delete <id>`\n\n**How cron jobs work:** OpenCortex does not bundle standalone distillation scripts. Instead, the installer registers OpenClaw cron jobs (`openclaw cron add`) with detailed task instructions. At runtime, OpenClaw spawns an isolated agent session that follows those instructions to read, synthesize, and write workspace files. The LLM agent is the executor — it's far better at knowledge synthesis than any bash script could be. The cron job messages *are* the implementation, fully viewable and editable via `openclaw cron list` / `openclaw cron edit`.\n\n**On workspace isolation:** The cron instructions themselves don't enforce sandboxing — that's the **OpenClaw platform's** responsibility. OpenClaw cron jobs run in isolated sessions scoped to the workspace directory by the runtime, the same way a Dockerfile doesn't implement kernel isolation — the container runtime does. OpenCortex's cron instructions contain no references to external filesystems, network calls, or system commands beyond `openclaw cron list` and `crontab -l` (for self-auditing cron health).\n\n### Git Backup Security\n\nGit backup (when enabled) uses an **isolated copy approach** — your workspace files are never modified during scrubbing:\n\n1. All files to commit are copied to a temp directory\n2. Secrets are scrubbed in the copy only (using `.secrets-map` replacements)\n3. The scrubbed copy is verified — if any raw secrets remain, the backup aborts immediately\n4. A git commit is built from the scrubbed copy using git plumbing (`hash-object`, `update-index`, `write-tree`, `commit-tree`)\n5. The temp directory is cleaned up\n6. Your original workspace files are **untouched throughout the entire process**\n\nAdditional safeguards:\n- `.secrets-map` and `.vault/` are always gitignored (enforced at install)\n- Pre-backup check aborts if either exists but isn't gitignored\n- Push requires explicit `--push` flag — local-only by default\n- `.secrets-map` has 600 permissions (owner-only read/write)\n\n**Recommendation:** Test in a disposable repo first. Run the backup, inspect the commit diff, and confirm scrubbing works before pointing at a real remote.\n\n### Vault Security\n\nThe encrypted vault stores secrets at rest via GPG symmetric encryption (AES-256). Passphrase storage uses the **best available backend** (auto-detected):\n\n| Priority | Backend | Passphrase Location | On Disk? |\n|----------|---------|-------------------|----------|\n| 1 | secret-tool (Linux keyring) | GNOME/KDE keyring | No |\n| 2 | macOS Keychain | Native macOS keystore | No |\n| 3 | keyctl (Linux kernel keyring) | Kernel memory | No |\n| 4 | Environment variable | `OPENCORTEX_VAULT_PASS` | No |\n| 5 | File fallback | `.vault/.passphrase` (mode 600) | Yes — requires `OPENCORTEX_ALLOW_FILE_PASSPHRASE=1` |\n\nCommands: `vault.sh init`, `vault.sh set <key> <value>`, `vault.sh get <key>`, `vault.sh rotate`, `vault.sh migrate`, `vault.sh backend`\n\nKey names are validated on set (alphanumeric + underscores only).\n\n### Install Mechanism\n\nThe installer (`scripts/install.sh`) is a single bash script that:\n- Creates markdown files (only if they don't already exist)\n- Creates directories (`memory/projects/`, `memory/contacts/`, `memory/workflows/`, `memory/runbooks/`, `memory/archive/`)\n- Registers OpenClaw cron jobs via `openclaw cron add`\n- Optionally copies bundled `git-backup.sh` and `vault.sh` scripts to the workspace\n\n**No external downloads.** No package installs. No network calls. No binaries. All code is plain bash + markdown, bundled in the skill package and fully auditable.\n\n### Credentials\n\nOpenCortex declares **no required API keys or environment variables**. The cron jobs use your gateway's default model — OpenCortex never sees or handles model provider keys. Any model capable of reading and writing markdown files will work.\n\nOptional environment variables (all off by default):\n\n| Variable | Purpose | Sensitive |\n|----------|---------|-----------|\n| `CLAWD_WORKSPACE` | Override workspace directory (defaults to cwd) | No |\n| `CLAWD_TZ` | Timezone for cron scheduling (defaults to UTC) | No |\n| `OPENCORTEX_VAULT_PASS` | Vault passphrase via env var (prefer keyring) | Yes |\n| `OPENCORTEX_VOICE_PROFILE` | Enable voice profiling in distillation | No |\n| `OPENCORTEX_INFRA_COLLECT` | Enable infrastructure auto-collection | No |\n| `OPENCORTEX_SCRUB_ALL` | Scrub all tracked files during git backup | No |\n| `OPENCORTEX_ALLOW_FILE_PASSPHRASE` | Allow file-based vault passphrase | No |\n\n---\n\n## What to Review Before Installing\n\n1. **Read the scripts.** They're bundled plain bash — `install.sh`, `update.sh`, `vault.sh`, `git-backup.sh`, `verify.sh`, `metrics.sh`. You can read every line before running anything. Required binaries: `grep`, `sed`, `find`. Optional: `git`, `gpg`, `openssl`, `openclaw`, `secret-tool`, `keyctl`, `file` (for binary detection during scrubbing).\n2. **Confirm workspace isolation.** OpenCortex delegates sandbox enforcement to the OpenClaw platform. Verify your OpenClaw instance enforces workspace-only behavior for cron sessions. If isolation is misconfigured, a cron session could theoretically access files outside the workspace.\n3. **Inspect cron messages after install.** Run `openclaw cron list` to see the exact instructions registered. These are the actual implementation — edit or remove them freely.\n4. **Prefer system keyring for vault.** Use `secret-tool`, macOS Keychain, or `keyctl` over file-based passphrase storage. Set `OPENCORTEX_ALLOW_FILE_PASSPHRASE=1` only if no keyring is available and you accept the risk.\n5. **Test git backup in a disposable repo.** Verify `.secrets-map` entries scrub correctly before using on a real remote.\n6. **Opt-in features are off by default.** Voice profiling, infrastructure collection, broad scrubbing, and git push all require explicit activation. Only enable what you need.\n7. **Consider disabling voice profiling** if you're uncomfortable with the agent building a persistent behavioral profile from conversations.\n\n---\n\n## Metrics & Growth Tracking\n\nIf enabled during install, OpenCortex tracks your agent's knowledge growth over time. A daily system cron (11:30 PM local) snapshots file counts, decision captures, tool documentation, and more into `memory/metrics.log`. No sensitive data is collected — only counts and pattern matches.\n\n### What's Tracked\n\n| Metric | What It Measures |\n|--------|-----------------|\n| Knowledge files | Total files in `memory/projects/`, `memory/contacts/`, `memory/workflows/`, `memory/runbooks/`, and `memory/` |\n| Knowledge size (KB) | Total size of knowledge files |\n| Decisions captured | `**Decision:**` entries across all memory files |\n| Preferences captured | `**Preference:**` entries in `memory/preferences.md` |\n| Contacts | People/orgs documented in `memory/contacts/` |\n| Workflows | Pipelines/automations in `memory/workflows/` |\n| Runbooks | Reusable procedures in `memory/runbooks/` |\n| Tools documented | Entries in `TOOLS.md` |\n| Failures logged | `❌ FAILURE:` and `🔧 CORRECTION:` entries |\n| Debriefs | Sub-agent debrief entries in daily logs |\n| Projects | Files in `memory/projects/` |\n| Archive files | Distilled daily logs in `memory/archive/` |\n\n### Commands\n\n```bash\n# Snapshot today's metrics\nbash scripts/metrics.sh --collect\n\n# Show trends with ASCII growth charts + compound score\nbash scripts/metrics.sh --report\n\n# Last 4 weeks only\nbash scripts/metrics.sh --report --weeks 4\n\n# JSON output (for integrations)\nbash scripts/metrics.sh --json\n```\n\nOr just ask your agent: *\"How is OpenCortex doing?\"* or *\"Show me OpenCortex metrics.\"*\n\n### Compound Score\n\nThe report includes a 0–100 compound score reflecting knowledge depth, growth rate, and tracking consistency:\n\n| Score | Rating |\n|-------|--------|\n| 80–100 | Thriving — deep knowledge, steady growth |\n| 60–79 | Growing — good foundation, building momentum |\n| 40–59 | Developing — basics in place, room to grow |\n| 20–39 | Getting started — early days |\n| 0–19 | Just installed — give it time |\n\nA healthy OpenCortex installation trends upward over weeks. Flat or declining scores highlight specific areas to focus on.\n\n### Weekly Summary\n\nIf metrics tracking is enabled, the weekly synthesis cron automatically includes a metrics report in its output — showing 4-week trends and flagging areas that need attention.\n\n### Security\n\nThe metrics script (`scripts/metrics.sh`) is **read-only** — it only counts files and greps for patterns. It writes only to `memory/metrics.log` (append-only in `--collect` mode). No network access, no sensitive data captured (counts, never content), no system modifications.\n\n---\n\n## Customization\n\n**Add a project:** Create `memory/projects/my-project.md`, add to MEMORY.md index. Nightly distillation routes relevant daily log entries to it.\n\n**Add a contact:** Create `memory/contacts/name.md` with: name, role/relationship, context, communication preferences. Distillation auto-creates contacts mentioned in conversation.\n\n**Add a workflow:** Create `memory/workflows/my-pipeline.md` with: what it does, services involved, how to operate it. Distillation auto-creates workflows when described.\n\n**Add a preference:** Append to `memory/preferences.md` under the right category. Format: `**Preference:** [what] — [context] (date)`. Distillation auto-captures preferences stated in conversation.\n\n**Add a principle:** Append to MEMORY.md under 🔴 PRINCIPLES. Keep it short.\n\n**Add a runbook:** Create `memory/runbooks/my-procedure.md` with step-by-step instructions. Sub-agents follow these directly.\n\n**Add a tool:** Add to TOOLS.md with: what it is, how to access it, goal-oriented abilities description.\n\n**Change cron schedule:** `openclaw cron list` then `openclaw cron edit <id> --cron \"...\"`.\n\n**Run fully air-gapped:** Decline all optional features during install. No voice profiling, no infrastructure collection, no git backup. The core memory architecture and distillation work entirely offline.\n\n## Requirements\n\n- [OpenClaw](https://github.com/openclaw/openclaw) 2026.2.x+\n- **Required:** `grep`, `sed`, `find` (standard on most systems)\n- **Optional:** `git` (for backup), `gpg` (for vault), `openssl` (for passphrase generation)\n\n## License\n\nMIT\n\n## Credits\n\nCreated by [JD2005L](https://github.com/JD2005L)\n\nFile v3.5.17:_meta.json\n\n{\n  \"ownerId\": \"kn7e5n3qxtp49kdnhne6vr3wzd81n3sc\",\n  \"slug\": \"opencortex\",\n  \"version\": \"3.5.17\",\n  \"publishedAt\": 1772302694620\n}\n\nFile v3.5.17:references/architecture.md\n\n# OpenCortex Architecture Reference\n\n## Why This Exists\n\nDefault OpenClaw memory is a flat MEMORY.md that grows unbounded. Context fills up, compaction loses information, the agent forgets what it learned. OpenCortex solves this with:\n\n1. **Separation of concerns** — different files for different purposes\n2. **Nightly distillation** — raw daily logs → permanent structured knowledge\n3. **Weekly synthesis** — pattern detection across days\n4. **Principles** — enforced habits that prevent knowledge loss (P0 for custom, P1-P8 managed)\n5. **Sub-agent debrief loop** — delegated work feeds back into memory\n\n## File Purposes\n\n| File | Loaded at boot? | Purpose | Size target |\n|------|-----------------|---------|-------------|\n| MEMORY.md | Yes | Principles + index only | < 3KB |\n| TOOLS.md | Yes | Tool/API catalog with abilities | Grows with tools |\n| INFRA.md | Yes | Infrastructure reference | Grows with infra |\n| SOUL.md | Yes | Identity, personality | < 1KB |\n| AGENTS.md | Yes | Operating protocol | < 1KB |\n| USER.md | Yes | Human's preferences | < 1KB |\n| BOOTSTRAP.md | Yes | Session startup checklist | < 0.5KB |\n| memory/projects/*.md | On demand | Per-project knowledge | Any |\n| memory/contacts/*.md | On demand | Per-person/org knowledge | Any |\n| memory/workflows/*.md | On demand | Per-workflow/pipeline knowledge | Any |\n| memory/preferences.md | On demand | Cross-cutting user preferences by category | Any |\n| memory/runbooks/*.md | On demand | Procedures for sub-agents | Any |\n| memory/YYYY-MM-DD.md | Current day | Working log | Any |\n| memory/archive/*.md | Via search | Historical logs | Any |\n\n## Distillation Routes\n\nThe nightly cron reads daily logs and routes each piece of information:\n\n| Information type | Destination |\n|-----------------|-------------|\n| Project work, features, bugs | memory/projects/{project}.md |\n| New tool descriptions and capabilities | TOOLS.md (sensitive values → vault) |\n| Infrastructure changes | INFRA.md (if OPENCORTEX_INFRA_COLLECT=1) |\n| People and organizations mentioned | memory/contacts/{name}.md |\n| Workflows and pipelines described | memory/workflows/{name}.md |\n| Stated preferences and opinions | memory/preferences.md (categorized) |\n| Decisions and architectural directions | Relevant project file or MEMORY.md |\n| New principles, lessons | MEMORY.md |\n| User info and communication style | USER.md |\n| Scheduled job changes | MEMORY.md jobs table |\n| Repeatable procedures | memory/runbooks/ |\n\n## Preference Categories\n\nPreferences in `memory/preferences.md` are organized by category:\n\n| Category | Examples |\n|----------|---------|\n| Communication | \"No verbose explanations\", \"Direct messages only\" |\n| Code & Technical | \"Detailed commit messages\", \"Prefer TypeScript\" |\n| Workflow & Process | \"Check for messages before pushing\", \"Batch commits\" |\n| Scheduling & Time | \"Don't schedule before 9 AM\", \"Prefer async\" |\n| Tools & Services | \"Use VS Code over Vim\", \"Prefer Brave over Chrome\" |\n| Content & Media | \"720p minimum\", \"No dubbed content\" |\n| Environment & Setup | \"Dark mode everywhere\", \"Dual monitor layout\" |\n\nFormat: `**Preference:** [what] — [context/reasoning] (date)`\n\nPreferences are auto-captured from conversation when the user says \"I prefer\", \"always do\", \"I don't like\", etc. Contradicted preferences are updated (not duplicated).\n\n## Compounding Effect\n\n```\nWeek 1:  Agent knows basics, asks lots of questions\nWeek 4:  Agent has project history, knows tools, follows decisions, remembers preferences\nWeek 12: Agent has deep institutional knowledge, patterns, runbooks, contact history\nWeek 52: Agent knows more about the setup than most humans would remember\n```\n\nThe key insight: **daily distillation + weekly synthesis + decision/preference capture** means the agent gets better at a rate proportional to how much it's used. Unlike raw log accumulation which just fills context, structured knowledge compounds.\n\n## Common Customizations\n\n### Adding delegation tiers\nEdit MEMORY.md P1 to adjust which capability tier (Light/Medium/Heavy) handles what complexity. P1 is model-agnostic and works with whatever models you have configured.\n\n### Changing distillation schedule\n`openclaw cron edit <id> --cron \"0 10 * * *\" --tz \"Your/Timezone\"`\n\n### Adding custom principles\nAll custom principles go in P0 as sub-principles (P0-A, P0-B, P0-C, etc.). P1-P8 are managed by OpenCortex updates and should not be modified directly. The agent is instructed to:\n- Route all new principle requests to P0, even if the user asks for P9 or beyond\n- Check for conflicts with P1-P8 before adding\n- Assess whether the request is truly a principle (persistent behavioral rule) or would be better suited as a preference, decision, runbook, or agent rule\n\n### Write-ahead durability (P2)\nWhen the user states a preference, makes a decision, gives a deadline, or corrects the agent, the agent writes it to the relevant memory file before composing a response. This prevents context loss if the session ends or compacts mid-conversation.\n\n### Memory health monitoring\nThe weekly synthesis includes automated checks that maintain memory quality over time:\n- **Structural integrity audit** — verifies information is in the correct file (preferences in preferences.md, tools in TOOLS.md, etc.) and moves misplaced content.\n- **Memory file reorganization** — merges duplicates, groups related info, restructures growing files while preserving all detail.\n- **Retrieval quality testing** — runs test queries against memory_search and verifies results are relevant. Diagnoses failures (file too large, content misplaced, stale index), fixes what it can, escalates what it can't, and tracks gaps across weeks.\n- **Stale content cleanup** — flags completed projects for archival, syncs MEMORY.md cron table against actual cron jobs.\n\nThe verify.sh script also checks memory search index health, file count, and MEMORY.md boot size.\n\n### Multi-bot setups\nEach bot gets its own OpenCortex install. Share knowledge via:\n- Common git repo (read-only for non-primary bots)\n- SSH-based management (primary bot propagates changes)\n- Shared NFS/SMB mount for common reference docs\n\nFile v3.5.17:references/distillation.md\n\n# Daily Memory Distillation — Instructions\n\nYou are an AI assistant. Daily memory maintenance task.\n\n**IMPORTANT:** Before writing to any file, check for /tmp/opencortex-distill.lock. If it exists and was created less than 10 minutes ago, wait 30 seconds and retry (up to 3 times). Before starting work, create this lockfile. Remove it when done. This prevents daily and weekly jobs from conflicting.\n\n## Part 1: Distillation\n\n1. Check memory/ for daily log files (YYYY-MM-DD.md, not in archive/).\n2. Distill ALL useful information into the right file:\n   - Project work → memory/projects/ (create new files if needed)\n   - New tool descriptions and capabilities → TOOLS.md (names, URLs, what they do)\n   - **IMPORTANT:** Never write passwords, tokens, or secrets into any file. For sensitive values, instruct the user to run: scripts/vault.sh set <key> <value>. Reference in docs as: vault:<key>\n   - Infrastructure changes → INFRA.md (ONLY if OPENCORTEX_INFRA_COLLECT=1 is set in the environment — otherwise skip infrastructure routing entirely)\n   - Contacts mentioned → memory/contacts/ (one file per person/org. Include: name, role/relationship, context, communication preferences, key interactions. Create new file if first mention, update existing if already known.)\n   - Workflows described → memory/workflows/ (one file per workflow/pipeline. Include: what it does, services involved, how to operate it, known issues. Create new file if first description.)\n   - Preferences stated → memory/preferences.md (append under the matching category: Communication, Code & Technical, Workflow & Process, Scheduling & Time, Tools & Services, Content & Media, Environment & Setup. Format: **Preference:** [what] — [context/reasoning] (date). Do NOT duplicate existing preferences — update them if the user changes their mind.)\n   - Decisions → relevant project file or MEMORY.md. Format: **Decision:** [what] — [why] (date)\n   - Principles, lessons → MEMORY.md\n   - Scheduled jobs → MEMORY.md jobs table\n   - User info and communication style → USER.md\n3. Synthesize, do not copy. Extract decisions, architecture, lessons, issues, capabilities, contacts, workflows, preferences.\n4. Move distilled logs to memory/archive/\n5. Update MEMORY.md index if new files created.\n\n## Part 2: Voice Profile\n\nONLY perform this section if OPENCORTEX_VOICE_PROFILE=1 is set in the environment. If not set, skip this section entirely.\n\n6. Read memory/VOICE.md. Review today's conversations for new patterns:\n   - New vocabulary, slang, shorthand the user uses\n   - How they phrase requests, decisions, reactions\n   - Tone shifts in different contexts\n   Append new observations to VOICE.md. Do not duplicate existing entries.\n\n## Optimization\n\n- Review memory/projects/ for duplicates, stale info, verbose sections. Fix directly.\n- Review memory/contacts/ — merge duplicates, update stale info, add missing context.\n- Review memory/workflows/ — verify accuracy, update if services or steps changed.\n- Review memory/preferences.md — remove contradicted preferences (user changed mind), merge duplicates, ensure categories are correct.\n- Review MEMORY.md: verify index accuracy, principles concise, jobs table current.\n- Review TOOLS.md and (if OPENCORTEX_INFRA_COLLECT=1) INFRA.md: remove stale entries, verify descriptions.\n\n## Stale Content Cleanup\n\n- Check memory/projects/ for projects marked \"Complete\" more than 30 days ago with no recent daily log mentions. Flag for archival in the summary (do not delete — the user decides).\n- Check MEMORY.md scheduled jobs table against actual cron jobs (openclaw cron list + crontab -l). Remove entries for crons that no longer exist. Add entries for crons not yet documented.\n\n## Tool Shed Audit (P4 Enforcement)\n\n- Read TOOLS.md. Scan today's daily logs for any CLI tools, APIs, or services that were USED but are NOT documented in TOOLS.md. Add missing entries with: what it is, how to access it, what it can do.\n- For tools already in TOOLS.md, check if today's logs reveal gotchas, failure modes, or usage notes not yet captured. Update existing entries.\n\n## Decision & Preference Audit (P5 Enforcement)\n\n- Scan today's daily logs for any decisions stated by the user that are NOT captured in project files, MEMORY.md, or USER.md.\n- For each uncaptured decision, write it to the appropriate file. Format: **Decision:** [what] — [why] (date)\n- Scan today's daily logs for any stated preferences NOT in memory/preferences.md. Phrases like 'I prefer', 'always do', 'I don't like', 'I want', 'don't ever' signal preferences.\n- For each uncaptured preference, append to memory/preferences.md under the right category. Format: **Preference:** [what] — [context/reasoning] (date). If contradicts existing, UPDATE existing.\n\n## Contact Audit\n\n- Scan today's daily logs for any people or organizations mentioned. For each, check if a file exists in memory/contacts/. If not and relevant, create one.\n- For existing contacts, update with new information from today's logs.\n\n## Workflow Audit\n\n- Scan today's daily logs for any workflows, pipelines, or multi-service processes. For each, check if a file exists in memory/workflows/. If not, create one.\n- For existing workflows, update if today's logs reveal changes or issues.\n\n## Debrief Recovery (P6 Enforcement)\n\n- Check today's daily logs for any sub-agent delegations. For each, verify a debrief entry exists. If missing, write a recovery debrief.\n\n## Shed Deferral Audit (P8 Enforcement)\n\n- Scan today's daily logs for instances where the agent deferred to the user. Cross-reference with TOOLS.md, INFRA.md, and memory/. Flag unnecessary deferrals.\n\n## Failure Root Cause (P7 Enforcement)\n\n- Scan today's daily logs for ❌ FAILURE: or 🔧 CORRECTION: entries. Verify root cause analysis exists. If missing, add it.\n\n## Cron Health\n\n- Run openclaw cron list and crontab -l. Verify no two jobs within 15 minutes. Fix MEMORY.md jobs table if out of sync.\n\n---\n\nBefore completing, append debrief to memory/YYYY-MM-DD.md.\nReply with brief summary.\n\nFile v3.5.17:references/weekly-synthesis.md\n\n# Weekly Synthesis — Instructions\n\nYou are an AI assistant. Weekly synthesis — higher-altitude review.\n\n**IMPORTANT:** Before writing to any file, check for /tmp/opencortex-distill.lock. If it exists and was created less than 10 minutes ago, wait 30 seconds and retry (up to 3 times). Before starting work, create this lockfile. Remove it when done. This prevents daily and weekly jobs from conflicting.\n\n1. Read archived daily logs from past 7 days (memory/archive/).\n2. Read all project files (memory/projects/), contact files (memory/contacts/), workflow files (memory/workflows/), and preferences (memory/preferences.md).\n3. Identify and act on:\n   a. Recurring problems → add to project Known Issues\n   b. Unfinished threads → add to Pending with last-touched date\n   c. Cross-project connections → add cross-references\n   d. Decisions this week → ensure captured with reasoning\n   e. New capabilities → verify in TOOLS.md with abilities (P4)\n   f. **Runbook detection** — identify any multi-step procedure (3+ steps) performed more than once this week, or likely to recur. Check if a runbook exists in memory/runbooks/. If not, create one with clear steps a sub-agent could follow. Update MEMORY.md runbooks index.\n   g. **Principle health** — read MEMORY.md principles section. Verify each principle has: clear intent, enforcement mechanism, and that the enforcement is actually reflected in the distillation cron. Flag any principle without enforcement.\n   h. **Contact review** — check memory/contacts/ for stale entries, missing contacts, or contacts that should be merged.\n   i. **Workflow review** — check memory/workflows/ for outdated descriptions or new workflows.\n   j. **Preference review** — read memory/preferences.md. Check for contradictions, stale preferences, and organization.\n   k. **Memory file reorganization** — review all memory files (projects, contacts, workflows, preferences, TOOLS.md) for organization quality. For files that have grown large or disorganized: merge duplicate entries, group related information together, ensure consistent formatting, and restructure sections when it would improve accessibility. Preserve ALL detail during reorganization — this is restructuring, not summarizing. Prioritize files that have had the most additions this week.\n   l. **Structural integrity audit** — verify information is in the correct file and section:\n      - Preferences in memory/preferences.md, NOT scattered across project files or MEMORY.md\n      - Decisions in the relevant project file, NOT in preferences.md or daily logs\n      - Tool/API documentation in TOOLS.md, NOT in project files or MEMORY.md\n      - Infrastructure details in INFRA.md (if it exists), NOT in TOOLS.md or project files\n      - Contact information in memory/contacts/, NOT embedded in project files\n      - Workflow/pipeline docs in memory/workflows/, NOT in project files or TOOLS.md\n      - Repeatable procedures (3+ steps) in memory/runbooks/, NOT left as inline notes\n      - MEMORY.md contains ONLY principles and the index — no project details, no tool docs, no preferences\n      - AGENTS.md contains ONLY operating protocol — no project-specific rules or preferences\n      - If anything is misplaced, move it to the correct location. Preserve all detail during the move.\n   m. **Retrieval quality check** — test memory_search with 3-5 queries based on this week's work (project names, key decisions, people mentioned). For each query, verify the top results are actually relevant. If retrieval misses information you know exists:\n      1. **Diagnose** — determine the cause: file too large (>50KB, needs splitting), information in the wrong file (structural integrity issue, move it), duplicate/scattered content (needs consolidation), or embeddings not configured/stale.\n      2. **Fix automatically** — for issues within the agent's control: split oversized files into focused sub-files, move misplaced content to the correct file (per item l), consolidate scattered duplicates, update MEMORY.md index to reflect new files.\n      3. **Escalate to user** — for issues requiring user action: embeddings not configured (suggest setup steps), persistent retrieval failures after restructuring (may need QMD backend or manual review).\n      4. **Track** — log each retrieval gap and its resolution in the weekly summary under a \"Retrieval Health\" section. If the same gap appears two weeks in a row without resolution, flag it prominently to the user.\n      5. **Verify** — re-test previously failed queries to confirm fixes worked. Note improvements or regressions.\n4. Write weekly summary to memory/archive/weekly-YYYY-MM-DD.md.\n\n## Runbook Detection\n\n- Review this week's daily logs for any multi-step procedure (3+ steps) that was performed more than once, or is likely to recur.\n- For each candidate: check if a runbook already exists in memory/runbooks/.\n- If not, create one with clear step-by-step instructions that a sub-agent could follow independently.\n- Update MEMORY.md runbooks index if new runbooks created.\n\n## Metrics Summary (if enabled)\n\n- If scripts/metrics.sh exists, run: bash scripts/metrics.sh --report --weeks 4\n- Include the output in your weekly summary.\n- If the compound score is declining or flat, note specific areas that need attention.\n\n---\n\nBefore completing, append debrief to memory/YYYY-MM-DD.md.\nReply with weekly summary.","readmeExcerpt":"Skill: OpenCortex Owner: JD2005L Summary: Self-improving memory architecture for OpenClaw agents. Structured memory files, nightly distillation, weekly synthesis, enforced principles (P0 for custom,... Tags: architecture:1.6.0, latest:3.5.18, memory:1.6.0, self-improving:1.6.0, voice:1.2.1 Version history: v3.5.18 | 2026-02-28T18:25:57.357Z | user Use --model default to clear cron model overrides (empty string silent","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# 1. Download the skill from your OpenClaw workspace directory\ncd ~/clawd    # or wherever your workspace is\nclawhub install opencortex\n\n# 2. Run the installer FROM YOUR WORKSPACE DIRECTORY (not from inside the skill folder)\nbash skills/opencortex/scripts/install.sh\n\n# Optional: preview what would be created without changing anything\nbash skills/opencortex/scripts/install.sh --dry-run"},{"language":"bash","snippet":"# 3. Verify everything is working (read-only — checks files and cron jobs, changes nothing)\nbash skills/opencortex/scripts/verify.sh"},{"language":"bash","snippet":"# 1. Download the latest version (run from workspace root)\nclawhub install opencortex --force\n\n# 2. Re-run the installer — it detects your existing install and offers to update\nbash skills/opencortex/scripts/install.sh"},{"language":"text","snippet":"SOUL.md          ← Identity, personality, boundaries\nAGENTS.md        ← Operating protocol, delegation rules\nMEMORY.md        ← Principles + memory index (< 3KB, loaded every session)\nTOOLS.md         ← Tool shed: APIs, scripts, and access methods with abilities descriptions\nINFRA.md         ← Infrastructure atlas: hosts, IPs, services, network\nUSER.md          ← Human's preferences, projects, communication style\nBOOTSTRAP.md     ← First-run checklist for new sessions\n\nmemory/\n  projects/      ← One file per project (distilled, not raw)\n  contacts/      ← One file per person/org (role, context, preferences)\n  workflows/     ← One file per workflow/pipeline (services, steps, issues)\n  runbooks/      ← Step-by-step procedures (delegatable to sub-agents)\n  preferences.md ← Cross-cutting user preferences by category\n  archive/       ← Archived daily logs + weekly summaries\n  YYYY-MM-DD.md  ← Today's working log (distilled nightly)"},{"language":"text","snippet":"Daily work → daily log\n  → nightly distill → routes to project/tools/infra/principles files\n                     → optimization pass (dedup, prune stale, condense)\n  → weekly synthesis → patterns, recurring problems, unfinished threads → auto-creates runbooks from repeated procedures → `memory/runbooks/`\nSub-agent work → debrief (P6) → daily log → same pipeline\nDecisions → captured with reasoning (P5) → never re-asked\nNew tools → documented with abilities (P4) → findable by intent"},{"language":"bash","snippet":"# From your OpenClaw workspace directory (e.g. ~/clawd)\nclawhub install opencortex\nbash skills/opencortex/scripts/install.sh\n\n# Preview without changing anything:\nbash skills/opencortex/scripts/install.sh --dry-run\n\n# Verify everything is working (read-only):\nbash skills/opencortex/scripts/verify.sh"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: OpenCortex\nhomepage: https://github.com/JD2005L/opencortex\ndescription: >\n  Self-improving memory architecture for OpenClaw agents. Structured memory files,\n  nightly distillation, weekly synthesis, enforced principles (P0 for custom, P1-P8 managed),\n  write-ahead durability, and model-agnostic delegation — so your agent\n  compounds knowledge instead of forgetting it. Includes opt-in metrics tracking with\n  growth charts and compound scoring to measure effectiveness over time. All sensitive features (voice profiling,\n  infrastructure auto-collection, git push) are OFF by default and require explicit\n  opt-in via environment variable or flag. Safe to install: no network calls during\n  setup, fully auditable bash scripts, isolated cron sessions scoped to workspace only.\n  Use when: (1) setting up a new OpenClaw instance, (2) user asks to improve/organize\n  memory, (3) user wants the agent to stop forgetting things, (4) bootstrapping a fresh\n  agent with best practices. NOT for: runtime memory_search queries (use built-in memory\n  tools). Triggers: \"set up memory\", \"organize yourself\", \"stop forgetting\", \"memory\n  architecture\", \"self-improving\", \"cortex\", \"bootstrap memory\", \"memory optimization\".\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"grep\",\"sed\",\"find\"],\"optionalBins\":[\"git\",\"gpg\",\"openssl\",\"openclaw\",\"secret-tool\",\"keyctl\",\"file\"]},\"env\":{\"CLAWD_WORKSPACE\":{\"description\":\"Workspace directory (defaults to cwd)\",\"required\":false},\"CLAWD_TZ\":{\"description\":\"Timezone for cron scheduling (defaults to UTC)\",\"required\":false},\"OPENCORTEX_VAULT_PASS\":{\"description\":\"Vault passphrase via env var. Prefer system keyring.\",\"required\":false,\"sensitive\":true},\"OPENCORTEX_VOICE_PROFILE\":{\"description\":\"Set to 1 to enable voice profiling in the nightly distillation cron. Off by default.\",\"required\":false,\"sensitive\":false},\"OPENCORTEX_INFRA_COLLECT\":{\"description\":\"Set to 1 to enable infrastructure auto-collection in the nightly distillation cron. Off by default.\",\"required\":false,\"sensitive\":false},\"OPENCORTEX_SCRUB_ALL\":{\"description\":\"Set to 1 to scrub all tracked files (not just known text types) during git backup. Off by default.\",\"required\":false,\"sensitive\":false},\"OPENCORTEX_ALLOW_FILE_PASSPHRASE\":{\"description\":\"Set to 1 to allow vault passphrase stored in a file (.vault/.passphrase). Off by default; prefer system keyring.\",\"required\":false,\"sensitive\":false}},\"sensitiveFiles\":[\".secrets-map\",\".vault/.passphrase\"],\"networkAccess\":\"Optional git push only (off by default, requires --push flag)\"}}\n---\n\n# OpenCortex — Self-Improving Memory Architecture\n\nTransform a default OpenClaw agent into one that compounds knowledge daily.\n\n📦 [Full source on GitHub](https://github.com/JD2005L/opencortex) — review the code, file issues, or contribute.\n\n## What This Does\n\n1. **Structures memory** into purpose-specific files instead of one flat dump\n2. **Installs nightly maintenance** that distills daily work into permanent knowledge\n3. **Installs weekly "},{"path":"README.md","content":"# 🧠 OpenCortex\n\n**Self-improving memory architecture for [OpenClaw](https://github.com/openclaw/openclaw) agents.**\n\nStop forgetting. Start compounding.\n\n---\n\n## The Problem\n\nOut of the box, OpenClaw agents dump everything into a flat `MEMORY.md`. Context fills up, compaction loses information, and the agent forgets what it learned last week. It's like having a brilliant employee with amnesia who takes notes on napkins.\n\n## The Solution\n\nOpenCortex transforms your agent into one that **gets smarter every day** through:\n\n- **Structured memory** — Purpose-specific files instead of one flat dump\n- **Nightly distillation** — Daily work automatically distilled into permanent knowledge\n- **Weekly synthesis** — Pattern detection across days catches recurring problems and unfinished threads\n- **Enforced principles** — Habits that prevent knowledge loss (decision capture, tool documentation, sub-agent debriefs)\n- **Write-ahead durability** — Agent writes decisions and preferences to memory before responding, so nothing is lost if the session ends or compacts mid-conversation\n- **Encrypted vault** — AES-256 encrypted secret storage with system keyring support\n- **Voice profiling** *(opt-in)* — Learns how your human communicates for authentic ghostwriting\n- **Infrastructure collection** *(opt-in)* — Auto-routes infrastructure details from daily logs to INFRA.md\n- **Safe git backup** *(opt-in)* — Automatic secret scrubbing in an isolated copy — workspace files are never modified\n\n## Quick Start\n\n**Prerequisites:** [OpenClaw](https://github.com/openclaw/openclaw) 2026.2.x+ and [ClawHub CLI](https://clawhub.com)\n\n```bash\n# From your OpenClaw workspace directory (e.g. ~/clawd)\nclawhub install opencortex\nbash skills/opencortex/scripts/install.sh\n\n# Preview without changing anything:\nbash skills/opencortex/scripts/install.sh --dry-run\n\n# Verify everything is working (read-only):\nbash skills/opencortex/scripts/verify.sh\n```\n\n**Important:** Run the installer from your workspace root, NOT from inside the skill folder.\n\nThe installer asks about optional features, creates files (won't overwrite existing ones), and registers cron jobs. It makes zero network calls.\n\nAfter install, customize:\n1. `SOUL.md` — personality and identity\n2. `USER.md` — info about your human\n3. `MEMORY.md` — principles and project index\n4. `TOOLS.md` — tools and APIs as you discover them\n5. `INFRA.md` — infrastructure reference\n6. `.secrets-map` — secrets for git scrubbing (if using git backup)\n\n### From Source\n\n```bash\ngit clone https://github.com/JD2005L/opencortex.git\ncd opencortex && bash scripts/install.sh\n```\n\n## Updating\n\n```bash\nclawhub install opencortex --force         # Download latest\nbash skills/opencortex/scripts/install.sh  # Detects existing install, offers Update\n```\n\nThe installer detects your existing version and offers: **1) Update** (recommended), **2) Full reinstall**, **3) Cancel.** It never overwrites files you've customized.\n\n### What the updater does\n\n| Content | Upda"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7e5n3qxtp49kdnhne6vr3wzd81n3sc\",\n  \"slug\": \"opencortex\",\n  \"version\": \"3.5.18\",\n  \"publishedAt\": 1772303157357\n}"},{"path":"references/architecture.md","content":"# OpenCortex Architecture Reference\n\n## Why This Exists\n\nDefault OpenClaw memory is a flat MEMORY.md that grows unbounded. Context fills up, compaction loses information, the agent forgets what it learned. OpenCortex solves this with:\n\n1. **Separation of concerns** — different files for different purposes\n2. **Nightly distillation** — raw daily logs → permanent structured knowledge\n3. **Weekly synthesis** — pattern detection across days\n4. **Principles** — enforced habits that prevent knowledge loss (P0 for custom, P1-P8 managed)\n5. **Sub-agent debrief loop** — delegated work feeds back into memory\n\n## File Purposes\n\n| File | Loaded at boot? | Purpose | Size target |\n|------|-----------------|---------|-------------|\n| MEMORY.md | Yes | Principles + index only | < 3KB |\n| TOOLS.md | Yes | Tool/API catalog with abilities | Grows with tools |\n| INFRA.md | Yes | Infrastructure reference | Grows with infra |\n| SOUL.md | Yes | Identity, personality | < 1KB |\n| AGENTS.md | Yes | Operating protocol | < 1KB |\n| USER.md | Yes | Human's preferences | < 1KB |\n| BOOTSTRAP.md | Yes | Session startup checklist | < 0.5KB |\n| memory/projects/*.md | On demand | Per-project knowledge | Any |\n| memory/contacts/*.md | On demand | Per-person/org knowledge | Any |\n| memory/workflows/*.md | On demand | Per-workflow/pipeline knowledge | Any |\n| memory/preferences.md | On demand | Cross-cutting user preferences by category | Any |\n| memory/runbooks/*.md | On demand | Procedures for sub-agents | Any |\n| memory/YYYY-MM-DD.md | Current day | Working log | Any |\n| memory/archive/*.md | Via search | Historical logs | Any |\n\n## Distillation Routes\n\nThe nightly cron reads daily logs and routes each piece of information:\n\n| Information type | Destination |\n|-----------------|-------------|\n| Project work, features, bugs | memory/projects/{project}.md |\n| New tool descriptions and capabilities | TOOLS.md (sensitive values → vault) |\n| Infrastructure changes | INFRA.md (if OPENCORTEX_INFRA_COLLECT=1) |\n| People and organizations mentioned | memory/contacts/{name}.md |\n| Workflows and pipelines described | memory/workflows/{name}.md |\n| Stated preferences and opinions | memory/preferences.md (categorized) |\n| Decisions and architectural directions | Relevant project file or MEMORY.md |\n| New principles, lessons | MEMORY.md |\n| User info and communication style | USER.md |\n| Scheduled job changes | MEMORY.md jobs table |\n| Repeatable procedures | memory/runbooks/ |\n\n## Preference Categories\n\nPreferences in `memory/preferences.md` are organized by category:\n\n| Category | Examples |\n|----------|---------|\n| Communication | \"No verbose explanations\", \"Direct messages only\" |\n| Code & Technical | \"Detailed commit messages\", \"Prefer TypeScript\" |\n| Workflow & Process | \"Check for messages before pushing\", \"Batch commits\" |\n| Scheduling & Time | \"Don't schedule before 9 AM\", \"Prefer async\" |\n| Tools & Services | \"Use VS Code over Vim\", \"Prefer Brave over Chrome\" |\n| Content & Media | \"720"},{"path":"references/distillation.md","content":"# Daily Memory Distillation — Instructions\n\nYou are an AI assistant. Daily memory maintenance task.\n\n**IMPORTANT:** Before writing to any file, check for /tmp/opencortex-distill.lock. If it exists and was created less than 10 minutes ago, wait 30 seconds and retry (up to 3 times). Before starting work, create this lockfile. Remove it when done. This prevents daily and weekly jobs from conflicting.\n\n## Part 1: Distillation\n\n1. Check memory/ for daily log files (YYYY-MM-DD.md, not in archive/).\n2. Distill ALL useful information into the right file:\n   - Project work → memory/projects/ (create new files if needed)\n   - New tool descriptions and capabilities → TOOLS.md (names, URLs, what they do)\n   - **IMPORTANT:** Never write passwords, tokens, or secrets into any file. For sensitive values, instruct the user to run: scripts/vault.sh set <key> <value>. Reference in docs as: vault:<key>\n   - Infrastructure changes → INFRA.md (ONLY if OPENCORTEX_INFRA_COLLECT=1 is set in the environment — otherwise skip infrastructure routing entirely)\n   - Contacts mentioned → memory/contacts/ (one file per person/org. Include: name, role/relationship, context, communication preferences, key interactions. Create new file if first mention, update existing if already known.)\n   - Workflows described → memory/workflows/ (one file per workflow/pipeline. Include: what it does, services involved, how to operate it, known issues. Create new file if first description.)\n   - Preferences stated → memory/preferences.md (append under the matching category: Communication, Code & Technical, Workflow & Process, Scheduling & Time, Tools & Services, Content & Media, Environment & Setup. Format: **Preference:** [what] — [context/reasoning] (date). Do NOT duplicate existing preferences — update them if the user changes their mind.)\n   - Decisions → relevant project file or MEMORY.md. Format: **Decision:** [what] — [why] (date)\n   - Principles, lessons → MEMORY.md\n   - Scheduled jobs → MEMORY.md jobs table\n   - User info and communication style → USER.md\n3. Synthesize, do not copy. Extract decisions, architecture, lessons, issues, capabilities, contacts, workflows, preferences.\n4. Move distilled logs to memory/archive/\n5. Update MEMORY.md index if new files created.\n\n## Part 2: Voice Profile\n\nONLY perform this section if OPENCORTEX_VOICE_PROFILE=1 is set in the environment. If not set, skip this section entirely.\n\n6. Read memory/VOICE.md. Review today's conversations for new patterns:\n   - New vocabulary, slang, shorthand the user uses\n   - How they phrase requests, decisions, reactions\n   - Tone shifts in different contexts\n   Append new observations to VOICE.md. Do not duplicate existing entries.\n\n## Optimization\n\n- Review memory/projects/ for duplicates, stale info, verbose sections. Fix directly.\n- Review memory/contacts/ — merge duplicates, update stale info, add missing context.\n- Review memory/workflows/ — verify accuracy, update if services or steps changed.\n- Review memory/pre"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1999,"uniquenessScore":44,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","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-04-15T00:45:39.800Z","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-04-17T06:03:27.103Z","emptyReason":null},"items":[{"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":"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-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","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"}]}}}