chaos-memory

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