AIMindMesh is a privacy-first, local-first agentic ecosystem designed to orchestrate a mesh of heterogeneous nodes—Android devices, high-performance PC clients, and specialized server orchestrators—into a single, unified cognitive fabric. It is the first assistant capable of autonomous self-evolution, repairing and improving its own source code through a multi-path agentic loop.

AIMindMesh breaks the traditional "Wrapper" paradigm by implementing a strict Native/Frontend Split:

• Computational Bedrock (Native C++/Kotlin/Rust): Executes heavy-lift operations—LLM inference, NPU delegation, high-fidelity audio processing, and vector similarity—directly on bare metal.
• State Orchestration (React/TypeScript): Manages complex business logic, UI state, and real-time synchronization via a custom Robust Proxy Pattern.
• Distributed Mesh Topology: Nodes (Mobile, PC, VPS) communicate via a secured WireHole (WireGuard) tunnel, sharing inference power, knowledge deltas, and task execution.

The mobile node is not just a client; it's a high-performance inference powerhouse optimized for modern Snapdragon silicon that could also run standalone.

• Adreno OpenCL & Vulkan: Optimized GGUF inference using the Qualcomm-contributed OpenCL backend for Adreno GPUs, significantly outperforming generic Vulkan implementations.
• Hexagon NPU Delegation: Direct routing of LiteRT (.litertlm) models to the Qualcomm Hexagon HTP via QNN delegates, achieving studio-level tokens-per-second with minimal thermal impact.
• Speculative Decoding (MTP): Implements Multi-Token Prediction (LiteRT 0.11.0) to predict and verify multiple tokens per forward pass.
• Persistent KV Cache: Disk-based serialization of conversation states to cache/litert_cache/, allowing instant resumption of context after app restarts or backgrounding.
• VRAM Guardian: Dynamic RAM-pressure scaling that monitors onTrimMemory to prevent OOM kills by proactively compressing history via local summarization.

• Offline TTS Engine (Kokoro & Piper): High-quality, real-time voice synthesis running entirely on-device without cloud dependencies.
  • Kokoro TTS (v1.0): State-of-the-art multi-lingual voice model integrated via a statically-linked Sherpa-ONNX backend. Features dynamic runtime language switching (e.g. English, Italian) and seamless in-app bundle downloading or local .tar.bz2 importing.
  • Piper TTS: Fast, private synthesis using raw ONNX models with dynamic voice management.
• 3-Pass Diarization:
  1. Profiling: Global clustering of ECAPA-TDNN voice embeddings.
  2. Classification: Segment assignment based on speaker centroid proximity.
  3. HMM Smoothing: Viterbi decoding to eliminate spurious speaker oscillations.
• Voxtral Realtime: 4B Multimodal STT (PCM → mel → CLIP → llama) for near-zero latency voice interaction.
• Durable Recording: Direct-to-disk PCM encoding ensures reliability for long sessions (>3h) without memory exhaustion.

• Driving-Optimized UI: Custom GridTemplate dashboard for safe, hands-free interaction.
• Seamless Sync: Real-time access to your Agenda, Kanban, and Assistant Call directly from the car's head unit.
• Privacy-First Call Mode: Routes audio through the earpiece or car speakers with full VAD-based turn-taking.

The server acts as the "Central Nervous System", managing long-term memory and the ecosystem's autonomous growth.

• Tiered Task Prioritization: Dynamically routes tasks (Embeddings → Lightweight → Complex → Evolution) across the mesh based on node hardware capability, proximity, and quota. The routes are customizable via Client PC and Admin Mobile per task type (e.g. embed, lightweight, complex, evolution).
• Claude First, While the Credit Lasts: the monthly Claude API credit of the Max plan answers chats, research, debates, wiki pages and code generation first (Haiku, Sonnet or Opus per category, prompt caching, half-price Message Batches for the scheduled cycles), and the server agents (OpenClaw, Hermes, venture builds) through the same proxy; when the credit or the internal budget runs out, the usual chain (Gemini, OpenRouter, FreeLLMAPI, local nodes) takes over.
• Neural Wiki & Knowledge Graph (Neo4j): Automatically synthesizes raw meeting data and memories into a structured Neo4j knowledge graph, creating a persistent, searchable "Neural Wiki" of your entire digital life.
• FCM Proactive Push: Real-time delivery of server-generated "Neural Insights" directly to mobile notification trays via Firebase.

Orchestrates autonomous operations, team roles expansion, and automated verification:

• AI Council Debate: A short multi-role review that ends with structured votes; a two-thirds majority approves, and only a human approval starts a build.
• Gitea VCS Provisioning: Repository creation with the generated technical specification, done by the server.
• Venture Build Loop: The OpenClaw agent works without credentials in a server-managed folder; the server snapshots each run, validates it in a throw-away Docker container (install online, build and tests offline) and pushes it only if it passes. Every loop has a budget and a kill switch.
• HR Recruitment Service: Analysis of the organization's gaps, proposing new Agent roles that a human materializes.
• Meeting-to-Organization Bridge: Scans meeting transcripts on mobile nodes to extract goal/directive candidates, selectively routing them to the AI Council.

AIMindMesh actively improves its own source tree through three distinct generation paths:

1. Server-Native Evolution: Orchestrates multi-file contexts to ensure architecturally sound patches, delegating to Claude (while its credit lasts), then Gemini or Openrouter for complex refactoring.
2. Agentic OpenClaw Loop: High-autonomy worker for user-requested projects that need external research.
3. On-Device Termux Scripting: Local models generate and execute bash/python scripts via the native Termux Bridge for system-level Android optimizations.

A lightweight Tauri-based client that bridges high-performance PC hardware into the mesh.

• Ollama Bridge: Lends local GPU power to mobile nodes for complex reasoning.
• Telemetry Dashboard: Real-time monitoring of CPU/RAM/Thermal states across the entire mesh.

• Admin Mobile (aimindmesh-admin-mobile): Capacitor app to operate the server from the phone — inference queue, nodes, logs, Kasm sessions, document ingestion, auto-evolution proposals and server configuration (secrets are shown masked).
• Hermes (aimindmesh-hermes): NousResearch Hermes agent container, an alternative agent runtime next to OpenClaw, configured from the *.example files in its folder.

• WireHole VPN: WireGuard tunnel + PiHole (DNS privacy) + Unbound (Recursive DNS).
• Gitea: Self-hosted Git service for autonomous VCS and evolution patches.
• SearXNG: Private metasearch engine ensuring untracked web research.
• FreeLLMAPI: Private, self-hosted LLM gateway ensuring OpenAI-compatible model routing and credential isolation. (https://github.com/tashfeenahmed/freellmapi)
• Anthropic Claude API: the plan's monthly credit, called by the server with its own key (never given to the agents); spend, budget and cache hits are visible in the admin apps.
• Kasm Workspaces: Secure, containerized environments for agentic execution and shadow testing.
• Neo4j Graph Database: The containerized knowledge engine powering the "Neural Wiki."

1. Foundation: Run ./deploy_infrastructure.sh on your VPS. This sets up the networking, Gitea, SearXNG, and Kasm, while automatically disabling any native Neo4j services to prevent port conflicts.
2. Brain: Deploy aimindmesh-server using Docker Compose. Use ./deploy_to_cloud.sh --full for a complete automated setup of the Server, Neo4j, and OpenClaw gateway.
   • Create config.json from config.json.example and src/config.ts from src/config.ts.example. Set a strong server.apiKey and autoEvolution.giteaWebhookSecret (use the same secret in the Gitea webhook settings).
   • Place firebase-service-account.json next to docker-compose.yml: it is mounted at runtime, never baked into the image.
   • The server (3030) and Neo4j (7474/7687) are published only on 127.0.0.1 and the VPN address 10.2.0.1.
3. Nodes: Point the Mobile app, the PC client and the Admin mobile app to http://10.2.0.1:3030 over WireGuard, with the server API key (sent as x-api-key, and as ?token= on WebSockets).
4. CI (optional): register a Gitea Actions runner with the hardened example in infrastructure/docker/services/gitea/act_runner/ to run .gitea/workflows/ci.yml (see DEVELOPMENT_GUIDE.md).

The OpenClaw agent requires a configuration folder containing its skills and auth tokens.

1. Copy the template folder: cp -r aimindmesh-server/openclaw-config.template aimindmesh-server/openclaw-config
2. Open aimindmesh-server/openclaw-config/openclaw.json and insert your Telegram Bot Token and define a Gateway Auth Token.
3. The folder is automatically ignored by Git to protect your tokens.

The repository includes *.sh.example templates for rapid deployment (e.g., deploy_to_cloud.sh.example, publish_android.sh.example). Copy each one without the .example suffix, configure, and run.

• Use ./deploy_to_cloud.sh --full to deploy and configure the entire server stack (Server, Neo4j, OpenClaw).
• These files are git-ignored to protect your private credentials.

Licensed under the PolyForm Noncommercial License 1.0.0.

• Free for personal, educational, and research use.
• Commercial use requires a separate, paid license agreement.

Architect & Designer: Andre (@aimindmesh)
Development Support: Co-authored and implemented in collaboration with Gemini & Claude.

Contact: aimindmesh@proton.me
Philosophy: Privacy is a right, Autonomy is the goal. Designed by Human intelligence, evolved with Artificial Intelligence.