know-cli 0.4.0__tar.gz → 0.4.2__tar.gz

{know_cli-0.4.0 → know_cli-0.4.2}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: know-cli
-Version: 0.4.0
+Version: 0.4.2
 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
+Project-URL: Homepage, https://github.com/sushilk1991/know-cli
+Project-URL: Repository, https://github.com/sushilk1991/know-cli
 Author-email: Sushil Kumar <sushilk.1991@gmail.com>
 License-Expression: MIT
 Keywords: ai,cli,codebase,coding-agent,context,embeddings,llm,mcp,tokens
@@ -17,16 +17,24 @@ 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: tiktoken>=0.5.0
+Requires-Dist: tree-sitter-c>=0.23.0
+Requires-Dist: tree-sitter-go>=0.23.0
+Requires-Dist: tree-sitter-java>=0.23.0
+Requires-Dist: tree-sitter-javascript>=0.23.0
+Requires-Dist: tree-sitter-python>=0.23.0
+Requires-Dist: tree-sitter-ruby>=0.23.0
+Requires-Dist: tree-sitter-rust>=0.23.0
+Requires-Dist: tree-sitter-typescript>=0.23.0
+Requires-Dist: tree-sitter>=0.24.0
 Requires-Dist: watchdog>=3.0.0
 Requires-Dist: xxhash>=3.0.0
+Provides-Extra: ai
+Requires-Dist: anthropic>=0.8.0; extra == 'ai'
 Provides-Extra: dev
 Requires-Dist: black>=23.0.0; extra == 'dev'
 Requires-Dist: mypy>=1.0.0; extra == 'dev'
@@ -36,9 +44,6 @@ 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'
@@ -68,6 +73,8 @@ AI coding agents dump entire files into context. Every `@file` reference, every
 - 📊 Import graph knows what depends on what
 - 🧠 Cross-session memory means agents never re-discover the same things
 - 💰 Token budgeting keeps costs predictable
+- ⚡ Background daemon for sub-100ms query latency
+- 🤖 Agent-native commands (`next-file`, `signatures`, `related`) for autonomous workflows
 
 **60-80% fewer tokens. Same (or better) results.**
 
@@ -84,6 +91,8 @@ 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.
 
+The background daemon starts automatically on first use — subsequent queries return in under 100ms.
+
 ---
 
 ## Works With
@@ -129,39 +138,17 @@ 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)
+### 🔍 Semantic Search — `know search`
 
-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)**
+Real embeddings, not grep. Understands meaning, not just keywords.
 
 ```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
+know search "authentication" --chunk  # Search at function level
 ```
 
-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.
+Uses [fastembed](https://github.com/qdrant/fastembed) (BAAI/bge-small-en-v1.5) — runs locally, no API calls.
 
 ### 📊 Import Graph — `know graph`
 
@@ -197,76 +184,38 @@ know mcp config                   # Print Claude Desktop config
 
 **MCP Resources:** `codebase://digest`, `codebase://structure`, `codebase://memories`
 
-### 🛠 Tool Discovery — `know tools`
+### 🤖 Agent Commands
 
-Find runnable project tools so agents stop guessing commands.
+Purpose-built for autonomous AI agent workflows.
 
 ```bash
-know tools list
-know tools search "database"
-know tools suggest "deploy"
-know --output-format markdown tools list
+know next-file "authentication" --exclude src/auth/old.py
+know signatures src/auth/middleware.py
+know related src/auth/middleware.py
+know generate-context --budget 8000
+know diff --since "3 days ago"
 ```
 
-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
-```
+| Command | Description |
+|---------|-------------|
+| `know next-file "query"` | Return the single most relevant file for a query |
+| `know signatures [file]` | Get function/class signatures for a file or project |
+| `know related <file>` | Show import dependencies and dependents |
+| `know generate-context` | Generate `.know/CONTEXT.md` for agents to read on session start |
+| `know diff --since "1 week ago"` | Show architectural changes over time |
 
-### 🔗 Dependency Neighbors — `know related`
+### ⚡ Background Daemon
 
-See what a file imports and what imports it.
+A Unix socket daemon keeps indexes in memory for instant responses.
 
 ```bash
-know related src/auth.py
+know status   # Shows daemon status, index age, cache size
 ```
 
-### 📊 Module Summaries — `know summarize`
-
-One-sentence summary for each module in the codebase.
-
-```bash
-know summarize --limit 50
-```
+- Starts automatically on first CLI call
+- Serves search, signatures, related, and memory queries over IPC
+- Falls back to direct SQLite access if daemon is unavailable
+- Disable with `KNOW_NO_DAEMON=1` for CI/CD environments
 
 ### 📈 Usage Stats — `know stats`
 
@@ -361,31 +310,29 @@ know status --json
 | `know remember "text"` | Store a memory |
 | `know recall "query"` | Recall memories |
 | `know forget <id>` | Delete a memory |
+| `know memories list` | List all memories |
 | `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 |
+| `know next-file "query"` | Best file for a query (agent use) |
+| `know signatures [file]` | Function/class signatures |
+| `know related <file>` | Import deps and dependents |
+| `know generate-context` | Generate `.know/CONTEXT.md` |
+| `know diff --since "1w"` | Architectural changes over time |
+| `know hooks install` | Install git hooks for auto-update |
+| `know hooks uninstall` | Remove git hooks |
 
 ### 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 |
@@ -433,6 +380,8 @@ Your Query → know context
 
 All processing is **local**. Embeddings run on your machine. No data leaves your laptop (except `know explain` which calls Claude API).
 
+Semantic search via [fastembed](https://github.com/qdrant/fastembed) is optional — install with `pip install know-cli[search]`. Without it, know uses fast BM25 full-text search as the default.
+
 ---
 
 ## Configuration
@@ -475,10 +424,22 @@ exclude_paths:
 
 ---
 
+## Architecture
+
+```
+.know/
+  config.yaml     # Project configuration
+  daemon.db       # Unified SQLite database (chunks, memories, imports)
+  cache/
+    index.db      # Scanner cache
+```
+
+**Single database:** All data (code chunks, memories, import graph) lives in one SQLite database with WAL mode for concurrent access. The background daemon keeps it in memory; CLI commands fall back to direct access when the daemon is unavailable.
+
 ## Contributing
 
 ```bash
-git clone https://github.com/vic/know-cli
+git clone https://github.com/sushilk1991/know-cli
 cd know-cli
 pip install -e ".[dev,search,mcp]"
 python -m pytest tests/ -v

{know_cli-0.4.0 → know_cli-0.4.2}/README.md

@@ -22,6 +22,8 @@ AI coding agents dump entire files into context. Every `@file` reference, every
 - 📊 Import graph knows what depends on what
 - 🧠 Cross-session memory means agents never re-discover the same things
 - 💰 Token budgeting keeps costs predictable
+- ⚡ Background daemon for sub-100ms query latency
+- 🤖 Agent-native commands (`next-file`, `signatures`, `related`) for autonomous workflows
 
 **60-80% fewer tokens. Same (or better) results.**
 
@@ -38,6 +40,8 @@ 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.
 
+The background daemon starts automatically on first use — subsequent queries return in under 100ms.
+
 ---
 
 ## Works With
@@ -83,39 +87,17 @@ 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)
+### 🔍 Semantic Search — `know search`
 
-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)**
+Real embeddings, not grep. Understands meaning, not just keywords.
 
 ```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
+know search "authentication" --chunk  # Search at function level
 ```
 
-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.
+Uses [fastembed](https://github.com/qdrant/fastembed) (BAAI/bge-small-en-v1.5) — runs locally, no API calls.
 
 ### 📊 Import Graph — `know graph`
 
@@ -151,76 +133,38 @@ know mcp config                   # Print Claude Desktop config
 
 **MCP Resources:** `codebase://digest`, `codebase://structure`, `codebase://memories`
 
-### 🛠 Tool Discovery — `know tools`
+### 🤖 Agent Commands
 
-Find runnable project tools so agents stop guessing commands.
+Purpose-built for autonomous AI agent workflows.
 
 ```bash
-know tools list
-know tools search "database"
-know tools suggest "deploy"
-know --output-format markdown tools list
+know next-file "authentication" --exclude src/auth/old.py
+know signatures src/auth/middleware.py
+know related src/auth/middleware.py
+know generate-context --budget 8000
+know diff --since "3 days ago"
 ```
 
-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
-```
+| Command | Description |
+|---------|-------------|
+| `know next-file "query"` | Return the single most relevant file for a query |
+| `know signatures [file]` | Get function/class signatures for a file or project |
+| `know related <file>` | Show import dependencies and dependents |
+| `know generate-context` | Generate `.know/CONTEXT.md` for agents to read on session start |
+| `know diff --since "1 week ago"` | Show architectural changes over time |
 
-### 🔗 Dependency Neighbors — `know related`
+### ⚡ Background Daemon
 
-See what a file imports and what imports it.
+A Unix socket daemon keeps indexes in memory for instant responses.
 
 ```bash
-know related src/auth.py
+know status   # Shows daemon status, index age, cache size
 ```
 
-### 📊 Module Summaries — `know summarize`
-
-One-sentence summary for each module in the codebase.
-
-```bash
-know summarize --limit 50
-```
+- Starts automatically on first CLI call
+- Serves search, signatures, related, and memory queries over IPC
+- Falls back to direct SQLite access if daemon is unavailable
+- Disable with `KNOW_NO_DAEMON=1` for CI/CD environments
 
 ### 📈 Usage Stats — `know stats`
 
@@ -315,31 +259,29 @@ know status --json
 | `know remember "text"` | Store a memory |
 | `know recall "query"` | Recall memories |
 | `know forget <id>` | Delete a memory |
+| `know memories list` | List all memories |
 | `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 |
+| `know next-file "query"` | Best file for a query (agent use) |
+| `know signatures [file]` | Function/class signatures |
+| `know related <file>` | Import deps and dependents |
+| `know generate-context` | Generate `.know/CONTEXT.md` |
+| `know diff --since "1w"` | Architectural changes over time |
+| `know hooks install` | Install git hooks for auto-update |
+| `know hooks uninstall` | Remove git hooks |
 
 ### 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 |
@@ -387,6 +329,8 @@ Your Query → know context
 
 All processing is **local**. Embeddings run on your machine. No data leaves your laptop (except `know explain` which calls Claude API).
 
+Semantic search via [fastembed](https://github.com/qdrant/fastembed) is optional — install with `pip install know-cli[search]`. Without it, know uses fast BM25 full-text search as the default.
+
 ---
 
 ## Configuration
@@ -429,10 +373,22 @@ exclude_paths:
 
 ---
 
+## Architecture
+
+```
+.know/
+  config.yaml     # Project configuration
+  daemon.db       # Unified SQLite database (chunks, memories, imports)
+  cache/
+    index.db      # Scanner cache
+```
+
+**Single database:** All data (code chunks, memories, import graph) lives in one SQLite database with WAL mode for concurrent access. The background daemon keeps it in memory; CLI commands fall back to direct access when the daemon is unavailable.
+
 ## Contributing
 
 ```bash
-git clone https://github.com/vic/know-cli
+git clone https://github.com/sushilk1991/know-cli
 cd know-cli
 pip install -e ".[dev,search,mcp]"
 python -m pytest tests/ -v

know_cli-0.4.2/docs/arc.md

@@ -0,0 +1,38 @@
+# know-cli
+
+
+
+*Generated by [know](https://github.com/sushilk1991/know-cli)*
+
+
+## 📁 Project Structure
+
+- **[src.know.ai](src/know/ai.py)** - AI integration for intelligent code understanding with advanced token optimization.
+- **[src.know.diff](src/know/diff.py)** - Diff mode for tracking architectural changes safely using git worktrees.
+- **[src.know.knowledge_base](src/know/knowledge_base.py)** - Knowledge base: cross-session memory for AI agents.
+- **[src.know.index](src/know/index.py)** - Index management for incremental code scanning.
+- **[src.know.logger](src/know/logger.py)** - Logging configuration for know.
+- **[src.know.watcher](src/know/watcher.py)** - File system watcher for auto-updating documentation.
+- **[src.know.models](src/know/models.py)** - Data models for know-cli.
+- **[src.know.token_counter](src/know/token_counter.py)** - Token counting for context budget management.
+- **[src.know.model_router](src/know/model_router.py)** - Smart model router for cost-optimized AI interactions.
+- **[src.know.stats](src/know/stats.py)** - Usage statistics tracker for know-cli.
+- **[src.know.semantic_search](src/know/semantic_search.py)** - Semantic code search using real embeddings and vector similarity.
+- **[src.know.__init__](src/know/__init__.py)** - know - Living documentation generator for codebases.
+- **[src.know.cli](src/know/cli.py)** - CLI entry point for know.
+- **[src.know.generator](src/know/generator.py)** - Documentation generator.
+- **[src.know.config](src/know/config.py)** - Configuration management for know.
+- ... and 8 more modules
+
+## 📊 Statistics
+
+- **Files:** 23
+- **Modules:** 23
+- **Functions:** 57
+- **Classes:** 47
+
+---
+
+*Generated by [know](https://github.com/sushilk1991/know-cli) v1.0.0*
+
+Run `know update` to refresh this documentation.