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.
