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

# CHAOS Memory - ClawdHub Skill

**Hybrid search for team memories with auto-capture.**

[![Version](https://img.shields.io/badge/version-1.0.0-blue)](https://clawdhub.com/skills/chaos-memory)
[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/hargabyte/chaos-memory/blob/main/LICENSE)

---

## Features

🔍 **Hybrid Search** - Combines 4 signals for optimal relevance:
- BM25 keyword matching (0.4 weight)
- Vector semantic search (0.4 weight)
- Graph relationships (0.1 weight)
- Heat/access patterns (0.1 weight)

🤖 **Auto-Capture (The Killer Feature - Opt-In)** - Automatically builds your memory from sessions:
- **43x faster** than manual entry - captures context while you work
- Extracts decisions, insights, facts automatically with Qwen3-1.7B
- 100% local processing (no cloud/external APIs)
- **Disabled by default** for privacy - you control what it reads
- See "Auto-Capture" section below for setup (takes ~5 minutes)

📊 **Progressive Disclosure** - Choose detail level:
- Index mode: ~75 tokens/result (90% savings)
- Summary mode: ~250 tokens/result (67% savings)
- Full mode: ~750 tokens/result (complete context)

⚡ **43x Faster** - Optimized extraction:
- 2.6s per message
- ~42s per 16-message session
- Qwen3-1.7B with thinking disabled

🔗 **Enhanced with Cortex + Beads** (optional):
- **Cortex** - Anchor memories to code locations (semantic linking)
- **Beads** - Link memories to tasks/issues (project tracking)
- Together: Search shows memories → code → tasks in one view

---

## Installation

### Via ClawdHub (Recommended)

```bash
clawdhub install chaos-memory
```

### Via Bot

Send to your AI assistant:
```
Install the chaos-memory skill from ClawdHub
```

### Manual

```bash
curl -fsSL https://raw.githubusercontent.com/hargabyte/Chaos-mind/main/install.sh | bash
```

---

## Quick Start

**Search memories:**
```bash
chaos-cli search "pricing decisions" --mode summary --limit 5
```

**Store a memory:**
```bash
chaos-cli store "I...