Metadata-Version: 2.4
Name: know-cli
Version: 0.3.9
Summary: Context Intelligence for AI Coding Agents — smart, token-budgeted code context
Project-URL: Homepage, https://github.com/vic/know-cli
Project-URL: Repository, https://github.com/vic/know-cli
Author-email: Sushil Kumar <sushilk.1991@gmail.com>
License-Expression: MIT
Keywords: ai,cli,codebase,coding-agent,context,embeddings,llm,mcp,tokens
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.8.0
Requires-Dist: click>=8.1.0
Requires-Dist: fastembed>=0.3.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pathspec>=0.11.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: xxhash>=3.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: parser
Requires-Dist: tree-sitter-languages>=1.10.0; extra == 'parser'
Requires-Dist: tree-sitter>=0.20.0; extra == 'parser'
Provides-Extra: search
Requires-Dist: fastembed>=0.3.0; extra == 'search'
Requires-Dist: numpy>=1.24.0; extra == 'search'
Description-Content-Type: text/markdown

# know — Context Intelligence for AI Coding Agents

> Your AI agent wastes tokens. **know** gives it exactly what it needs.

[![PyPI](https://img.shields.io/pypi/v/know-cli)](https://pypi.org/project/know-cli/)
[![Python](https://img.shields.io/pypi/pyversions/know-cli)](https://pypi.org/project/know-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

---

## The Problem

AI coding agents dump entire files into context. Every `@file` reference, every `cat` command — full files, whether you need 3 lines or 3000.

**Result:** Slow. Expensive. Often irrelevant. Your agent burns through your token budget reading imports it doesn't need.

## The Solution

**know** understands your codebase and serves the *minimum* context needed.

- 🎯 Semantic search finds the *relevant* functions, not entire files
- 📊 Import graph knows what depends on what
- 🧠 Cross-session memory means agents never re-discover the same things
- 💰 Token budgeting keeps costs predictable

**60-80% fewer tokens. Same (or better) results.**

---

## Quick Start (30 seconds)

```bash
pip install know-cli
cd your-project
know init
know context "help me fix the auth bug" --budget 4000
```

That's it. You just got the most relevant code for your task, packed into exactly 4000 tokens.

---

## Works With

| Tool | Integration |
|------|-------------|
| **Claude Code** | Drop in `KNOW_SKILL.md` — Claude uses know automatically |
| **Claude Desktop** | MCP server: `know mcp serve` |
| **Cursor** | MCP server or CLI |
| **Any CLI agent** | Pipe-friendly: `know context "query" --json` |
| **Any MCP client** | Standard MCP protocol |

---

## Features

### 🎯 Smart Context — `know context`

The killer feature. Ask for what you need, get exactly that — within budget.

```bash
know context "fix the authentication middleware" --budget 8000
know context "add pagination to the users API" --budget 4000 --json
echo "refactor the config system" | know context --budget 6000
```

**How it works:**
1. Semantic search finds relevant functions/classes (not whole files)
2. Import graph pulls in dependencies (signatures only)
3. Test matcher finds related tests
4. Git recency boosts recently-changed code
5. Token budgeting packs it all optimally

### 🧠 Cross-Session Memory — `know remember` / `know recall`

Agents forget everything between sessions. know doesn't.

```bash
know remember "The auth system uses JWT with Redis session store"
know remember "Never modify the migration files directly" --tags "warning,db"
know recall "how does auth work?"
```

Memories are automatically included in `know context` results. Your agent gets smarter over time.

### 🔍 Search — `know search` (Hybrid like qmd)

Hybrid retrieval by default:
- **Lexical**: SQLite **FTS5** (BM25 ranking) over chunk text + metadata
- **Vector**: embeddings via **fastembed** (when installed)
- **Deterministic rerank**: **Reciprocal Rank Fusion (RRF)**

```bash
# Default: hybrid (FTS + vectors when available)
know search "error handling"

# JSON output (stable schema)
know --json search "database connection pooling" --top-k 10
# (also supported after the command)
know search "database connection pooling" --top-k 10 --json

Notes:
- Queries with punctuation (e.g. `click.option`) are normalized for lexical search.
- Results downweight docs/tests so source code tends to rank higher.
# Force engine
know search "authentication" --engine lexical
know search "authentication" --engine vector

# Filters
know search "jwt" --path src/auth/ --type py

# Better snippets
know search "retry" --line-numbers
```

Notes:
- The FTS index is stored in: `.know/cache/index.db` (table: `chunks_fts`).
- If **FTS5** and/or **fastembed** are unavailable, `know search` gracefully falls back.

### 📊 Import Graph — `know graph`

Real dependency resolution, not guessing.

```bash
know graph src/auth/middleware.py
```

```
📊 Import Graph: src/auth/middleware.py

## Imports (dependencies)
  → src.auth.tokens
  → src.db.session

## Imported by (dependents)
  ← src.api.routes
  ← src.api.admin
```

### 🔌 MCP Server — `know mcp serve`

Standard [Model Context Protocol](https://modelcontextprotocol.io/) server. Works with Claude Desktop, Cursor, and any MCP client.

```bash
know mcp serve                    # stdio transport (Claude Desktop)
know mcp serve --sse --port 3000  # SSE transport (web clients)
know mcp config                   # Print Claude Desktop config
```

**MCP Tools:** `get_context`, `search_code`, `remember`, `recall`, `explain_component`, `show_graph`

**MCP Resources:** `codebase://digest`, `codebase://structure`, `codebase://memories`

### 🛠 Tool Discovery — `know tools`

Find runnable project tools so agents stop guessing commands.

```bash
know tools list
know tools search "database"
know tools suggest "deploy"
know --output-format markdown tools list
```

Scans common sources: `scripts/`, `bin/`, `tools/`, `package.json` scripts, `Makefile` targets, Python CLIs, `docker-compose` services, and GitHub Actions workflows.

### 🧭 Agent State — `know state`

Track active task progress and create checkpoints you can restore later.

```bash
know state set --task "fix auth bug" --progress "analyzed middleware"
know state get
know state checkpoint --name "before refactor"
know state restore cp_1739078400
```

### 🗂 Execution History — `know history`

Log what you tried and whether it worked.

```bash
know history log --command "npm test" --result failed --reason "missing env var"
know history search "test" --result failed
know history success-rate "deploy"
```

### 💸 Cost Analytics — `know cost`

Analyze token usage and estimated cost from local telemetry.
If exact pricing/baseline data is unavailable, know reports fallback estimates and `unknown_fields` explicitly.

```bash
know cost summary
know cost by-query --limit 5
know cost savings
know cost budget --limit 100000
```

### ⚡ Quick File Context — `know quick`

Get a minimal context bundle for one file (default 500-token budget).

```bash
know quick src/auth.py
know quick src/auth.py --budget 800 --json
```

### 🔗 Dependency Neighbors — `know related`

See what a file imports and what imports it.

```bash
know related src/auth.py
```

### 📊 Module Summaries — `know summarize`

One-sentence summary for each module in the codebase.

```bash
know summarize --limit 50
```

### 📈 Usage Stats — `know stats`

Track your ROI. See how much context you're serving and how efficiently.

```bash
know stats
```

```
📊 know-cli Statistics
─────────────────────
  Project: my-app (42 files, 380 functions)

  Knowledge Base:
    12 memories (5 manual, 7 auto)

  Context Engine:
    Queries served: 47
    Avg budget utilization: 82%
    Avg response time: 340ms

  Search:
    Queries: 23
    Avg response time: 85ms
```

---

## For AI Agents

### Claude Code Skill

Drop `KNOW_SKILL.md` into your project root (see below) and Claude Code will automatically use know-cli:

```markdown
# know-cli Integration

Before starting a task:
  Run: know context "<task description>" --budget 8000 --quiet

When you learn something about the codebase:
  Run: know remember "<insight>"

To search for specific code:
  Run: know search "<query>" --json

To understand dependencies:
  Run: know graph <file_path>
```

### MCP Setup (Claude Desktop)

```bash
know mcp config
```

Outputs the JSON config to add to your Claude Desktop settings:

```json
{
  "mcpServers": {
    "know-cli": {
      "command": "know",
      "args": ["mcp", "serve"],
      "cwd": "/path/to/your/project"
    }
  }
}
```

### Pipe-Friendly Output

Every command supports `--json` and `--quiet` for machine consumption:

```bash
know context "query" --json | jq '.code[0].body'
know search "auth" --json
know recall "patterns" --json
know status --json
```

---

## Commands Reference

| Command | Description |
|---------|-------------|
| `know init` | Initialize know in your project |
| `know context "query"` | Build smart, budgeted context |
| `know search "query"` | Semantic code search |
| `know remember "text"` | Store a memory |
| `know recall "query"` | Recall memories |
| `know forget <id>` | Delete a memory |
| `know graph <file>` | Show import dependencies |
| `know quick <file>` | Minimal context for one file |
| `know related <file>` | Show import/dependent neighbors for a file |
| `know summarize` | One-line module summaries |
| `know explain -c <name>` | AI-explain a component |
| `know stats` | Usage statistics |
| `know status` | Project health check |
| `know tools list` | List discovered project tools |
| `know tools search "query"` | Search for tools |
| `know tools suggest "intent"` | Suggest relevant tools for a task |
| `know state set/get/checkpoint/restore` | Manage agent task state |
| `know history log/search/success-rate` | Track command outcomes |
| `know cost summary/by-query/savings/budget` | Token/cost analytics + budget |
| `know reindex` | Rebuild search index |
| `know mcp serve` | Start MCP server |
| `know mcp config` | Print MCP client config |
| `know digest` | Generate codebase summary |
| `know watch` | Auto-update on file changes |

### Global Flags

| Flag | Description |
|------|-------------|
| `--json` | Machine-readable JSON output |
| `--output-format markdown` | Human-readable markdown output for supported commands |
| `--quiet` | Minimal output |
| `--verbose` | Detailed output |
| `--time` | Show execution time |
| `--config <path>` | Custom config file |

---

## Installation

```bash
# Core (CLI + context engine + memory)
pip install know-cli

# With semantic search (recommended)
pip install know-cli[search]

# With MCP server
pip install know-cli[mcp]

# Everything
pip install know-cli[search,mcp]
```

**Requirements:** Python 3.10+

---

## How It Works

```
Your Query → know context
  ├─ Semantic Search (fastembed embeddings)
  │    └─ Finds relevant functions/classes
  ├─ Import Graph (AST-based)
  │    └─ Pulls in dependency signatures
  ├─ Test Matcher
  │    └─ Finds related test files
  ├─ Git Recency
  │    └─ Boosts recently-changed code
  ├─ Knowledge Base
  │    └─ Injects cross-session memories
  └─ Token Budget Allocator
       └─ 40% code | 30% imports | 20% summaries | 10% overview
```

All processing is **local**. Embeddings run on your machine. No data leaves your laptop (except `know explain` which calls Claude API).

---

## Configuration

```bash
know init  # Creates .know/config.yaml
```

Configuration lives in `.know/config.yaml`:

```yaml
project:
  name: my-project
  description: "A web application"
languages:
  - python
include_paths:
  - src/
  - lib/
exclude_paths:
  - tests/fixtures/
  - scripts/
```

---

## Pricing

**Free forever:**
- Full CLI (`know context`, `know search`, `know remember`, etc.)
- MCP server
- Local embeddings
- Unlimited usage

**Pro (coming soon):**
- Cloud sync across machines
- Team knowledge sharing
- Advanced analytics
- Priority support

---

## Contributing

```bash
git clone https://github.com/vic/know-cli
cd know-cli
pip install -e ".[dev,search,mcp]"
python -m pytest tests/ -v
```

---

## License

MIT
