OpenCortex

Self-improving memory architecture for OpenClaw agents. Structured memory files, nightly distillation, weekly synthesis, enforced principles (P0 for custom,...

Security Scan

OpenCortex's files, installer, and runtime instructions are coherent with its stated purpose as a workspace-scoped memory architecture; optional sensitive features are gated and the installer makes no hidden network calls by default.

Purpose & Capability

The name/description (self-improving memory, distillation, synthesis, vault, git backup) matches the provided scripts and SKILL.md. Required binaries (grep, sed, find) and optional tools (git, gpg, openclaw) are appropriate for the declared tasks. No unrelated credentials or tools are requested.

Instruction Scope

The SKILL.md and scripts instruct the agent to read and write many workspace files, register cron jobs, and optionally build voice profiles or collect infra details. Those actions are consistent with the memory-management purpose, but they do grant the skill read/write access to essentially the entire workspace and autonomous cron-based activity — pay attention to opt-in toggles (VOICE_PROFILE, INFRA_COLLECT, SCRUB_ALL) before enabling them.

Install Mechanism

No external download/install spec is present; all provided code is plain bash in the skill bundle. The installer claims and appears to make no network calls during setup. Updates are performed by user-invoked 'clawhub install --force' (external download) which is a normal update flow and requires explicit action.

Credentials

No required environment credentials are declared. Optional env vars (workspace, timezone, vault passphrase, feature flags) are reasonable and documented; the only sensitive env is OPENCORTEX_VAULT_PASS which is justified for the encrypted vault. The skill advises preferring system keyring over file-based passphrases.

Persistence & Privilege

The skill registers two cron jobs that run isolated OpenClaw agent sessions scoped to the workspace. Autonomous cron execution is necessary for nightly distillation/weekly synthesis and is expected, but it does mean the skill has ongoing, automated execution capability; 'always:true' is NOT set and it does not modify other skills' configs.

Assessment

OpenCortex is internally consistent with its stated purpose, but review and decide on opt-in features before installing. Recommended steps: (1) run the installer in dry-run mode first (bash skills/opencortex/scripts/install.sh --dry-run); (2) inspect scripts/vault.sh and scripts/git-backup.sh to ensure their behaviors align with your policies; (3) keep .vault/ and .secrets-map in .gitignore as the installer suggests; (4) avoid enabling voice profiling or infrastructure collection unless you are comfortable with the agent reading conversation logs and infra mentions (these are off by default and require explicit flags); (5) prefer system keyring to file-based passphrases (do not set OPENCORTEX_ALLOW_FILE_PASSPHRASE unless necessary); (6) if you use git backup, avoid passing --push unless you intend to push scrubbed commits to a remote; (7) after install, run bash skills/opencortex/scripts/verify.sh and review the cron entries (openclaw cron list / crontab -l) to confirm scheduled jobs; (8) updates require an explicit clawhub install --force (no silent network pull during initial install).

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 or .opencortex-flags with 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) and your preferred AI model for cron jobs (e.g. sonnet, opus, haiku). Saved to .opencortex-model. 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.