CALM - Claude Agent Learning & Management

A unified system for memory, learning, and workflow orchestration for Claude Code agents.

What is CALM?

CALM provides Claude Code with:

• Memory: Persistent semantic memories that improve over time
• Learning: Structured capture of experiences via the GHAP (Goal-Hypothesis-Action-Prediction) loop
• Orchestration: Task tracking, phase gates, and workflow management (opt-in)

CALM supports two install tiers and two usage modes:

Install tiers:

Tier	Command	What's Included
Lean (default)	calm install	CLI, worktrees, gates, roles, skills, SessionStart hook
Full	calm install --full	+ MCP server, Qdrant, all hooks, daemon, semantic memory, GHAP

Usage modes:

Mode	Activation	Features
Orchestration	/orchestrate per session	Tasks, phases, gates, worktrees, workers, reviews
Memory	Always on (full install)	Memory storage/retrieval, GHAP tracking, context assembly

Features

• Semantic Memory: Store and retrieve memories with categories (facts, preferences, decisions, workflows)
• Code Indexing: Index and search Python/TypeScript/Rust/Java code with TreeSitter
• Git Analysis: Analyze commit history, find churn hotspots, identify code authors
• GHAP Learning: Track hypotheses, compare predictions to outcomes, cluster experiences
• Context Assembly: Automatically inject relevant memories and experiences into sessions
• Workflow Orchestration: Full software development lifecycle management with phase gates

Installation

Prerequisites

• Python 3.12+ - Download
• uv - Fast Python package installer

  curl -LsSf https://astral.sh/uv/install.sh | sh

• Docker (full install only) - For running Qdrant vector database
  • Docker Desktop (macOS/Windows)
  • Or Docker Engine (Linux)

Quick Start

1. Clone the repository:

   git clone <your-repo-url>   # Replace with your actual repo URL
   cd calm

2. Install dependencies:

   uv sync

3. Run the installer:

   # Lean install (orchestration only, no Docker required)
   calm install
   
   # Full install (with MCP server, Qdrant, semantic memory)
   calm install --full

   Lean install sets up:

   • CLI, database, worktrees, gates, roles, skills
   • SessionStart hook
   • Workflow files at ~/.calm/workflow/

   Full install additionally sets up:

   • Qdrant in Docker
   • MCP server registered in ~/.claude.json
   • All 4 Claude Code hooks
   • CALM daemon

4. Verify installation: Open a new Claude Code session. You should see:

   CALM (Claude Agent Learning & Management) is available.
   

Installation Options

# Lean install (default)
calm install

# Full install
calm install --full

# Full install, skip Qdrant setup (use existing instance)
calm install --full --skip-qdrant

# Preview what will be configured
calm install --dry-run

# Skip confirmation prompts
calm install -y

What Gets Configured

CALM installs globally, working across all Claude Code sessions:

• Storage: ~/.calm/ stores all data
  • metadata.db - SQLite database for sessions, tasks, workers, reviews
  • sessions/ - Session logs for reflection
  • roles/ - Specialist role definitions
  • workflow/ - Orchestration workflow instructions
  • skills/ - Claude Code skill wrappers
  • journal/ - Session journal storage
• Hooks: Registered in ~/.claude/settings.json
  • Lean: SessionStart only (announce CALM availability)
  • Full: + UserPromptSubmit, PreToolUse, PostToolUse (memory injection, GHAP)
• MCP Server (full only): Added to ~/.claude.json
• Qdrant (full only): Docker container on localhost:6333

Uninstallation

# Remove CALM but keep data
./scripts/uninstall.sh

# Full removal including ~/.calm/
./scripts/uninstall.sh --remove-data

Usage

Session Skills (Both Modes)

Session Wrapup - End sessions cleanly with /wrapup:

/wrapup           # Archive session
/wrapup continue  # Handoff for continuation

Reflection - Extract learnings from past sessions with /reflection:

• Analyzes unreflected session logs
• Proposes memories (full mode uses MCP for richer analysis)

Memory Features (Full Install)

Memory features work automatically in every Claude Code session:

Context Injection - Automatic memory retrieval:

• Relevant memories are injected at the start of each prompt
• GHAP experiences inform similar debugging scenarios

Orchestration Mode (Opt-In)

Enable full workflow orchestration for a session:

/orchestrate

This activates:

• Task Management: Create, track, and transition tasks through phases
• Phase Gates: Automated checks before phase transitions
• Worktrees: Isolated git worktrees for each task
• Workers: Dispatch specialist agents for implementation
• Reviews: 2x review requirement before advancing

See CLAUDE.md for detailed workflow instructions.

CLI Reference

The calm CLI provides all orchestration commands:

# Installation
calm install             # Lean install (default)
calm install --full      # Full install with MCP/Qdrant

# System status
calm status              # Full status overview

# Task management
calm task create SPEC-001 "Feature title"
calm task list
calm task show SPEC-001
calm task transition SPEC-001 DESIGN --gate-result pass

# Gate checks
calm gate check SPEC-001 IMPLEMENT-CODE_REVIEW
calm gate list

# Worktrees
calm worktree create SPEC-001
calm worktree list
calm worktree merge SPEC-001

# Server
calm server start
calm server stop
calm server status

Run calm --help or calm <command> --help for full documentation.

Architecture

Core Components

• Embedding: sentence-transformers with Nomic Embed (semantic) and MiniLM (code)
• Vector Store: Qdrant for semantic search
• Metadata Store: SQLite for structured data
• Parsing: TreeSitter for code analysis
• Clustering: HDBSCAN for experience grouping
• MCP Server: Exposes tools to Claude Code

Directory Structure

~/.calm/
├── config.yaml              # User preferences
├── metadata.db              # SQLite database
├── workflow/
│   ├── orchestration.md     # Full orchestration workflow
│   └── mcp.md               # MCP/GHAP/learning features
├── roles/
│   ├── architect.md
│   ├── backend.md
│   ├── reviewer.md
│   └── ...
├── skills/                  # Claude Code skill wrappers
├── journal/                 # Session journal storage
└── sessions/
    └── <timestamp>.jsonl    # Session logs for reflection

Source Layout

src/calm/
├── cli/            # Click-based CLI commands
├── clustering/     # HDBSCAN experience clustering
├── context/        # Context assembly and token budgeting
├── db/             # SQLite metadata store
├── embedding/      # Embedding service implementations
├── ghap/           # GHAP state machine and persistence
├── git/            # Git history analysis
├── hooks/          # Claude Code hook scripts
├── indexers/       # Tree-sitter code parsing
├── install/        # Installation and setup
├── orchestration/  # Task, worktree, worker, gate management
├── search/         # Unified semantic search
├── server/         # MCP server
├── storage/        # Vector store (Qdrant and in-memory)
├── tools/          # MCP tool definitions
├── utils/          # Shared utilities
└── values/         # Value store and validation

Development

# Install dev dependencies
uv sync

# Run tests
pytest -vvsx

# Run linter
ruff check src tests

# Run type checker
mypy --strict src

Test Categories

• Unit tests: Core functionality with mocked dependencies
• Integration tests: Real Qdrant instance (tests/integration/)
• Cold-start tests: Empty state scenarios (-m cold_start)
• Performance tests: Latency benchmarks (tests/performance/)

Troubleshooting

Port 6333 already in use:

# Stop existing Qdrant
docker stop $(docker ps -q --filter ancestor=qdrant/qdrant)

# Or use existing instance
./scripts/install.sh --skip-qdrant

Python version too old:

python3 --version  # Must be 3.12+

Docker not running:

# macOS: Open Docker Desktop
# Linux: sudo systemctl start docker

MCP server not responding:

# Check server status
calm server status

# Restart the server
calm server restart

CALM not recognized in Claude Code:

# Verify MCP server is registered (full install)
cat ~/.claude.json | grep calm

# Verify hooks are registered
cat ~/.claude/settings.json | grep calm

# Restart Claude Code after installation

Database schema out of date: Schema migrations run automatically on first connection. No manual calm init is needed after updating CALM.

Worktree merge refuses to run: If you get "current working directory is inside the worktree", cd to the main repo directory first. Running calm worktree merge from inside the worktree would break your shell.

Animated Explainer

An interactive visualization of how CALM works is available in calm-visualizer/. Open index.html in a browser to view a 90-second animated explainer covering the GHAP learning loop and context injection.

License

MIT