concierge-graph 3.8.2__py3-none-any.whl

concierge_graph-3.8.2.dist-info/METADATA

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: concierge-graph
+Version: 3.8.2
+Summary: Long-Term Memory (LTM) Palace for AI Agents — hybrid search, semantic graphs, and MCP tools for Cursor, Claude Desktop, and autonomous agents.
+Author: LuisinTheLegend
+License: MIT License
+        
+        Copyright (c) 2026 LuisinTheLegend / Grafo Concierge Team
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/LuisinTheLegend/GrafoConcierge
+Project-URL: Repository, https://github.com/LuisinTheLegend/GrafoConcierge
+Project-URL: Issues, https://github.com/LuisinTheLegend/GrafoConcierge/issues
+Keywords: mcp,memory,graph,ai-agents,rag,semantic-search,vector-database,llm,cursor,claude-desktop,embeddings
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: chromadb>=1.0
+Requires-Dist: mcp>=1.0
+Requires-Dist: sentence-transformers>=3.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: starlette>=0.36
+Requires-Dist: sse-starlette>=2.0
+Requires-Dist: uvicorn>=0.25
+Requires-Dist: httpx>=0.25
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tenacity>=8.0
+Requires-Dist: pathspec>=0.11
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.7; extra == "qdrant"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+English · [Português (Brasil)](README.pt-BR.md)
+---
+
+# 🧠 Concierge Graph v3.8.2
+
+**The Open-Source Long-Term Memory (LTM) & Cognitive Palace for AI Agents, IDEs & Developer Environments**
+
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+[![Protocol MCP](https://img.shields.io/badge/Protocol-MCP-purple.svg)](https://modelcontextprotocol.io/)
+[![Docker Supported](https://img.shields.io/badge/Docker-Ready-blue)](docker-compose.yml)
+
+Concierge Graph is a high-performance, local cognitive memory server designed to solve LLM "amnesia" and context window pollution. Unlike simple RAG (Retrieval-Augmented Generation) scripts, Concierge Graph acts as a bi-temporal, self-healing memory engine combining relational SQL persistence, vector search, hierarchical context synthesis (Zoom Gear), and autonomous background maintenance (Janitor Loop).
+
+---
+
+## 💡 What is Concierge Graph? (For Beginners & Senior Devs)
+
+### 👶 Simple Explanation (The Analogy)
+> Imagine hiring a brilliant senior software engineer who suffers from short-term memory loss. Every time you open a new chat window in Cursor or Claude Desktop, they forget your project structure, coding standards, and past architectural decisions.
+>
+> **Concierge Graph is that engineer's permanent external brain.** Connected seamlessly via the Model Context Protocol (MCP), your AI assistant automatically consults, learns from, and updates this brain in milliseconds—without you ever copying and pasting context again!
+
+### 🧙‍♂️ Technical Deep-Dive (For Engineers)
+Concierge Graph is a local/VPS daemon that provides:
+1. **Bi-Temporal Fact Persistence**: Stores semantic facts and code entities with explicit valid time and transaction time tracking.
+2. **Hybrid Search v4 Engine**: Balances dense vector embeddings (50%), precise keyword signatures via SQLite FTS5 BM25 (25%), and graph signals (25% combining centrality and exponential recency decay $W = W_0 \cdot e^{-\lambda t}$).
+3. **AST-Aware Apex Ingestion**: Parses Python, TypeScript, JS, Go, Rust, Java, C/C++ files into structural AST nodes with delta-hashing (SHA-256) to skip unmodified code.
+4. **Autonomous Self-Healing (Janitor Loop)**: Operates in a background thread to reconcile relational SQLite tables with vector collections, prune orphan embeddings, and decay inactive context.
+
+---
+
+## 🔌 Simultaneous Multi-Client Integration via MCP
+
+Powered by Anthropic's **Model Context Protocol (MCP)**, a single Concierge Graph server instance communicates **simultaneously** with all your favorite tools:
+
+```
+    ┌───────────────────────────┐      ┌───────────────────────────┐
+    │     Cursor / Windsurf     │      │       Claude Desktop      │
+    └─────────────┬─────────────┘      └─────────────┬─────────────┘
+                  │                                  │
+                  │        JSON-RPC / SSE (MCP)      │
+                  └─────────────────┬────────────────┘
+                                    │
+                                    ▼
+                     ┌─────────────────────────────┐
+                     │ 🧠 Concierge Graph Server   │
+                     │  (Local / VPS - Port 8000)  │
+                     └─────────────────────────────┘
+```
+
+* 💻 **Cursor & Windsurf**: Your IDE agent dynamically searches, recalls, and commits project memory as you write code.
+* 💬 **Claude Desktop**: Grants your desktop AI assistant instant macro awareness of your repos.
+* 🤖 **Autonomous Agents & Workflows**: Connect n8n, LangChain, AutoGen, or custom python scripts via SSE endpoints.
+
+---
+
+## ⚡ Quick Start Guide (3 Minutes)
+
+### Option 1: Install via PyPI (Recommended for Most Users)
+
+```bash
+# Install Grafo Concierge package & CLI
+pip install concierge-graph
+
+# Uninstall anytime
+pip install concierge-graph --upgrade # to update
+pip uninstall concierge-graph         # to uninstall
+```
+
+### Option 2: Local Setup from Source (For Developers & Contributors)
+
+1. **Clone & Install in Editable Mode**:
+   ```bash
+   git clone https://github.com/LuisinTheLegend/GrafoConcierge.git
+   cd GrafoConcierge
+   pip install -e .[dev]
+   ```
+
+2. **Configure Environment (`.env`)**:
+   ```bash
+   cp .env.example .env
+   ```
+   Add your Gemini or OpenAI key:
+   ```env
+   GRAFO_LLM_API_KEY=your_gemini_api_key_here
+   GRAFO_LLM_MODEL=gemini-2.0-flash
+   ```
+
+3. **Start the MCP Server**:
+   ```bash
+   concierge-mcp
+   # or: python main.py
+   ```
+
+---
+
+### Option 2: VPS Deployment (Direct `pip` or `Docker`) 🌐
+
+You can host Concierge Graph on any Linux VPS (Ubuntu/Debian) in two ways:
+
+#### A) Direct Installation (Native `pip`)
+```bash
+# 1. Install directly on your VPS
+pip install concierge-graph
+
+# 2. Set your environment variables (or create a .env file)
+export GRAFO_LLM_API_KEY="your_gemini_key"
+export GRAFO_HOST="0.0.0.0"
+export GRAFO_API_KEY="your_secure_vps_token"
+
+# 3. Launch the server
+concierge-mcp
+```
+
+#### B) Containerized Installation (Docker 🐳)
+```bash
+# Set your API Key for remote security in .env
+echo "GRAFO_API_KEY=your_secure_vps_token" >> .env
+
+# Boot the containerized server
+docker compose up -d
+```
+
+---
+
+## 💻 1-Click Configuration for IDEs & Claude Desktop
+
+### For Claude Desktop (`claude_desktop_config.json`)
+Add Concierge Graph to your configuration file:
+
+```json
+{
+  "mcpServers": {
+    "concierge-graph": {
+      "command": "python",
+      "args": ["-m", "interface.mcp_server"],
+      "cwd": "/path/to/GrafoConcierge",
+      "env": {
+        "GRAFO_LLM_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### For Remote VPS / SSE Connections (Cursor / Custom Scripts)
+When running on a server:
+```json
+{
+  "mcpServers": {
+    "concierge-graph": {
+      "url": "http://your-vps-ip:8000/sse",
+      "headers": {
+        "Authorization": "Bearer your_secure_remote_token"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🚀 Performance Benchmarks (Colossus Protocol)
+
+Tested against 20,000 code nodes under the **Colossus Protocol**:
+
+| Metric | Result (20,000 nodes) |
+| --- | --- |
+| **Search Latency (P50)** | 41.69 ms |
+| **Search Latency (P99)** | 112.75 ms |
+| **Scalability Factor** | 0.93x (Linear performance preserved) |
+| **Ingestion Throughput (SQLite)** | ~536 nodes/second |
+| **Ingestion Throughput (ChromaDB)** | ~914 vectors/second |
+| **Background Maintenance (Janitor)** | 20,000 orphan vectors reconciled in ~11s |
+
+---
+
+## 🛠️ Hybrid Search v4 Formula
+
+Relevance scores are calculated by composing three distinct signals:
+
+$$\text{Score} = (0.50 \times \text{Vector Similarity}) + (0.25 \times \text{Normalized FTS5 BM25}) + (0.25 \times \max(\text{Recency}, \text{Centrality}))$$
+
+1. **Vector Similarity (50%)**: Captures deep conceptual meaning using dense embeddings.
+2. **FTS5 BM25 (25%)**: Exact token signatures for function names, classes, and symbols.
+3. **Graph Signals (25%)**:
+   - **Centrality**: Relative connectivity of a node (in-degree normalized).
+   - **Recency**: Time-based exponential decay ensuring historical context ages gracefully:
+     $$W = W_0 \cdot e^{-\lambda t}$$
+
+---
+
+## 🔌 Core MCP Tools Reference
+
+* **`concierge_mine`**: Ingests a directory, chunks code (AST), extracts tags, and generates L0/L1/L2 summaries.
+* **`concierge_search`**: Runs the complete Hybrid Search v4 pipeline across indexed projects.
+* **`concierge_wakeup`**: Reactivates agent consciousness on session start by returning the Context Compass, reference wings, and recent commits.
+* **`concierge_resume`**: Retrieves macro summary of project context (ideal for system prompt injection).
+* **`concierge_load`**: On-demand lazy loader for full node contents, edges, and dependencies.
+* **`concierge_commit`**: Registers audited architectural changes to the cognitive ledger.
+* **`concierge_store_fact`**: Records user preferences and architectural rules with bi-temporal invalidation.
+
+---
+
+## 🛠️ Global CLI Subcommands Reference (`concierge`)
+
+After running `pip install concierge-graph`, two global terminal commands are installed via `pyproject.toml`:
+1. **`concierge-mcp`**: Boots the FastMCP Server daemon.
+2. **`concierge`**: Multifunctional CLI utility supporting the following subcommands:
+
+```bash
+# 1. Register a new workspace/project
+concierge register --name my-project --wing backend --privacy PUBLIC
+
+# 2. Mine / Ingest a codebase directory into the memory graph
+concierge mine --path /path/to/codebase --name my-project
+
+# 3. Perform Hybrid Search v4 across indexed memory
+concierge search --query "authentication middleware" --project my-project
+
+# 4. Reactivate agent consciousness (Compass + Wings + Commits)
+concierge wakeup --project my-project
+
+# 5. Retrieve Context Compass macro summary
+concierge resume --project my-project
+
+# 6. Register audited architectural commit to ledger
+concierge commit --project <uuid> --phase build --technical_changes "Added Auth JWT"
+
+# 7. Lazy load a single node on demand
+concierge load --node_id 42
+
+# 8. Display system health, counts, and database status
+concierge status
+
+# 9. List all registered projects inside the local database
+concierge projects
+
+# 10. Purge a project and all associated relational & vector records
+concierge delete --project my-project
+```
+
+---
+
+## 🧪 Test Suite & Health Diagnostics
+
+Run all unit and stress tests:
+```bash
+python -m pytest
+```
+
+Run full memory diagnostics:
+```bash
+python -m tests.check_brain
+```
+
+---
+
+## 📄 License
+Distributed under the MIT License. See `LICENSE` for details.

concierge_graph-3.8.2.dist-info/RECORD

@@ -0,0 +1,37 @@
+main.py,sha256=OiwcJToPED-xo7cWvvgH42BxH8c97fWKyotv1zFuTqs,10831
+agents/__init__.py,sha256=aiv-lzDZOuYJ1v1hy_L_qZMoBBH4zYB5icZ7A2x1R1A,316
+agents/revisor_critico.py,sha256=5I3g3ecinZcVaEf_EEZwHrjn4SydeBam5gGbg59kG14,22859
+concierge_graph-3.8.2.dist-info/licenses/LICENSE,sha256=beaj4SlugpnDBdWYB60ZFmz7jm1eNjdjkVezhbZdhaM,1095
+core/__init__.py,sha256=OLHPSeAmiDlsQp49m5OzL0qtX5RxGll_jadoWT_-dmA,743
+core/config.py,sha256=g2SzQkYfghXl_flMzAyAUHFTYctZtEO4LkYjTtgc_ZU,7600
+core/hybrid_search.py,sha256=Zw3u03RniUGQFyuMaTjGOMz-Bgr3dVtTzNKL2M3KcJU,10901
+core/memory_extractor.py,sha256=92hliQ95HOxMM04bz-H82h30bzR7xFMaU8WzvHFVW4s,9899
+core/middleware.py,sha256=fz8kODNq5TK5kCdkEuo7eJUeYjf1mQ6ChmaHVVg7TlU,27275
+core/probabilistic_retriever.py,sha256=shd15a-qcgVv1WVhUmxmAeOmULPeBmnesu1821YPw5M,3963
+core/project_index.py,sha256=iXWw00SIoZl3pCdHnWU1OTwOp0_JFYIR1i0dDIbLrrM,11192
+core/vector_backend.py,sha256=o_tAd-ryGQrhd2EIB4v4nY0guRdtMucjs3fQ8tvG8DA,17817
+ingestion/__init__.py,sha256=lgVDHW1b_yGYujf5-QYOB6UxiaN0aXRI2SOwBAHIxEk,887
+ingestion/crawler.py,sha256=3I5VlOhbIv9kiFmuBikNTCE51o_sXgow450hWQCmZN8,27092
+ingestion/orchestrator.py,sha256=ghycXlZ866pml-u6lGwJrxwznjc7ta5Y2ow0VdmVZdo,38927
+ingestion/parser.py,sha256=DXbwLHDdYGMAEhsfdUIRN3hyBrTD9qep1qQGn-Fikls,42703
+ingestion/summarizer.py,sha256=u7JQHZlMQXT5AEd6_9GmifG0vjy9SQeGtJk-qe-dmyY,38365
+interface/__init__.py,sha256=JJfzzJ4rny-irT8WWFR3PVre8vp0D_LzyyCNbfoF-0k,518
+interface/action_hooks.py,sha256=hDLWFPI-IlDKbFPdtaxr2Uf-KoPb0A4c1ZOq9y-ul7o,9358
+interface/cli.py,sha256=3_EgVPnvlC63ijfZ3EAwYYd9s0HmeGRAiShsbbFnb_s,13773
+interface/mcp_server.py,sha256=li85mieI6nmEgqo-s-9dYe9Myv5b2IAMgcB7lKkwozk,68239
+scripts/bootstrap_core_memory.py,sha256=WWpLRWW-hshG5CycFW8sewAyKB7NJSCua9hx48cRWUE,3078
+services/__init__.py,sha256=Wv1zgdLcI952L0peXz9GXDIj0twQzddA9J8S22fjG68,291
+services/janitor.py,sha256=Ni_3VgYzlB8hme0eAkSPq4Au6a6PDLn0H3Bs5xply6I,32372
+storage/__init__.py,sha256=R-27e_wVEdrgfep-wNR76Mm6urrjtFP8RdTAkXG-YPg,1147
+storage/base_backend.py,sha256=cMBnseCEYekmJx1r5p8aF1H42JPN_iJrezPLrR_KIqk,7728
+storage/connection.py,sha256=bKYLJAxAHTTtKStDgsatB4s7l7EolakYqNKZhJeor3o,11876
+storage/logic.py,sha256=awPrK5bPvMHKLVFJGdFeTwZ7ji4jPLgsa6GVFinBfb4,26052
+storage/schema.py,sha256=Su5ao27a0OUrDDqmsE9pHAW3NRZJ_788mRqDftMVxSI,16625
+storage/semantic_logic.py,sha256=_NxWts8CGFjwjfavFmSPjuvs2yg--dFZ3DTEBSZW6SI,4502
+storage/store.py,sha256=eKvkVSLQPDMR1MleLwswozIEcIwETRNx7DYckvy8p9g,35425
+storage/vector_store.py,sha256=LrGsMsrO-JaNBxftg1QgBkfnTxcDzWCUzNDhhXvh4OY,28338
+concierge_graph-3.8.2.dist-info/METADATA,sha256=uiIvZpW7KlJS8P8ZqwoqFstqJ9x1HFqCI6GbQro5maU,13481
+concierge_graph-3.8.2.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+concierge_graph-3.8.2.dist-info/entry_points.txt,sha256=vWr7eJ-whTZPUezGLbT7bjoSQqb9wUJEE6nTCKD94P0,75
+concierge_graph-3.8.2.dist-info/top_level.txt,sha256=FT9rVGklAMOPrsCbIav9diYmtAaNjPUXg5CrSQTV_O8,62
+concierge_graph-3.8.2.dist-info/RECORD,,

concierge_graph-3.8.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

concierge_graph-3.8.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+concierge = interface.cli:main
+concierge-mcp = main:main

concierge_graph-3.8.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LuisinTheLegend / Grafo Concierge Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

concierge_graph-3.8.2.dist-info/top_level.txt

@@ -0,0 +1,8 @@
+agents
+core
+ingestion
+interface
+main
+scripts
+services
+storage

core/__init__.py

@@ -0,0 +1,23 @@
+"""
+core/__init__.py — Grafo Concierge v3.8.0 (Absolute Solidity)
+
+core/ package — Agent Brain.
+
+Exports the central Facade (GrafoConcierge) and intelligence submodules:
+    - GrafoConcierge       → Unified facade for memory operations
+    - ConciergeConfig      → Centralized constants and parameters
+    - ProjectIndex         → Knowledge GPS / Wing Categorization
+    - HybridSearchEngine   → Hybrid Search Engine v4
+"""
+
+from core.config import ConciergeConfig
+from core.project_index import ProjectIndex
+from core.hybrid_search import HybridSearchEngine
+from core.middleware import GrafoConcierge
+
+__all__ = [
+    "ConciergeConfig",
+    "ProjectIndex",
+    "HybridSearchEngine",
+    "GrafoConcierge",
+]

core/config.py

@@ -0,0 +1,192 @@
+"""
+core/config.py — Grafo Concierge v3.8.0 (Absolute Solidity)
+
+Centralization of all constants, weights, and system parameters.
+
+This module is the SINGLE source of truth for magic values.
+No other module should define duplicate constants.
+The values here reflect exactly what was specified in
+Architecture v3.8 and validated in stress tests.
+
+Sections:
+    1. Hybrid Search v4 — Tri-signal weights
+    2. Recency — Exponential decay
+    3. Centrality — In-degree normalization
+    4. FTS5 — BM25 parameters
+    5. Wings — Keywords for automatic categorization
+    6. Ingestion — Limits and ignored directories
+    7. Summarization — Tokens per Zoom Gear level
+    8. MCP Server — Runtime configurations
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class ConciergeConfig:
+    """Centralized configurations of Grafo Concierge.
+
+    frozen=True guarantees immutability. To override values,
+    create a new instance passing the modified fields.
+
+    Example:
+        config = ConciergeConfig(vector_backend="qdrant")
+    """
+
+    # =================================================================
+    # 1. HYBRID SEARCH v4 — Tri-signal weights
+    # =================================================================
+    # score = (weight_vector × vector)
+    #       + (weight_fts5 × normalized_bm25)
+    #       + (weight_recency_centrality × max(recency, centrality))
+    weight_vector: float = 0.50
+    weight_fts5: float = 0.25
+    weight_recency_centrality: float = 0.25
+
+    # =================================================================
+    # 2. RECENCY — Exponential decay
+    # =================================================================
+    # Half-life of 7 days: score drops to 0.50 after 7 days without commit.
+    # Formula: max(e^(-λ × t), recency_min_score)
+    # λ = ln(2) / half_life_days ≈ 0.09902
+    recency_half_life_days: float = 7.0
+    recency_lambda: float = field(default=0.0, init=False)
+    recency_min_score: float = 0.01
+
+    # =================================================================
+    # 3. CENTRALITY — In-degree normalization
+    # =================================================================
+    # min(in_degree / centrality_max_in_degree, 1.0)
+    # A node with 10+ dependents is a "Super-Node" (score = 1.0).
+    centrality_max_in_degree: int = 10
+
+    # =================================================================
+    # 4. FTS5 — BM25 Parameters
+    # =================================================================
+    bm25_k1: float = 1.5
+    bm25_b: float = 0.75
+    bm25_fields: tuple[str, ...] = ("label", "tags", "summary")
+
+    # =================================================================
+    # 5. WINGS — Keywords for automatic categorization
+    # =================================================================
+    wing_keywords: dict[str, list[str]] = field(default_factory=lambda: {
+        "marketing/vendas": [
+            "marketing", "venda", "copy", "cta", "conversão", "landing",
+            "funil", "lead", "promo", "anúncio", "tráfego",
+        ],
+        "finanças/quant": [
+            "finança", "quant", "trade", "ação", "crypto", "investimento",
+            "bolsa", "daytrade", "renda", "mercado", "carteira",
+        ],
+        "gestão/saas": [
+            "saas", "dashboard", "gestão", "erp", "admin", "painel",
+            "plataforma", "multi-tenant", "subscription",
+        ],
+        "automação/rh": [
+            "automação", "excel", "planilha", "rh", "workflow",
+            "zapier", "n8n", "integração", "bot",
+        ],
+        "estatística": [
+            "estatística", "análise", "dados", "média", "probabilidade",
+            "regressão", "machine learning", "dataset",
+        ],
+    })
+
+    # Default wing when no keyword is detected.
+    default_wing: str = "geral"
+
+    # Recommended limit of wings — warns user if exceeded.
+    max_wings: int = 12
+
+    # =================================================================
+    # 6. INGESTION — Limits and filters
+    # =================================================================
+    ignore_dirs: tuple[str, ...] = (
+        ".git", "node_modules", ".next", "dist", "build",
+        "__pycache__", ".mypy_cache", ".pytest_cache", "venv",
+        ".venv", "env", ".env", ".tox", "eggs", "*.egg-info",
+    )
+
+    # Supported file extensions for ingestion.
+    supported_extensions: tuple[str, ...] = (
+        ".py", ".js", ".ts", ".jsx", ".tsx", ".java", ".go",
+        ".rs", ".rb", ".php", ".cs", ".cpp", ".c", ".h",
+        ".md", ".txt", ".rst", ".yaml", ".yml", ".toml",
+        ".json", ".xml", ".html", ".css", ".scss", ".sql",
+    )
+
+    # Maximum file size for ingestion (in bytes). Default: 1MB.
+    max_file_size_bytes: int = 1_048_576
+
+    # =================================================================
+    # 7. SUMMARIZATION — Tokens per level (Zoom Gear)
+    # =================================================================
+    max_l0_tokens: int = 150   # Individual chunk
+    max_l1_tokens: int = 300   # Cluster / Folder
+    max_l2_tokens: int = 300   # Project Compass
+    l2_relevance_threshold: float = 0.15  # Selective Amnesia
+
+    # =================================================================
+    # 8. MCP SERVER — Runtime configurations
+    # =================================================================
+    vector_backend: str = "chroma"
+    embedding_model: str = "all-MiniLM-L6-v2"
+    embedding_dimensions: int = 384
+    default_scope: str = "primary_wing"
+
+    # Lightweight mode (saves RAM by disabling vector search and using FTS5)
+    lightweight_mode: bool = False
+
+    # Result limits for searches.
+    search_top_k: int = 10
+    fts_limit: int = 20
+
+    # Resume: token limits in the Compass.
+    max_resume_tokens: int = 300
+    max_commit_tokens: int = 100
+
+    # Critical Revisor: maximum loops of auditing.
+    max_revisor_loops: int = 3
+
+    # Security & VPS authentication
+    api_key: Optional[str] = None
+    cors_origins: tuple[str, ...] = ("*",)
+
+    def __post_init__(self) -> None:
+        """Calculates derived fields after initialization."""
+        # frozen=True requires object.__setattr__ for calculated fields.
+        object.__setattr__(
+            self, "recency_lambda",
+            math.log(2) / self.recency_half_life_days
+        )
+
+        import os
+        if not self.lightweight_mode:
+            env_val = os.environ.get("GRAFO_LIGHTWEIGHT_MODE", "false").lower() == "true"
+            if env_val:
+                object.__setattr__(self, "lightweight_mode", True)
+
+        if self.api_key is None:
+            env_key = os.environ.get("GRAFO_API_KEY")
+            if env_key:
+                object.__setattr__(self, "api_key", env_key)
+
+        env_cors = os.environ.get("GRAFO_CORS_ORIGINS")
+        if env_cors:
+            origins = tuple(o.strip() for o in env_cors.split(",") if o.strip())
+            if origins:
+                object.__setattr__(self, "cors_origins", origins)
+
+
+
+# ---------------------------------------------------------------------------
+# Default global instance — import directly when customizing values is
+# not necessary.
+# ---------------------------------------------------------------------------
+
+DEFAULT_CONFIG = ConciergeConfig()