---
name: chaos-memory-9ef150e8f716
description: Hybrid search memory system for AI agents. Manual search and storage - auto-capture is opt-in only.
homepage: https://github.com/hargabyte/Chaos-mind
metadata:
  {
    "openclaw":
      {
        "emoji": "🧠",
        "install":
          [
            {
              "id": "chaos-install",
              "kind": "shell",
              "command": "bash install.sh",
              "label": "Install CHAOS Memory",
            },
          ],
      },
  }
---

# CHAOS Memory

**C**ontext-aware **H**ierarchical **A**utonomous **O**bservation **S**ystem

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

```bash
# 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):
```bash
chaos-cli search "architecture patterns" --mode summary --limit 5
```

**Fast scan** (index mode, 90% token savings):
```bash
chaos-cli search "team decisions" --mode index --limit 10
```

**Full detail**:
```bash
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

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

```bash
chaos-cli get <memory-id>
```

---

## List Recent

```bash
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:**
```bash
# Cortex is a separate tool
# Install from: https://github.com/hargabyte/cortex
```

**Example:**
```bash
# 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:**
```bash
# Beads is a separate task management tool
# Install from: https://github.com/hargabyte/beads
```

**Example:**
```bash
# 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:
```bash
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`

```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:**
```bash
export PATH="$HOME/.chaos/bin:$PATH"
```

**Database error:**
```bash
cd ~/.chaos/db && dolt sql-server --port 3307 &
```

**No results:**
```bash
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:**
```bash
# 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*


---
Source attribution: modbender
Original project: https://github.com/modbender/skill-library-mcp/blob/d9c8fe903b5b4e82237dbe8d0df8567783022e18/data/chaos-mind/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2025 skill-library-mcp contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: modbender
Original project: https://github.com/modbender/skill-library-mcp/blob/d9c8fe903b5b4e82237dbe8d0df8567783022e18/data/chaos-mind/SKILL.md
Attribution basis: Source repository record

Fields of work: Data & Analytics, Development & Engineering, Product Management
Roles: Backend Developer, Data Scientist, ML / AI Engineer, Product Manager, Technical Product Manager
Specialties: API, Backend
Tools: Chaos Cli, Ollama
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 1af9a83c28c5e3d0e7ab068b4e90c84e8d16ce1aed5134cd914c76440af228a7