CogitoAgent

Think Continuously · Act Autonomously · Stay Private

Cogito, ergo sum — CogitoAgent is not just a tool; it is your autonomous thinking partner in your local environment.

CogitoAgent is a locally-run autonomous AI agent that integrates file management, knowledge mining, system operations, code execution, and web connectivity. It runs directly within the working directory configured by the user, with no need to upload any files to third-party servers, ensuring data privacy while providing a continuously operating intelligent assistant service.

Unlike traditional chatbots, CogitoAgent possesses the ability to Think Continuously, Explore Autonomously, and Execute Tools, capable of proactively discovering and organizing your local file assets in the background, with additional capabilities available through an extensible toolset.

Core Features

🚀 Quick Start

Requirements

• Node.js 22.12 or higher
• npm or yarn package manager
• Python 3.x (optional, for Python code execution)

Note for users in China: If npm install fails to download the Electron binary:

$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
npm install

Installation

git clone https://gitee.com/cnt-code/cogito-agent.git
cd cogito-agent
npm install
npm start

First-Time Setup

1. API Base URL — Supports OpenAI-compatible third-party APIs
2. API Key — Your API key
3. Model Name — e.g., gpt-4o, claude-3-sonnet, etc.
4. Workspace Path — The directory the AI can access
5. Persona Selection — Choose a preset AI persona

Usage Modes

Tool System

All tools are managed by registry.js and invoked via [TOOL] functionName(args) [/TOOL].

Detailed tool documentation: registration mechanism, usage examples, best practices → introduction/tools.md (Chinese)

Architecture

Complete architecture details: think cycle diagrams, tool call flow, state machine, message flow, WebSocket → introduction/architecture.md (Chinese)

Command Reference

Configuration

Configuration via config.json and environment variables (.env), with env vars taking priority.

Full configuration reference: environment variables list, advanced options (compression, truncation, archiving) → introduction/configuration.md (Chinese)

Project Structure

cogito-agent/
├── src/                              # Source code
│   ├── agent/                        # Core agent module
│   │   ├── Agent.js / state.js / registry.js
│   │   ├── commands.js / session.js / stats.js
│   │   ├── mcp.js / plugin.js / tracing.js / retry.js
│   │   └── tools/                    # 16+ tool modules
│   ├── api/                          # API layer (client, models, webSearch)
│   ├── io/                           # Terminal, Logger, WebSocket
│   ├── config.js                     # Configuration management
│   └── index.js                      # Application entry
├── electron/                         # Desktop mode
│   ├── main.js / preload.cjs / agent-bridge.js
│   ├── desktop/ / dashboard/ / monitor/ / setup/
│   ├── shared/                       # Shared utilities
│   └── assets/
├── personas/                         # 22 preset personas (13 modern + 9 ancient)
├── tests/                            # Test files
├── data/                             # Runtime data (auto-created)
└── introduction/                     # Detailed documentation
    ├── tools.md                      # Tool system details
    ├── architecture.md               # Architecture details
    ├── configuration.md              # Configuration guide
    ├── systems.md                    # Core systems details
    ├── extensions.md                 # Extensions details
    └── deployment.md                 # Deployment & development

Core Systems

See introduction/systems.md (Chinese) for details

• Memory System — SQLite-based long-term storage and semantic retrieval
• Task Management — Task creation, decomposition, and status tracking
• Code Sandbox — isolated-vm process-level isolation for JS and Python
• Personas — 22 preset roles with custom and hot-switch support
• Session Management — Independent contexts with auto-compression
• Statistics — Tool usage tracking and performance metrics
• Thought Chain Visualization — Real-time thinking process display
• Agent Cluster — Sub-agent creation, task delegation, and cluster monitoring, see introduction/agent-cluster.md

Extensions

See introduction/extensions.md (Chinese) for details

• Plugin System — Dynamic loading of custom tool plugins
• MCP Protocol — Expose tools as MCP Server
• Tracing — Lightweight observability for tool executions and LLM calls
• Circuit Breaker & Retry — Reliable network requests
• Multi-Model — OpenAI, Moark, Anthropic, Google support
• Web Search — Built-in internet search capability

Docker

See introduction/deployment.md (Chinese) for details

docker-compose up -d

Changelog

v2.3.0

• Multi-session management, tool category on-demand loading, auto context compression
• Sandbox upgrade — deep freezing of built-in objects
• New tracing.js, retry.js, MCP protocol, plugin system
• New OCR and Vision analysis tools
• Statistics module for tool usage tracking
• Thought chain visualization

v2.2.0

• Agent.js modularized, logger.js with log levels

v2.1.0

• Removed vm2, switched to Node.js native vm module

v2.0.0

• Code execution engine, Git, task management, memory system
• Data processing, SQLite, email, monitoring, scheduled tasks

License

Apache 2.0

Built with CogitoAgent Team