What is Cognova?

Installation

Prerequisites, install steps, and running the setup wizard.

Prerequisites

Dependency	Version	Required	Notes
Node.js	>= 22	Yes	nodejs.org
Python 3	Any	Yes	Used by skills and hooks
pnpm	Any	Yes	`npm install -g pnpm`
Docker	Any	No	Only needed for local PostgreSQL
Claude Code CLI	Any	No	Installed during init if missing

The cognova init wizard checks all of these automatically and will exit with instructions if a required dependency is missing.

Install

Install Cognova globally from npm:

npm install -g cognova

Then run the setup wizard:

cognova init

What the Wizard Does

The wizard is interactive and handles the full setup in sequence:

1. Prerequisite Check

Validates Node.js, Python 3, and pnpm versions. Offers to install Claude Code CLI if missing.

2. Agent Personality

Configures your agent's identity:

Name -- what the agent is called (default: Cognova)
Your name -- how the agent addresses you
Tone -- concise, casual, formal, or custom
Traits -- proactive, opinionated, cautious, curious, organized
Communication style -- bullets, narrative, or mixed
Proactivity -- reactive, balanced, or proactive

3. Install Directory

Choose where Cognova files are stored. Default: ~/cognova.

The wizard copies the application source (app, server, shared, build output) to this directory.

4. Vault Location

Choose where your markdown knowledge base lives. Default: ~/vault.

If the directory does not exist, the wizard creates it with the PARA folder structure:

vault/
  inbox/        # Quick captures
  areas/        # Ongoing responsibilities
  projects/     # Active work with deadlines
  resources/    # Reference material
  archive/      # Completed or inactive items

5. Database

Choose one of:

Local PostgreSQL -- spins up a postgres:16-alpine Docker container on port 5432. Requires Docker.
Remote PostgreSQL -- paste a connection string from Neon, Supabase, or any hosted provider.

6. Network Access

Select how you will access the web UI:

Option	Binds to	Use case
Local only	`localhost:3000`	Same machine
Specific IP/domain	`0.0.0.0:3000`	LAN or reverse proxy
Any connection	`0.0.0.0:3000`	Open access (not recommended without TLS)

Cognova gives Claude Code unrestricted shell access. If exposed to a network, always put a reverse proxy with TLS in front. See the production checklist.

7. Admin Credentials

Set your email, password (minimum 8 characters), and display name. These seed the database on first startup.

8. Install & Launch

The wizard:

Generates .env from your answers
Installs Claude Code config to ~/.claude/ (CLAUDE.md, skills, hooks, rules, settings.json)
Runs pnpm install
Installs PM2 (if not present)
Starts the app via PM2
Runs a health check against http://localhost:3000/api/health

When the wizard completes, open the URL shown in the summary and log in.

After Installation

Manage Cognova with the CLI:

cognova start      # Start the app
cognova stop       # Stop the app
cognova restart    # Restart the app
cognova update     # Update to latest version
cognova doctor     # Run health checks
cognova reset      # Re-generate Claude config

See Self-Hosting CLI for details on each command.

For Docker or Coolify deployment instead of bare-metal, see Self-Hosting.

What is Cognova?

Personal knowledge management system with an AI agent that has full access to your machine.

Configuration

Complete environment variable reference -- the single source of truth for all Cognova configuration.