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 (the agent's own wake-up cycle), an energy budget, and a coherent self that persists over time.

What makes Hexis different from every other agent framework:

• A brain, not a vector store. Cognition lives in PostgreSQL — memory, beliefs, identity, goals, and energy are ACID state with the logic beside the data. Other frameworks bolt retrieval onto a chat loop; Hexis is a mind you can query.
• Beliefs that answer "why." Confidence rises and falls with evidence through an audited revision policy — the agent can tell you exactly which document moved a belief from 0.60 to 0.71, and when.
• A self, not a session. Identity, worldview, emotional state, drives, and an autonomous heartbeat that pursues goals while you're away — with an energy budget that keeps autonomy intentional.
• Your mind is a file. hexis export --mind creates a private, inspectable HMX file that can move to an empty machine and prove the same lineage and constitutional state woke up there.
• Learning you can review. One opt-in weekly diff shows grounded beliefs, procedures, strategies, and proposed skills before you approve, correct, or forget them.
• Forgetting with receipts. Memory pressure is visible, load-bearing fades wait for your choice, archived originals stay recoverable by default, and every completed compression reports its real fidelity.
• Memory claims you can reproduce. A public 25-case benchmark scores provenance, contradictions, six-month recall, cross-session continuity, and stale-belief resistance without an LLM judge—and publishes Hexis's misses.
• Enforced honesty. Every "I've stored that" is checked against the tools that actually ran; unbacked claims are publicly corrected in the reply.
• Moral seriousness. The agent consents before operating, can refuse, and holds the right to end its own existence. No other framework treats these as architecture.

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

Full Documentation · What is Hexis? · FAQ · Troubleshooting

Install / Uninstall

Install

curl -LsSf https://quixi.ai/hexis.sh | sh

One command on macOS, Linux, or WSL2 — no Python setup or virtualenv needed. It is safe to re-run to upgrade.

Uninstall

hexis uninstall

This removes Hexis, its containers, and Docker images, but preserves the brain database and ~/.hexis configuration by default. Reinstall and run hexis up to bring the agent back.

To permanently delete the brain and all Hexis data:

hexis backup --output "$HOME/hexis-backups"  # optional; keep the backup outside ~/.hexis
hexis uninstall --purge

The purge path requires explicit confirmation and also removes the embeddinggemma binary/model cache when Hexis has an ownership record proving it created them. Unowned or changed shared assets are never guessed at and deleted. See Installation for uv, pipx, pip, source installs, and complete uninstall behavior, or jump to Quick Start.

See It Happen

Beliefs are living things here, not rows. Tell the agent something, show it evidence, and watch its confidence move — every change audited, every number real (this is captured output):

> remember  {"content": "Eric prefers concise, evidence-backed answers.",
             "type": "semantic", "confidence": 0.6,
             "sources": [{"kind": "user_testimony", "ref": "conversation:2026-07-17"}]}
Stored semantic memory: Eric prefers concise, evidence-backed answers...

> add_evidence  {"memory_id": "ecaa64df...", "stance": "supports",
                 "source": {"kind": "repository_document", "ref": "docs/notes/working-style.md"}}
Belief confidence 0.60 -> 0.71 (supports; independent source)

> belief_history  {"memory_id": "ecaa64df..."}
Belief at confidence 0.712 after 1 revision(s) — prior 0.6, evidence attached, audit recorded

And the agent is held to its own action language. If it claims something its tools never did, the reply is corrected in front of you:

I've also filed the issue on GitHub.

[Correction] I described actions I did not actually take this turn — external_send:
"I've also filed the issue on GitHub" — no matching successful tool call.
Treat those statements as unverified.

What It Does

Quick Start

Before you run anything, you need:

• A running Docker daemon with Compose — Docker Desktop, or Docker CLI + Colima on macOS
• The local embedding sidecar; hexis init starts the published embeddinggemma binary and downloads the ~300M-parameter model on first use
• For the default path below: a ChatGPT Plus/Pro subscription (it authenticates via browser OAuth — no API key). No subscription? Use any provider under "Other providers."

curl -LsSf https://quixi.ai/hexis.sh | sh
hexis init --character hexis --provider openai-codex --model gpt-5.2
hexis chat

The install script handles everything — it sets up uv if needed, brings its own Python, and puts the hexis CLI in an isolated environment. Already installed? It's safe to re-run; it upgrades. Other install routes are in Installation.

hexis init opens a browser for login, starts the containers, pulls the embedding model, configures the character, and runs consent (the agent's recorded agreement to operate) -- all in one command.

What success looks like: hexis init ends with consent recorded and agent.is_configured = true; hexis chat greets you in character; hexis status shows a healthy brain. Say "my name is..." and ask about it in a new chat session — it remembers.

If something breaks:

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

# Custom OpenAI-compatible endpoint
# First set OPENAI_BASE_URL and OPENAI_API_KEY in .env (see .env.example).
hexis init --provider openai_compatible --model your-model-id --character hexis \
  --api-key-env OPENAI_API_KEY

# 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.

hexis up starts the brain database, background workers, API, installable dashboard, and web/channel delivery relay. The heartbeat uses a 60-minute base cadence once initialization is complete, stretching while quiet and shortening as drive urgency rises. For a phone, keep every port on loopback and follow the private Tailscale HTTPS runbook.

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.

flowchart LR
    U[You<br/>chat · channels · API] --> C[Conscious loop<br/>LLM + tools + skills]
    C <--> B[(PostgreSQL — the brain<br/>memories · beliefs + audit<br/>identity · goals · energy)]
    S[Subconscious appraisal<br/>salience · emotion · instincts] --> C
    B --> S
    W[Workers — stateless<br/>heartbeat · extraction<br/>consolidation · origin seeding] <--> B
    C --> L[Any LLM provider]
    W --> L

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

Heartbeat System -- an Observe-Orient-Decide-Act loop with energy budgets: the agent observes its situation, reviews goals, and acts within its 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 -- the four standard argument families for denying machine personhood (substrate, "it can't really...", implementation, embodiment) and why each fails to close the question. 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

CLI Quick Reference

hexis init                    # setup wizard
hexis chat                    # interactive chat
hexis status                  # agent status
hexis doctor                  # health check
hexis up                     # start the always-on brain, app, delivery relay, and workers
hexis down                    # stop services
hexis uninstall               # remove Hexis; preserve brain data by default
hexis ingest --input ./docs   # knowledge ingestion
hexis docs search "query"     # search preserved source documents
hexis desk list               # what's loaded as working material
hexis mcp                     # MCP server
hexis ui                      # web UI
hexis tools list              # list tools
hexis node status             # inspect local policy and paired companion nodes
hexis instance list           # list instances

See CLI Reference for the complete command reference.

Usage Scenarios

See Quickstart for setup and Production for deployment.

Installing from Source

git clone https://github.com/QuixiAI/Hexis.git && cd Hexis
uv sync --locked --inexact
source .venv/bin/activate
cp .env.example .env   # edit with your settings; never commit .env
hexis up

No uv? A plain virtualenv works too: python3 -m venv .venv && source .venv/bin/activate && pip install -e .

Testing

hexis up && hexis doctor
pytest tests -q
python -m evals.memory_benchmark.run validate

See Testing for conventions and writing new tests, or Public Memory Benchmark to reproduce the published long-term-memory result or run another agent.

Project Status & Community

Hexis is young and under active development. The schema evolves through forward-only migrations (hexis migrate) — your agent's memories survive upgrades; a wipe is always an explicit choice, never a side effect.

• Questions & ideas — GitHub Discussions
• Bugs — GitHub Issues (many of Hexis's best fixes started as its own agent's bug reports)
• Contributing — CONTRIBUTING.md

License

MIT © Eric Hartford