Source Code

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:

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

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)

chaos-mind