Cognis

Cognis is a Java 21 autonomous agent runtime focused on practical execution: tool use, scheduling, memory, payment guardrails, and auditable operations for mobile-first workflows.

Cognis started from ideas inspired by NanoClaw/OpenClaw, then evolved into a Java-first MCP + mobile architecture.

Why Cognis

Cognis is positioned as a trusted autonomous operator:

• Guardrailed actions (payments policy + confirmation thresholds)
• Accountable execution (audit trail + dashboard metrics)
• Mobile-native interaction (WebSocket protocol with typing/streaming/ack)
• Local-first deployment (Docker, file-backed state, no managed cloud dependency required)

Architecture

clawmobile (mobile)
        |
        | WebSocket + HTTP
        v
+-----------------------------+
| cognis-app (composition)    |
|  - GatewayServer (Undertow) |
|  - CLI commands             |
+--------------+--------------+
               |
               v
+----------------------------------------------------+
| cognis-core                                        |
|                                                    |
|  Agent Layer                                       |
|  ├── AgentOrchestrator  (LLM loop, trace, heartbeat)|
|  ├── AgentTool          (spawn/await/steer/kill)   |
|  ├── AgentPool          (semaphore concurrency cap)|
|  ├── SubagentRegistry   (persistent run tracking) |
|  ├── TaskQueue          (DAG dependency executor) |
|  ├── CoordinatorTool    (goal → task graph → LLM) |
|  ├── TraceContext       (traceId/spanId chain)    |
|  └── ZombieReaper       (stale run detection)     |
|                                                    |
|  Infrastructure                                    |
|  ├── TopicMessageBus    (pub/sub fan-out)         |
|  ├── SharedMemoryStore  (namespaced agent memory) |
|  ├── ProviderRouter     (LLM provider fallback)   |
|  ├── ToolRegistry       (tool dispatch)           |
|  └── Workflow/Cron/Payments/Observability         |
+----------------------------------------------------+
               |
               v
       File-backed stores
  (.cognis/*, memory/*, uploads/*)

Multi-Agent Execution Model

Cognis uses a single-orchestrator + async subagent pool model. The parent LLM loop drives orchestration by calling agent tools; the framework handles concurrency, tracing, and fault recovery.

AgentOrchestrator (root)
  │  TraceContext.root() → traceId propagated to all descendants
  │
  ├─ AgentTool.spawn("research X") ──► AgentPool.submit() ──► child run (virtual thread)
  │                                         child.traceId == root.traceId
  ├─ AgentTool.spawn("research Y") ──► AgentPool.submit() ──► child run (virtual thread)
  │
  ├─ AgentTool.await_all([runA, runB])  ← blocks until both complete
  │
  └─ CoordinatorTool.decompose(goal)
       │  planner LLM → JSON task graph [{id, prompt, role, dependsOn[]}]
       └─ TaskQueue.submit(tasks)
            ├─ tasks with no deps     → spawned immediately (parallel)
            └─ tasks with dependsOn  → CompletableFuture.allOf(...).thenCompose(spawn)
                                        zero polling, event-driven chaining

Key properties:

• MAX_DEPTH = 2: child agents can spawn grandchildren; deeper nesting is blocked
• AgentPool: semaphore-bounded — rejects spawns when at capacity (default 10 concurrent)
• SubagentRegistry: all runs persisted to .cognis/subagents/runs.json for audit and recovery
• ZombieReaper: scheduled every 60s — marks RUNNING runs with stale heartbeats as FAILED
• TraceContext: traceId shared across entire spawn tree; spanId unique per run; emitted in all observability events

Topic Message Bus

TopicMessageBus
  ├── publish("cron.workflow", msg)  → fan-out to all "cron.workflow" subscribers (virtual threads)
  ├── publish("channel.whatsapp", msg)
  └── subscribe("channel.whatsapp", handler)  → returns subscriptionId for later unsubscribe

Verticals subscribe to topics they care about. Adding a new notification channel (e.g. email, push) requires only a new subscribe() call — no changes to existing vertical code.

Shared Memory

Agents within the same spawn tree share facts via SharedMemoryStore without passing raw context strings:

field-intake agent  →  sharedMemory.write(parentRunId, "beneficiary_count", "47 at Juba site 3")
supply-matching agent  ←  getSummary(parentRunId) injected into system prompt automatically

Modules

• cognis-core: domain logic, providers, tools, workflow, payments, observability, gateway primitives
• cognis-cli: command-line shell around core runtime
• cognis-app: executable app and wiring (providers, tools, gateway, stores)
• cognis-dashboard: React/Vite operations dashboard for metrics + audit trail

Documentation

• Migration plan: docs/MIGRATION_PLAN.md
• Operations runbook: docs/OPERATIONS.md
• MCP server bootstrap guide: docs/MCP_SERVER.md
• Contributing guide: CONTRIBUTING.md
• Mobile test client (React Native): https://github.com/rmukubvu/clawmobile

Core Features

• Java 21 runtime (virtual threads for all subagent spawning)
• Multi-provider routing + fallback chains
  • openrouter, openai, anthropic, bedrock, bedrock_openai, openai_codex, github_copilot
• Multi-agent orchestration
  • agent tool: spawn, await, await_all, steer, kill, status, create, chat, list
  • coordinator tool: decomposes a goal via a planner LLM into a parallel task graph, executes via TaskQueue
  • TaskQueue: DAG dependency resolution (Kahn's topological sort) + CompletableFuture chaining, zero polling
  • AgentPool: semaphore-based concurrency cap (configurable, default 10 concurrent subagent runs)
  • ZombieReaper: background daemon that terminates stalled subagent runs via heartbeat liveness check
  • TraceContext: traceId/spanId/parentSpanId propagated through every spawn chain and emitted in all audit events
• Shared memory
  • SharedMemoryStore: namespaced key-value store so parallel subagents share facts without string serialisation
• Pub/sub message bus
  • TopicMessageBus: topic-based fan-out with virtual-thread listener dispatch and subscribe/unsubscribe
• Tooling
  • filesystem, shell, web, cron, message, memory, profile, notify, payments, workflow, vision (when configured)
• Typed result handling
  • AgentResult carries AgentStatus (SUCCESS, MAX_ITERATIONS, TOOL_ERROR) — callers no longer string-match timeout messages
• Mobile gateway
  • HTTP upload/transcribe/files + WebSocket chat protocol
• Memory and context
  • SQLite-backed conversation history (default), session summary, profile, long-term memory
• Payments guardrails
  • policy limits, merchant/category allowlists, confirmation threshold, quiet hours, status and ledger tracking
• Observability
  • append-only audit events with full trace IDs + derived dashboard metrics
• Dashboard
  • KPI cards, execution snapshot, audit filtering, CSV export

Repository Layout

.
├── cognis-app/
├── cognis-cli/
├── cognis-core/
├── cognis-dashboard/
├── docker/
├── docker-compose.yml
├── Dockerfile
└── .env.example

Requirements

• Java 21
• Maven 3.9+
• Docker + Docker Compose (optional, recommended for quick start)
• Node 20+ (for cognis-dashboard)

Quick Start (Docker)

1. Create environment file:

cd /path/to/cognis
cp .env.example .env

If .env.example does not show in Finder, enable hidden files with Cmd+Shift+. or run ls -la.

2. Optional helper: open the local env setup page to generate your .env values.

• File location: docs/env-setup.html
• Open it directly in your browser (double-click in Finder or drag into a browser tab).

3. Set at least one provider credential in .env:

OPENROUTER_API_KEY=...
# or OPENAI_API_KEY=...
# or ANTHROPIC_API_KEY=...
# or Bedrock via IAM credentials/role:
# AWS_REGION=us-east-1
# AWS_ACCESS_KEY_ID=...
# AWS_SECRET_ACCESS_KEY=...
# AWS_SESSION_TOKEN=...   # only for temporary credentials
# AWS_PROFILE=...         # optional local profile alternative
# or Bedrock OpenAI-compatible endpoint (bearer token):
# COGNIS_PROVIDER=bedrock_openai
# AWS_BEARER_TOKEN=...
# BEDROCK_OPENAI_API_BASE=https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1

4. Start Cognis gateway + MCP server + dashboard:

docker compose up --build

Gateway default URL:

• HTTP: http://127.0.0.1:8787
• WebSocket: ws://127.0.0.1:8787/ws?client_id=<your-client-id>
• MCP tools endpoint: http://127.0.0.1:8791/mcp/tools
• Operations dashboard: http://127.0.0.1:4173

Persistent data:

• ./docker-data -> /home/cognis/.cognis inside container

Useful Docker commands

# Run gateway in background
docker compose up -d --build

# Tail logs
docker compose logs -f cognis cognis-mcp-server cognis-dashboard

# Tail only SMS/MCP flow
docker compose logs -f cognis-mcp-server | rg "twilio|/mcp/call|ERROR|WARN"

# Tail tool + task execution path
docker compose logs -f cognis | rg "task_|tool_|ERROR|WARN"

# Stop
docker compose down

# Run one-off CLI prompt in container
docker compose run --rm cognis agent "hello from docker"

Dashboard audit quick filter:

1. Open http://127.0.0.1:4173.
2. In Audit Trail, set Scope to Tool events only.
3. Optionally set Type to tool_succeeded and search twilio.send_sms.

In Action: Cognis + ClawMobile

End-to-end flow using the ClawMobile app connected to a local Cognis gateway.

1. Open chat list and verify Cognis appears.
2. Edit/connect the Cognis agent (ws://localhost:8787/ws + client id).
3. Open a Cognis conversation with starter prompts.
4. Ask for a reminder and receive both ack + follow-up notification.
5. Review the cleaner settings menu layout.
6. Open Spending Controls from Settings and adjust limits.

| | | | |---|---|---| | <