Chaos Mind

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

Security Scan

The skill generally matches its stated purpose (a local, opt‑in memory extractor), but there are several inconsistencies and surprising installation/runtime behaviors (install instructions that encourage curl|bash, undocumented default capture globs in some docs, no checksum verification in the installer) that could lead to accidental exposure of session data or unverified code execution if users follow the quick-install guidance.

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.

What to consider before installing

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

CHAOS Memory

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:

1. Before a task: chaos-cli search "keywords" --mode index --limit 10
2. During a task: chaos-cli store "important fact" --category decision --priority 0.9
3. 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 <memory-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:

1. Review privacy implications - reads your session transcripts
2. Edit config: nano ~/.chaos/config/consolidator.yaml
3. Set: auto_capture.enabled: true
4. Configure paths: Add your session directories to auto_capture.sources
5. Install Ollama: https://ollama.com (if not already installed)
6. Pull model: ollama pull qwen3:1.7b
7. 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