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

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