concierge-graph 3.8.2__tar.gz

concierge_graph-3.8.2/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,261 @@
+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/agents/__init__.py

@@ -0,0 +1,14 @@
+"""
+agents/__init__.py — Grafo Concierge v3.8.0 (Absolute Solidity)
+
+agents/ package — Guardians of Evolution.
+
+Exports the critical AI agents:
+    - RevisorCritico → Evolution Auditor + Drawer Reranking
+"""
+
+from agents.revisor_critico import RevisorCritico
+
+__all__ = [
+    "RevisorCritico",
+]