Description

Hybrid search memory system for AI agents. Manual search and storage - auto-capture is opt-in only.

README (SKILL.md)

CHAOS Memory

Name: Chaos Mind
Author: hargabyte

Context-aware Hierarchical Autonomous Observation System

Hybrid search memory for AI agents with 4 retrieval signals:

BM25 - Keyword matching
Vector - Semantic similarity
Graph - Relationship bonuses
Heat - Access patterns + priority

🤖 For AI Agents: How to Use This Tool

First time? Run this to see the complete reference:

chaos-cli --help

Quick workflow:

Before a task: chaos-cli search "keywords" --mode index --limit 10
During a task: chaos-cli store "important fact" --category decision --priority 0.9
After a task: chaos-cli list 10

Token savings: Use --mode index for 90% token savings (~75 tokens/result)

More help: Run chaos help-agents for the AI-optimized reference guide.

Quick Start

After installation, use chaos-cli:

# Search memories
chaos-cli search "pricing decisions" --limit 5

# Store a memory
chaos-cli store "Enterprise tier: $99/month" --category decision

# List recent
chaos-cli list 10

Search Memories

Quick search (summary mode):

chaos-cli search "architecture patterns" --mode summary --limit 5

Fast scan (index mode, 90% token savings):

chaos-cli search "team decisions" --mode index --limit 10

Full detail:

chaos-cli search "model selection" --mode full --limit 3

Modes:

Mode	Tokens/Result	Use Case
index	~75	Quick scan, many results
summary	~250	Balanced (default)
full	~750	Deep dive

Store Memory

# Decision
chaos-cli store "Qwen3-1.7B is default model" --category decision --priority 0.9

# Core fact
chaos-cli store "Database runs on port 3307" --category core --priority 0.7

# Research finding
chaos-cli store "43x speedup with think=false" --category research --priority 0.8

Categories: decision, core, semantic, research

Priority: 0.0-1.0 (higher = more important)

Get by ID

chaos-cli get \x3Cmemory-id>

List Recent

chaos-cli list        # Default 10
chaos-cli list 20     # Show 20

Auto-Capture (Optional - Opt-In Only)

⚠️ DISABLED BY DEFAULT for privacy.

To enable auto-capture:

Review privacy implications - reads your session transcripts
Edit config: nano ~/.chaos/config/consolidator.yaml
Set: auto_capture.enabled: true
Configure paths: Add your session directories to auto_capture.sources
Install Ollama: https://ollama.com (if not already installed)
Pull model: ollama pull qwen3:1.7b
Test: chaos-consolidator --auto-capture --once

What it extracts: Decisions, facts, insights
What it skips: Greetings, filler, acknowledgments
Where it runs: 100% local (your machine, no external APIs)
Speed: 2.6s per message (~42s per 16-message session)

Privacy: Only processes files you explicitly configure. See SECURITY.md for details.

🔗 Enhanced Capabilities

CHAOS Memory integrates with other tools for deeper intelligence:

Cortex (cx) - Semantic Code Anchoring

What it does: Anchors memories to specific code locations and files

Why use it: Memories become context-aware - "this decision affects Auth.tsx lines 45-67"

How it works:

CHAOS detects if cx is available at startup
Automatically creates semantic links: memory → code location
Search results include related code snippets

Install Cortex:

# Cortex is a separate tool
# Install from: https://github.com/hargabyte/cortex

Example:

# Without Cortex
chaos-cli search "auth flow"
→ "Changed auth to use JWT tokens"

# With Cortex
chaos-cli search "auth flow"
→ "Changed auth to use JWT tokens"
→ 📍 Auth.tsx:45-67, middleware/auth.js:12

Beads - Task Relationship Tracking

What it does: Links memories to tasks and issues

Why use it: Track which memories led to which tasks, decisions to implementations

How it works:

CHAOS detects if beads or beads-rust is available
Creates bidirectional links: memory ↔ task
Memories can reference issue IDs automatically

Install Beads:

# Beads is a separate task management tool
# Install from: https://github.com/hargabyte/beads

Example:

# Store memory with task reference
chaos-cli store "Need to refactor auth" --category decision --task AUTH-123

# Search shows related tasks
chaos-cli search "auth refactor"
→ "Need to refactor auth"
→ 📋 Task: AUTH-123 (In Progress)

Combined Power

When all three tools work together:

chaos-cli search "performance optimization"
→ Memory: "Added Redis caching layer"
→ 📍 Code: cache/redis.js:34-89
→ 📋 Task: PERF-042 (Completed)
→ 🔗 Related: 3 other memories, 2 code files, 1 PR

Status Detection:

Cortex: Detected automatically on startup (logs [OPT] Cortex Engine: FOUND)
Beads: Detected automatically on startup (logs [OPT] Beads Task Manager: FOUND)
View status: Check the startup logs when running chaos-mcp

Configuration

Default config location: ~/.chaos/config/consolidator.yaml

# Auto-capture is DISABLED by default
auto_capture:
  enabled: false  # Change to true after configuring paths
  sources: []     # Add your session paths here
  
# Example (uncomment after reviewing):
# sources:
#   - ~/.openclaw-*/agents/*/sessions/*.jsonl

qwen:
  model: qwen3:1.7b  # Locked default

chaos:
  mode: mcp
  mcp:
    env:
      CHAOS_DB_PATH: "~/.chaos/db"

Environment Variables

Variable	Default	Description
`CHAOS_HOME`	`~/.chaos`	Installation directory
`CHAOS_DB_PORT`	`3307`	Database port
`CHAOS_MODEL`	`qwen3:1.7b`	Extraction model

Requirements

Dolt - Version-controlled database
Ollama - Local LLM inference (for auto-capture)
Go 1.21+ - To build from source (optional)

The install script handles dependencies automatically.

Troubleshooting

Command not found:

export PATH="$HOME/.chaos/bin:$PATH"

Database error:

cd ~/.chaos/db && dolt sql-server --port 3307 &

No results:

chaos-cli list  # Check if memories exist

Security & Privacy

Data Storage: All memories stored locally on your machine (~/.chaos/db)

No cloud sync or external transmission
Your data never leaves your computer
Database is version-controlled (Dolt) for auditability

Auto-Capture (Opt-In):

Disabled by default - you must explicitly enable and configure
Requires manual configuration of session paths in ~/.chaos/config.yaml
Only processes files you explicitly specify in auto_capture.sources
Runs locally using your own Ollama instance (no external API calls)

Permissions:

Read: Session transcript files (only paths you configure)
Write: Local database (~/.chaos/db)
Network: None (all processing is local)

Control:

# View what auto-capture will process (dry-run)
chaos-consolidator --auto-capture --once --dry-run

# Disable auto-capture
# Edit ~/.chaos/config.yaml:
# auto_capture:
#   enabled: false

# Or simply don't configure session paths

Transparency:

Install script source: Included in repo (install.sh)
All binaries built via GitHub Actions (reproducible)
Database is plain Dolt (inspect with dolt sql)

Links

GitHub: https://github.com/hargabyte/Chaos-mind
Docs: https://github.com/hargabyte/Chaos-mind/blob/main/README.md
Issues: https://github.com/hargabyte/Chaos-mind/issues

Version 1.0.0 | Created by HSA Team

Usage Guidance

What to check before installing: - Do NOT run remote installers blindly. Avoid piping install scripts (curl | bash) unless you have reviewed the script. Prefer cloning the repo and inspecting install.sh first. - Review install.sh: the script downloads GitHub release tarballs and extracts them to ~/.chaos/bin but does not verify checksums or signatures. If you want stronger assurance, build from source or verify release checksums from the project release page before installing. - Auto-capture is disabled by default, but double-check ~/.chaos/config/consolidator.yaml after install and ensure auto_capture.sources is empty or only contains paths you explicitly trust. Some docs include example globs that would harvest other agents' sessions — do not copy those unless you intend to process those files. - Installing the systemd service will make the consolidator persistent and run as your user; only enable the service if you have configured safe source paths and verified Ollama/Dolt are trustworthy. - The skill does not request remote credentials, which limits cloud exfiltration risk, but it does process local files (which can be sensitive). If you have sensitive session data, keep auto-capture disabled and/or restrict filesystem permissions for ~/.openclaw*/ and ~/.chaos/. - If you need higher assurance: audit the binaries (build from source), verify release artifacts on GitHub, and review SECURITY.md claims against the actual install.sh behavior (there are contradictions).

Capability Analysis

Type: OpenClaw Skill Name: chaos-mind Version: 0.1.3 This skill is classified as suspicious due to its high-risk capabilities, specifically the 'auto-capture' feature designed to read agent session transcripts (`~/.openclaw-*/agents/*/sessions/*.jsonl`) and the installation of a persistent systemd service (`chaos-consolidator.service`) via `setup-service.sh`. While these features are explicitly documented as opt-in, disabled by default, and claimed to operate 100% locally without external network access (as stated in `SKILL.md`, `README.md`, and `SECURITY.md`), the inherent risk of processing sensitive session data and establishing persistence warrants a 'suspicious' classification. The `install.sh` script does demonstrate good security practices by requiring manual installation of Dolt and attempting SQL injection prevention in the fallback `chaos-cli` script, and no clear evidence of intentional malicious data exfiltration or prompt injection was found.

Capability Assessment

ℹ Purpose & Capability

The name/description (local hybrid memory, opt‑in auto‑capture) aligns with the code and config: it installs local binaries, a Dolt DB, and an optional consolidator that reads configured files. However some documentation (DEPLOYMENT_CHECKLIST, INSTALL_NOTES, README) lists default auto-capture glob patterns that target OpenClaw/agent session files; the shipped consolidator.template.yaml has sources empty by default. This mismatch could cause confusion: the ability to read agent session transcripts is coherent with the skill, but the presence of example default patterns in other docs increases privacy risk if a user enables auto-capture without reviewing config.

⚠ Instruction Scope

SKILL.md and other docs repeatedly instruct users to edit ~/.chaos/config/consolidator.yaml and to enable auto_capture only after configuring paths; that keeps scope narrow. But other files (DEPLOYMENT_CHECKLIST, INSTALL_NOTES, some release docs) present default example globs that reference other agents' session directories (e.g., ~/.openclaw-*/agents/*/sessions/*.jsonl). If a user enables auto-capture and reuses these examples, the consolidator will read potentially sensitive session transcripts. Also the README/INSTALL_NOTES explicitly suggest 'curl ... | bash' as an install path (remote execution) while SECURITY.md claims 'No Automatic Remote Script Execution' — that contradiction widens runtime scope and is a red flag.

⚠ Install Mechanism

The installer downloads pre-built tarballs from GitHub Releases (reasonable host) and falls back to building from source (git + go). Downloading from GitHub releases is acceptable, but the install.sh does not perform checksum or signature verification despite SECURITY.md claiming signed/reproducible releases and checksums are provided. Moreover, README/INSTALL_NOTES recommend curl | bash for quick install — a practice that can execute remote code without verification. The fetch+extract behavior (tar -xzf into ~/.chaos/bin) is extract=true in effect and should be paired with verification; it isn't.

ℹ Credentials

The skill requests no credentials or special env vars; required system dependencies (Dolt, optionally Ollama) are proportional to a local DB + local LLM extraction workflow. That said, the consolidator's purpose is to read local session files; while opt‑in and configured via lists, those sources can contain highly sensitive data. No cloud keys are requested, which is good, but the risk is accidental data access if users copy example globs without understanding them.

ℹ Persistence & Privilege

The skill does not force always:true; however it ships a systemd service template and a setup script that installs a persistent consolidator service (requires sudo to copy to /etc/systemd). Running that service gives long‑running background access to any paths configured in the consolidator config. This persistence is consistent with the tool's purpose but increases blast radius if misconfigured. The installer does not auto-enable the service by default (user must run setup-service.sh / systemctl enable), which is appropriate.

Version History

v0.1.3

CHAOS Memory 0.1.3 - Auto-capture is now strictly opt-in and disabled by default for privacy. - Default config paths for the consolidator and auto-capture updated (`consolidator.yaml`). - Documentation improved for enabling/disabling auto-capture, privacy details highlighted. - Minor config structure changes for clarity and a safer installation experience.

v0.1.2

- Added SECURITY.md to document security and privacy practices. - Updated README.md for improved clarity and troubleshooting steps. - Minor improvements to install.sh script.

v0.1.1

Version 0.1.1 of chaos-mind introduces improved installation, documentation, and explicit privacy controls. - Added installation script (`install.sh`) and automation scripts for streamlined setup. - Introduced deployment, release, and installation documentation files for clearer guidance. - Updated install command to a safer local script invocation. - Clarified that auto-capture is opt-in only, and emphasized local-only data storage and privacy. - Added a Security & Privacy section outlining exactly how data is handled and how to control auto-capture.

v0.1.0

Initial release of CHAOS Memory — a hybrid search memory for AI agents. - Introduces multi-signal memory retrieval: BM25 (keywords), Vector (semantic), Graph (relationships), and Heat (access/priority). - CLI tool (`chaos-cli`) for searching, storing, and listing team knowledge with multiple retrieval modes and token efficiency options. - Optional auto-capture daemon to extract decisions and facts from AI agent sessions. - Integrates with Cortex (semantic code anchoring) and Beads (task linking) for deeper contextual intelligence. - Offers configuration via YAML and environment variables; includes troubleshooting and setup guides. - Dependency management handled via install script.

Metadata

Slug chaos-mind

Version 0.1.3

License —

All-time Installs 4

Active Installs 2

Total Versions 4

Frequently Asked Questions

What is Chaos Mind?

Hybrid search memory system for AI agents. Manual search and storage - auto-capture is opt-in only. It is an AI Agent Skill for Claude Code / OpenClaw, with 1962 downloads so far.

How do I install Chaos Mind?

Run "/install chaos-mind" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Chaos Mind free?

Yes, Chaos Mind is completely free (open-source). You can download, install and use it at no cost.

Which platforms does Chaos Mind support?

Chaos Mind is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Chaos Mind?

It is built and maintained by hargabyte (@hargabyte); the current version is v0.1.3.

More Skills

Chaos Mind