---
description: How and when to use the insights CLI for knowledge management
globs:
alwaysApply: true
---
# Insights CLI

A knowledge management system for storing and retrieving concise, reusable insights organized by topic. Insights persist across sessions and conversations.

## Commands

```
insights add <topic> <name> <overview> <details>    # Store a new insight
insights search <terms...> [-t topic] [-e exact]     # Search across all insights
insights get <topic> <name> [-o overview-only]        # Retrieve a specific insight
insights update <topic> <name> [-o overview] [-d details]  # Update an existing insight
insights delete <topic> <name> [-f force]             # Remove an insight
insights list [topic] [-v] [--pinned] [--sort=X]     # List insights, optionally filtered
insights topics                                       # List all topics
insights pin <topic> <name>                          # Protect insight from pruning
insights unpin <topic> <name>                        # Remove pruning protection
```

## When to Use Insights

**At the start of work:** Search for relevant insights before diving into code. Insights are consolidated, searchable, and source-agnostic — often a as good a starting point as the repo itself.

**During work:** Make multiple searches as you learn more. Follow leads from one insight to the next.

**When you discover something:** Add insights for problem-solution patterns, configuration that works well, workflow optimizations, integration patterns, and niche discoveries about a codebase.

**When you find stale info:** If an insight contradicts what you observe, stop, verify with available tools, and `insights update` the bad information. Before deleting, check usage stats with `insights list -v` — high retrieval or search hit counts suggest the insight is valuable even if the content seems stale. Prefer updating over deleting for frequently accessed insights.

**At the end of work:** Summarize what was done with one final insight.

## Pinning Insights

Pinned insights are protected from pruning and receive a small relevance boost in search results. Use `insights pin` and `insights unpin` to manage them.

**When to pin:**
- Insights that are foundational to the codebase or workflow
- Insights the user explicitly asks to preserve
- Insights you observe being referenced repeatedly across sessions

**When to unpin:** When an insight is no longer relevant or has been superseded by a better one.

**Never delete a pinned insight** without explicitly confirming with the user. If the content is stale, update it instead.

## Usage-Aware Decisions

Insights automatically track how often they are retrieved (`get`) and how often they appear in search results. Use `insights list -v` to see usage stats.

- Before deleting, check access counts — a frequently accessed insight deserves an update, not deletion
- Use `insights list --sort=least-accessed` to find pruning candidates
- Use `insights list --pinned` to review which insights are protected

## What Makes a Good Insight

An insight should be:
- **Reusable** — likely to apply to future situations
- **Non-obvious** — not basic knowledge found in documentation
- **Contextual** — specific to this codebase, workflow, or domain
- **Actionable** — provides clear guidance
- **Focused** — one specific point or pattern per insight

Keep overviews to one sentence. Keep details to 1-3 paragraphs max.

## Topic Organization

Topics are **specific subjects**, not broad categories. One topic per distinct subject (a repo, a tool, an SME, a technology).

Good: `bentley`, `cursor-mcp`, `react-hooks`, `frontend-ui`
Bad: `team-knowledge`, `tool-knowledge`, `repository-knowledge`
