mnemo-dev 0.4.0__tar.gz → 0.5.0__tar.gz

mnemo_dev-0.5.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: mnemo-dev
+Version: 0.5.0
+Summary: Persistent memory and repo map for AI coding assistants
+Author: Mnemo Contributors
+License: AGPL-3.0
+Project-URL: Homepage, https://github.com/Mnemo-mcp/Mnemo
+Project-URL: Repository, https://github.com/Mnemo-mcp/Mnemo
+Project-URL: Issues, https://github.com/Mnemo-mcp/Mnemo/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: tree-sitter>=0.21
+Requires-Dist: tree-sitter-python>=0.21
+Requires-Dist: tree-sitter-javascript>=0.21
+Requires-Dist: tree-sitter-typescript>=0.21
+Requires-Dist: tree-sitter-c-sharp>=0.21
+Requires-Dist: tree-sitter-go>=0.21
+Requires-Dist: tree-sitter-java>=0.21
+Requires-Dist: tree-sitter-rust>=0.21
+Requires-Dist: gitpython>=3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: onnxruntime>=1.17
+Requires-Dist: tokenizers>=0.15
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Provides-Extra: binary
+Requires-Dist: pyinstaller>=6.0; extra == "binary"
+Provides-Extra: all-languages
+Requires-Dist: tree-sitter-ruby>=0.21; extra == "all-languages"
+Requires-Dist: tree-sitter-php>=0.22; extra == "all-languages"
+Requires-Dist: tree-sitter-c>=0.21; extra == "all-languages"
+Requires-Dist: tree-sitter-cpp>=0.21; extra == "all-languages"
+Requires-Dist: tree-sitter-kotlin>=0.21; extra == "all-languages"
+Requires-Dist: tree-sitter-swift>=0.21; extra == "all-languages"
+Requires-Dist: tree-sitter-scala>=0.21; extra == "all-languages"
+Dynamic: license-file
+
+# Mnemo
+
+**Persistent engineering cognition for AI coding agents.**
+
+[![PyPI](https://img.shields.io/pypi/v/mnemo-dev)](https://pypi.org/project/mnemo-dev/)
+[![Tests](https://img.shields.io/badge/tests-223%20passing-brightgreen)]()
+[![License](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)
+
+One command gives your AI agent accumulated engineering understanding across sessions — architecture intelligence, semantic search, code graph, and institutional memory.
+
+```bash
+pip install mnemo-dev
+mnemo init
+```
+
+Your agent now remembers decisions, understands code relationships, and never asks the same question twice.
+
+---
+
+## Why Mnemo
+
+| Without Mnemo | With Mnemo |
+|---------------|-----------|
+| Re-explain your stack every session | Agent already knows your architecture |
+| Agent breaks call chains it can't see | Full dependency graph with impact analysis |
+| "What caching do we use?" → agent greps | Semantic search finds "Redis for sessions" instantly |
+| Decisions lost between sessions | Permanent decisions survive forever |
+| Context window wasted on repetition | ~500 tokens of targeted recall per session |
+
+## Benchmarks
+
+| Metric | Mnemo | Built-in (CLAUDE.md) |
+|--------|-------|---------------------|
+| **Search R@5** | **100%** | N/A (grep) |
+| **Search latency** | **2ms** | — |
+| **RAM** | **265 MB** | 0 |
+| **Store 1 memory** | **5ms** | manual edit |
+| **Token cost/session** | ~500 | 22,000+ (full file) |
+| **Cross-session persistence** | ✅ | ❌ (resets) |
+
+> Search uses ONNX all-MiniLM-L6-v2 dense embeddings + BM25 keyword + knowledge graph traversal, fused with Reciprocal Rank Fusion.
+
+## Quick Start
+
+```bash
+# Install
+pip install mnemo-dev
+
+# Initialize in your repo
+cd your-project
+mnemo init --client kiro    # or: cursor, claude-code, amazonq, copilot, generic
+
+# That's it. Your agent now has persistent memory.
+```
+
+### What `mnemo init` does:
+1. Scans your codebase (tree-sitter + Roslyn for C#)
+2. Builds a knowledge graph (classes, methods, calls, communities)
+3. Installs lifecycle hooks (auto-capture learnings, inject context)
+4. Configures MCP server for your AI client
+5. Downloads embedding model (~86MB, one-time)
+
+### Verify it works:
+```bash
+mnemo recall          # See what the agent will know
+mnemo serve           # Open dashboard at localhost:3333
+mnemo doctor          # Diagnose any issues
+```
+
+---
+
+## How It Works
+
+```
+Session Start (agent-spawn hook)
+  → mnemo_recall injects: decisions + memories + active task + repo map
+  → Agent starts with full context (~500 tokens)
+
+User asks a question (user-prompt-submit hook)
+  → Semantic search finds relevant memories
+  → Injected as <mnemo-relevant-context>
+
+Agent works (tools available via MCP)
+  → mnemo_lookup: class details, methods, signatures
+  → mnemo_graph: neighbors, communities, impact analysis
+  → mnemo_search: find code by meaning
+  → mnemo_remember: store important context
+  → mnemo_decide: record permanent decisions
+
+Session ends (stop hook)
+  → Auto-captures learnings, decisions, session summary
+  → Memories decay over time (hot → warm → cold → evicted)
+  → Contradictions detected and superseded
+```
+
+## Features
+
+### 🧠 Memory System
+- **Categorized storage**: architecture, pattern, bug, preference, decision
+- **Retention scoring**: access frequency × recency × importance
+- **Branch-aware**: memories tagged with git branch, filtered on recall
+- **Contradiction detection**: new facts supersede old conflicting ones
+- **Token-budgeted recall**: never exceeds ~2000 tokens regardless of memory count
+- **Memory slots**: pinned context (project_context, user_preferences, known_gotchas)
+
+### 🔍 Triple-Stream Search
+- **BM25**: stemmed keyword matching with synonym expansion
+- **Vector**: ONNX all-MiniLM-L6-v2 dense embeddings (384-dim, cosine similarity)
+- **Graph**: Dijkstra traversal from code symbols to linked memories
+- **Fusion**: Reciprocal Rank Fusion (RRF) combines all three streams
+
+### 🏗️ Code Intelligence (LadybugDB)
+- **Knowledge graph**: files, classes, methods, functions, projects, communities
+- **14 languages**: Python, JS, TS, C#, Go, Java, Rust + 7 optional
+- **Roslyn enrichment**: C# method signatures, implements, full AST
+- **Leiden clustering**: automatic community detection
+- **Impact analysis**: upstream/downstream dependency tracing
+- **Incremental freshness**: graph auto-updates within 30s of file changes
+
+### 📋 Planning & Records
+- **Task plans**: create, track progress, mark done
+- **Error patterns**: store errors with causes and fixes
+- **Incidents**: root cause analysis with affected services
+- **Code reviews**: feedback history per file
+- **Corrections**: wrong→right pairs the agent learns from
+
+### 🛡️ Safety & Audit
+- **Security scan**: hardcoded secrets, SQL injection, insecure HTTP
+- **Dead code detection**: symbols with no incoming edges
+- **Convention checking**: naming violations
+- **Pre-tool-use hook**: blocks catastrophic shell commands
+
+### 🌐 Dashboard UI
+```bash
+mnemo serve    # http://localhost:3333
+```
+- Interactive knowledge graph (vis-network)
+- Memory & decisions viewer
+- Community explorer with zoom-to-cluster
+- Code search with click-to-focus
+- Health monitoring
+
+---
+
+## MCP Tools (16 agent-facing)
+
+| Tool | Purpose |
+|------|---------|
+| `mnemo_recall` | Load full project context (budgeted) |
+| `mnemo_remember` | Store a memory with category |
+| `mnemo_forget` | Delete a memory |
+| `mnemo_decide` | Record permanent decision |
+| `mnemo_search_memory` | Semantic search across memories |
+| `mnemo_search` | Search code graph (classes/methods/files) |
+| `mnemo_lookup` | Detailed symbol info (methods, signatures) |
+| `mnemo_graph` | Query graph (stats/neighbors/find) |
+| `mnemo_impact` | Upstream/downstream dependency analysis |
+| `mnemo_plan` | Create and track task plans |
+| `mnemo_audit` | Security, health, dead-code reports |
+| `mnemo_record` | Store errors, incidents, reviews |
+| `mnemo_generate` | Commit messages and PR descriptions |
+| `mnemo_map` | Regenerate repo map |
+| `mnemo_ask` | Combined graph + memory lookup |
+| `mnemo_lesson` | Store/retrieve learned patterns |
+
+---
+
+## Supported Clients
+
+| Client | MCP | Hooks | Agent Config |
+|--------|-----|-------|-------------|
+| **Kiro** | ✅ | 5 hooks | ✅ agent + skill |
+| **Amazon Q** | ✅ | — | ✅ rules |
+| **Claude Code** | ✅ | — | ✅ CLAUDE.md |
+| **Cursor** | ✅ | — | ✅ .cursorrules |
+| **Copilot** | ✅ | — | ✅ instructions |
+| **Generic MCP** | ✅ | — | ✅ MNEMO.md |
+
+---
+
+## Performance
+
+| Operation | Time |
+|-----------|------|
+| `mnemo init` (55 files) | 3.5s |
+| `mnemo init` (300 files) | 7s |
+| Re-init (no changes) | 0.01s |
+| Remember 1 memory | 5ms |
+| Recall | 33ms |
+| Semantic search | 2ms |
+| Graph query | 0.2ms |
+
+| Resource | Value |
+|----------|-------|
+| RAM | 265 MB |
+| Disk (.mnemo/) | ~16 MB |
+| Model (one-time download) | 86 MB |
+| External databases | 0 |
+
+---
+
+## Architecture
+
+```
+.mnemo/
+├── memory.json          # Memories with retention scores
+├── decisions.json       # Permanent architectural decisions
+├── plans.json           # Task tracking
+├── graph.lbug           # LadybugDB knowledge graph
+├── vectors_memory.npy   # Dense embedding vectors
+├── meta_memory.json     # Vector metadata
+├── engine-meta.json     # File hashes for incremental updates
+├── parse-cache.json     # AST parse cache
+├── tree.md              # Compact repo map
+└── context.json         # Project context key-values
+```
+
+**Stack**: Python · LadybugDB (Kuzu) · ONNX Runtime · tree-sitter · Roslyn
+
+---
+
+## Links
+
+- **Website**: [mnemo-mcp.github.io/Mnemo](https://mnemo-mcp.github.io/Mnemo/)
+- **PyPI**: [pypi.org/project/mnemo-dev](https://pypi.org/project/mnemo-dev/)
+- **GitHub**: [github.com/Mnemo-mcp/Mnemo](https://github.com/Mnemo-mcp/Mnemo)
+- **VS Code Extension**: [Marketplace](https://marketplace.visualstudio.com/items?itemName=Nikhil1057.mnemo-vscode)
+
+## License
+
+[AGPL-3.0](LICENSE)

mnemo_dev-0.5.0/README.md

@@ -0,0 +1,231 @@
+# Mnemo
+
+**Persistent engineering cognition for AI coding agents.**
+
+[![PyPI](https://img.shields.io/pypi/v/mnemo-dev)](https://pypi.org/project/mnemo-dev/)
+[![Tests](https://img.shields.io/badge/tests-223%20passing-brightgreen)]()
+[![License](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)
+
+One command gives your AI agent accumulated engineering understanding across sessions — architecture intelligence, semantic search, code graph, and institutional memory.
+
+```bash
+pip install mnemo-dev
+mnemo init
+```
+
+Your agent now remembers decisions, understands code relationships, and never asks the same question twice.
+
+---
+
+## Why Mnemo
+
+| Without Mnemo | With Mnemo |
+|---------------|-----------|
+| Re-explain your stack every session | Agent already knows your architecture |
+| Agent breaks call chains it can't see | Full dependency graph with impact analysis |
+| "What caching do we use?" → agent greps | Semantic search finds "Redis for sessions" instantly |
+| Decisions lost between sessions | Permanent decisions survive forever |
+| Context window wasted on repetition | ~500 tokens of targeted recall per session |
+
+## Benchmarks
+
+| Metric | Mnemo | Built-in (CLAUDE.md) |
+|--------|-------|---------------------|
+| **Search R@5** | **100%** | N/A (grep) |
+| **Search latency** | **2ms** | — |
+| **RAM** | **265 MB** | 0 |
+| **Store 1 memory** | **5ms** | manual edit |
+| **Token cost/session** | ~500 | 22,000+ (full file) |
+| **Cross-session persistence** | ✅ | ❌ (resets) |
+
+> Search uses ONNX all-MiniLM-L6-v2 dense embeddings + BM25 keyword + knowledge graph traversal, fused with Reciprocal Rank Fusion.
+
+## Quick Start
+
+```bash
+# Install
+pip install mnemo-dev
+
+# Initialize in your repo
+cd your-project
+mnemo init --client kiro    # or: cursor, claude-code, amazonq, copilot, generic
+
+# That's it. Your agent now has persistent memory.
+```
+
+### What `mnemo init` does:
+1. Scans your codebase (tree-sitter + Roslyn for C#)
+2. Builds a knowledge graph (classes, methods, calls, communities)
+3. Installs lifecycle hooks (auto-capture learnings, inject context)
+4. Configures MCP server for your AI client
+5. Downloads embedding model (~86MB, one-time)
+
+### Verify it works:
+```bash
+mnemo recall          # See what the agent will know
+mnemo serve           # Open dashboard at localhost:3333
+mnemo doctor          # Diagnose any issues
+```
+
+---
+
+## How It Works
+
+```
+Session Start (agent-spawn hook)
+  → mnemo_recall injects: decisions + memories + active task + repo map
+  → Agent starts with full context (~500 tokens)
+
+User asks a question (user-prompt-submit hook)
+  → Semantic search finds relevant memories
+  → Injected as <mnemo-relevant-context>
+
+Agent works (tools available via MCP)
+  → mnemo_lookup: class details, methods, signatures
+  → mnemo_graph: neighbors, communities, impact analysis
+  → mnemo_search: find code by meaning
+  → mnemo_remember: store important context
+  → mnemo_decide: record permanent decisions
+
+Session ends (stop hook)
+  → Auto-captures learnings, decisions, session summary
+  → Memories decay over time (hot → warm → cold → evicted)
+  → Contradictions detected and superseded
+```
+
+## Features
+
+### 🧠 Memory System
+- **Categorized storage**: architecture, pattern, bug, preference, decision
+- **Retention scoring**: access frequency × recency × importance
+- **Branch-aware**: memories tagged with git branch, filtered on recall
+- **Contradiction detection**: new facts supersede old conflicting ones
+- **Token-budgeted recall**: never exceeds ~2000 tokens regardless of memory count
+- **Memory slots**: pinned context (project_context, user_preferences, known_gotchas)
+
+### 🔍 Triple-Stream Search
+- **BM25**: stemmed keyword matching with synonym expansion
+- **Vector**: ONNX all-MiniLM-L6-v2 dense embeddings (384-dim, cosine similarity)
+- **Graph**: Dijkstra traversal from code symbols to linked memories
+- **Fusion**: Reciprocal Rank Fusion (RRF) combines all three streams
+
+### 🏗️ Code Intelligence (LadybugDB)
+- **Knowledge graph**: files, classes, methods, functions, projects, communities
+- **14 languages**: Python, JS, TS, C#, Go, Java, Rust + 7 optional
+- **Roslyn enrichment**: C# method signatures, implements, full AST
+- **Leiden clustering**: automatic community detection
+- **Impact analysis**: upstream/downstream dependency tracing
+- **Incremental freshness**: graph auto-updates within 30s of file changes
+
+### 📋 Planning & Records
+- **Task plans**: create, track progress, mark done
+- **Error patterns**: store errors with causes and fixes
+- **Incidents**: root cause analysis with affected services
+- **Code reviews**: feedback history per file
+- **Corrections**: wrong→right pairs the agent learns from
+
+### 🛡️ Safety & Audit
+- **Security scan**: hardcoded secrets, SQL injection, insecure HTTP
+- **Dead code detection**: symbols with no incoming edges
+- **Convention checking**: naming violations
+- **Pre-tool-use hook**: blocks catastrophic shell commands
+
+### 🌐 Dashboard UI
+```bash
+mnemo serve    # http://localhost:3333
+```
+- Interactive knowledge graph (vis-network)
+- Memory & decisions viewer
+- Community explorer with zoom-to-cluster
+- Code search with click-to-focus
+- Health monitoring
+
+---
+
+## MCP Tools (16 agent-facing)
+
+| Tool | Purpose |
+|------|---------|
+| `mnemo_recall` | Load full project context (budgeted) |
+| `mnemo_remember` | Store a memory with category |
+| `mnemo_forget` | Delete a memory |
+| `mnemo_decide` | Record permanent decision |
+| `mnemo_search_memory` | Semantic search across memories |
+| `mnemo_search` | Search code graph (classes/methods/files) |
+| `mnemo_lookup` | Detailed symbol info (methods, signatures) |
+| `mnemo_graph` | Query graph (stats/neighbors/find) |
+| `mnemo_impact` | Upstream/downstream dependency analysis |
+| `mnemo_plan` | Create and track task plans |
+| `mnemo_audit` | Security, health, dead-code reports |
+| `mnemo_record` | Store errors, incidents, reviews |
+| `mnemo_generate` | Commit messages and PR descriptions |
+| `mnemo_map` | Regenerate repo map |
+| `mnemo_ask` | Combined graph + memory lookup |
+| `mnemo_lesson` | Store/retrieve learned patterns |
+
+---
+
+## Supported Clients
+
+| Client | MCP | Hooks | Agent Config |
+|--------|-----|-------|-------------|
+| **Kiro** | ✅ | 5 hooks | ✅ agent + skill |
+| **Amazon Q** | ✅ | — | ✅ rules |
+| **Claude Code** | ✅ | — | ✅ CLAUDE.md |
+| **Cursor** | ✅ | — | ✅ .cursorrules |
+| **Copilot** | ✅ | — | ✅ instructions |
+| **Generic MCP** | ✅ | — | ✅ MNEMO.md |
+
+---
+
+## Performance
+
+| Operation | Time |
+|-----------|------|
+| `mnemo init` (55 files) | 3.5s |
+| `mnemo init` (300 files) | 7s |
+| Re-init (no changes) | 0.01s |
+| Remember 1 memory | 5ms |
+| Recall | 33ms |
+| Semantic search | 2ms |
+| Graph query | 0.2ms |
+
+| Resource | Value |
+|----------|-------|
+| RAM | 265 MB |
+| Disk (.mnemo/) | ~16 MB |
+| Model (one-time download) | 86 MB |
+| External databases | 0 |
+
+---
+
+## Architecture
+
+```
+.mnemo/
+├── memory.json          # Memories with retention scores
+├── decisions.json       # Permanent architectural decisions
+├── plans.json           # Task tracking
+├── graph.lbug           # LadybugDB knowledge graph
+├── vectors_memory.npy   # Dense embedding vectors
+├── meta_memory.json     # Vector metadata
+├── engine-meta.json     # File hashes for incremental updates
+├── parse-cache.json     # AST parse cache
+├── tree.md              # Compact repo map
+└── context.json         # Project context key-values
+```
+
+**Stack**: Python · LadybugDB (Kuzu) · ONNX Runtime · tree-sitter · Roslyn
+
+---
+
+## Links
+
+- **Website**: [mnemo-mcp.github.io/Mnemo](https://mnemo-mcp.github.io/Mnemo/)
+- **PyPI**: [pypi.org/project/mnemo-dev](https://pypi.org/project/mnemo-dev/)
+- **GitHub**: [github.com/Mnemo-mcp/Mnemo](https://github.com/Mnemo-mcp/Mnemo)
+- **VS Code Extension**: [Marketplace](https://marketplace.visualstudio.com/items?itemName=Nikhil1057.mnemo-vscode)
+
+## License
+
+[AGPL-3.0](LICENSE)

{mnemo_dev-0.4.0 → mnemo_dev-0.5.0}/mnemo/__init__.py

@@ -2,4 +2,4 @@
 
 from __future__ import annotations
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"

mnemo_dev-0.5.0/mnemo/api_discovery/__init__.py

@@ -0,0 +1,133 @@
+"""API Discovery — uses engine/ graph + OpenAPI spec parsing."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from ..config import IGNORE_DIRS
+
+
+def _should_ignore(path: Path) -> bool:
+    return any(part in IGNORE_DIRS for part in path.parts)
+
+
+def _find_openapi_specs(repo_root: Path) -> list[Path]:
+    """Find OpenAPI/Swagger spec files."""
+    specs = []
+    for pattern in ("swagger.json", "openapi.json", "swagger.yaml", "openapi.yaml"):
+        for f in repo_root.rglob(pattern):
+            if not _should_ignore(f):
+                specs.append(f)
+    return specs
+
+
+def _parse_openapi(spec_path: Path) -> dict[str, Any] | None:
+    """Parse an OpenAPI spec into a compact summary."""
+    try:
+        content = spec_path.read_text()
+        if spec_path.suffix in (".yaml", ".yml"):
+            import yaml
+            data = yaml.safe_load(content)
+        else:
+            data = json.loads(content)
+    except Exception:
+        return None
+
+    if not data or not isinstance(data, dict):
+        return None
+
+    info = data.get("info", {})
+    paths = data.get("paths", {})
+    endpoints = []
+    for path, methods in paths.items():
+        for method, details in methods.items():
+            if method in ("get", "post", "put", "delete", "patch"):
+                endpoints.append({"method": method.upper(), "path": path, "summary": details.get("summary", "")})
+    return {"title": info.get("title", spec_path.stem), "version": info.get("version", ""), "endpoints": endpoints}
+
+
+def _detect_endpoints_from_graph(repo_root: Path) -> list[dict[str, Any]]:
+    """Detect API endpoints from controller files indexed in graph."""
+    from ..engine.db import open_db, get_db_path
+
+    if not get_db_path(repo_root).exists():
+        return []
+
+    _, conn = open_db(repo_root)
+    endpoints = []
+
+    # Find controller files and their functions
+    result = conn.execute("""
+        MATCH (f:File)-[:FILE_DEFINES_CLASS]->(c:Class)
+        WHERE f.path CONTAINS 'Controller'
+        AND NOT f.path CONTAINS 'test'
+        RETURN f.path, c.name
+    """)
+    controller_files: list[tuple[str, str]] = []
+    while result.has_next():
+        row = result.get_next()
+        controller_files.append((row[0], row[1]))
+
+    # For each controller, read source to extract route attributes
+    for file_path, class_name in controller_files:
+        fp = repo_root / file_path
+        if not fp.exists():
+            continue
+        try:
+            content = fp.read_text(errors="replace")
+        except OSError:
+            continue
+
+        service = file_path.split("/")[0]
+        class_route = ""
+        route_match = re.search(r'\[Route\("([^"]+)"\)\]', content)
+        if route_match:
+            class_route = route_match.group(1)
+
+        for match in re.finditer(
+            r'\[(Http(Get|Post|Put|Delete|Patch))(?:\("([^"]*)"\))?\]\s*(?:\[.*?\]\s*)*public\s+(?:async\s+)?\S+\s+(\w+)',
+            content, re.DOTALL
+        ):
+            method = match.group(2).upper()
+            route = match.group(3) or ""
+            func_name = match.group(4)
+            full_path = f"/{class_route}/{route}".replace("//", "/").rstrip("/")
+            full_path = re.sub(r'\[controller\]', class_name.replace('Controller', '').lower(), full_path)
+            endpoints.append({"service": service, "method": method, "path": full_path, "handler": func_name})
+
+    return endpoints
+
+
+def discover_apis(repo_root: Path) -> str:
+    """Discover all APIs in the repo."""
+    lines = ["# API Discovery\n"]
+
+    specs = _find_openapi_specs(repo_root)
+    if specs:
+        lines.append("## OpenAPI Specifications\n")
+        for spec_path in specs:
+            parsed = _parse_openapi(spec_path)
+            if parsed:
+                lines.append(f"### {parsed['title']} (v{parsed['version']})")
+                for ep in parsed["endpoints"]:
+                    lines.append(f"- `{ep['method']} {ep['path']}` {ep['summary']}")
+                lines.append("")
+
+    controller_endpoints = _detect_endpoints_from_graph(repo_root)
+    if controller_endpoints:
+        lines.append("## Controller Endpoints\n")
+        by_service: dict[str, list] = {}
+        for ep in controller_endpoints:
+            by_service.setdefault(ep["service"], []).append(ep)
+        for svc in sorted(by_service):
+            lines.append(f"### {svc}")
+            for ep in by_service[svc]:
+                lines.append(f"- `{ep['method']} {ep['path']}` → {ep['handler']}()")
+            lines.append("")
+
+    if len(lines) <= 2:
+        return "No APIs discovered."
+    return "\n".join(lines)