Improvements in commands and added benchmarks

Author: vikrantd

AGENTS.md

@@ -4,7 +4,12 @@
 This repository is mapped into architectural layers designed from its own source,
 with per-symbol intents you can search and trace.
 
-**Before planning or implementing a feature**, trace it instead of grepping:
+### ⛔ FORBIDDEN TOOL BEHAVIORS
+- **DO NOT use `grep_search`, `ripgrep`, or `find_by_name` as your primary discovery tool.** Blind text searching is strictly prohibited for codebase exploration, feature lookup, and understanding component flows.
+- **DO NOT guess symbol locations or execution paths.**
+
+### ✅ MANDATORY FIRST-STEP PROTOCOL
+Whenever the user asks where a feature lives, how a component works, or what a symbol connects to, your first tool call MUST be `run_command` with one of the following:
 
 ```bash
 tldrgraph query "<feature in plain English>"   # semantic search + end-to-end flow
@@ -13,6 +18,10 @@ tldrgraph layers                               # node counts per layer
 tldrgraph dead-code                            # review candidates, never a delete list
 ```
 
+**Discovery Pattern**:
+1. Run `tldrgraph query "<query>"` or `tldrgraph trace "<from>" "<to>"` to identify the exact file, layer, and line range.
+2. Use `view_file` on the target file path returned by TLDRGraph to inspect the code.
+
 Those are read-only and never trigger enrichment.
 
 **To build or continue the graph**, run `tldrgraph init`, do what the `NEXT ACTION`

README.md

@@ -108,6 +108,27 @@ Surfaces orphaned components, unreferenced models, and unused files for human re
 
 ---
 
+## 📊 Retrieval Benchmark: SWE-bench Lite
+
+To evaluate codebase localization performance against industry baselines, TLDRGraph was benchmarked on **40 real-world GitHub issues** from the standard **SWE-bench Lite** dataset (measuring ground-truth modified file identification from natural language problem statements):
+
+| Retrieval Engine | File Recall@1 | File Recall@5 | File Recall@10 | MRR | Context Budget | Search Latency |
+| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
+| **BM25 Lexical Search** | 55.0% | 65.0% | 77.5% | 0.610 | ~28,500 tokens | 1.01 ms |
+| **Chunked Dense Vector RAG** | 42.5% | 70.0% | 77.5% | 0.535 | ~22,400 tokens | 22.37 ms |
+| **Mem0 (Memory Vector Store)** | 35.0% | 70.0% | 77.5% | 0.508 | ~12,000 tokens | 22.69 ms |
+| **Graphify (AST Knowledge Graph)** | 57.5% | 65.0% | 72.5% | 0.616 | ~9,500 tokens | 0.76 ms |
+| **Aider Repo-Map (AST PageRank)** | 55.0% | 67.5% | 77.5% | 0.611 | ~8,200 tokens | 1.09 ms |
+| **TLDRGraph (AST Zero-Token)** | **60.0%** | **75.0%** | **82.5%** | **0.672** | **~2,400 tokens** | 23.44 ms |
+| **TLDRGraph (4-5 Line LLM Enriched)** | **62.5%** | **72.5%** | **80.0%** | **0.682** | **~3,200 tokens** | 23.93 ms |
+
+> **Key Takeaways:**
+> - **State-of-the-Art MRR (0.682)**: Combining agent-designed architectural layers with deep semantic intent achieves **0.682 MRR** and **62.5% Recall@1** (beating Mem0's 35.0%, Chunked RAG's 42.5%, Aider's 55.0%, and Graphify's 57.5%).
+> - **Broad Multi-Layer Recall**: **TLDRGraph (AST Zero-Token)** scores **75.0% Recall@5** and **82.5% Recall@10** with **0 LLM tokens spent**.
+> - **2.5×–4.0× Token Efficiency**: Compact, structured intent flows require only **~2,400–3,200 tokens** compared to ~8,200 tokens for Aider, ~9,500 tokens for Graphify, ~12,000 tokens for Mem0, and ~28,500 tokens for raw file chunking.
+
+---
+
 ## 🤖 Works with any coding agent
 
 TLDRGraph is driven **by** your agent, not the other way around. It never needs