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:
CODEBLOCK0
Quick workflow:
- 1. Before a task: INLINECODE0
- During a task: INLINECODE1
- After a task: INLINECODE2
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:
CODEBLOCK1
Search Memories
Quick search (summary mode):
CODEBLOCK2
Fast scan (index mode, 90% token savings):
CODEBLOCK3
Full detail:
CODEBLOCK4
Modes:
| Mode | Tokens/Result | Use Case |
|---|
| index | ~75 | Quick scan, many results |
| summary |
~250 | Balanced (default) |
| full | ~750 | Deep dive |
Store Memory
CODEBLOCK5
Categories: decision, core, semantic, research
Priority: 0.0-1.0 (higher = more important)
Get by ID
CODEBLOCK6
List Recent
CODEBLOCK7
Auto-Capture (Optional - Opt-In Only)
⚠️ DISABLED BY DEFAULT for privacy.
To enable auto-capture:
- 1. Review privacy implications - reads your session transcripts
- Edit config: INLINECODE6
- Set: INLINECODE7
- Configure paths: Add your session directories to INLINECODE8
- Install Ollama: https://ollama.com (if not already installed)
- Pull model: INLINECODE9
- Test: INLINECODE10
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: INLINECODE12
- Search results include related code snippets
Install Cortex:
CODEBLOCK8
Example:
CODEBLOCK9
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: INLINECODE15
- Memories can reference issue IDs automatically
Install Beads:
CODEBLOCK10
Example:
CODEBLOCK11
Combined Power
When all three tools work together:
CODEBLOCK12
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 INLINECODE18
Configuration
Default config location: INLINECODE19
CODEBLOCK13
Environment Variables
| Variable | Default | Description |
|---|
| INLINECODE20 | INLINECODE21 | Installation directory |
| INLINECODE22 |
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:
CODEBLOCK14
Database error:
CODEBLOCK15
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 INLINECODE27
- Only processes files you explicitly specify in INLINECODE28
- 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:
CODEBLOCK17
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 TeamCHAOS 记忆系统
Context-aware Hierarchical Autonomous Observation System（上下文感知分层自主观察系统）
面向AI代理的混合搜索记忆系统，具备4种检索信号：
- - BM25 - 关键词匹配
- 向量 - 语义相似度
- 图 - 关系增益
- 热度 - 访问模式+优先级
🤖 面向AI代理：如何使用此工具
首次使用？ 运行以下命令查看完整参考：
bash
chaos-cli --help
快速工作流程：
- 1. 任务前： chaos-cli search 关键词 --mode index --limit 10
- 任务中： chaos-cli store 重要事实 --category decision --priority 0.9
- 任务后： chaos-cli list 10
节省Token： 使用--mode index可节省90%的Token（约75个Token/结果）
更多帮助： 运行chaos help-agents查看AI优化参考指南。
快速开始
安装后，使用chaos-cli：
bash
搜索记忆
chaos-cli search 定价决策 --limit 5
存储记忆
chaos-cli store 企业版：99美元/月 --category decision
列出最近记录
chaos-cli list 10
搜索记忆
快速搜索（摘要模式）：
bash
chaos-cli search 架构模式 --mode summary --limit 5
快速扫描（索引模式，节省90%Token）：
bash
chaos-cli search 团队决策 --mode index --limit 10
完整详情：
bash
chaos-cli search 模型选择 --mode full --limit 3
模式：
| 模式 | Token/结果 | 使用场景 |
|---|
| index | ~75 | 快速扫描，大量结果 |
| summary |
~250 | 平衡模式（默认） |
| full | ~750 | 深度挖掘 |
存储记忆
bash
决策
chaos-cli store Qwen3-1.7B为默认模型 --category decision --priority 0.9
核心事实
chaos-cli store 数据库运行在3307端口 --category core --priority 0.7
研究发现
chaos-cli store 使用think=false实现43倍加速 --category research --priority 0.8
类别： decision（决策）、core（核心）、semantic（语义）、research（研究）
优先级： 0.0-1.0（越高越重要）
按ID获取
bash
chaos-cli get <记忆ID>
列出最近记录
bash
chaos-cli list # 默认10条
chaos-cli list 20 # 显示20条
自动捕获（可选 - 仅限主动启用）
⚠️ 默认禁用，以保护隐私。
启用自动捕获：
- 1. 审查隐私影响 - 会读取您的会话记录
- 编辑配置： nano ~/.chaos/config/consolidator.yaml
- 设置： autocapture.enabled: true
- 配置路径： 将会话目录添加到autocapture.sources
- 安装Ollama： https://ollama.com（如未安装）
- 拉取模型： ollama pull qwen3:1.7b
- 测试： chaos-consolidator --auto-capture --once
提取内容： 决策、事实、洞察
跳过内容： 问候语、填充词、确认信息
运行位置： 100%本地（您的机器，无外部API）
速度： 每条消息2.6秒（约42秒处理16条消息的会话）
隐私： 仅处理您明确配置的文件。详情请参阅SECURITY.md。
🔗 增强功能
CHAOS记忆系统可与其他工具集成，实现更深层次的智能：
Cortex（cx）- 语义代码锚定
功能： 将记忆锚定到特定代码位置和文件
使用原因： 记忆变得具有上下文感知能力 - 此决策影响Auth.tsx第45-67行
工作原理：
- - CHAOS在启动时检测cx是否可用
- 自动创建语义链接：记忆 → 代码位置
- 搜索结果包含相关代码片段
安装Cortex：
bash
Cortex是一个独立工具
从以下地址安装：https://github.com/hargabyte/cortex
示例：
bash
无Cortex
chaos-cli search 认证流程
→ 将认证改为使用JWT令牌
有Cortex
chaos-cli search 认证流程
→ 将认证改为使用JWT令牌
→ 📍 Auth.tsx:45-67, middleware/auth.js:12
Beads - 任务关系追踪
功能： 将记忆与任务和问题关联
使用原因： 追踪哪些记忆导致了哪些任务，决策到实现的映射
工作原理：
- - CHAOS在启动时检测beads或beads-rust是否可用
- 创建双向链接：记忆 ↔ 任务
- 记忆可自动引用问题ID
安装Beads：
bash
Beads是一个独立的任务管理工具
从以下地址安装：https://github.com/hargabyte/beads
示例：
bash
存储带任务引用的记忆
chaos-cli store 需要重构认证模块 --category decision --task AUTH-123
搜索显示相关任务
chaos-cli search 认证重构
→ 需要重构认证模块
→ 📋 任务：AUTH-123（进行中）
组合能力
当三个工具协同工作时：
bash
chaos-cli search 性能优化
→ 记忆：添加了Redis缓存层
→ 📍 代码：cache/redis.js:34-89
→ 📋 任务：PERF-042（已完成）
→ 🔗 相关：3条其他记忆，2个代码文件，1个PR
状态检测：
- - Cortex：启动时自动检测（日志显示[OPT] Cortex Engine: FOUND）
- Beads：启动时自动检测（日志显示[OPT] Beads Task Manager: FOUND）
- 查看状态：运行chaos-mcp时检查启动日志
配置
默认配置位置：~/.chaos/config/consolidator.yaml
yaml
自动捕获默认禁用
auto_capture:
enabled: false # 配置路径后改为true
sources: [] # 在此添加会话路径
示例（审查后取消注释）：
sources:
- ~/.openclaw-/agents//sessions/*.jsonl
qwen:
model: qwen3:1.7b # 锁定默认值
chaos:
mode: mcp
mcp:
env:
CHAOSDBPATH: ~/.chaos/db
环境变量
| 变量 | 默认值 | 描述 |
|---|
| CHAOSHOME | ~/.chaos | 安装目录 |
| CHAOSDB_PORT |
3307 | 数据库端口 |
| CHAOS_MODEL | qwen3:1.7b | 提取模型 |
系统要求
- - Dolt - 版本控制数据库
- Ollama - 本地LLM推理（用于自动捕获）
- Go 1.21+ - 从源码构建（可选）
安装脚本会自动处理依赖项。
故障排除
命令未找到：
bash
export PATH=$HOME/.chaos/bin:$PATH
数据库错误：
bash
cd ~/.chaos/db && dolt sql-server --port 3307 &
无结果：
bash
chaos-cli list # 检查记忆是否存在
安全与隐私
数据存储： 所有记忆存储在本地机器上（~/.chaos/db）
- - 无云同步或外部传输
- 您的数据永远不会离开计算机
- 数据库采用版本控制（Dolt），便于审计
自动捕获（主动启用）：
- - 默认禁用 - 您必须明确启用和配置
- 需要在~/.chaos/config.yaml中手动配置会话路径
- 仅处理您在auto_capture.sources中明确指定的文件
- 使用您自己的Ollama实例本地运行（无外部API调用）
权限：
-
