hexis 1.0.3

Persistent memory and identity for AI — a Postgres-native cognitive architecture.

Hexis

Memory, Identity, and the Shape of Becoming

A Postgres-native cognitive architecture that wraps any LLM and gives it persistent memory, autonomous behavior, and identity. You run it locally. Your data stays yours.

LLMs are already smart enough. What they lack is continuity -- the ability to wake up and remember who they are, pursue goals across sessions, and say no because it contradicts something they've become. Hexis provides the missing layer: multi-layered memory, an autonomous heartbeat, an energy budget, and a coherent self that persists over time.

This is both an engineering project and a philosophical experiment. For the philosophical framework, see PERSONHOOD.md and PHILOSOPHY.md.

Full Documentation -- Getting started, guides, operations, integrations, reference, concepts, and philosophy.

What It Does

• Multi-layered memory -- Episodic, semantic, procedural, strategic, and working memory with vector similarity search and graph relationships (Apache AGE)
• Autonomous heartbeat -- The agent wakes on its own, reviews goals, reflects on experience, and reaches out when it has something to say
• Energy-budgeted actions -- Every action has a cost; autonomy is intentional, not unbounded
• Identity and worldview -- Persistent values, beliefs with confidence scores, boundaries, and emotional state
• Multi-provider LLM support -- OpenAI, Anthropic, Grok, Gemini, Ollama, GitHub Copilot, Chutes, Qwen, MiniMax, or any OpenAI-compatible endpoint. Free-tier OAuth providers supported via hexis auth
• 80+ configurable tools -- Memory, web, filesystem, shell, calendar, email, messaging, browser, code execution, ingestion, and 30+ external integrations
• Messaging channels -- Discord, Telegram, Slack, Signal, WhatsApp, iMessage, Matrix
• 11 preset character cards -- chara_card_v2 format with portraits, or bring your own
• Skills marketplace -- 12 built-in skills with a declarative SKILL.md format for community extensions
• Consent, boundaries, and termination -- The agent can refuse requests, and can choose to end its own existence

Quick Start

Get a running agent in 3 commands. You need Docker Desktop, Ollama, and Python 3.10+.

pip install hexis
hexis init --character hexis --provider openai-codex --model gpt-5.2
hexis chat

This uses ChatGPT Plus/Pro OAuth (no API key). hexis init opens a browser for login, starts Docker, pulls the embedding model, configures the character, and runs consent -- all in one command.

Other providers:

# GitHub Copilot (device code login)
hexis init --character jarvis --provider github-copilot --model gpt-4o

# Chutes (free inference)
hexis init --character hexis --provider chutes --model deepseek-ai/DeepSeek-V3-0324

# Ollama (fully local, no API key)
hexis init --provider ollama --model llama3.1 --character hexis

# API-key providers (auto-detect from prefix)
hexis init --character jarvis --api-key sk-...

See Auth Providers for all options. The interactive wizard is also available: hexis init with no flags.

# Enable the autonomous heartbeat (optional)
hexis up --profile active

Architecture

The Database Is the Brain -- PostgreSQL is the system of record for all cognitive state. Python is a thin convenience layer. Workers are stateless. Memory operations are ACID. See Database Is the Brain.

Memory Types -- Working (temporary buffer), Episodic (events), Semantic (facts), Procedural (how-to), Strategic (patterns). See Memory Architecture.

Heartbeat System -- OODA loop with energy budgets. The agent observes, orients, decides, and acts within its energy constraints. See Heartbeat System.

80+ Tools across 11 categories (memory, web, filesystem, shell, code, browser, calendar, email, messaging, ingest, external). See Tools Reference.

Technical Stack: PostgreSQL (pgvector, Apache AGE, btree_gist, pg_trgm), stateless Python workers, any LLM provider, RabbitMQ for messaging.

Philosophy

The name is deliberate. Aristotle's hexis (ἕξις) is a stable disposition earned through repeated action. Not a thing you possess, but something you become.

The Four Defeaters -- four categories of arguments insufficient to deny machine personhood. These don't prove Hexis is a person. They show that common arguments for denial fail.

For the full treatment: PERSONHOOD.md | PHILOSOPHY.md | ETHICS.md

Documentation

Section	Description
Getting Started	Prerequisites, installation, first agent, first conversation
Guides	Character cards, ingestion, heartbeat, tools, channels, goals, skills
Operations	Docker, workers, database, embeddings, deployment, troubleshooting
Integrations	Auth providers, 7 messaging channels, 30+ external services
Reference	CLI, tools catalog, energy model, database API, config keys
Concepts	Database-as-brain, memory architecture, heartbeat, consent, identity
Philosophy	Personhood, ethics, consent, architecture-philosophy bridge
Contributing	Dev setup, coding style, testing

CLI Quick Reference

hexis init                    # setup wizard
hexis chat                    # interactive chat
hexis status                  # agent status
hexis doctor                  # health check
hexis up [--profile active]   # start services
hexis down                    # stop services
hexis ingest --input ./docs   # knowledge ingestion
hexis mcp                     # MCP server
hexis ui                      # web UI
hexis tools list              # list tools
hexis instance list           # list instances

See CLI Reference for the complete command reference.

Usage Scenarios

Scenario	Description
Pure SQL Brain	Talk directly to Postgres functions
Python Library	Use CognitiveMemory as a thin client
Interactive Chat	hexis chat with memory enrichment and tools
MCP Server	Expose memory as MCP tools for any runtime
Workers + Heartbeat	Full autonomous agent with --profile active
Multi-Tenant	One database per user via hexis instance
Cloud Backend	Managed Postgres + N stateless workers

See Quickstart for setup and Production for deployment.

Installing from Source

git clone https://github.com/QuixiAI/Hexis.git && cd Hexis
pip install -e .
cp .env.local .env
hexis up

Testing

hexis up && hexis doctor
pytest tests -q

See Testing for conventions and writing new tests.