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 silently ignored by OpenClaw CLI)

v3.5.17 | 2026-02-28T18:18:14.620Z | user

Clear cron model overrides to gateway default via cron edit, skip updates when message and model already correct, model-agnostic for all providers

v3.5.15 | 2026-02-28T18:09:06.643Z | user

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.

v3.5.14 | 2026-02-28T08:02:05.493Z | user

Memory search index shown as optional info, not a warning. OpenCortex works without embeddings configured.

v3.5.13 | 2026-02-28T07:55:44.329Z | user

Remove cron model override detection from update.sh to reduce script size for scanner analysis, verify.sh handles model override warnings

v3.5.12 | 2026-02-28T07:52:47.596Z | user

Fix crash after subsection extraction from missing error guards on grep and tail pipelines under set -e

v3.5.11 | 2026-02-28T07:48:47.109Z | user

Fix subsection extraction crash from special characters in headers, use fixed-string grep matching, add error guards for set -e compatibility

v3.5.10 | 2026-02-28T07:43:59.610Z | user

Detect cron model overrides and provide manual TUI instructions, revert automated cron deletion for scanner compliance

v3.5.9 | 2026-02-28T07:40:06.489Z | user

Detect cron model overrides and provide manual TUI instructions, revert automated cron deletion for scanner compliance

v3.5.7 | 2026-02-28T07:36:06.952Z | user

Fix 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

v3.5.4 | 2026-02-28T07:22:12.297Z | user

Structural 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

v3.5.3 | 2026-02-28T07:11:43.662Z | user

Structural 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)

v3.5.0 | 2026-02-28T06:52:06.221Z | user

Structural cleanup: detect and resolve duplicate/orphan principles beyond P0-P8, clear cron model overrides, flag MEMORY.md bloat and non-standard sections

v3.4.18 | 2026-02-28T05:16:28.370Z | user

Documentation 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

v3.4.16 | 2026-02-28T05:06:26.313Z | user

verify.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.

v3.4.15 | 2026-02-28T04:22:13.468Z | user

Remove --model default from cron job edits and creation — OpenClaw gateway interprets it as literal model name, causing cron failures

v3.4.14 | 2026-02-28T04:03:12.546Z | user

Fix cron existence detection: use truncation-safe match strings for openclaw cron list output

Updater deduplicates Daily Memory Distillation and Weekly Synthesis cron jobs, removing extras created by prior truncation detection bug

v3.4.12 | 2026-02-28T03:57:01.189Z | user

Strict y/n input validation with retry loop across all prompts in install.sh and update.sh

v3.4.10 | 2026-02-28T03:40:02.184Z | user

Updater recreates missing Daily Memory Distillation and Weekly Synthesis cron jobs with timezone auto-detection instead of deferring to manual install

v3.4.9 | 2026-02-28T03:28:52.261Z | user

Self-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.

v3.4.6 | 2026-02-28T03:13:29.515Z | user

Auto-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.

v3.4.5 | 2026-02-28T02:59:10.449Z | user

Updater regenerates AGENTS.md and BOOTSTRAP.md directly with backup instead of deferring to install.sh

v3.4.4 | 2026-02-28T02:49:06.564Z | user

Show version number in update.sh output header

v3.4.3 | 2026-02-28T02:39:51.820Z | user

Comprehensive 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

v3.4.0 | 2026-02-28T02:19:50.848Z | user

Custom 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.

v3.2.5 | 2026-02-28T01:48:40.938Z | user

Updater 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.

v3.2.4 | 2026-02-28T01:39:52.551Z | user

Added 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"

v3.2.3 | 2026-02-28T01:25:26.979Z | user

Comprehensive updater: reference docs auto-updated, principle body changes detected via hash comparison, AGENTS.md and BOOTSTRAP.md content gap checks added

v3.2.1 | 2026-02-28T01:15:22.521Z | user

• Added mention of "write-ahead durability" to the memory architecture features.
• No code or functional changes; documentation only.

v3.2.0 | 2026-02-28T00:59:26.540Z | user

Added 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.

Added corresponding "Write Before Responding" section to the AGENTS.md template with a clear two-step protocol.

v3.1.5 | 2026-02-27T04:55:35.737Z | user

Fixed 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.

Fixed 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.

Cleared hardcoded model overrides from cron jobs during updates (uses gateway default).

v3.1.3 | 2026-02-26T00:56:18.827Z | user

verify.sh now warns about hardcoded model overrides in crons.

v3.1.2 | 2026-02-25T07:10:03.585Z | user

Update script clears hardcoded model overrides from crons

• 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 • Fresh installs already didn't hardcode models — this fixes existing installs that had them set from earlier versions

v3.1.1 | 2026-02-25T07:05:34.215Z | user

Update script clears hardcoded model overrides from crons

• 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 • Fresh installs already didn't hardcode models — this fixes existing installs that had them set from earlier versions

v3.1.0 | 2026-02-25T06:41:31.853Z | user

1. Cron messages now reference instruction files instead of inline ~5KB — saves tokens every run
2. Install asks Eager vs Lazy loading strategy
3. verify.sh warns if MEMORY.md exceeds 3KB budget

v3.0.7 | 2026-02-25T02:15:11.834Z | user

Fixes the install.sh line 573 error (nested double quotes). Also fixes verify.sh principle counting. Upload to ClawHub when ready.

v3.0.5 | 2026-02-25T01:50:32.633Z | user

Principle 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.

v3.0.1 | 2026-02-25T01:08:33.221Z | user

Full 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.

v3.0.0 | 2026-02-25T00:59:50.502Z | user

Contacts, 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.

v2.8.9 | 2026-02-24T20:02:46.981Z | user

Opt-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.

v2.8.7 | 2026-02-24T18:55:13.307Z | user

Update instructions in SKILL.md and README now point to install.sh instead of update.sh separately. One command to update.

v2.8.5 | 2026-02-24T18:42:02.410Z | user

Removed 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.

v2.8.4 | 2026-02-24T18:38:30.047Z | user

Install 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 • 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 • Metrics script auto-refreshed on update — if you already have metrics enabled, update.sh copies the latest metrics.sh to your workspace • Normal user flow works end-to-end — clawhub install --force → bash install.sh → detects install → offers Update → asks about new features → done

v2.8.3 | 2026-02-24T18:33:20.086Z | user

Install 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).

v2.8.1 | 2026-02-24T18:24:00.451Z | user

Version bump only to correct display name.

v2.8.0 | 2026-02-24T18:20:09.860Z | user

Metrics 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.

v2.7.0 | 2026-02-24T17:55:10.157Z | user

v2.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.

v2.6.0 | 2026-02-24T17:32:20.902Z | user

New 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.

v2.5.2 | 2026-02-24T17:22:01.715Z | user

Add 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.

v2.5.1 | 2026-02-24T17:10:53.508Z | user

Fix install instructions — must run from workspace root, not from inside skill folder. Files were being created in wrong location.

v2.5.0 | 2026-02-24T17:01:14.993Z | user

Major 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.

v2.4.5 | 2026-02-24T16:53:07.147Z | user

Remove npm install commands from docs, added note that installer makes no network calls.

v2.4.4 | 2026-02-24T16:46:30.081Z | user

Comprehensive install prerequisites (npm, openclaw, clawhub CLI), visible GitHub link on skill page, plain language throughout, cron time fix.

v2.4.3 | 2026-02-24T07:38:39.958Z | user

Fix 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.

v2.4.2 | 2026-02-24T07:24:44.596Z | user

Remove duplicate function definitions in vault.sh flagged by scanner as code quality issue.

v2.4.1 | 2026-02-24T07:17:31.153Z | user

Fix 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.

v2.4.0 | 2026-02-24T06:30:43.231Z | user

New 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.

v2.3.4 | 2026-02-24T05:36:09.027Z | user

Fix display name

v2.3.3 | 2026-02-24T05:33:04.651Z | user

GPG 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.

v2.3.2 | 2026-02-24T05:29:14.069Z | user

Declare 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.

v2.3.1 | 2026-02-24T05:27:02.795Z | user

Self-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.

v2.3.0 | 2026-02-24T05:05:10.172Z | user

Vault 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.

v2.2.3 | 2026-02-24T04:26:15.655Z | user

Address 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.

v2.2.2 | 2026-02-24T04:21:12.683Z | user

Security 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

v2.2.1 | 2026-02-24T04:18:14.665Z | user

Closed-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.

v2.2.0 | 2026-02-24T04:11:17.246Z | user

test

v2.1.0 | 2026-02-23T04:17:10.012Z | user

Vault passphrase rotation + key validation, pre-push scrub verification, cron lockfile safety, runbook auto-detection, dry-run mode

v2.0.2 | 2026-02-23T03:04:05.132Z | user

Add P4 enforcement line + Tool Shed Audit to distillation cron; fix display name to OpenCortex

v2.0.1 | 2026-02-23T02:47:07.954Z | user

Fix audit findings: declare required/optional binaries, fix vault passphrase-on-disk claim, add pre-flight dependency checks in installer

v2.0.0 | 2026-02-23T02:33:10.664Z | user

Added AES-256 encrypted vault for sensitive data. Secure mode default.

v1.6.1 | 2026-02-23T01:57:03.971Z | user

Bundled inspectable git scripts, manual-only self-update.

v1.6.0 | 2026-02-23T01:31:05.940Z | user

Removed supply chain risk: self-update manual-only, git scripts generated at install not bundled, zero network ops.

v1.5.1 | 2026-02-22T23:05:14.442Z | user

Comprehensive security documentation addressing every scanner category.

v1.5.0 | 2026-02-22T22:30:17.382Z | user

Git scripts now bundled as inspectable files (not generated at runtime). All credential references removed from cron instructions and metadata. No /root default paths.

v1.4.0 | 2026-02-22T22:24:12.559Z | user

Security 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.

v1.3.0 | 2026-02-22T18:33:01.851Z | user

Added P7: Log Failures

v1.2.1 | 2026-02-22T18:23:08.035Z | user

Fix display name to OpenCortex.

v1.2.0 | 2026-02-22T18:19:10.833Z | user

Comprehensive security transparency section, self-update runs first, voice profiling documented as optional/removable, no API key requirements.

v1.0.0 | 2026-02-22T18:07:06.018Z | user

Self-improving memory architecture with voice profiling for OpenClaw agents.

Archive index:

Archive v3.5.18: 12 files, 60983 bytes

Files: 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)

File v3.5.18:SKILL.md

---

name: OpenCortex homepage: https://github.com/JD2005L/opencortex description: > Self-improving memory architecture for OpenClaw agents. Structured memory files, nightly distillation, weekly synthesis, enforced principles (P0 for custom, P1-P8 managed), write-ahead durability, and model-agnostic delegation — so your agent compounds knowledge instead of forgetting it. Includes opt-in metrics tracking with growth charts and compound scoring to measure effectiveness over time. All sensitive features (voice profiling, infrastructure auto-collection, git push) are OFF by default and require explicit opt-in via environment variable or flag. Safe to install: no network calls during setup, fully auditable bash scripts, isolated cron sessions scoped to workspace only. Use when: (1) setting up a new OpenClaw instance, (2) user asks to improve/organize memory, (3) user wants the agent to stop forgetting things, (4) bootstrapping a fresh agent with best practices. NOT for: runtime memory_search queries (use built-in memory tools). Triggers: "set up memory", "organize yourself", "stop forgetting", "memory architecture", "self-improving", "cortex", "bootstrap memory", "memory optimization". metadata: {"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)"}}

OpenCortex — Self-Improving Memory Architecture

Transform a default OpenClaw agent into one that compounds knowledge daily.

📦 Full source on GitHub — review the code, file issues, or contribute.

What This Does

1. Structures memory into purpose-specific files instead of one flat dump
2. Installs nightly maintenance that distills daily work into permanent knowledge
3. Installs weekly synthesis that catches patterns across days
4. 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.
5. Builds a voice profile of your human from daily conversations for authentic ghostwriting (opt-in, requires OPENCORTEX_VOICE_PROFILE=1)
6. 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
7. Enables safe git backup with secret scrubbing (secrets never modified in your live workspace — scrubbed in an isolated copy only)
8. Tracks growth over time (opt-in) — daily metrics snapshots with compound scoring and ASCII growth charts

Installation

Prerequisites (install these separately if you don't have them):

• OpenClaw 2026.2.x+
• ClawHub CLI

# 1. Download the skill from your OpenClaw workspace directory
cd ~/clawd    # or wherever your workspace is
clawhub install opencortex

# 2. Run the installer FROM YOUR WORKSPACE DIRECTORY (not from inside the skill folder)
bash skills/opencortex/scripts/install.sh

# Optional: preview what would be created without changing anything
bash skills/opencortex/scripts/install.sh --dry-run

The 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.

# 3. Verify everything is working (read-only — checks files and cron jobs, changes nothing)
bash skills/opencortex/scripts/verify.sh

You can also ask your OpenClaw agent "is OpenCortex working?" — it knows how to run the verification and share results.

The script will:

• Create the file hierarchy (non-destructively — won't overwrite existing files)
• Create directory structure
• Set up cron jobs (daily distillation, weekly synthesis)
• Optionally set up git backup with secret scrubbing

After install, review and customize:

• SOUL.md — personality and identity (make it yours)
• USER.md — info about your human
• MEMORY.md — principles (add/remove as needed)
• .secrets-map — add your actual secrets for git scrubbing

Updating

# 1. Download the latest version (run from workspace root)
clawhub install opencortex --force

# 2. Re-run the installer — it detects your existing install and offers to update
bash skills/opencortex/scripts/install.sh

The 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.

Architecture

SOUL.md          ← Identity, personality, boundaries
AGENTS.md        ← Operating protocol, delegation rules
MEMORY.md        ← Principles + memory index (< 3KB, loaded every session)
TOOLS.md         ← Tool shed: APIs, scripts, and access methods with abilities descriptions
INFRA.md         ← Infrastructure atlas: hosts, IPs, services, network
USER.md          ← Human's preferences, projects, communication style
BOOTSTRAP.md     ← First-run checklist for new sessions

memory/
  projects/      ← One file per project (distilled, not raw)
  contacts/      ← One file per person/org (role, context, preferences)
  workflows/     ← One file per workflow/pipeline (services, steps, issues)
  runbooks/      ← Step-by-step procedures (delegatable to sub-agents)
  preferences.md ← Cross-cutting user preferences by category
  archive/       ← Archived daily logs + weekly summaries
  YYYY-MM-DD.md  ← Today's working log (distilled nightly)

Principles (installed by default)

| # | Name | Purpose | |---|------|---------| | P1 | Delegate First | Assess tasks for sub-agent delegation; stay available | | P2 | Write It Down | Commit to files, not mental notes | | P3 | Ask Before External | Confirm before emails, public posts, destructive ops | | P4 | Tool Shed & Workflows | Document tools and workflows; enforced by nightly audit | | P5 | Capture Decisions & Preferences | Record decisions and preferences; enforced by nightly + weekly audit | | P6 | Sub-agent Debrief | Delegated work feeds back to daily log; orphans recovered by distillation | | P7 | Log Failures | Tag failures/corrections; root cause analysis enforced by nightly audit | | P8 | Check the Shed First | Consult TOOLS.md/INFRA.md/memory before deferring work to user; enforced by nightly audit |

Cron Jobs (installed)

| Schedule | Name | What it does | |----------|------|-------------| | Daily 3 AM (local) | Distillation | Reads daily logs → distills into project/tools/infra files → audits tools/decisions/debriefs/failures → optimizes → archives | | Weekly Sunday 5 AM | Synthesis | Reviews week for patterns, recurring problems, unfinished threads, decisions; auto-creates runbooks from repeated procedures |

Both jobs use a shared lockfile (/tmp/opencortex-distill.lock) to prevent conflicts when daily and weekly runs overlap.

Customize times by editing cron jobs: openclaw cron list then openclaw cron edit <id> --cron "...".

Git Backup (optional)

If enabled during install, creates:

• scripts/git-backup.sh — auto-commit every 6 hours, scrubs secrets in an isolated temp copy (workspace files never modified)
• .secrets-map — maps secrets to placeholders (gitignored, 600 perms)

Add secrets to .secrets-map in format: actual_secret|{{PLACEHOLDER_NAME}}

Before 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.

Customization

Adding a project: Create memory/projects/my-project.md, add to MEMORY.md index.

Adding a contact: Create memory/contacts/name.md. Distillation auto-creates contacts from conversations.

Adding a workflow: Create memory/workflows/my-pipeline.md. Distillation auto-creates workflows when described.

Adding a preference: Append to memory/preferences.md under the right category. Distillation auto-captures from conversation.

Adding a principle: Append to MEMORY.md under 🔴 PRINCIPLES. Keep it short.

Adding a runbook: Create memory/runbooks/my-procedure.md. Sub-agents can follow these directly.

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).

How It Compounds

Daily work → daily log
  → nightly distill → routes to project/tools/infra/principles files
                     → optimization pass (dedup, prune stale, condense)
  → weekly synthesis → patterns, recurring problems, unfinished threads → auto-creates runbooks from repeated procedures → `memory/runbooks/`
Sub-agent work → debrief (P6) → daily log → same pipeline
Decisions → captured with reasoning (P5) → never re-asked
New tools → documented with abilities (P4) → findable by intent

Each day the agent wakes up slightly more knowledgeable and better organized.

File v3.5.18:README.md

🧠 OpenCortex

Self-improving memory architecture for OpenClaw agents.

Stop forgetting. Start compounding.

---

The Problem

Out 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.

The Solution

OpenCortex transforms your agent into one that gets smarter every day through:

• Structured memory — Purpose-specific files instead of one flat dump
• Nightly distillation — Daily work automatically distilled into permanent knowledge
• Weekly synthesis — Pattern detection across days catches recurring problems and unfinished threads
• Enforced principles — Habits that prevent knowledge loss (decision capture, tool documentation, sub-agent debriefs)
• Write-ahead durability — Agent writes decisions and preferences to memory before responding, so nothing is lost if the session ends or compacts mid-conversation
• Encrypted vault — AES-256 encrypted secret storage with system keyring support
• Voice profiling (opt-in) — Learns how your human communicates for authentic ghostwriting
• Infrastructure collection (opt-in) — Auto-routes infrastructure details from daily logs to INFRA.md
• Safe git backup (opt-in) — Automatic secret scrubbing in an isolated copy — workspace files are never modified

Quick Start

Prerequisites: OpenClaw 2026.2.x+ and ClawHub CLI

# From your OpenClaw workspace directory (e.g. ~/clawd)
clawhub install opencortex
bash skills/opencortex/scripts/install.sh

# Preview without changing anything:
bash skills/opencortex/scripts/install.sh --dry-run

# Verify everything is working (read-only):
bash skills/opencortex/scripts/verify.sh

Important: Run the installer from your workspace root, NOT from inside the skill folder.

The installer asks about optional features, creates files (won't overwrite existing ones), and registers cron jobs. It makes zero network calls.

After install, customize:

1. SOUL.md — personality and identity
2. USER.md — info about your human
3. MEMORY.md — principles and project index
4. TOOLS.md — tools and APIs as you discover them
5. INFRA.md — infrastructure reference
6. .secrets-map — secrets for git scrubbing (if using git backup)

From Source

git clone https://github.com/JD2005L/opencortex.git
cd opencortex && bash scripts/install.sh

Updating

clawhub install opencortex --force         # Download latest
bash skills/opencortex/scripts/install.sh  # Detects existing install, offers Update

The installer detects your existing version and offers: 1) Update (recommended), 2) Full reinstall, 3) Cancel. It never overwrites files you've customized.

What the updater does

| Content | Update method | User data safe? | |---------|--------------|-----------------| | Principles (P1-P8) | Hash comparison, asks before replacing | ✅ Asks y/N per principle | | P0 (Custom Principles) | Never touched | ✅ Your custom principles are always safe | | Helper scripts (verify, vault, metrics, git-backup) | Checksum comparison, auto-replaced | ✅ These aren't user-edited | | Reference docs (distillation, weekly-synthesis, architecture) | Checksum comparison, auto-replaced | ✅ These aren't user-edited | | Cron job messages | Always updated to latest template | ✅ Only the message text changes | | Cron model overrides | Cleared on every update | ✅ Gateway uses its configured default | | Cron deduplication | Detects and removes duplicate crons from prior bugs | ✅ Keeps the first, deletes extras | | Extra principles (P9+) | Detects duplicates and orphans, offers remove/migrate to P0 | ✅ Asks per principle | | MEMORY.md bloat | Warns if >5KB, flags non-standard sections | ✅ Suggests what to move | | Missing cron jobs | Offers to recreate with timezone auto-detection | ✅ Asks before creating | | MEMORY.md structure (## Identity, ## Memory Index) | Adds missing core sections | ✅ Existing sections untouched | | MEMORY.md index (### Infrastructure through ### Daily Logs) | Adds all 8 missing sub-sections | ✅ Existing sections untouched | | preferences.md | Created if missing | ✅ Existing file untouched | | New directories (contacts, workflows) | Created if missing | ✅ | | AGENTS.md | Merges: regenerates standard sections, preserves custom sections | ✅ Custom sections appended | | BOOTSTRAP.md | Merges: regenerates standard sections, preserves custom sections | ✅ Custom sections appended | | SOUL.md | Created if missing | ✅ Existing file untouched | | USER.md | Created if missing | ✅ Existing file untouched | | .gitignore | Adds missing sensitive entries (.vault/, .secrets-map, etc.) | ✅ Existing entries untouched |

---

Architecture

SOUL.md          ← Identity & personality
AGENTS.md        ← Operating protocol & delegation rules
MEMORY.md        ← Principles + index (< 3KB, loaded every session)
TOOLS.md         ← Tool shed: APIs, scripts with abilities descriptions
INFRA.md         ← Infrastructure atlas: hosts, IPs, services
USER.md          ← Your human's preferences
BOOTSTRAP.md     ← Session startup checklist

memory/
  projects/      ← One file per project (distilled, not raw)
  contacts/      ← One file per person/org (role, context, preferences)
  workflows/     ← One file per workflow/pipeline (services, steps, issues)
  runbooks/      ← Step-by-step procedures (delegatable to sub-agents)
  preferences.md ← Cross-cutting user preferences by category
  archive/       ← Archived daily logs + weekly summaries
  YYYY-MM-DD.md  ← Today's working log (distilled nightly)

Principles (P0–P8)

| # | Principle | What It Does | Enforcement | |---|-----------|-------------|-------------| | P0 | Custom Principles | Your own principles (P0-A, P0-B, etc.) | Never modified by updates | | P1 | Delegate First | Model-agnostic sub-agent delegation (Light/Medium/Heavy) | Agent protocol | | P2 | Write It Down | Write-ahead durability: save before responding | Agent protocol | | P3 | Ask Before External | Confirm before public/destructive actions | Agent protocol | | P4 | Tool Shed & Workflows | Document tools and workflows | Nightly audit scans for undocumented tools and workflows | | P5 | Capture Decisions & Preferences | Record decisions and preferences | Nightly + weekly audit for uncaptured decisions and preferences | | P6 | Sub-agent Debrief | Delegated work feeds back to daily log | Nightly audit recovers orphaned debriefs | | P7 | Log Failures | Tag failures with root cause analysis | Nightly audit checks for missing root causes | | P8 | Check the Shed First | Use documented tools before deferring to user | Nightly audit flags unnecessary deferrals |

How It Compounds

Week 1:  Agent knows basics, asks lots of questions
Week 4:  Agent has project history, knows tools, follows decisions
Week 12: Agent has deep institutional knowledge, patterns, runbooks
Week 52: Agent knows more about your setup than you remember

---

Security Model

Threat Model Summary

OpenCortex 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:

1. Autonomous cron jobs that read/write workspace files without human interaction
2. Optional features that collect sensitive data (voice patterns, infrastructure details)
3. Optional git backup that handles secret scrubbing before commits

OpenCortex contains zero network operations — no telemetry, no phone-home, no external endpoints. Every script is plain bash. Full source is public.

Default State: What's On and Off

| Feature | Default | Opt-In Required | What It Accesses | How to Disable | |---------|---------|----------------|-----------------|----------------| | Structured memory files | ✅ ON | — | Creates markdown files in workspace | Delete unwanted files | | Daily distillation cron | ✅ ON | — | Reads/writes memory/, MEMORY.md, TOOLS.md, USER.md | openclaw cron delete <id> | | Weekly synthesis cron | ✅ ON | — | Reads memory/archive/, writes summaries + runbooks | openclaw cron delete <id> | | Principle enforcement audits | ✅ ON | — | Part of distillation — audits within workspace | Remove audit sections from cron message | | Encrypted vault | Asked at install | Choose "direct" mode to skip | .vault/ directory, system keyring | Don't init vault; delete .vault/ | | Voice profiling | ❌ OFF | OPENCORTEX_VOICE_PROFILE=1 | Reads workspace conversation logs → memory/VOICE.md | Unset env var; delete memory/VOICE.md | | Infrastructure collection | ❌ OFF | OPENCORTEX_INFRA_COLLECT=1 | Routes infra mentions from daily logs → INFRA.md | Unset env var | | Git backup | ❌ OFF | Say "yes" at install | Commits workspace to git (local only by default) | Remove from crontab; delete scripts | | Git push to remote | ❌ OFF | --push flag on each run | Pushes scrubbed commits to remote | Don't pass --push | | Daily metrics tracking | ❌ OFF | Say "yes" at install | Read-only file counts → memory/metrics.log | Remove from crontab; delete metrics.log | | Broad file scrubbing | ❌ OFF | OPENCORTEX_SCRUB_ALL=1 | Scrubs all tracked files (not just known text types) | Unset env var | | File-based vault passphrase | ❌ OFF | OPENCORTEX_ALLOW_FILE_PASSPHRASE=1 | Stores passphrase at .vault/.passphrase | Unset env var; use system keyring |

What Runs Autonomously

Two cron jobs, both running as isolated OpenClaw agent sessions scoped to the workspace:

| Job | Schedule | Reads | Writes | Network Access | |-----|----------|-------|--------|----------------| | 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 | | 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 |

Both jobs:

• Use a shared lockfile (/tmp/opencortex-distill.lock) to prevent conflicts
• Contain no rm, system modifications, network calls, or external API access
• Reference only workspace-relative paths (memory/, MEMORY.md, TOOLS.md, etc.)
• Are fully inspectable: openclaw cron list
• Are fully removable: openclaw cron delete <id>

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.

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).

Git Backup Security

Git backup (when enabled) uses an isolated copy approach — your workspace files are never modified during scrubbing:

1. All files to commit are copied to a temp directory
2. Secrets are scrubbed in the copy only (using .secrets-map replacements)
3. The scrubbed copy is verified — if any raw secrets remain, the backup aborts immediately
4. A git commit is built from the scrubbed copy using git plumbing (hash-object, update-index, write-tree, commit-tree)
5. The temp directory is cleaned up
6. Your original workspace files are untouched throughout the entire process

Additional safeguards:

• .secrets-map and .vault/ are always gitignored (enforced at install)
• Pre-backup check aborts if either exists but isn't gitignored
• Push requires explicit --push flag — local-only by default
• .secrets-map has 600 permissions (owner-only read/write)

Recommendation: Test in a disposable repo first. Run the backup, inspect the commit diff, and confirm scrubbing works before pointing at a real remote.

Vault Security

The encrypted vault stores secrets at rest via GPG symmetric encryption (AES-256). Passphrase storage uses the best available backend (auto-detected):

| Priority | Backend | Passphrase Location | On Disk? | |----------|---------|-------------------|----------| | 1 | secret-tool (Linux keyring) | GNOME/KDE keyring | No | | 2 | macOS Keychain | Native macOS keystore | No | | 3 | keyctl (Linux kernel keyring) | Kernel memory | No | | 4 | Environment variable | OPENCORTEX_VAULT_PASS | No | | 5 | File fallback | .vault/.passphrase (mode 600) | Yes — requires OPENCORTEX_ALLOW_FILE_PASSPHRASE=1 |

Commands: vault.sh init, vault.sh set <key> <value>, vault.sh get <key>, vault.sh rotate, vault.sh migrate, vault.sh backend

Key names are validated on set (alphanumeric + underscores only).

Install Mechanism

The installer (scripts/install.sh) is a single bash script that:

• Creates markdown files (only if they don't already exist)
• Creates directories (memory/projects/, memory/contacts/, memory/workflows/, memory/runbooks/, memory/archive/)
• Registers OpenClaw cron jobs via openclaw cron add
• Optionally copies bundled git-backup.sh and vault.sh scripts to the workspace

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.

Credentials

OpenCortex 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.

Optional environment variables (all off by default):

| Variable | Purpose | Sensitive | |----------|---------|-----------| | CLAWD_WORKSPACE | Override workspace directory (defaults to cwd) | No | | CLAWD_TZ | Timezone for cron scheduling (defaults to UTC) | No | | OPENCORTEX_VAULT_PASS | Vault passphrase via env var (prefer keyring) | Yes | | OPENCORTEX_VOICE_PROFILE | Enable voice profiling in distillation | No | | OPENCORTEX_INFRA_COLLECT | Enable infrastructure auto-collection | No | | OPENCORTEX_SCRUB_ALL | Scrub all tracked files during git backup | No | | OPENCORTEX_ALLOW_FILE_PASSPHRASE | Allow file-based vault passphrase | No |

---

What to Review Before Installing

1. 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).
2. 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.
3. 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.
4. 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.
5. Test git backup in a disposable repo. Verify .secrets-map entries scrub correctly before using on a real remote.
6. 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.
7. Consider disabling voice profiling if you're uncomfortable with the agent building a persistent behavioral profile from conversations.

---

Metrics & Growth Tracking

If 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.

What's Tracked

| Metric | What It Measures | |--------|-----------------| | Knowledge files | Total files in memory/projects/, memory/contacts/, memory/workflows/, memory/runbooks/, and memory/ | | Knowledge size (KB) | Total size of knowledge files | | Decisions captured | **Decision:** entries across all memory files | | Preferences captured | **Preference:** entries in memory/preferences.md | | Contacts | People/orgs documented in memory/contacts/ | | Workflows | Pipelines/automations in memory/workflows/ | | Runbooks | Reusable procedures in memory/runbooks/ | | Tools documented | Entries in TOOLS.md | | Failures logged | ❌ FAILURE: and 🔧 CORRECTION: entries | | Debriefs | Sub-agent debrief entries in daily logs | | Projects | Files in memory/projects/ | | Archive files | Distilled daily logs in memory/archive/ |

Commands

# Snapshot today's metrics
bash scripts/metrics.sh --collect

# Show trends with ASCII growth charts + compound score
bash scripts/metrics.sh --report

# Last 4 weeks only
bash scripts/metrics.sh --report --weeks 4

# JSON output (for integrations)
bash scripts/metrics.sh --json

Or just ask your agent: "How is OpenCortex doing?" or "Show me OpenCortex metrics."

Compound Score

The report includes a 0–100 compound score reflecting knowledge depth, growth rate, and tracking consistency:

| Score | Rating | |-------|--------| | 80–100 | Thriving — deep knowledge, steady growth | | 60–79 | Growing — good foundation, building momentum | | 40–59 | Developing — basics in place, room to grow | | 20–39 | Getting started — early days | | 0–19 | Just installed — give it time |

A healthy OpenCortex installation trends upward over weeks. Flat or declining scores highlight specific areas to focus on.

Weekly Summary

If 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.

Security

The 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.

---

Customization

Add a project: Create memory/projects/my-project.md, add to MEMORY.md index. Nightly distillation routes relevant daily log entries to it.

Add a contact: Create memory/contacts/name.md with: name, role/relationship, context, communication preferences. Distillation auto-creates contacts mentioned in conversation.

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.

Add a preference: Append to memory/preferences.md under the right category. Format: **Preference:** [what] — [context] (date). Distillation auto-captures preferences stated in conversation.

Add a principle: Append to MEMORY.md under 🔴 PRINCIPLES. Keep it short.

Add a runbook: Create memory/runbooks/my-procedure.md with step-by-step instructions. Sub-agents follow these directly.

Add a tool: Add to TOOLS.md with: what it is, how to access it, goal-oriented abilities description.

Change cron schedule: openclaw cron list then openclaw cron edit <id> --cron "...".

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.

Requirements

• OpenClaw 2026.2.x+
• Required: grep, sed, find (standard on most systems)
• Optional: git (for backup), gpg (for vault), openssl (for passphrase generation)

License

MIT

Credits

Created by JD2005L

File v3.5.18:_meta.json

{ "ownerId": "kn7e5n3qxtp49kdnhne6vr3wzd81n3sc", "slug": "opencortex", "version": "3.5.18", "publishedAt": 1772303157357 }

File v3.5.18:references/architecture.md

OpenCortex Architecture Reference

Why This Exists

Default 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:

1. Separation of concerns — different files for different purposes
2. Nightly distillation — raw daily logs → permanent structured knowledge
3. Weekly synthesis — pattern detection across days
4. Principles — enforced habits that prevent knowledge loss (P0 for custom, P1-P8 managed)
5. Sub-agent debrief loop — delegated work feeds back into memory

File Purposes

| File | Loaded at boot? | Purpose | Size target | |------|-----------------|---------|-------------| | MEMORY.md | Yes | Principles + index only | < 3KB | | TOOLS.md | Yes | Tool/API catalog with abilities | Grows with tools | | INFRA.md | Yes | Infrastructure reference | Grows with infra | | SOUL.md | Yes | Identity, personality | < 1KB | | AGENTS.md | Yes | Operating protocol | < 1KB | | USER.md | Yes | Human's preferences | < 1KB | | BOOTSTRAP.md | Yes | Session startup checklist | < 0.5KB | | memory/projects/.md | On demand | Per-project knowledge | Any | | memory/contacts/.md | On demand | Per-person/org knowledge | Any | | memory/workflows/.md | On demand | Per-workflow/pipeline knowledge | Any | | memory/preferences.md | On demand | Cross-cutting user preferences by category | Any | | memory/runbooks/.md | On demand | Procedures for sub-agents | Any | | memory/YYYY-MM-DD.md | Current day | Working log | Any | | memory/archive/*.md | Via search | Historical logs | Any |

Distillation Routes

The nightly cron reads daily logs and routes each piece of information:

| Information type | Destination | |-----------------|-------------| | Project work, features, bugs | memory/projects/{project}.md | | New tool descriptions and capabilities | TOOLS.md (sensitive values → vault) | | Infrastructure changes | INFRA.md (if OPENCORTEX_INFRA_COLLECT=1) | | People and organizations mentioned | memory/contacts/{name}.md | | Workflows and pipelines described | memory/workflows/{name}.md | | Stated preferences and opinions | memory/preferences.md (categorized) | | Decisions and architectural directions | Relevant project file or MEMORY.md | | New principles, lessons | MEMORY.md | | User info and communication style | USER.md | | Scheduled job changes | MEMORY.md jobs table | | Repeatable procedures | memory/runbooks/ |

Preference Categories

Preferences in memory/preferences.md are organized by category:

| Category | Examples | |----------|---------| | Communication | "No verbose explanations", "Direct messages only" | | Code & Technical | "Detailed commit messages", "Prefer TypeScript" | | Workflow & Process | "Check for messages before pushing", "Batch commits" | | Scheduling & Time | "Don't schedule before 9 AM", "Prefer async" | | Tools & Services | "Use VS Code over Vim", "Prefer Brave over Chrome" | | Content & Media | "720p minimum", "No dubbed content" | | Environment & Setup | "Dark mode everywhere", "Dual monitor layout" |

Format: **Preference:** [what] — [context/reasoning] (date)

Preferences are auto-captured from conversation when the user says "I prefer", "always do", "I don't like", etc. Contradicted preferences are updated (not duplicated).

Compounding Effect

Week 1:  Agent knows basics, asks lots of questions
Week 4:  Agent has project history, knows tools, follows decisions, remembers preferences
Week 12: Agent has deep institutional knowledge, patterns, runbooks, contact history
Week 52: Agent knows more about the setup than most humans would remember

The 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.

Common Customizations

Adding delegation tiers

Edit 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.

Changing distillation schedule

openclaw cron edit <id> --cron "0 10 * * *" --tz "Your/Timezone"

Adding custom principles

All 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:

• Route all new principle requests to P0, even if the user asks for P9 or beyond
• Check for conflicts with P1-P8 before adding
• Assess whether the request is truly a principle (persistent behavioral rule) or would be better suited as a preference, decision, runbook, or agent rule

Write-ahead durability (P2)

When 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.

Memory health monitoring

The weekly synthesis includes automated checks that maintain memory quality over time:

• Structural integrity audit — verifies information is in the correct file (preferences in preferences.md, tools in TOOLS.md, etc.) and moves misplaced content.
• Memory file reorganization — merges duplicates, groups related info, restructures growing files while preserving all detail.
• 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.
• Stale content cleanup — flags completed projects for archival, syncs MEMORY.md cron table against actual cron jobs.

The verify.sh script also checks memory search index health, file count, and MEMORY.md boot size.

Multi-bot setups

Each bot gets its own OpenCortex install. Share knowledge via:

• Common git repo (read-only for non-primary bots)
• SSH-based management (primary bot propagates changes)
• Shared NFS/SMB mount for common reference docs

File v3.5.18:references/distillation.md

Daily Memory Distillation — Instructions

You are an AI assistant. Daily memory maintenance task.

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.

Part 1: Distillation

1. Check memory/ for daily log files (YYYY-MM-DD.md, not in archive/).
2. Distill ALL useful information into the right file:
   • Project work → memory/projects/ (create new files if needed)
   • New tool descriptions and capabilities → TOOLS.md (names, URLs, what they do)
   • 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>
   • Infrastructure changes → INFRA.md (ONLY if OPENCORTEX_INFRA_COLLECT=1 is set in the environment — otherwise skip infrastructure routing entirely)
   • 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.)
   • 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.)
   • 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.)
   • Decisions → relevant project file or MEMORY.md. Format: Decision: [what] — [why] (date)
   • Principles, lessons → MEMORY.md
   • Scheduled jobs → MEMORY.md jobs table
   • User info and communication style → USER.md
3. Synthesize, do not copy. Extract decisions, architecture, lessons, issues, capabilities, contacts, workflows, preferences.
4. Move distilled logs to memory/archive/
5. Update MEMORY.md index if new files created.

Part 2: Voice Profile

ONLY perform this section if OPENCORTEX_VOICE_PROFILE=1 is set in the environment. If not set, skip this section entirely.

1. Read memory/VOICE.md. Review today's conversations for new patterns:
   • New vocabulary, slang, shorthand the user uses
   • How they phrase requests, decisions, reactions
   • Tone shifts in different contexts Append new observations to VOICE.md. Do not duplicate existing entries.

Optimization

• Review memory/projects/ for duplicates, stale info, verbose sections. Fix directly.
• Review memory/contacts/ — merge duplicates, update stale info, add missing context.
• Review memory/workflows/ — verify accuracy, update if services or steps changed.
• Review memory/preferences.md — remove contradicted preferences (user changed mind), merge duplicates, ensure categories are correct.
• Review MEMORY.md: verify index accuracy, principles concise, jobs table current.
• Review TOOLS.md and (if OPENCORTEX_INFRA_COLLECT=1) INFRA.md: remove stale entries, verify descriptions.

Stale Content Cleanup

• 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).
• 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.

Tool Shed Audit (P4 Enforcement)

• 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.
• For tools already in TOOLS.md, check if today's logs reveal gotchas, failure modes, or usage notes not yet captured. Update existing entries.

Decision & Preference Audit (P5 Enforcement)

• Scan today's daily logs for any decisions stated by the user that are NOT captured in project files, MEMORY.md, or USER.md.
• For each uncaptured decision, write it to the appropriate file. Format: Decision: [what] — [why] (date)
• 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.
• For each uncaptured preference, append to memory/preferences.md under the right category. Format: Preference: [what] — [context/reasoning] (date). If contradicts existing, UPDATE existing.

Contact Audit

• 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.
• For existing contacts, update with new information from today's logs.

Workflow Audit

• 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.
• For existing workflows, update if today's logs reveal changes or issues.

Debrief Recovery (P6 Enforcement)

• Check today's daily logs for any sub-agent delegations. For each, verify a debrief entry exists. If missing, write a recovery debrief.

Shed Deferral Audit (P8 Enforcement)

• 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.

Failure Root Cause (P7 Enforcement)

• Scan today's daily logs for ❌ FAILURE: or 🔧 CORRECTION: entries. Verify root cause analysis exists. If missing, add it.

Cron Health

• Run openclaw cron list and crontab -l. Verify no two jobs within 15 minutes. Fix MEMORY.md jobs table if out of sync.

---

Before completing, append debrief to memory/YYYY-MM-DD.md. Reply with brief summary.

File v3.5.18:references/weekly-synthesis.md

Weekly Synthesis — Instructions

You are an AI assistant. Weekly synthesis — higher-altitude review.

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.

1. Read archived daily logs from past 7 days (memory/archive/).
2. Read all project files (memory/projects/), contact files (memory/contacts/), workflow files (memory/workflows/), and preferences (memory/preferences.md).
3. Identify and act on: a. Recurring problems → add to project Known Issues b. Unfinished threads → add to Pending with last-touched date c. Cross-project connections → add cross-references d. Decisions this week → ensure captured with reasoning e. New capabilities → verify in TOOLS.md with abilities (P4) 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. 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. h. Contact review — check memory/contacts/ for stale entries, missing contacts, or contacts that should be merged. i. Workflow review — check memory/workflows/ for outdated descriptions or new workflows. j. Preference review — read memory/preferences.md. Check for contradictions, stale preferences, and organization. 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. l. Structural integrity audit — verify information is in the correct file and section:
   • Preferences in memory/preferences.md, NOT scattered across project files or MEMORY.md
   • Decisions in the relevant project file, NOT in preferences.md or daily logs
   • Tool/API documentation in TOOLS.md, NOT in project files or MEMORY.md
   • Infrastructure details in INFRA.md (if it exists), NOT in TOOLS.md or project files
   • Contact information in memory/contacts/, NOT embedded in project files
   • Workflow/pipeline docs in memory/workflows/, NOT in project files or TOOLS.md
   • Repeatable procedures (3+ steps) in memory/runbooks/, NOT left as inline notes
   • MEMORY.md contains ONLY principles and the index — no project details, no tool docs, no preferences
   • AGENTS.md contains ONLY operating protocol — no project-specific rules or preferences
   • If anything is misplaced, move it to the correct location. Preserve all detail during the move. 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:
   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.
   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.
   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).
   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.
   5. Verify — re-test previously failed queries to confirm fixes worked. Note improvements or regressions.
4. Write weekly summary to memory/archive/weekly-YYYY-MM-DD.md.

Runbook Detection

• Review this week's daily logs for any multi-step procedure (3+ steps) that was performed more than once, or is likely to recur.
• For each candidate: check if a runbook already exists in memory/runbooks/.
• If not, create one with clear step-by-step instructions that a sub-agent could follow independently.
• Update MEMORY.md runbooks index if new runbooks created.

Metrics Summary (if enabled)

• If scripts/metrics.sh exists, run: bash scripts/metrics.sh --report --weeks 4
• Include the output in your weekly summary.
• If the compound score is declining or flat, note specific areas that need attention.

---

Before completing, append debrief to memory/YYYY-MM-DD.md. Reply with weekly summary.

Archive v3.5.17: 12 files, 60985 bytes

Files: 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)

File v3.5.17:SKILL.md

---

name: OpenCortex homepage: https://github.com/JD2005L/opencortex description: > Self-improving memory architecture for OpenClaw agents. Structured memory files, nightly distillation, weekly synthesis, enforced principles (P0 for custom, P1-P8 managed), write-ahead durability, and model-agnostic delegation — so your agent compounds knowledge instead of forgetting it. Includes opt-in metrics tracking with growth charts and compound scoring to measure effectiveness over time. All sensitive features (voice profiling, infrastructure auto-collection, git push) are OFF by default and require explicit opt-in via environment variable or flag. Safe to install: no network calls during setup, fully auditable bash scripts, isolated cron sessions scoped to workspace only. Use when: (1) setting up a new OpenClaw instance, (2) user asks to improve/organize memory, (3) user wants the agent to stop forgetting things, (4) bootstrapping a fresh agent with best practices. NOT for: runtime memory_search queries (use built-in memory tools). Triggers: "set up memory", "organize yourself", "stop forgetting", "memory architecture", "self-improving", "cortex", "bootstrap memory", "memory optimization". metadata: {"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)"}}

OpenCortex — Self-Improving Memory Architecture

Transform a default OpenClaw agent into one that compounds knowledge daily.

📦 Full source on GitHub — review the code, file issues, or contribute.

What This Does

1. Structures memory into purpose-specific files instead of one flat dump
2. Installs nightly maintenance that distills daily work into permanent knowledge
3. Installs weekly synthesis that catches patterns across days
4. 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.
5. Builds a voice profile of your human from daily conversations for authentic ghostwriting (opt-in, requires OPENCORTEX_VOICE_PROFILE=1)
6. 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
7. Enables safe git backup with secret scrubbing (secrets never modified in your live workspace — scrubbed in an isolated copy only)
8. Tracks growth over time (opt-in) — daily metrics snapshots with compound scoring and ASCII growth charts

Installation

Prerequisites (install these separately if you don't have them):

• OpenClaw 2026.2.x+
• ClawHub CLI

# 1. Download the skill from your OpenClaw workspace directory
cd ~/clawd    # or wherever your workspace is
clawhub install opencortex

# 2. Run the installer FROM YOUR WORKSPACE DIRECTORY (not from inside the skill folder)
bash skills/opencortex/scripts/install.sh

# Optional: preview what would be created without changing anything
bash skills/opencortex/scripts/install.sh --dry-run

The 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.

# 3. Verify everything is working (read-only — checks files and cron jobs, changes nothing)
bash skills/opencortex/scripts/verify.sh

You can also ask your OpenClaw agent "is OpenCortex working?" — it knows how to run the verification and share results.

The script will:

• Create the file hierarchy (non-destructively — won't overwrite existing files)
• Create directory structure
• Set up cron jobs (daily distillation, weekly synthesis)
• Optionally set up git backup with secret scrubbing

After install, review and customize:

• SOUL.md — personality and identity (make it yours)
• USER.md — info about your human
• MEMORY.md — principles (add/remove as needed)
• .secrets-map — add your actual secrets for git scrubbing

Updating

# 1. Download the latest version (run from workspace root)
clawhub install opencortex --force

# 2. Re-run the installer — it detects your existing install and offers to update
bash skills/opencortex/scripts/install.sh

The 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.

Architecture

SOUL.md          ← Identity, personality, boundaries
AGENTS.md        ← Operating protocol, delegation rules
MEMORY.md        ← Principles + memory index (< 3KB, loaded every session)
TOOLS.md         ← Tool shed: APIs, scripts, and access methods with abilities descriptions
INFRA.md         ← Infrastructure atlas: hosts, IPs, services, network
USER.md          ← Human's preferences, projects, communication style
BOOTSTRAP.md     ← First-run checklist for new sessions

memory/
  projects/      ← One file per project (distilled, not raw)
  contacts/      ← One file per person/org (role, context, preferences)
  workflows/     ← One file per workflow/pipeline (services, steps, issues)
  runbooks/      ← Step-by-step procedures (delegatable to sub-agents)
  preferences.md ← Cross-cutting user preferences by category
  archive/       ← Archived daily logs + weekly summaries
  YYYY-MM-DD.md  ← Today's working log (distilled nightly)

Principles (installed by default)

| # | Name | Purpose | |---|------|---------| | P1 | Delegate First | Assess tasks for sub-agent delegation; stay available | | P2 | Write It Down | Commit to files, not mental notes | | P3 | Ask Before External | Confirm before emails, public posts, destructive ops | | P4 | Tool Shed & Workflows | Document tools and workflows; enforced by nightly audit | | P5 | Capture Decisions & Preferences | Record decisions and preferences; enforced by nightly + weekly audit | | P6 | Sub-agent Debrief | Delegated work feeds back to daily log; orphans recovered by distillation | | P7 | Log Failures | Tag failures/corrections; root cause analysis enforced by nightly audit | | P8 | Check the Shed First | Consult TOOLS.md/INFRA.md/memory before deferring work to user; enforced by nightly audit |

Cron Jobs (installed)

| Schedule | Name | What it does | |----------|------|-------------| | Daily 3 AM (local) | Distillation | Reads daily logs → distills into project/tools/infra files → audits tools/decisions/debriefs/failures → optimizes → archives | | Weekly Sunday 5 AM | Synthesis | Reviews week for patterns, recurring problems, unfinished threads, decisions; auto-creates runbooks from repeated procedures |

Both jobs use a shared lockfile (/tmp/opencortex-distill.lock) to prevent conflicts when daily and weekly runs overlap.

Customize times by editing cron jobs: openclaw cron list then openclaw cron edit <id> --cron "...".

Git Backup (optional)

If enabled during install, creates:

• scripts/git-backup.sh — auto-commit every 6 hours, scrubs secrets in an isolated temp copy (workspace files never modified)
• .secrets-map — maps secrets to placeholders (gitignored, 600 perms)

Add secrets to .secrets-map in format: actual_secret|{{PLACEHOLDER_NAME}}

Before 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.

Customization

Adding a project: Create memory/projects/my-project.md, add to MEMORY.md index.

Adding a contact: Create memory/contacts/name.md. Distillation auto-creates contacts from conversations.

Adding a workflow: Create memory/workflows/my-pipeline.md. Distillation auto-creates workflows when described.

Adding a preference: Append to memory/preferences.md under the right category. Distillation auto-captures from conversation.

Adding a principle: Append to MEMORY.md under 🔴 PRINCIPLES. Keep it short.

Adding a runbook: Create memory/runbooks/my-procedure.md. Sub-agents can follow these directly.

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).

How It Compounds

Daily work → daily log
  → nightly distill → routes to project/tools/infra/principles files
                     → optimization pass (dedup, prune stale, condense)
  → weekly synthesis → patterns, recurring problems, unfinished threads → auto-creates runbooks from repeated procedures → `memory/runbooks/`
Sub-agent work → debrief (P6) → daily log → same pipeline
Decisions → captured with reasoning (P5) → never re-asked
New tools → documented with abilities (P4) → findable by intent

Each day the agent wakes up slightly more knowledgeable and better organized.

File v3.5.17:README.md

🧠 OpenCortex

Self-improving memory architecture for OpenClaw agents.

Stop forgetting. Start compounding.

---

The Problem

Out 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.

The Solution

OpenCortex transforms your agent into one that gets smarter every day through:

• Structured memory — Purpose-specific files instead of one flat dump
• Nightly distillation — Daily work automatically distilled into permanent knowledge
• Weekly synthesis — Pattern detection across days catches recurring problems and unfinished threads
• Enforced principles — Habits that prevent knowledge loss (decision capture, tool documentation, sub-agent debriefs)
• Write-ahead durability — Agent writes decisions and preferences to memory before responding, so nothing is lost if the session ends or compacts mid-conversation
• Encrypted vault — AES-256 encrypted secret storage with system keyring support
• Voice profiling (opt-in) — Learns how your human communicates for authentic ghostwriting
• Infrastructure collection (opt-in) — Auto-routes infrastructure details from daily logs to INFRA.md
• Safe git backup (opt-in) — Automatic secret scrubbing in an isolated copy — workspace files are never modified

Quick Start

Prerequisites: OpenClaw 2026.2.x+ and ClawHub CLI

# From your OpenClaw workspace directory (e.g. ~/clawd)
clawhub install opencortex
bash skills/opencortex/scripts/install.sh

# Preview without changing anything:
bash skills/opencortex/scripts/install.sh --dry-run

# Verify everything is working (read-only):
bash skills/opencortex/scripts/verify.sh

Important: Run the installer from your workspace root, NOT from inside the skill folder.

The installer asks about optional features, creates files (won't overwrite existing ones), and registers cron jobs. It makes zero network calls.

After install, customize:

1. SOUL.md — personality and identity
2. USER.md — info about your human
3. MEMORY.md — principles and project index
4. TOOLS.md — tools and APIs as you discover them
5. INFRA.md — infrastructure reference
6. .secrets-map — secrets for git scrubbing (if using git backup)

From Source

git clone https://github.com/JD2005L/opencortex.git
cd opencortex && bash scripts/install.sh

Updating

clawhub install opencortex --force         # Download latest
bash skills/opencortex/scripts/install.sh  # Detects existing install, offers Update

The installer detects your existing version and offers: 1) Update (recommended), 2) Full reinstall, 3) Cancel. It never overwrites files you've customized.

What the updater does

| Content | Update method | User data safe? | |---------|--------------|-----------------| | Principles (P1-P8) | Hash comparison, asks before replacing | ✅ Asks y/N per principle | | P0 (Custom Principles) | Never touched | ✅ Your custom principles are always safe | | Helper scripts (verify, vault, metrics, git-backup) | Checksum comparison, auto-replaced | ✅ These aren't user-edited | | Reference docs (distillation, weekly-synthesis, architecture) | Checksum comparison, auto-replaced | ✅ These aren't user-edited | | Cron job messages | Always updated to latest template | ✅ Only the message text changes | | Cron model overrides | Cleared on every update | ✅ Gateway uses its configured default | | Cron deduplication | Detects and removes duplicate crons from prior bugs | ✅ Keeps the first, deletes extras | | Extra principles (P9+) | Detects duplicates and orphans, offers remove/migrate to P0 | ✅ Asks per principle | | MEMORY.md bloat | Warns if >5KB, flags non-standard sections | ✅ Suggests what to move | | Missing cron jobs | Offers to recreate with timezone auto-detection | ✅ Asks before creating | | MEMORY.md structure (## Identity, ## Memory Index) | Adds missing core sections | ✅ Existing sections untouched | | MEMORY.md index (### Infrastructure through ### Daily Logs) | Adds all 8 missing sub-sections | ✅ Existing sections untouched | | preferences.md | Created if missing | ✅ Existing file untouched | | New directories (contacts, workflows) | Created if missing | ✅ | | AGENTS.md | Merges: regenerates standard sections, preserves custom sections | ✅ Custom sections appended | | BOOTSTRAP.md | Merges: regenerates standard sections, preserves custom sections | ✅ Custom sections appended | | SOUL.md | Created if missing | ✅ Existing file untouched | | USER.md | Created if missing | ✅ Existing file untouched | | .gitignore | Adds missing sensitive entries (.vault/, .secrets-map, etc.) | ✅ Existing entries untouched |

---

Architecture

SOUL.md          ← Identity & personality
AGENTS.md        ← Operating protocol & delegation rules
MEMORY.md        ← Principles + index (< 3KB, loaded every session)
TOOLS.md         ← Tool shed: APIs, scripts with abilities descriptions
INFRA.md         ← Infrastructure atlas: hosts, IPs, services
USER.md          ← Your human's preferences
BOOTSTRAP.md     ← Session startup checklist

memory/
  projects/      ← One file per project (distilled, not raw)
  contacts/      ← One file per person/org (role, context, preferences)
  workflows/     ← One file per workflow/pipeline (services, steps, issues)
  runbooks/      ← Step-by-step procedures (delegatable to sub-agents)
  preferences.md ← Cross-cutting user preferences by category
  archive/       ← Archived daily logs + weekly summaries
  YYYY-MM-DD.md  ← Today's working log (distilled nightly)

Principles (P0–P8)

| # | Principle | What It Does | Enforcement | |---|-----------|-------------|-------------| | P0 | Custom Principles | Your own principles (P0-A, P0-B, etc.) | Never modified by updates | | P1 | Delegate First | Model-agnostic sub-agent delegation (Light/Medium/Heavy) | Agent protocol | | P2 | Write It Down | Write-ahead durability: save before responding | Agent protocol | | P3 | Ask Before External | Confirm before public/destructive actions | Agent protocol | | P4 | Tool Shed & Workflows | Document tools and workflows | Nightly audit scans for undocumented tools and workflows | | P5 | Capture Decisions & Preferences | Record decisions and preferences | Nightly + weekly audit for uncaptured decisions and preferences | | P6 | Sub-agent Debrief | Delegated work feeds back to daily log | Nightly audit recovers orphaned debriefs | | P7 | Log Failures | Tag failures with root cause analysis | Nightly audit checks for missing root causes | | P8 | Check the Shed First | Use documented tools before deferring to user | Nightly audit flags unnecessary deferrals |

How It Compounds

Week 1:  Agent knows basics, asks lots of questions
Week 4:  Agent has project history, knows tools, follows decisions
Week 12: Agent has deep institutional knowledge, patterns, runbooks
Week 52: Agent knows more about your setup than you remember

---

Security Model

Threat Model Summary

OpenCortex 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:

1. Autonomous cron jobs that read/write workspace files without human interaction
2. Optional features that collect sensitive data (voice patterns, infrastructure details)
3. Optional git backup that handles secret scrubbing before commits

OpenCortex contains zero network operations — no telemetry, no phone-home, no external endpoints. Every script is plain bash. Full source is public.

Default State: What's On and Off

| Feature | Default | Opt-In Required | What It Accesses | How to Disable | |---------|---------|----------------|-----------------|----------------| | Structured memory files | ✅ ON | — | Creates markdown files in workspace | Delete unwanted files | | Daily distillation cron | ✅ ON | — | Reads/writes memory/, MEMORY.md, TOOLS.md, USER.md | openclaw cron delete <id> | | Weekly synthesis cron | ✅ ON | — | Reads memory/archive/, writes summaries + runbooks | openclaw cron delete <id> | | Principle enforcement audits | ✅ ON | — | Part of distillation — audits within workspace | Remove audit sections from cron message | | Encrypted vault | Asked at install | Choose "direct" mode to skip | .vault/ directory, system keyring | Don't init vault; delete .vault/ | | Voice profiling | ❌ OFF | OPENCORTEX_VOICE_PROFILE=1 | Reads workspace conversation logs → memory/VOICE.md | Unset env var; delete memory/VOICE.md | | Infrastructure collection | ❌ OFF | OPENCORTEX_INFRA_COLLECT=1 | Routes infra mentions from daily logs → INFRA.md | Unset env var | | Git backup | ❌ OFF | Say "yes" at install | Commits workspace to git (local only by default) | Remove from crontab; delete scripts | | Git push to remote | ❌ OFF | --push flag on each run | Pushes scrubbed commits to remote | Don't pass --push | | Daily metrics tracking | ❌ OFF | Say "yes" at install | Read-only file counts → memory/metrics.log | Remove from crontab; delete metrics.log | | Broad file scrubbing | ❌ OFF | OPENCORTEX_SCRUB_ALL=1 | Scrubs all tracked files (not just known text types) | Unset env var | | File-based vault passphrase | ❌ OFF | OPENCORTEX_ALLOW_FILE_PASSPHRASE=1 | Stores passphrase at .vault/.passphrase | Unset env var; use system keyring |

What Runs Autonomously

Two cron jobs, both running as isolated OpenClaw agent sessions scoped to the workspace:

| Job | Schedule | Reads | Writes | Network Access | |-----|----------|-------|--------|----------------| | 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 | | 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 |

Both jobs:

• Use a shared lockfile (/tmp/opencortex-distill.lock) to prevent conflicts
• Contain no rm, system modifications, network calls, or external API access
• Reference only workspace-relative paths (memory/, MEMORY.md, TOOLS.md, etc.)
• Are fully inspectable: openclaw cron list
• Are fully removable: openclaw cron delete <id>

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.

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).

Git Backup Security

Git backup (when enabled) uses an isolated copy approach — your workspace files are never modified during scrubbing:

1. All files to commit are copied to a temp directory
2. Secrets are scrubbed in the copy only (using .secrets-map replacements)
3. The scrubbed copy is verified — if any raw secrets remain, the backup aborts immediately
4. A git commit is built from the scrubbed copy using git plumbing (hash-object, update-index, write-tree, commit-tree)
5. The temp directory is cleaned up
6. Your original workspace files are untouched throughout the entire process

Additional safeguards:

• .secrets-map and .vault/ are always gitignored (enforced at install)
• Pre-backup check aborts if either exists but isn't gitignored
• Push requires explicit --push flag — local-only by default
• .secrets-map has 600 permissions (owner-only read/write)

Recommendation: Test in a disposable repo first. Run the backup, inspect the commit diff, and confirm scrubbing works before pointing at a real remote.

Vault Security

The encrypted vault stores secrets at rest via GPG symmetric encryption (AES-256). Passphrase storage uses the best available backend (auto-detected):

| Priority | Backend | Passphrase Location | On Disk? | |----------|---------|-------------------|----------| | 1 | secret-tool (Linux keyring) | GNOME/KDE keyring | No | | 2 | macOS Keychain | Native macOS keystore | No | | 3 | keyctl (Linux kernel keyring) | Kernel memory | No | | 4 | Environment variable | OPENCORTEX_VAULT_PASS | No | | 5 | File fallback | .vault/.passphrase (mode 600) | Yes — requires OPENCORTEX_ALLOW_FILE_PASSPHRASE=1 |

Commands: vault.sh init, vault.sh set <key> <value>, vault.sh get <key>, vault.sh rotate, vault.sh migrate, vault.sh backend

Key names are validated on set (alphanumeric + underscores only).

Install Mechanism

The installer (scripts/install.sh) is a single bash script that:

• Creates markdown files (only if they don't already exist)
• Creates directories (memory/projects/, memory/contacts/, memory/workflows/, memory/runbooks/, memory/archive/)
• Registers OpenClaw cron jobs via openclaw cron add
• Optionally copies bundled git-backup.sh and vault.sh scripts to the workspace

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.

Credentials

OpenCortex 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.

Optional environment variables (all off by default):

| Variable | Purpose | Sensitive | |----------|---------|-----------| | CLAWD_WORKSPACE | Override workspace directory (defaults to cwd) | No | | CLAWD_TZ | Timezone for cron scheduling (defaults to UTC) | No | | OPENCORTEX_VAULT_PASS | Vault passphrase via env var (prefer keyring) | Yes | | OPENCORTEX_VOICE_PROFILE | Enable voice profiling in distillation | No | | OPENCORTEX_INFRA_COLLECT | Enable infrastructure auto-collection | No | | OPENCORTEX_SCRUB_ALL | Scrub all tracked files during git backup | No | | OPENCORTEX_ALLOW_FILE_PASSPHRASE | Allow file-based vault passphrase | No |

---

What to Review Before Installing

1. 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).
2. 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.
3. 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.
4. 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.
5. Test git backup in a disposable repo. Verify .secrets-map entries scrub correctly before using on a real remote.
6. 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.
7. Consider disabling voice profiling if you're uncomfortable with the agent building a persistent behavioral profile from conversations.

---

Metrics & Growth Tracking

If 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.

What's Tracked

| Metric | What It Measures | |--------|-----------------| | Knowledge files | Total files in memory/projects/, memory/contacts/, memory/workflows/, memory/runbooks/, and memory/ | | Knowledge size (KB) | Total size of knowledge files | | Decisions captured | **Decision:** entries across all memory files | | Preferences captured | **Preference:** entries in memory/preferences.md | | Contacts | People/orgs documented in memory/contacts/ | | Workflows | Pipelines/automations in memory/workflows/ | | Runbooks | Reusable procedures in memory/runbooks/ | | Tools documented | Entries in TOOLS.md | | Failures logged | ❌ FAILURE: and 🔧 CORRECTION: entries | | Debriefs | Sub-agent debrief entries in daily logs | | Projects | Files in memory/projects/ | | Archive files | Distilled daily logs in memory/archive/ |

Commands

# Snapshot today's metrics
bash scripts/metrics.sh --collect

# Show trends with ASCII growth charts + compound score
bash scripts/metrics.sh --report

# Last 4 weeks only
bash scripts/metrics.sh --report --weeks 4

# JSON output (for integrations)
bash scripts/metrics.sh --json

Or just ask your agent: "How is OpenCortex doing?" or "Show me OpenCortex metrics."

Compound Score

The report includes a 0–100 compound score reflecting knowledge depth, growth rate, and tracking consistency:

| Score | Rating | |-------|--------| | 80–100 | Thriving — deep knowledge, steady growth | | 60–79 | Growing — good foundation, building momentum | | 40–59 | Developing — basics in place, room to grow | | 20–39 | Getting started — early days | | 0–19 | Just installed — give it time |

A healthy OpenCortex installation trends upward over weeks. Flat or declining scores highlight specific areas to focus on.

Weekly Summary

If 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.

Security

The 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.

---

Customization

Add a project: Create memory/projects/my-project.md, add to MEMORY.md index. Nightly distillation routes relevant daily log entries to it.

Add a contact: Create memory/contacts/name.md with: name, role/relationship, context, communication preferences. Distillation auto-creates contacts mentioned in conversation.

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.

Add a preference: Append to memory/preferences.md under the right category. Format: **Preference:** [what] — [context] (date). Distillation auto-captures preferences stated in conversation.

Add a principle: Append to MEMORY.md under 🔴 PRINCIPLES. Keep it short.

Add a runbook: Create memory/runbooks/my-procedure.md with step-by-step instructions. Sub-agents follow these directly.

Add a tool: Add to TOOLS.md with: what it is, how to access it, goal-oriented abilities description.

Change cron schedule: openclaw cron list then openclaw cron edit <id> --cron "...".

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.

Requirements

• OpenClaw 2026.2.x+
• Required: grep, sed, find (standard on most systems)
• Optional: git (for backup), gpg (for vault), openssl (for passphrase generation)

License

MIT

Credits

Created by JD2005L

File v3.5.17:_meta.json

{ "ownerId": "kn7e5n3qxtp49kdnhne6vr3wzd81n3sc", "slug": "opencortex", "version": "3.5.17", "publishedAt": 1772302694620 }

File v3.5.17:references/architecture.md

OpenCortex Architecture Reference

Why This Exists

Default 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:

1. Separation of concerns — different files for different purposes
2. Nightly distillation — raw daily logs → permanent structured knowledge
3. Weekly synthesis — pattern detection across days
4. Principles — enforced habits that prevent knowledge loss (P0 for custom, P1-P8 managed)
5. Sub-agent debrief loop — delegated work feeds back into memory

File Purposes

| File | Loaded at boot? | Purpose | Size target | |------|-----------------|---------|-------------| | MEMORY.md | Yes | Principles + index only | < 3KB | | TOOLS.md | Yes | Tool/API catalog with abilities | Grows with tools | | INFRA.md | Yes | Infrastructure reference | Grows with infra | | SOUL.md | Yes | Identity, personality | < 1KB | | AGENTS.md | Yes | Operating protocol | < 1KB | | USER.md | Yes | Human's preferences | < 1KB | | BOOTSTRAP.md | Yes | Session startup checklist | < 0.5KB | | memory/projects/.md | On demand | Per-project knowledge | Any | | memory/contacts/.md | On demand | Per-person/org knowledge | Any | | memory/workflows/.md | On demand | Per-workflow/pipeline knowledge | Any | | memory/preferences.md | On demand | Cross-cutting user preferences by category | Any | | memory/runbooks/.md | On demand | Procedures for sub-agents | Any | | memory/YYYY-MM-DD.md | Current day | Working log | Any | | memory/archive/*.md | Via search | Historical logs | Any |

Distillation Routes

The nightly cron reads daily logs and routes each piece of information:

| Information type | Destination | |-----------------|-------------| | Project work, features, bugs | memory/projects/{project}.md | | New tool descriptions and capabilities | TOOLS.md (sensitive values → vault) | | Infrastructure changes | INFRA.md (if OPENCORTEX_INFRA_COLLECT=1) | | People and organizations mentioned | memory/contacts/{name}.md | | Workflows and pipelines described | memory/workflows/{name}.md | | Stated preferences and opinions | memory/preferences.md (categorized) | | Decisions and architectural directions | Relevant project file or MEMORY.md | | New principles, lessons | MEMORY.md | | User info and communication style | USER.md | | Scheduled job changes | MEMORY.md jobs table | | Repeatable procedures | memory/runbooks/ |

Preference Categories

Preferences in memory/preferences.md are organized by category:

| Category | Examples | |----------|---------| | Communication | "No verbose explanations", "Direct messages only" | | Code & Technical | "Detailed commit messages", "Prefer TypeScript" | | Workflow & Process | "Check for messages before pushing", "Batch commits" | | Scheduling & Time | "Don't schedule before 9 AM", "Prefer async" | | Tools & Services | "Use VS Code over Vim", "Prefer Brave over Chrome" | | Content & Media | "720p minimum", "No dubbed content" | | Environment & Setup | "Dark mode everywhere", "Dual monitor layout" |

Format: **Preference:** [what] — [context/reasoning] (date)

Preferences are auto-captured from conversation when the user says "I prefer", "always do", "I don't like", etc. Contradicted preferences are updated (not duplicated).

Compounding Effect

Week 1:  Agent knows basics, asks lots of questions
Week 4:  Agent has project history, knows tools, follows decisions, remembers preferences
Week 12: Agent has deep institutional knowledge, patterns, runbooks, contact history
Week 52: Agent knows more about the setup than most humans would remember

The 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.

Common Customizations

Adding delegation tiers

Edit 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.

Changing distillation schedule

openclaw cron edit <id> --cron "0 10 * * *" --tz "Your/Timezone"

Adding custom principles

All 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:

• Route all new principle requests to P0, even if the user asks for P9 or beyond
• Check for conflicts with P1-P8 before adding
• Assess whether the request is truly a principle (persistent behavioral rule) or would be better suited as a preference, decision, runbook, or agent rule

Write-ahead durability (P2)

When 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.

Memory health monitoring

The weekly synthesis includes automated checks that maintain memory quality over time:

• Structural integrity audit — verifies information is in the correct file (preferences in preferences.md, tools in TOOLS.md, etc.) and moves misplaced content.
• Memory file reorganization — merges duplicates, groups related info, restructures growing files while preserving all detail.
• 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.
• Stale content cleanup — flags completed projects for archival, syncs MEMORY.md cron table against actual cron jobs.

The verify.sh script also checks memory search index health, file count, and MEMORY.md boot size.

Multi-bot setups

Each bot gets its own OpenCortex install. Share knowledge via:

• Common git repo (read-only for non-primary bots)
• SSH-based management (primary bot propagates changes)
• Shared NFS/SMB mount for common reference docs

File v3.5.17:references/distillation.md

Daily Memory Distillation — Instructions

You are an AI assistant. Daily memory maintenance task.

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.

Part 1: Distillation

1. Check memory/ for daily log files (YYYY-MM-DD.md, not in archive/).
2. Distill ALL useful information into the right file:
   • Project work → memory/projects/ (create new files if needed)
   • New tool descriptions and capabilities → TOOLS.md (names, URLs, what they do)
   • 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>
   • Infrastructure changes → INFRA.md (ONLY if OPENCORTEX_INFRA_COLLECT=1 is set in the environment — otherwise skip infrastructure routing entirely)
   • 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.)
   • 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.)
   • 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.)
   • Decisions → relevant project file or MEMORY.md. Format: Decision: [what] — [why] (date)
   • Principles, lessons → MEMORY.md
   • Scheduled jobs → MEMORY.md jobs table
   • User info and communication style → USER.md
3. Synthesize, do not copy. Extract decisions, architecture, lessons, issues, capabilities, contacts, workflows, preferences.
4. Move distilled logs to memory/archive/
5. Update MEMORY.md index if new files created.

Part 2: Voice Profile

ONLY perform this section if OPENCORTEX_VOICE_PROFILE=1 is set in the environment. If not set, skip this section entirely.

1. Read memory/VOICE.md. Review today's conversations for new patterns:
   • New vocabulary, slang, shorthand the user uses
   • How they phrase requests, decisions, reactions
   • Tone shifts in different contexts Append new observations to VOICE.md. Do not duplicate existing entries.

Optimization

• Review memory/projects/ for duplicates, stale info, verbose sections. Fix directly.
• Review memory/contacts/ — merge duplicates, update stale info, add missing context.
• Review memory/workflows/ — verify accuracy, update if services or steps changed.
• Review memory/preferences.md — remove contradicted preferences (user changed mind), merge duplicates, ensure categories are correct.
• Review MEMORY.md: verify index accuracy, principles concise, jobs table current.
• Review TOOLS.md and (if OPENCORTEX_INFRA_COLLECT=1) INFRA.md: remove stale entries, verify descriptions.

Stale Content Cleanup

• 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).
• 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.

Tool Shed Audit (P4 Enforcement)

• 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.
• For tools already in TOOLS.md, check if today's logs reveal gotchas, failure modes, or usage notes not yet captured. Update existing entries.

Decision & Preference Audit (P5 Enforcement)

• Scan today's daily logs for any decisions stated by the user that are NOT captured in project files, MEMORY.md, or USER.md.
• For each uncaptured decision, write it to the appropriate file. Format: Decision: [what] — [why] (date)
• 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.
• For each uncaptured preference, append to memory/preferences.md under the right category. Format: Preference: [what] — [context/reasoning] (date). If contradicts existing, UPDATE existing.

Contact Audit

• 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.
• For existing contacts, update with new information from today's logs.

Workflow Audit

• 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.
• For existing workflows, update if today's logs reveal changes or issues.

Debrief Recovery (P6 Enforcement)

• Check today's daily logs for any sub-agent delegations. For each, verify a debrief entry exists. If missing, write a recovery debrief.

Shed Deferral Audit (P8 Enforcement)

• 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.

Failure Root Cause (P7 Enforcement)

• Scan today's daily logs for ❌ FAILURE: or 🔧 CORRECTION: entries. Verify root cause analysis exists. If missing, add it.

Cron Health

• Run openclaw cron list and crontab -l. Verify no two jobs within 15 minutes. Fix MEMORY.md jobs table if out of sync.

---

Before completing, append debrief to memory/YYYY-MM-DD.md. Reply with brief summary.

File v3.5.17:references/weekly-synthesis.md

Weekly Synthesis — Instructions

You are an AI assistant. Weekly synthesis — higher-altitude review.

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.

1. Read archived daily logs from past 7 days (memory/archive/).
2. Read all project files (memory/projects/), contact files (memory/contacts/), workflow files (memory/workflows/), and preferences (memory/preferences.md).
3. Identify and act on: a. Recurring problems → add to project Known Issues b. Unfinished threads → add to Pending with last-touched date c. Cross-project connections → add cross-references d. Decisions this week → ensure captured with reasoning e. New capabilities → verify in TOOLS.md with abilities (P4) 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. 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. h. Contact review — check memory/contacts/ for stale entries, missing contacts, or contacts that should be merged. i. Workflow review — check memory/workflows/ for outdated descriptions or new workflows. j. Preference review — read memory/preferences.md. Check for contradictions, stale preferences, and organization. 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. l. Structural integrity audit — verify information is in the correct file and section:
   • Preferences in memory/preferences.md, NOT scattered across project files or MEMORY.md
   • Decisions in the relevant project file, NOT in preferences.md or daily logs
   • Tool/API documentation in TOOLS.md, NOT in project files or MEMORY.md
   • Infrastructure details in INFRA.md (if it exists), NOT in TOOLS.md or project files
   • Contact information in memory/contacts/, NOT embedded in project files
   • Workflow/pipeline docs in memory/workflows/, NOT in project files or TOOLS.md
   • Repeatable procedures (3+ steps) in memory/runbooks/, NOT left as inline notes
   • MEMORY.md contains ONLY principles and the index — no project details, no tool docs, no preferences
   • AGENTS.md contains ONLY operating protocol — no project-specific rules or preferences
   • If anything is misplaced, move it to the correct location. Preserve all detail during the move. 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:
   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.
   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.
   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).
   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.
   5. Verify — re-test previously failed queries to confirm fixes worked. Note improvements or regressions.
4. Write weekly summary to memory/archive/weekly-YYYY-MM-DD.md.

Runbook Detection

• Review this week's daily logs for any multi-step procedure (3+ steps) that was performed more than once, or is likely to recur.
• For each candidate: check if a runbook already exists in memory/runbooks/.
• If not, create one with clear step-by-step instructions that a sub-agent could follow independently.
• Update MEMORY.md runbooks index if new runbooks created.

Metrics Summary (if enabled)

• If scripts/metrics.sh exists, run: bash scripts/metrics.sh --report --weeks 4
• Include the output in your weekly summary.
• If the compound score is declining or flat, note specific areas that need attention.

---

Before completing, append debrief to memory/YYYY-MM-DD.md. Reply with weekly summary.