Cognithor is an agent operating system, not a chatbot. The distinction matters because chatbots have one shape (user → LLM → response) and agents have a loop (user → plan → check → tool → observe → plan again). Every piece of Cognithor exists to make that loop safe, auditable, and fast on local hardware.
This page sketches how the pieces fit. Each bolded system has a dedicated deep-dive either in these docs or on the Features pages.
The four layers
Layer 1 — Channels carry messages in and out. Telegram, Discord, Slack, Voice, CLI, Web UI, and 12 more — 18 total. They normalize whatever the transport hands them into a single message shape and pass it to the Gateway. See Connect a Channel.
Layer 2 — The Gateway is the entry point. It owns the session, routes messages to the right conversation, coordinates the PGE loop, and handles the approval flow when the Gatekeeper asks for user input. The Gateway is the thing you are actually talking to; everything below it is machinery.
Layer 3 — The PGE Trinity is the loop. Planner proposes a tool call. Gatekeeper classifies the call's risk. Executor runs it. Memory writes the result back. The Planner sees the new state and decides the next move. See the PGE Trinity feature page for the visual walkthrough.
Layer 4 — Memory, Tools, and Skills are what the PGE loop operates on. Six memory tiers (chat, episode, vault, identity, tactical, entity) store state across runs. 145 MCP tools (filesystem, shell, web, media, vault, code, ...) give the agent things to do. Skills are the LLM prompts that tell the agent how to use the tools for a given task.
The four layers in order:
| Layer | Role | Details |
|---|---|---|
| 1. Channels | Transport | 18 adapters (Telegram, Discord, Slack, voice, CLI, ...) |
| 2. Gateway | Entry point | Session state, routing, approval flow |
| 3. PGE Trinity | The loop | Planner → Gatekeeper → Executor, Memory closes the loop |
| 4. Capabilities | What the loop uses | 6 memory tiers, 145 MCP tools, N skills |
The same flow, animated and clickable: PGE Trinity feature page.
Why three agents, not one
The obvious design for an LLM agent is: model picks a tool, runtime runs the tool, model sees the result. This is what most agent frameworks do. The problem is that when the model picks a destructive tool, it runs. There is no check between "the model proposed this" and "the tool executed". Bugs, hallucinations, and prompt-injection attacks all become irreversible actions.
Cognithor splits the loop into three roles so that the check is structural:
- Planner is the model that sees the conversation and picks the next action. It is explicitly not allowed to run anything.
- Gatekeeper is a deterministic classifier (plus a smaller model for edge cases). It reads the proposed action and returns one of four classes: GREEN (safe), YELLOW (user notice), ORANGE (user approval required), RED (blocked). Every unknown tool defaults to ORANGE.
- Executor runs the action only if the Gatekeeper cleared it.
Because the roles are separated, the Planner cannot bypass the check by deciding to skip it. The Executor literally cannot run anything that did not come through the Gatekeeper. The audit log records every Gatekeeper decision, so you can read exactly why a call was cleared or blocked.
The full story lives on the PGE Trinity feature page with an animated walkthrough.
Memory: six tiers, one assistant
Context is not just "the last 4000 tokens." Cognithor has six memory tiers that each play a different role:
| Tier | Cadence | What it holds |
|---|---|---|
| Chat | Turn | Raw messages in the current conversation |
| Episode | Session | Summary of previous sessions |
| Vault | Batch | Indexed files, notes, documents you loaded |
| Identity | Slow | Who you are — preferences, projects, names |
| Tactical | Turn | Live facts promoted from this conversation |
| Entity | Slow | A graph of people, places, things |
The Planner gets a context bundle assembled from all six tiers on every turn. The Vault tier runs a TF-IDF search with optional dense rerank. Tactical memory is a hybrid RAM+SQLite store with per-fact scoring. Identity memory is curated (quality-scored, reviewable) so the "who I am" layer stays clean.
Visual walkthrough on the Memory feature page.
Tools: 145 capabilities, always gated
The 145 MCP tools live under src/jarvis/mcp/ in 14 module groups. Filesystem, shell, web, media, vault, code, skills, browser, arc, documents, and a few more. Every tool declares its risk class, input schema, and execution function. The Gatekeeper reads the risk class and the concrete arguments to make its decision.
Tools do not talk to each other directly. The only loop that strings them together is the PGE loop — if the Planner wants to read a file and then post its contents to Discord, that is two turns through the PGE loop, with two Gatekeeper checks.
See the MCP Tools feature page for the full catalog and the four flavor groups.
Skills: prompts you can read
A skill is a markdown file that tells the Planner how to use the tools for a specific job. "Post a daily standup to Slack" is a skill. "Draft a PR review comment" is a skill. "Hunt leads on Reddit" is a skill that ships as a pack.
Skills are plain text. You can read them, edit them, and replace them. Built-in skills ship MIT-licensed. Community skills go through a 5-check validation pipeline (syntax, prompt-injection scan, tool allowlist, safety scan, signature check) before install. Generated skills are drafted by the Meta-Learner from observed patterns and land pending your review.
See the Skills feature page.
Local by default, always
Every component above runs on your machine. The channels reach outward to carry messages, but the brain — Planner, Gatekeeper, Executor, Memory, Tools, Skills — is all local. No remote inference unless you explicitly opt in. No telemetry. No training on your data. See the Manifesto for the full commitment.
What's next
- PGE Trinity (deep dive) — the full feature page with an animated loop
- Memory (deep dive)
- MCP Tools (deep dive)
- Writing a Skill