deiu/cogitator repository overview

⁠Cogitator

cogitator.me⁠

A personal AI agent that remembers what you tell it, works while you sleep, and gets smarter the longer you use it.

Most AI assistants remember isolated facts about you. Cogitator builds a knowledge graph: facts connect to preferences, preferences connect to patterns, and the agent adapts its behavior based on evidence over time. It runs tasks autonomously on schedules you define, fixes its own failures, and gets measurably better the longer you use it.

One Go binary. One SQLite database. No Redis, no Postgres, no Kubernetes. Runs on your Mac or a $5/month VPS.

⁠What makes it different

Memory that connects. A persistent knowledge graph with vector retrieval. Facts link to preferences, preferences link to patterns, and relationships between ideas surface automatically. The agent on day 100 is measurably different from day 1.

Behavioral adaptation. A compact profile that evolves based on evidence. Three feedback loops at different timescales: micro-reflection during conversations, immediate debugging after task failures, and periodic revision that synthesizes new rules from accumulated episodes.

Autonomous tasks. Schedule tasks that run on cron with the full agent loop. Morning briefings, weekly reports, website monitoring, notifications. When a task fails, the agent reads the failure log, figures out what went wrong, and fixes it.

Two-tier model economics. Every operation is classified as cheap or standard. Memory enrichment, retrieval, and routine tasks run on inexpensive models. Complex reasoning and conversations use capable models. This cuts costs 60 to 80% compared to running everything on a frontier model.

Built-in observability. Token consumption tracked per model tier, per day, with visual charts. Every task run audited with tool calls, duration, error classification, and full transcripts.

Multi-user. Multiple people share one instance. Each person gets their own sessions, tasks, and private memories. Shared memories let the whole household or team benefit from common knowledge. Invite codes for onboarding.

⁠Quick start

git clone https://github.com/cogitatorai/cogitator.git
cd cogitator

# Install dashboard dependencies and build
cd dashboard && npm ci && npm run build && cd ..

# Build the server
cd server && go build -trimpath -o ../cogitator ./cmd/cogitator && cd ..

# Copy the .env file (recommended to set the JWT param to enable persistent sessions)
cp .env.example .env

# Run
./cogitator

Open http://localhost:8484. Create your admin account, configure an LLM provider in Models, and start a conversation.

⁠Requirements

• Go 1.25+
• Node.js 20+ (for dashboard build)
• An OpenAI-compatible LLM provider (OpenAI, Anthropic, Groq, Together, OpenRouter, or local Ollama)
• For voice: an OpenAI API key (used for Whisper STT and TTS; other providers can be added)

⁠Development

# Install dashboard dependencies
cd dashboard && npm ci && cd ..

# Start backend + dashboard dev server (hot reload)
# From project root:
cd server && go build -trimpath -o ../../cogitator ./cmd/cogitator && cd .. && \
  trap 'kill 0' EXIT && ./cogitator & cd dashboard && npm run dev

# Run Go tests
cd server && go test ./... -count=1

# Lint
cd server && go vet ./...

# Evaluate memory/agent quality (retrieval mechanics — hermetic, no API key;
# also covered by `go test ./...` via the eval test wrappers)
cd server && go run ./eval/cmd run -stage retrieval -embedder deterministic

The evaluation harness for memory retrieval and agent quality lives in server/eval/ — see server/eval/README.md⁠ for the deterministic (hermetic) and real-embedding (cached, offline-reproducible) retrieval evals, the "why was my memory missed?" drop-reason diagnostics, and how to add cases.

If you are building from the parent monorepo (which includes platform wrappers, mobile app, and other components), a top-level Makefile provides convenience targets: make all, make dev, make test, make lint.

⁠Docker

Pre-built images for amd64 and arm64 are published to Docker Hub⁠ on every release:

docker pull deiu/cogitator

To build from source and run with Compose:

docker compose up

The container exposes port 8484 by default and persists state to a /data volume (the host path is configurable via COGITATOR_WORKSPACE_PATH in .env). Copy .env.example to .env before starting.

Set the TZ environment variable to your local timezone (e.g. TZ=Europe/Berlin) so that scheduled tasks run at the expected local time. Without it, the container defaults to UTC.

⁠Architecture

server/
  cmd/cogitator/        Entry point
  internal/
    agent/              LLM agent loop with tool calling and context building
    api/                HTTP/REST API and route handlers
    auth/               JWT, refresh tokens, request context
    bus/                In-process event bus
    channel/            Chat transports (WebSocket, Telegram)
    config/             YAML config with environment variable overrides
    database/           SQLite with WAL mode, auto-migrations
    mcp/                MCP server lifecycle, tool discovery, remote transport
    memory/             Knowledge graph: nodes, edges, vector embeddings, retrieval
    provider/           LLM provider abstraction (OpenAI-compatible)
    sandbox/            Shell execution sandbox (host or Docker)
    security/           Path filtering, command blocking, domain allowlisting, audit
    session/            Conversation and message persistence
    skills/             Skill discovery, installation, and management
    task/               Scheduled task execution, runs, cancellation
    tools/              Built-in and custom tool registry
    user/               User store, invite codes, authentication
    voice/              Voice STT/TTS provider interfaces and implementations
    worker/             Background workers: enrichment, profiling, consolidation
    workspace/          File system layout for data, memories, skills, tools

dashboard/
  src/                  React 19 + Vite + Tailwind CSS SPA
  public/               Static assets

⁠Features

⁠Tools

30+ built-in tools plus custom tool support via YAML definitions.

The last four tools are provided by the built-in Google connector and require OAuth setup. Custom tools are defined as YAML files in the tools/ directory (within the defined workspace) with a name, description, parameters schema, and shell command template.

⁠MCP servers

Connect external tools via the Model Context Protocol. Add local (stdio) or remote (SSE/Streamable HTTP) servers through the dashboard or API. The agent discovers server tools automatically, enriches their descriptions, and generates a skill per server so it knows when and how to use each tool. Remote servers support header-based auth and OAuth. Servers auto-reconnect with exponential backoff.

⁠Connectors

OAuth-based integrations with external services. Google Calendar and Gmail ship built in. The agent calls calendar tools during conversation to check schedules, list events, and search across multiple calendars. The connector runtime supports custom connectors defined as YAML manifests with OAuth config, REST endpoints, and jq-based response mapping.

Chrome Browser connector gives the agent CDP-based browser control: navigate pages, read content via accessibility tree snapshots, click elements, type text, evaluate JavaScript, take screenshots, and more. Requires Chrome 146+ with debugging enabled in chrome://inspect/#remote-debugging. Enable on the Connectors page in the dashboard.

⁠Voice

Full voice conversation on the mobile app. Speak to the agent and hear responses read aloud. The voice pipeline uses a hybrid REST + WebSocket architecture: audio is uploaded via POST /api/chat/voice, transcribed server-side (OpenAI Whisper), processed through the LLM, and the TTS response (OpenAI TTS) is streamed back as audio chunks over the existing WebSocket connection. Provider interfaces are pluggable so other STT/TTS providers can be added. Configure voice providers and voice selection on the Models page.

⁠Security

API keys, bot tokens, and OAuth credentials are stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux secret-service) with file-based fallback. Shell commands run in an isolated subdirectory with a scrubbed environment (variables containing API_KEY, SECRET, TOKEN, PASSWORD, etc. are stripped). Sensitive files are blocked from shell access by path filtering. Optional Docker sandboxing runs commands in throwaway containers with memory/PID limits, read-only rootfs, and no network by default.

⁠Dashboard

Pages: Chat, Tasks, Memory, Skills, Connectors, MCP Servers, History, Resources, Account, Users (admin), Settings, Models (admin). Client-mode lets you connect the dashboard to a remote Cogitator server by entering its URL and credentials.

⁠Configuration

Cogitator also uses a cogitator.yaml config file with environment variable overrides. The config is auto-saved to the workspace directory so dashboard settings persist across restarts.

The precedence is: env vars > cogitator.yaml > defaults.

# Environment variables (.env or export)
COGITATOR_SERVER_PORT=8484
COGITATOR_SERVER_HOST=0.0.0.0
COGITATOR_WORKSPACE_PATH=~/.cogitator
COGITATOR_JWT_SECRET=<random-hex-string>

# Model configuration (optional, can also be set in the dashboard)
COGITATOR_MODEL_PROVIDER=openai        # openai, anthropic, ollama, groq, together, openrouter
COGITATOR_MODEL=gpt-4o                 # model identifier for the primary (standard) slot
COGITATOR_MEMORY_EMBEDDING_MODEL=text-embedding-3-small  # embedding model (auto-selects nomic-embed-text for Ollama)

# Memory retrieval tuning (optional)
COGITATOR_RETRIEVAL_TOKEN_BUDGET=2000       # max tokens of retrieved context in system prompt
COGITATOR_RETRIEVAL_MIN_SIMILARITY=0.3      # cosine similarity floor for candidates
COGITATOR_RETRIEVAL_TYPE_BOOST=1.1          # score multiplier for fact/preference nodes
COGITATOR_DEDUP_SIMILARITY_THRESHOLD=0.90   # cosine threshold for deduplicating memories
COGITATOR_ENRICHMENT_VERSION=1              # bump to trigger re-enrichment of all nodes

# Database tuning (optional)
COGITATOR_DATABASE_MAX_READERS=4            # concurrent reader connections (SQLite WAL mode)

# Logging and observability (optional)
COGITATOR_LOG_LEVEL=info                    # debug, info, warn, error
COGITATOR_LOG_FORMAT=text                   # text or json
COGITATOR_RETRIEVAL_TRACE=false             # log a per-turn memory retrieval trace

# Auth token lifetimes (optional)
COGITATOR_AUTH_ACCESS_TOKEN_TTL=30m         # access token lifetime (Go duration)
COGITATOR_AUTH_REFRESH_TOKEN_TTL=720h       # refresh token lifetime (Go duration)

# Connectors and login (optional OAuth credentials)
GOOGLE_CLIENT_ID=<your-google-client-id>
GOOGLE_CLIENT_SECRET=<your-google-client-secret>

Provider credentials can be set via environment variables or through the Settings page. Credentials are stored in the OS keychain with automatic fallback to file.

Model tiers. Tasks and conversations use a two-tier model system (standard and cheap). Configure each tier with a provider and model name via the Settings page.

Social sign-in. To enable "Sign in with Google", set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env. Create OAuth 2.0 credentials in the Google Cloud Console⁠ and add your callback URL (http://localhost:8484/api/auth/google/callback) as an authorized redirect URI. The macOS desktop app injects these at build time via ldflags; Docker and CLI builds read them from environment variables.

⁠Workspace layout

~/.cogitator/
  cogitator.db          SQLite database
  cogitator.yaml        Persisted config (no secrets)
  mcp.json              MCP server configurations
  content/
    profile.md          Agent personality / system prompt
    memories/           Content files for memory nodes
    transcripts/        Conversation transcripts
  skills/
    installed/          Downloaded skill packages
    learned/            Skills the agent has learned
  tools/custom/         Custom tool YAML definitions
  sandbox/              Working directory for shell commands

⁠API

All endpoints require JWT authentication. The WebSocket endpoint is at /ws.

⁠Platforms

macOS app. A native .app bundle wraps the server with a WebKit-based UI, system notifications, and auto-updates from GitHub releases. Available at cogitator.me⁠.

iOS and Android. A React Native companion app connects to a running Cogitator instance. Supports voice conversation mode with real-time waveform visualization, continuous conversation toggle, and silence detection.

Docker. Single container, single volume. See the Docker section above.

Bare metal. The Go binary runs anywhere Go compiles. Point it at a workspace directory and go.

⁠Contributing

Contributions are welcome. Bug fixes, new channel adapters, connectors, dashboard improvements, and test coverage can go straight to a pull request. For anything that touches the agent loop, memory system, or security model, open a discussion first.

See CONTRIBUTING.md⁠ for the full guidelines.

⁠License

AGPL-3.0⁠.

The server and dashboard source code are free to use, modify, and distribute under the terms of the GNU Affero General Public License v3.0. If you run a modified version as a network service, you must make your source code available to users of that service.