OpenCortex

OpenClaw 代理的自我改进内存架构。结构化内存文件， 每晚蒸馏，每周合成，强制原则（P0 自定义，P1-P8 管理）， 预写持久性和与模型无关的委托——所以你的代理 复合知识而不是忘记它。包括选择加入指标跟踪 增长图表和复合评分来衡量一段时间内的有效性。所有敏感功能（语音分析、 基础设施自动收集、git推送）默认是关闭的，需要明确 通过环境变量或标志选择加入。安装安全：安装期间无网络调用 设置、完全可审核的 bash 脚本、仅限工作区范围的独立 cron 会话。 在以下情况下使用：(1) 设置新的 OpenClaw 实例，(2) 用户要求改进/组织 记忆，（3）用户希望代理停止忘记事情，（4）引导一个新的 具有最佳实践的代理。不适用于：运行时内存搜索查询（使用内置内存 工具）。触发点：“建立记忆”、“组织自己”、“停止遗忘”、“记忆” 架构”、“自我改进”、“皮质”、“引导内存”、“内存优化”。

## 概述（中文）

OpenClaw 代理的自我改进内存架构。结构化内存文件，
每晚蒸馏，每周合成，强制原则（P0 自定义，P1-P8 管理），
预写持久性和与模型无关的委托——所以你的代理
复合知识而不是忘记它。包括选择加入指标跟踪
增长图表和复合评分来衡量一段时间内的有效性。所有敏感功能（语音分析、
基础设施自动收集、git推送）默认是关闭的，需要明确
通过环境变量或标志选择加入。安装安全：安装期间无网络调用
设置、完全可审核的 bash 脚本、仅限工作区范围的独立 cron 会话。
在以下情况下使用：(1) 设置新的 OpenClaw 实例，(2) 用户要求改进/组织
记忆，（3）用户希望代理停止忘记事情，（4）引导一个新的
具有最佳实践的代理。不适用于：运行时内存搜索查询（使用内置内存
工具）。触发点：“建立记忆”、“组织自己”、“停止遗忘”、“记忆”
架构”、“自我改进”、“皮质”、“引导内存”、“内存优化”。

## 原文

# OpenCortex — Self-Improving Memory Architecture

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

📦 [Full source on GitHub](https://github.com/JD2005L/opencortex) — 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.
6. **Builds a voice profile** of your human from daily conversations for authentic ghostwriting (opt-in, requires `OPENCORTEX_VOICE_PROFILE=1`)
7. **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`
8. **Enables safe git backup** with secret scrubbing (secrets never modified in your live workspace — scrubbed in an isolated copy only)
9. **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](https://github.com/openclaw/openclaw) 2026.2.x+
- [ClawHub CLI](https://clawhub.com)

```bash
# 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.

```bash
# 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

```bash
# 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,