@monoes/monomindcli 1.8.0 → 1.9.1

package/.claude/commands/memory/README.md

@@ -1,9 +1,79 @@
+---
+name: memory:README
+---
+
 # Memory Commands
 
-Commands for memory operations in Monomind.
+Commands for the AgentDB memory system — vector search, namespaced storage, HNSW indexing, and cross-session persistence.
+
+## Available Subcommands
+
+| Subcommand | Description |
+|---|---|
+| `memory init` | Initialize memory backend (agentdb, sqlite, hybrid) |
+| `memory store` | Store a memory entry with optional vector embedding |
+| `memory retrieve` | Retrieve a memory entry by key |
+| `memory search` | Search memory (semantic / keyword / hybrid) |
+| `memory list` | List all memory entries with optional filters |
+| `memory edit` | Update an existing memory entry |
+| `memory delete` | Delete one or more memory entries |
+| `memory templates` | Manage memory templates |
+| `memory stats` | Show memory usage statistics |
+| `memory configure` | Configure memory backend settings |
+| `memory cleanup` | Remove expired or stale entries |
+| `memory compress` | Compress stored data and rebuild indexes |
+| `memory export` | Export memories to JSON/JSONL file |
+| `memory import` | Import memories from a file |
+
+## Quick Reference
+
+```bash
+# Initialize
+npx monomind memory init --backend hybrid
+
+# Store
+npx monomind memory store --key "auth-pattern" --value "Use JWT with refresh tokens" --namespace "patterns"
+
+# Search
+npx monomind memory search --query "authentication" --type hybrid --build-hnsw
+
+# Retrieve exact key
+npx monomind memory retrieve --key "auth-pattern"
+
+# List all in namespace
+npx monomind memory list --namespace "patterns"
+
+# Export / Import
+npx monomind memory export --output backup.json --format json
+npx monomind memory import --input backup.json --merge
+```
+
+## Files
+
+- [memory-search.md](./memory-search.md) — Search memory (semantic/keyword/hybrid + HNSW)
+
+## MCP Tools
+
+| Tool | Purpose |
+|---|---|
+| `mcp__monomind__memory_store` | Store a memory entry |
+| `mcp__monomind__memory_retrieve` | Retrieve by key |
+| `mcp__monomind__memory_search` | Search memory |
+| `mcp__monomind__memory_list` | List entries |
+| `mcp__monomind__memory_delete` | Delete entries |
+| `mcp__monomind__memory_stats` | Usage statistics |
+| `mcp__monomind__memory_migrate` | Migrate between backends |
+
+## Backends
+
+| Backend | Description | Recommended |
+|---|---|---|
+| `agentdb` | Full AgentDB with HNSW vector search | Production |
+| `sqlite` | SQLite-only, no vector search | Lightweight |
+| `hybrid` | SQLite + AgentDB HNSW | Default (recommended) |
 
-## Available Commands
+## See Also
 
-- [memory-usage](./memory-usage.md)
-- [memory-persist](./memory-persist.md)
-- [memory-search](./memory-search.md)
+- `hooks intelligence` — pattern learning on top of memory
+- `neural` — neural pattern training
+- `session` — session state (separate from memory)

package/.claude/commands/memory/memory-search.md

@@ -1,25 +1,77 @@
-# memory-search
+---
+name: memory:memory-search
+---
 
-Search through stored memory.
+# memory search
+
+Search stored memory using semantic, keyword, or hybrid search.
 
 ## Usage
+
 ```bash
 npx monomind memory search [options]
 ```
 
 ## Options
-- `--query <text>` - Search query
-- `--pattern <regex>` - Pattern matching
-- `--limit <n>` - Result limit
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--query` | `-q` | string | — | Search query text |
+| `--namespace` | `-n` | string | `default` | Namespace to search |
+| `--limit` | `-l` | number | `10` | Maximum results to return |
+| `--threshold` | — | number | `0.7` | Minimum similarity threshold (0–1) |
+| `--type` | `-t` | string | `hybrid` | Search type: `semantic`, `keyword`, `hybrid` |
+| `--build-hnsw` | — | boolean | `false` | Build HNSW index before search (150x–12,500x speedup) |
+| `--format` | — | string | — | Output format: `json` |
 
 ## Examples
+
 ```bash
-# Search memory
-npx monomind memory search --query "authentication"
+# Semantic search
+npx monomind memory search --query "authentication patterns"
+
+# Keyword search
+npx monomind memory search -q "JWT" --type keyword
+
+# Hybrid search with namespace
+npx monomind memory search -q "error handling" -n "project-x" --type hybrid
+
+# Build HNSW index first for large datasets
+npx monomind memory search -q "config" --build-hnsw --limit 20
+
+# High-precision search with threshold
+npx monomind memory search -q "OAuth flow" --threshold 0.9
 
-# Pattern search
-npx monomind memory search --pattern "api-.*"
+# JSON output
+npx monomind memory search -q "auth" --format json
+```
+
+## Search Types
+
+| Type | Description | Best For |
+|---|---|---|
+| `semantic` | Vector similarity search | Concept/meaning matching |
+| `keyword` | BM25 full-text search | Exact term matching |
+| `hybrid` | Combined semantic + keyword | General purpose (recommended) |
+
+## HNSW Index
 
-# Limited results
-npx monomind memory search --query "config" --limit 10
+Use `--build-hnsw` when searching large memory stores (1,000+ entries). The HNSW index provides 150x–12,500x search speedup after the one-time build cost.
+
+## MCP Tool
+
+```javascript
+mcp__monomind__memory_search({
+  query: "authentication patterns",
+  namespace: "default",
+  limit: 10,
+  threshold: 0.7,
+  type: "hybrid"
+})
 ```
+
+## See Also
+
+- `memory store` — store new memories
+- `memory list` — list all memories
+- `memory retrieve` — retrieve by exact key

package/.claude/commands/monitoring/README.md

@@ -1,9 +1,69 @@
+---
+name: monitoring:README
+---
+
 # Monitoring Commands
 
-Commands for monitoring operations in Monomind.
+Commands for monitoring Monomind system health — swarm status, agents, tasks, memory, and performance metrics.
 
 ## Available Commands
 
-- [swarm-monitor](./swarm-monitor.md)
-- [agent-metrics](./agent-metrics.md)
-- [real-time-view](./real-time-view.md)
+| Command | Description |
+|---|---|
+| `status` | Full system status (swarm, agents, tasks, memory, MCP) |
+| `status agents` | Detailed agent table with uptime and success rate |
+| `status tasks` | Detailed task table with progress and priority |
+| `status memory` | Memory backend stats and HNSW performance |
+| `agent metrics` | Agent performance metrics by type and time period |
+| `agent health` | Per-agent health check with optional watch mode |
+| `swarm status` | Swarm-specific status (topology, consensus, agents) |
+
+## Quick Reference
+
+```bash
+# One-shot system snapshot
+npx monomind status
+
+# Live watch (refreshes every 2s)
+npx monomind status --watch
+
+# Health checks with pass/warn/fail
+npx monomind status --health-check
+
+# Detailed agent view
+npx monomind status agents
+
+# Agent performance metrics
+npx monomind agent metrics --period 7d
+
+# Swarm status
+npx monomind swarm status
+```
+
+## Files
+
+- [status.md](./status.md) — Full system status + watch mode + health checks
+- [agents.md](./agents.md) — `status agents` subcommand
+- [agent-metrics.md](./agent-metrics.md) — `agent metrics` by type and period
+
+## MCP Tools
+
+| Tool | Purpose |
+|---|---|
+| `mcp__monomind__swarm_status` | Swarm health and agent counts |
+| `mcp__monomind__swarm_health` | Swarm health check |
+| `mcp__monomind__agent_list` | All agents with metrics |
+| `mcp__monomind__agent_status` | Specific agent status |
+| `mcp__monomind__agent_health` | Agent health check |
+| `mcp__monomind__memory_stats` | Memory backend stats |
+| `mcp__monomind__task_summary` | Task counts by status |
+| `mcp__monomind__task_list` | All tasks with progress |
+| `mcp__monomind__system_health` | Full system health |
+| `mcp__monomind__system_metrics` | System performance metrics |
+| `mcp__monomind__mcp_status` | MCP server status |
+
+## See Also
+
+- `doctor` — comprehensive diagnostics (`npx monomind doctor`)
+- `hooks metrics` — learning and intelligence metrics
+- `performance` — performance profiling commands

package/.claude/commands/monitoring/agent-metrics.md

@@ -1,25 +1,65 @@
-# agent-metrics
+---
+name: monitoring:agent-metrics
+---
 
-View agent performance metrics.
+# agent metrics
+
+Show agent performance metrics — tasks completed, success rate, and memory vectors by agent type.
 
 ## Usage
+
 ```bash
-npx monomind agent metrics [options]
+npx monomind agent metrics [agentId] [options]
 ```
 
+The optional `agentId` positional argument filters to a specific agent. Omit for all agents.
+
 ## Options
-- `--agent-id <id>` - Specific agent
-- `--period <time>` - Time period
-- `--format <type>` - Output format
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--period` | `-p` | string | `24h` | Time period: `1h`, `24h`, `7d`, `30d` |
+| `--format` | — | string | — | Output format: `json` |
 
 ## Examples
+
 ```bash
-# All agents metrics
+# All agents — last 24 hours
 npx monomind agent metrics
 
-# Specific agent
-npx monomind agent metrics --agent-id agent-001
-
 # Last hour
 npx monomind agent metrics --period 1h
+
+# Last 7 days
+npx monomind agent metrics -p 7d
+
+# Specific agent
+npx monomind agent metrics agent-001
+
+# JSON output
+npx monomind agent metrics --format json
 ```
+
+## Output Sections
+
+**Summary table** — total agents, active agents, tasks completed, average success rate, memory vector count
+
+**By Agent Type table** — per-type breakdown: count, tasks completed, success rate
+
+**Memory** — vector count and search backend (HNSW-indexed once vectors exist)
+
+## Data Source
+
+Metrics are read from `.swarm/agents/` state files and `.swarm/swarm-activity.json`. If no agents have been spawned yet, the output will note this with a suggestion to run `agent spawn`.
+
+## MCP Tool
+
+```javascript
+mcp__monomind__agent_status({ agentId: "agent-001" })
+```
+
+## See Also
+
+- `status agents` — live agent status table
+- `agent health` — per-agent health check with `--watch` mode
+- `agent list` — list all agents

package/.claude/commands/monitoring/agents.md

@@ -1,44 +1,71 @@
-# List Active Patterns
+---
+name: monitoring:agents
+---
 
-## 🎯 Key Principle
-**This tool coordinates Claude Code's actions. It does NOT write code or create content.**
+# status agents
 
-## MCP Tool Usage in Claude Code
+Show detailed agent status — ID, type, current task, uptime, and success rate for all running agents.
 
-**Tool:** `mcp__monomind__agent_list`
+## Usage
 
-## Parameters
-```json
-{
-  "swarmId": "current"
-}
+```bash
+npx monomind status agents [options]
 ```
 
-## Description
-View all active cognitive patterns and their current focus areas
+## Options
 
-## Details
-Filters:
-- **all**: Show all defined patterns
-- **active**: Currently engaged patterns
-- **idle**: Available but unused patterns
-- **busy**: Patterns actively coordinating tasks
+| Flag | Type | Description |
+|---|---|---|
+| `--format` | string | Output format: `json` |
 
-## Example Usage
+## Examples
 
-**In Claude Code:**
-1. List all agents: Use tool `mcp__monomind__agent_list`
-2. Get specific agent metrics: Use tool `mcp__monomind__agent_metrics` with parameters `{"agentId": "coder-123"}`
-3. Monitor agent performance: Use tool `mcp__monomind__swarm_monitor` with parameters `{"interval": 2000}`
+```bash
+# Show all agents
+npx monomind status agents
 
-## Important Reminders
-- ✅ This tool provides coordination and structure
-- ✅ Claude Code performs all actual implementation
-- ❌ The tool does NOT write code
-- ❌ The tool does NOT access files directly
-- ❌ The tool does NOT execute commands
+# JSON output
+npx monomind status agents --format json
+```
+
+## Output Columns
+
+| Column | Description |
+|---|---|
+| ID | Agent identifier |
+| Type | Agent type (coder, reviewer, tester, etc.) |
+| Status | `healthy` / `degraded` / `stopped` |
+| Current Task | Task the agent is executing (or `-`) |
+| Uptime | How long the agent has been running |
+| Success | Task success rate (%) |
+
+## Related Commands
+
+```bash
+# Quick agent count overview (in main status)
+npx monomind status
+
+# Agent performance metrics by type
+npx monomind agent metrics
+
+# Agent health check
+npx monomind agent health
+
+# List all agents
+npx monomind agent list
+```
+
+## MCP Tool
+
+```javascript
+mcp__monomind__agent_list({
+  includeMetrics: true,
+  status: "all"
+})
+```
 
 ## See Also
-- Main documentation: /CLAUDE.md
-- Other commands in this category
-- Workflow examples in /workflows/
+
+- `status` — full system status including agents
+- `agent metrics` — performance metrics over time
+- `agent health` — per-agent health checks

package/.claude/commands/monitoring/status.md

@@ -1,46 +1,108 @@
-# Check Coordination Status
+---
+name: monitoring:status
+---
 
-## 🎯 Key Principle
-**This tool coordinates Claude Code's actions. It does NOT write code or create content.**
+# status
 
-## MCP Tool Usage in Claude Code
+Show system status — swarm health, agents, tasks, memory, and MCP server. The primary monitoring command.
 
-**Tool:** `mcp__monomind__swarm_status`
+## Usage
 
-## Parameters
-```json
-{
-  "swarmId": "current"
-}
+```bash
+npx monomind status [options]
+npx monomind status <subcommand>
 ```
 
-## Description
-Monitor the effectiveness of current coordination patterns
+## Options
 
-## Details
-Shows:
-- Active coordination topologies
-- Current cognitive patterns in use
-- Task breakdown and progress
-- Resource utilization for coordination
-- Overall system health
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--watch` | `-w` | boolean | `false` | Continuously refresh status (live view) |
+| `--interval` | `-i` | number | `2` | Refresh interval in seconds (watch mode) |
+| `--health-check` | — | boolean | `false` | Run structured health checks and exit |
+| `--format` | — | string | — | Output format: `json` |
 
-## Example Usage
+## Subcommands
 
-**In Claude Code:**
-1. Check swarm status: Use tool `mcp__monomind__swarm_status`
-2. Monitor in real-time: Use tool `mcp__monomind__swarm_monitor` with parameters `{"interval": 1000}`
-3. Get agent metrics: Use tool `mcp__monomind__agent_metrics` with parameters `{"agentId": "agent-123"}`
-4. Health check: Use tool `mcp__monomind__health_check` with parameters `{"components": ["swarm", "memory", "neural"]}`
+| Subcommand | Description |
+|---|---|
+| `status agents` | Detailed agent status table (ID, type, current task, uptime, success rate) |
+| `status tasks` | Detailed task status table (ID, type, priority, agent, progress) |
+| `status memory` | Memory backend stats (entries, size, HNSW, performance metrics) |
 
-## Important Reminders
-- ✅ This tool provides coordination and structure
-- ✅ Claude Code performs all actual implementation
-- ❌ The tool does NOT write code
-- ❌ The tool does NOT access files directly
-- ❌ The tool does NOT execute commands
+## Examples
+
+```bash
+# One-shot status snapshot
+npx monomind status
+
+# Live watch mode (refreshes every 2s)
+npx monomind status --watch
+
+# Watch with custom interval
+npx monomind status --watch -i 5
+
+# Health checks with pass/warn/fail output
+npx monomind status --health-check
+
+# JSON output for scripting
+npx monomind status --format json
+
+# Detailed agent table
+npx monomind status agents
+
+# Detailed task table
+npx monomind status tasks
+
+# Memory backend details
+npx monomind status memory
+```
+
+## Status Display Sections
+
+- **Swarm** — ID, topology, health (`healthy` / `degraded` / `stopped`), uptime
+- **Agents** — active / idle / total counts
+- **Tasks** — pending / running / completed / failed / total
+- **Memory** — backend, entries, size, search time, cache hit rate
+- **MCP Server** — running state, transport, port
+- **Performance** — CPU usage, memory usage, Flash Attention, vector search speed
+
+## Health Check Mode
+
+`--health-check` runs structured checks and exits with code 0 (all pass) or 1 (any fail):
+
+| Check | Pass Condition |
+|---|---|
+| System Running | MCP/swarm reachable |
+| Swarm Health | status = `healthy` |
+| Agents Available | active > 0 |
+| MCP Server | running |
+| Memory Backend | backend != `none` |
+| Task Success Rate | < 5% failure rate |
+
+## Watch Mode
+
+`--watch` clears the screen and re-renders on each interval. Press `Ctrl+C` to exit.
+
+## MCP Tools (equivalent)
+
+```javascript
+// Swarm status
+mcp__monomind__swarm_status({ includeMetrics: true })
+
+// Memory stats
+mcp__monomind__memory_stats({})
+
+// Task summary
+mcp__monomind__task_summary({})
+
+// Agent list
+mcp__monomind__agent_list({ includeMetrics: true, status: "all" })
+```
 
 ## See Also
-- Main documentation: /CLAUDE.md
-- Other commands in this category
-- Workflow examples in /workflows/
+
+- `agent metrics` — performance metrics per agent type
+- `agent health` — agent-specific health check
+- `swarm status` — swarm-specific status
+- `doctor` — comprehensive system diagnostics

package/.claude/commands/monograph/README.md

@@ -0,0 +1,102 @@
+---
+name: monograph:README
+description: Monograph skills index — build, search, and explore the knowledge graph across code, docs, and PDFs using real CLI subcommands and MCP tools
+---
+
+# Monograph Commands
+
+Knowledge graph for code and documents — build, search, and explore relationships across your entire codebase and documentation.
+
+Alias: `monomind kg`
+
+## CLI Subcommands
+
+| Subcommand | Description |
+|---|---|
+| `monograph build` | Build knowledge graph from code + docs + PDFs |
+| `monograph wiki` | Scan all docs and PDFs into a searchable knowledge graph |
+| `monograph search` | Search the graph (BM25 / semantic / hybrid) |
+| `monograph stats` | Show node/edge counts and top concepts |
+| `monograph watch` | Watch for file changes and rebuild incrementally |
+
+## Quick Reference
+
+```bash
+# First-time build (code + all docs)
+npx monomind monograph build
+
+# Doc/wiki-focused build with Claude semantic extraction
+npx monomind monograph wiki --llm
+
+# Search
+npx monomind monograph search -q "authentication flow"
+npx monomind monograph search -q "pipeline" --mode semantic --label Section
+
+# Stats
+npx monomind monograph stats --top 20
+
+# Auto-rebuild on changes
+npx monomind monograph watch
+```
+
+## Files
+
+- [monograph-build.md](./monograph-build.md) — Full build (code + docs + PDFs)
+- [monograph-wiki.md](./monograph-wiki.md) — Doc/PDF-focused wiki build
+- [monograph-search.md](./monograph-search.md) — Search the knowledge graph
+- [monograph-stats.md](./monograph-stats.md) — Graph statistics
+- [monograph-watch.md](./monograph-watch.md) — Watch mode (incremental rebuild)
+
+## MCP Tools
+
+The monograph MCP tools (available in Claude Code via monomind MCP server) provide programmatic access to the graph without invoking the CLI:
+
+| Tool | Use When |
+|---|---|
+| `mcp__monomind__monograph_build` | Build/rebuild the graph |
+| `mcp__monomind__monograph_query` | BM25 keyword search; returns file + line number |
+| `mcp__monomind__monograph_suggest` | Start every task — returns relevant files ranked by task description |
+| `mcp__monomind__monograph_god_nodes` | Find high-centrality internal files |
+| `mcp__monomind__monograph_stats` | Node/edge counts |
+| `mcp__monomind__monograph_report` | Generate GRAPH_REPORT.md |
+| `mcp__monomind__monograph_shortest_path` | How two modules are connected |
+| `mcp__monomind__monograph_community` | Files forming a cohesive cluster |
+| `mcp__monomind__monograph_surprises` | Unexpected cross-community edges |
+| `mcp__monomind__monograph_export` | Export graph in various formats |
+| `mcp__monomind__monograph_watch` | Start watch mode via MCP |
+| `mcp__monomind__monograph_watch_stop` | Stop watch mode |
+| `mcp__monomind__monograph_context` | 360-degree view of a file: importers, imports, siblings |
+| `mcp__monomind__monograph_health` | Index staleness (commits behind HEAD) |
+
+## Node Types
+
+| Type | Description |
+|---|---|
+| `File` | Source code or document file |
+| `Section` | Markdown heading or document section |
+| `Function` | Code function or method |
+| `Class` | Code class or interface |
+| `Concept` | Extracted semantic concept |
+| `PDF` | PDF document chunk |
+
+## Edge Types
+
+| Relation | Meaning |
+|---|---|
+| `IMPORTS` | Code import dependency |
+| `DEFINES` | File defines symbol |
+| `TAGGED_AS` | Section tagged with concept |
+| `CO_OCCURS` | Concepts appear together |
+| `INFERRED` | Claude-extracted semantic relationship |
+| `DESCRIBES` / `CAUSES` / `PART_OF` | LLM-enriched semantic edges |
+
+## When to Use CLI vs MCP
+
+- **CLI** (`npx monomind monograph ...`) — One-time builds, manual searches, watching from terminal
+- **MCP tools** (`mcp__monomind__monograph_*`) — Claude Code integration, programmatic queries during tasks
+
+## See Also
+
+- `memory` — Vector memory storage (separate from graph)
+- `hooks intelligence` — Pattern learning
+- CLAUDE.md Knowledge Graph section — workflow guidance for multi-file tasks