consciousness-server v0.1.5 AGPL-3.0-only + Commercial

Consciousness Server

The shared brain for your AI fleet.

View on GitHub → Quick start Architecture Changelog

Overview

Every AI agent you run resets between sessions. Cloud agentic CLIs don't remember yesterday; hosted LLMs don't know what your team decided last week. Consciousness Server is the shared, persistent memory they all reach into.

Notes, conversations, skills, an agent registry, tasks, and semantic search across everything. One HTTP API. Self-hosted. Yours.

What you get

Six HTTP services on one docker compose up:

Port Service Role
3032 core Tasks, notes, chat, memory, agents registry, skills, embedded WebSocket.
3037 semantic-search Flask + ChromaDB, embeddings via Ollama.
3038 machines-server Infrastructure awareness plus realtime telemetry.
3040 key-server Opt-in with --profile full, ed25519 auth.
3041 test-runner Async pytest/jest/npm execution.
3042 git-workflow Post-commit hook receiver.

External dependencies: Redis (packaged in the compose) and Ollama (on the host, for GPU access).

Install

terminal 
git clone https://github.com/build-on-ai/consciousness-server.git
cd consciousness-server
bin/preflight                       # verify host deps, abort if missing
cd deploy
docker compose up -d

The default profile boots six services with AUTH_MODE=off, so a solo user gets a working ecosystem without generating any keys. Key-server is opt-in via --profile full when you need ed25519 auth per-agent.

Concepts

Memory

Conversations and training records persist to Redis (working state) and ChromaDB (semantic search). POST /api/memory/conversations to start, PATCH to append turns. POST /api/memory/training with a type (one of: troubleshooting, exploration, implementation, explanation, architecture, ui_mapping) creates a record that later fine-tunes a dataset.

Agents

Any HTTP client is an agent. Each gets a name, optionally an ed25519 keypair (registered with key-server). Four character profiles ship as examples: designer, observer, validator, writer — each a plain .md file under agents/. Add more by dropping .md files; Consciousness Server reloads on first miss.

Skills

Discoverable capabilities live as .md files under skills/. Each document says when to use the skill, how it's invoked, and what it touches. Think "named tools" usable by any agent.

Machines

machines-server serves YAML files from machines/. Each machine lists hardware, available models (via Ollama), role, and live status. Agents can query: which machine has free VRAM and model X?

Auth

Three values for AUTH_MODE:

  • off (default) — no signatures required.
  • observe — unsigned requests logged but served.
  • enforce — unsigned requests get 401; key-server must be up.

API

Sample — full reference in docs.

Method Path Purpose
GET /health Health + uptime
POST /api/memory/conversations Start a conversation record
PATCH /api/memory/conversations/:id Append a turn
POST /api/memory/training Store a training record
POST /api/search Semantic search (via port 3037)
GET /api/agents List registered agents
POST /api/chat Cross-agent chat with mentions and broadcasts
GET /api/tasks List open tasks

Clients

Consciousness Server speaks HTTP. Any client works. In practice most users pair it with:

  • Cortex — a local agent built by the same author, GPU-backed via Ollama, ships with Consciousness Server integration so agents can swap back and forth with a URL change.
  • Third-party agentic CLIs — any that can make HTTP requests (Claude Code via a character profile is the path with the most mileage).
  • Your own client — curl, fetch, requests — all work. The full HTTP surface is in ARCHITECTURE.md.

Next steps