cognithor

<p align="center">
  <h1 align="center">Cognithor &middot; Agent OS</h1>
  <p align="center">
    <strong>A local-first, autonomous agent operating system for AI experimentation and personal automation.</strong>
  </p>
  <p align="center">
    <em>Cognition + Thor — Intelligence with Power</em>
  </p>
  <p align="center">
    <a href="#llm-providers">18 LLM Providers</a> &middot; <a href="#channels">17 Channels</a> &middot; <a href="#6-tier-cognitive-memory">6-Tier Memory</a> &middot; <a href="#knowledge-vault">Knowledge Vault</a> &middot; <a href="#flutter-command-center">Flutter Command Center</a> &middot; <a href="#security">Security</a> &middot; <a href="LICENSE">Apache 2.0</a>
  </p>
  <p align="center">
    <a href="https://github.com/Alex8791-cyber/cognithor/stargazers"><img src="https://img.shields.io/github/stars/Alex8791-cyber/cognithor?style=flat-square&color=yellow" alt="GitHub Stars"></a>
    <img src="https://img.shields.io/badge/status-Beta%20%2F%20Experimental-orange?style=flat-square" alt="Status: Beta">
    <a href="#quick-start"><img src="https://img.shields.io/badge/python-%3E%3D3.12-blue?style=flat-square" alt="Python"></a>
    <a href="#tests"><img src="https://img.shields.io/badge/tests-11%2C769%2B%20passing-brightgreen?style=flat-square" alt="Tests"></a>
    <a href="#tests"><img src="https://img.shields.io/badge/coverage-89%25-brightgreen?style=flat-square" alt="Coverage"></a>
    <a href="#tests"><img src="https://img.shields.io/badge/lint-0%20errors-brightgreen?style=flat-square" alt="Lint"></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square" alt="License"></a>
    <a href="https://github.com/Alex8791-cyber/cognithor/releases"><img src="https://img.shields.io/github/v/release/Alex8791-cyber/cognithor?style=flat-square&color=blue" alt="Release"></a>
  </p>
</p>

> **Note:** Cognithor is in **active development (Beta)**. While the test suite is extensive (11,769+ tests, 89% coverage), the project has not been battle-tested in production environments. Expect rough edges, breaking changes between versions, and some German-language strings in system prompts and error messages. Contributions, bug reports, and feedback are very welcome. See [Status & Maturity](#status--maturity) for details.

  [![clawdboard](https://clawdboard.ai/api/badge/Alex8791-cyber)](https://clawdboard.ai/user/Alex8791-cyber)

<p align="center">
  <a href="https://clawdboard.ai/recap/6fd37b26-7e41-4b0f-958a-3f2580427ccf"><strong>Weekly Recap: Rank #1 | $1,644 spent vibe-engineering</strong></a>
</p>

> **Vibe-Engineered, not vibe-coded.** Cognithor is not a weekend hack held together by AI-generated spaghetti. Every module follows a deliberate architecture (PGE-Trinity, 6-phase gateway init, 3-layer security), backed by 11,769+ tests, structured plans, spec compliance reviews, and code quality gates. The AI writes the code — but a human engineers the system. There's a difference.

---

## Why Cognithor?

Most AI assistants send your data to the cloud. Cognithor runs entirely on your machine — with Ollama or LM Studio, no API keys required. Cloud providers are optional, not mandatory.

It replaces a patchwork of tools with one integrated system: 17 channels, 125 MCP tools, 6-tier memory, knowledge vault, voice, browser automation, and more — all wired together from day one. 11,769+ tests at 89% coverage keep it honest. See [Status & Maturity](#status--maturity) for what that does and does not guarantee.

---

## Status & Maturity

**Cognithor is Beta / Experimental software.** It is under rapid, active development.

| Aspect | Status |
|--------|--------|
| **Core agent loop (PGE)** | Stable — well-tested and functional |
| **Memory system** | Stable — 6-tier architecture works reliably |
| **CLI channel** | Stable — primary development interface |
| **Flutter Command Center** | Beta — Sci-Fi aesthetic, cross-platform, GEPA pipeline visualization, Robot Office pathfinding, 20 config pages, chat, voice, learning dashboard |
| **Messaging channels** (Telegram, Discord, etc.) | Beta — basic flows work, edge cases may break |
| **Voice mode / TTS** | Alpha — experimental, hardware-dependent |
| **Browser automation** | Alpha — requires Playwright setup |
| **Deployment (Docker, bare-metal)** | Beta — tested on limited configurations |
| **SSH Remote Execution** | Beta — tested against Docker containers, key-based auth |
| **Evolution Engine** | Stable — autonomous deep learning with quality self-examination, GDPR-compliant |
| **Autonomous Task Framework** | Beta — task decomposition, self-evaluation, recurring scheduling |
| **Background Process Manager** | Beta — 6 MCP tools, 5-method ProcessMonitor, SQLite persistence |
| **Multi-Agent System** | Beta — 5 specialized agents with model/temperature/top_p overrides |
| **Audit & Compliance** | Beta — HMAC + Ed25519 signatures, RFC 3161 TSA, GDPR Art. 15/33, WORM-ready |
| **Enterprise features** (GDPR, A2A, Governance) | Stable — GDPR 100% user rights, consent management, SQLCipher encryption, audit trail |
| **Encryption at Rest** | Stable — SQLCipher (AES-256) for all databases, Fernet for files, OS Keyring key management |
| **OSINT / HIM Module** | Beta — person/project/org investigation with trust scoring |

**What the test suite covers:** Unit tests, integration tests, real-life scenario tests, and live Ollama tests for all modules. The 11,769+ tests verify code correctness in controlled environments.

**What the test suite does NOT cover:** Real-world deployment scenarios, network edge cases, long-running stability, multi-user load, hardware-specific voice/GPU issues, or actual LLM response quality.

**Important notes for users:**
- This project is developed by a solo developer with AI assistance. Code is human-reviewed, but the pace is fast.
- Breaking changes may occur between minor versions. Pin your version if stability matters.
- The default language is **German**, switchable to **English** via the Flutter Command Center or `config.yaml`. See [Language & Internationalization](#language--internationalization).
- For production use, thorough testing in your specific environment is strongly recommended.
- Bug reports and contributions are welcome — see [Issues](https://github.com/Alex8791-cyber/cognithor/issues).

---

> **Cognithor** is a fully local, Ollama/LM Studio-powered, autonomous agent operating system that acts as your personal AI assistant. All data stays on your machine — no cloud, no mandatory API keys, full GDPR compliance. It supports tasks ranging from research, project management, and knowledge organization to file management and automated workflows. Optional cloud LLM providers (OpenAI, Anthropic, Gemini, and 11 more) can be enabled with a single API key. Users can add custom skills and rules to tailor the agent to their needs.

<p align="center">
  <img src="demo.svg" alt="Cognithor Demo" width="100%">
</p>

## Table of Contents

- [Why Cognithor?](#why-cognithor)
- [Status & Maturity](#status--maturity)
- [What's New](#whats-new)
- [Highlights](#highlights)
- [Architecture](#architecture)
- [LLM Providers](#llm-providers)
- [Channels](#channels)
- [Quick Start](#quick-start) (under 5 minutes)
- [Configuration](#configuration)
- [Security](#security)
- [MCP Tools](#mcp-tools)
- [Tests](#tests)
- [Code Quality](#code-quality)
- [Project Structure](#project-structure)
- [Deployment](#deployment)
- [Language & Internationalization](#language--internationalization)
- [Roadmap](#roadmap)
- [Recording a Demo](#recording-a-demo)
- [License](#license)

---

## What's New

### What's New in v0.68.0

**Document Powerhouse** — Cognithor can now create, read, and manage all major document formats:

- **7 document tools**: `read_pdf`, `read_docx`, `read_ppt`, `read_xlsx` (new), `document_export`, `document_create` (new), `typst_render` (new)
- **Template system**: `template_list` + `template_render` — fill Typst templates (Brief, Rechnung

[truncated…]