Content
# Tool List
[](https://python.org)
[](LICENSE)
[](https://github.com/piot5/CAI/actions)
[](https://github.com/psf/black)
---
## Table of Contents
- [Overview](#overview)
- [Architecture](#architecture)
- [Components](#components)
- [Quick Start](#quick-start)
- [Development](#development)
- [Testing](#testing)
- [Configuration](#configuration)
- [License](#license)
---
## Overview
CAI is a modular framework combining:
- **Vector database** (LanceDB, 768-dim `nomic-embed-text` embeddings)
- **Filesystem archive** (Mycelium graph, branching 0.85/mutation 0.15)
- **MCP server ecosystem** (5 servers: memory, filesystem, orchestration, messaging)
- **Batch consolidation** (scheduled pattern extraction and tool generation)
- **4-layer storage hierarchy** (global > vector > filesystem > workspace)
The system provides persistent cross-session storage, automatic context loading on workspace open, and scheduled pattern analysis.
---
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ CAI System │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Storage Hierarchy │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ │
│ │ │ GLOBAL │ │ VECTOR │ │ FILESYSTEM│ WORKSPACE│ │ │
│ │ │ config │ │ LanceDB │ │ Mycelium │ │ .clin. │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ MCP Servers │ │
│ │ ┌────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ NeuralMem │ │ MyceliumHuman│ │ Orchestrator │ │ │
│ │ │ (LanceDB) │ │ (Markdown FS)│ │ (Watchdog) │ │ │
│ │ └────────────┘ └──────────────┘ └──────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Batch Consolidation Pipeline │ │
│ │ ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────────┐ │ │
│ │ │ Ingest │→│Analyze │→│ Generate │→│ Deploy │ │ │
│ │ │ (100 │ │(Pattern│ │ (FastMCP │ │ (Dynamic │ │ │
│ │ │entries)│ │Detect) │ │ Tool) │ │ Skills) │ │ │
│ │ └────────┘ └────────┘ └──────────┘ └────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
---
## Components
### Storage Layer
| Component | Stack | Description |
| ------------ | ---------------------------- | -------------------------------------------------------------- |
| Vector Store | LanceDB + `nomic-embed-text` | 768-dim persistent storage with semantic search |
| File Archive | Mycelium graph | Branching filesystem (factor 0.85) with mutation (factor 0.15) |
| Bridge | `memory_bridge.py` | Unified read/write across all storage layers |
| Auto-Load | `recall()` on init | Hydrates context from vector store on workspace open |
| Hierarchy | 4 layers | Config > Vector > Filesystem > Workspace |
### MCP Servers
| Server | Function |
| ------------------- | ------------------------------------------------ |
| `NeuralMemory` | Vector database CRUD, semantic search |
| `MyceliumHumanized` | Markdown-format filesystem operations |
| `Orchestrator` | Server lifecycle management, hot-reload watchdog |
| `ThreemaGateway` | Message relay via Threema API |
### Batch Consolidation
| Stage | Details |
| -------- | ---------------------------------------------- |
| Schedule | Daily via Windows Task Scheduler |
| Input | Last 100 LanceDB entries |
| Analysis | Pattern detection via `qwen2.5-coder:32b` |
| Output | FastMCP tool for repetitive workflows |
| Deploy | `%LOCALAPPDATA%\mcp-dynamic-skills` hot-reload |
---
## Quick Start
### Prerequisites
```bash
python --version # 3.10+
ollama pull nomic-embed-text # embeddings model
ollama pull qwen2.5-coder:32b # analysis model
```
### Installation
```bash
git clone https://github.com/piot5/CAI.git
cd CAI
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Linux/Mac
pip install -r requirements.txt
```
### Project Structure
```
CAI/
├── .clinerules # Global configuration (4-layer hierarchy)
├── mcp.json # MCP server registration
├── memory/ # Core storage and MCP servers
│ ├── mcp_neural_memory.py # LanceDB vector store server
│ ├── mcp_mycelium.py # Mycelium filesystem server
│ ├── mcp_categorizer.py # Auto-categorization MCP
│ ├── mycelium_engine.py # Mycelium filesystem engine
│ ├── memory_bridge.py # Unified 4-layer memory bridge
│ ├── orchestrator.py # MCP server lifecycle manager
│ ├── dream_cycle.py # Batch consolidation pipeline
│ ├── path_config.py # Path resolution
│ ├── validation.py # Input validation
│ ├── categorizer.py # Category engine
│ ├── mcp_status_check.py # Health check utility
│ ├── cai_server.py # Development server
│ ├── global_mcp_manager.py # Global MCP activation
│ ├── autostart/ # Windows autostart components
│ │ └── autostart_orchestrator.py
│ ├── demos/ # Integration demos
│ │ ├── tool_integration_demo.py
│ │ ├── complete_mcp_integration_demo.py
│ │ ├── practical_mcp_usage.py
│ │ └── mcp_learning_demonstration.py
│ ├── tests/ # Test suite (36 tests)
│ │ └── test_mcps_comprehensive.py
│ └── docs/ # Reports and summaries
├── requirements.txt
└── README.md
```
### Development Server
```bash
python -m memory.cai_server # Start all MCP servers
python -m memory.memory_bridge # Storage layer only
python -m memory.orchestrator # MCP server manager
python -m memory.mcp_status_check # Health check
python -m memory.dream_cycle --dry-run # Consolidation dry-run
```
---
## Development
### VSCode
Pre-configured in `.vscode/`:
| File | Contents |
| ----------------- | ------------------------------------------ |
| `settings.json` | Python (Black, Ruff, isort), Markdown, Git |
| `extensions.json` | 10 recommended extensions |
| `launch.json` | 10 launch configs + 1 compound |
### Code Quality
```bash
black --line-length=100 memory/
isort --profile black --line-length=100 memory/
ruff check --line-length=100 memory/
mypy memory/
```
---
## Testing
```bash
python -m memory.tests.test_mcps_comprehensive.py # Full suite (36 tests)
python -m memory.mcp_status_check # Live system check
```
| Component | Tests | Status |
| -------------------- | ------ | ------ |
| Neural Memory Server | 8 | ✅ |
| Mycelium Server | 4 | ✅ |
| Mycelium Humanized | 6 | ✅ |
| Memory Bridge | 8 | ✅ |
| Dynamic Skills | 4 | ✅ |
| Threema Gateway | 2 | ✅ |
| Orchestrator | 4 | ✅ |
| **Total** | **36** | **✅** |
---
## Configuration
### MCP Server Registration
Global path (IDE-managed):
```
%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp.json
```
Local reference: `c:\Software\CAI\mcp.json`
### Runtime Config
File: `.clinerules` (JSON at project root)
- Defines server paths, model names, consolidation schedule
- Scanned on workspace open
- Supports workspace-specific overrides
---
## License
MIT License - see [LICENSE](LICENSE) for details.
---
<p align="center">v1.1.0 · <a href="https://github.com/piot5/CAI">github.com/piot5/CAI</a></p>
