🏰 A-Modular-Kingdom

🏰 A-Modular-Kingdom

High-Performance MCP Foundation for RAG, Scoped Memory, and Agentic Tools

✨ New: Automated Local Agent Setup Harness Integrated →

🏛️ Project Status: Setup Harness Integrated

A-Modular-Kingdom (AMK) is equipped with an automated local setup harness that auto-configures your local coding environments (such as Codex and Claude Code) to run this MCP server.

To connect your local agents instantly, just run:

./scripts/setup_mcp.sh

The Solution

A-Modular-Kingdom is the infrastructure layer you're missing. Now any agent (Claude Desktop, Codex, custom chatbots) gets instant access to:

• ✅ Hierarchical Scoped Memory (Global Rules, Project Context, Persona)
• ✅ Advanced V3 RAG (Hybrid Fusion + Cross-Encoder Reranking)
• ✅ 27+ Production Tools (Vision, Code Exec, Web Search, TTS/STT)

🏗️ Automated Local Setup Harness

To get up and running immediately, we provide a unified local setup script that handles the configuration path gymnastics and thermal throttling safety checks:

# Clone the repository
git clone https://github.com/MasihMoafi/A-Modular-Kingdom.git
cd A-Modular-Kingdom

# Run the automated setup script
./scripts/setup_mcp.sh

This script will automatically:

1. Register modular_kingdom_host in your Codex configuration (~/.codex/config.toml).
2. Register the server with Claude Code (claude mcp add) if the CLI is active.
3. Use a lightweight Thermal Safety Runner (scripts/thermal_runner.py) as a wrapper to monitor your CPU core temperatures and throttle execution if the temperature exceeds a safe threshold (85°C), preventing agent processes from causing workspace lag.

🏗️ Architecture

📑 Table of Contents

• ✨ Core Features
• 🚀 Quick Start
• 🛠️ Available Tools
• 📚 RAG System
• 🧠 Memory System
• 🎯 Integration Examples
• 🤖 Example Applications
• 🤝 Contributing

✨ Core Features

• MCP Protocol - Standard interface for AI tool access
• 3 RAG Versions - Choose your retrieval strategy (FAISS, Qdrant, custom)
• Scoped Memory - Global rules, preferences, project-specific context
• 8+ Tools - Vision, code exec, browser, web search, TTS/STT, and more
• No Vendor Lock-in - Local Ollama models, open-source stack
• Production Ready - Smart reindexing, Unicode support, error handling

🚀 Quick Start

Prerequisites

# Required
Python 3.10+
Ollama (for embeddings: ollama pull embeddinggemma)

# Optional
UV package manager (faster than pip)

Installation

# Clone the repository
git clone https://github.com/MasihMoafi/A-Modular-Kingdom.git
cd A-Modular-Kingdom

# Install dependencies
uv sync
# or: pip install -e .

# Pull required Ollama model
ollama pull embeddinggemma

Start the MCP Server

# Start host.py MCP server
python src/agent/host.py

Connect Your Agent

Option 1: Claude Desktop

// Add to claude_desktop_config.json
{
  "mcpServers": {
    "a-modular-kingdom": {
      "command": "python",
      "args": ["/full/path/to/A-Modular-Kingdom/src/agent/host.py"]
    }
  }
}

Option 2: Interactive Client

# Use the included chat interface
python src/agent/main.py

Option 3: Custom Integration

# Connect via MCP in your own agent
from mcp import StdioServerParameters

server_params = StdioServerParameters(
    command="python",
    args=["/path/to/host.py"]
)
# Use with ToolCollection.from_mcp(server_params)

🛠️ Available Tools

The MCP server exposes these tools:

📚 RAG System

Three implementations with different trade-offs:

V1 - Simple & Fast

• Stack: FAISS + BM25
• Speed: <1s
• Use Case: Small projects, quick prototypes

V2 - Production (Recommended)

• Stack: Qdrant + BM25 + CrossEncoder reranking
• Speed: <1s with smart caching
• Use Case: Production apps, large codebases
• Features: Smart reindexing, cloud-ready

V3 - Advanced (Highest Accuracy)

• Stack: Qdrant + BM25 + RRF fusion + CrossEncoder reranking
• Speed: <1s (cached), 6.7s (cold start)
• Use Case: Maximum accuracy, complex queries
• Features: Contextual retrieval, hybrid fusion

Benchmark Results (LLM-as-Judge)

Evaluated with curated queries on Napoleon.pdf and RAG documentation. Judge: Gemini 2.5 Flash. Results vary based on indexed content.

Usage:

# Via MCP tool
query_knowledge_base(
    query="How does authentication work?",
    version="v2",  # or "v1", "v3"
    doc_path="./src"  # optional
)

Supported Files: .py, .md, .txt, .pdf, .ipynb, .js, .ts

🧠 Memory System

Hierarchical scoped memory with automatic categorization:

Memory Scopes

Usage

# Save with explicit scope
save_memory(content="Always validate user input", scope="global_rules")

# Or use prefix shortcuts
save_memory(content="#global:rule:Never use eval()")
save_memory(content="#project:context:Uses FastAPI backend")

# Auto-inference from keywords
save_memory(content="User prefers Python 3.12")  # → global_preferences

# Search with priority (global → project)
search_memories(query="coding standards", top_k=5)

Storage: ~/.modular_kingdom/memories/ (global) + project-specific folders

🎯 Integration Examples

Claude Desktop

Already using Claude Code? Add A-Modular-Kingdom tools:

{
  "mcpServers": {
    "a-modular-kingdom": {
      "command": "python",
      "args": ["/path/to/src/agent/host.py"]
    }
  }
}

Now Claude has access to your codebase RAG, persistent memory, and all tools.

Gemini CLI

// gemini-extension.json
{
  "mcpServers": {
    "unified_knowledge_agent": {
      "command": "python",
      "args": ["/path/to/src/agent/host.py"]
    }
  }
}

Custom Agent

from smolagents import ToolCallingAgent, ToolCollection
from mcp import StdioServerParameters

# Connect to MCP server
params = StdioServerParameters(
    command="python",
    args=["/path/to/host.py"]
)

with ToolCollection.from_mcp(params) as tools:
    agent = ToolCallingAgent(tools=list(tools.tools))
    result = agent.run("Search the codebase for auth logic")

🤖 Example Applications

This repository includes example multi-agent systems built on the foundation:

Council Chamber (Hierarchical)

• 3-tier agent hierarchy (Queen → Teacher → Code Agent)
• Validation loops and task delegation
• Uses ACP SDK + smolagents
• Location: multiagents/council_chamber/

Gym (Sequential)

• Fitness planning workflow (Interview → Plan → Nutrition)
• CrewAI-powered coordination
• Web interface included
• Location: multiagents/gym/

Note: These are demonstration applications, not the core product. The foundation (host.py) is the main offering.

🏗️ Architecture

┌─────────────────────────────────────┐
│     Your AI Application             │
│  (Agents, Chatbots, Workflows)      │
└────────────┬────────────────────────┘
             │ MCP Protocol
┌────────────▼────────────────────────┐
│      A-Modular-Kingdom              │
│  ┌─────────┐ ┌─────────┐ ┌────────┐│
│  │   RAG   │ │ Memory  │ │ Tools  ││
│  │ V1/V2/V3│ │ Scoped  │ │ 8+     ││
│  └─────────┘ └─────────┘ └────────┘│
│           host.py (MCP Server)      │
└─────────────────────────────────────┘

🧪 Testing & Performance

Run Tests

# Run all tests
pytest tests/ -v

# Run specific test suites
pytest tests/test_rag_v2.py -v
pytest tests/test_rag_v3.py -v
pytest tests/test_memory_global.py -v

# Run benchmarks
python tests/benchmark_rag.py

Performance

Benchmark Results (GPU/CUDA):

Key Features:

• ✅ GPU acceleration (CUDA) for embeddings and reranking
• ✅ Smart caching (warm queries <0.5s)
• ✅ Tested with .py, .md, .txt, .ipynb files
• ✅ Global memory access from any directory

See detailed benchmarks: docs/RAG_PERFORMANCE.md

Docker Testing

Package verified to work in isolation:

docker build -f Dockerfile.test -t rag-mem-test .
docker run --rm rag-mem-test

🤝 Contributing

Contributions welcome! Focus areas:

1. Additional RAG strategies - New retrieval techniques
2. New tool integrations - Expand MCP tool offerings
3. Performance optimizations - Speed improvements
4. Documentation improvements - Tutorials, examples

Development Setup

# Fork and clone
git clone https://github.com/MasihMoafi/A-Modular-Kingdom.git
cd A-Modular-Kingdom

# Create branch
git checkout -b feature/your-feature

# Install dev dependencies
uv sync

# Make changes and test
pytest tests/

# Commit with descriptive message
git commit -m "feat: add new tool"

# Push and create PR
git push origin feature/your-feature

📜 License

MIT License - See LICENSE for details

Links

• Medium Article: https://medium.com/@masihmoafi12/a-modular-kingdom-fcaa69a6c1f0
• Demo Video: https://www.youtube.com/watch?v=hWoQnAr6R_E

A-Modular-Kingdom: The infrastructure layer AI agents deserve 🏰