@vainplex/openclaw-cortex

Conversation intelligence layer for OpenClaw — automated thread tracking, decision extraction, boot context generation, and pre-compaction snapshots.

What It Does

openclaw-cortex listens to OpenClaw message hooks and automatically:

• 📋 Tracks conversation threads — detects topic shifts, closures, decisions, and blocking items
• 🎯 Extracts decisions — recognizes when decisions are made (English + German) and logs them
• 🚀 Generates boot context — assembles a dense BOOTSTRAP.md at session start so the agent has continuity
• 📸 Pre-compaction snapshots — saves thread state + hot snapshot before memory compaction
• 📖 Structured narratives — generates 24h activity summaries from threads + decisions

Works alongside memory-core (OpenClaw's built-in memory) — doesn't replace it.

Install

# From npm
npm install @vainplex/openclaw-cortex

# Copy to OpenClaw extensions
cp -r node_modules/@vainplex/openclaw-cortex ~/.openclaw/extensions/openclaw-cortex

Or clone directly:

cd ~/.openclaw/extensions
git clone https://github.com/alberthild/openclaw-cortex.git
cd openclaw-cortex && npm install && npm run build

Configure

Add to your OpenClaw config:

{
  "plugins": {
    "openclaw-cortex": {
      "enabled": true,
      "patterns": {
        "language": "both"
      },
      "threadTracker": {
        "enabled": true,
        "pruneDays": 7,
        "maxThreads": 50
      },
      "decisionTracker": {
        "enabled": true,
        "maxDecisions": 100,
        "dedupeWindowHours": 24
      },
      "bootContext": {
        "enabled": true,
        "maxChars": 16000,
        "onSessionStart": true,
        "maxThreadsInBoot": 7,
        "maxDecisionsInBoot": 10,
        "decisionRecencyDays": 14
      },
      "preCompaction": {
        "enabled": true,
        "maxSnapshotMessages": 15
      },
      "narrative": {
        "enabled": true
      }
    }
  }
}

Restart OpenClaw after configuring.

How It Works

Hooks

Hook	Feature	Priority
message_received	Thread + Decision Tracking	100
message_sent	Thread + Decision Tracking	100
session_start	Boot Context Generation	10
before_compaction	Pre-Compaction Snapshot	5
after_compaction	Logging	200

Output Files

{workspace}/
├── BOOTSTRAP.md                    # Dense boot context (regenerated each session)
└── memory/
    └── reboot/
        ├── threads.json            # Thread state
        ├── decisions.json          # Decision log
        ├── narrative.md            # 24h activity summary
        └── hot-snapshot.md         # Pre-compaction snapshot

Pattern Languages

Thread and decision detection supports English, German, or both:

• Decision patterns: "we decided", "let's do", "the plan is", "wir machen", "beschlossen"
• Closure patterns: "is done", "it works", "fixed ✅", "erledigt", "gefixt"
• Wait patterns: "waiting for", "blocked by", "warte auf"
• Topic patterns: "back to", "now about", "jetzt zu", "bzgl."
• Mood detection: frustrated, excited, tense, productive, exploratory

Graceful Degradation

• Read-only workspace → runs in-memory, skips writes
• Corrupt JSON → starts fresh, next write recovers
• Missing directories → creates them automatically
• Hook errors → caught and logged, never crashes the gateway

Development

npm install
npm test            # 270 tests
npm run typecheck   # TypeScript strict mode
npm run build       # Compile to dist/

Performance

• Zero runtime dependencies (Node built-ins only)
• All hook handlers are non-blocking (fire-and-forget)
• Atomic file writes via .tmp + rename
• Tested with 270 unit + integration tests

Architecture

See docs/ARCHITECTURE.md for the full design document including module diagrams, data flows, type definitions, and testing strategy.

License

MIT — see LICENSE

Related

• @vainplex/nats-eventstore — Publish OpenClaw events to NATS JetStream
• OpenClaw — Multi-channel AI gateway