Consciousness Server

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
`13032`	`core`	Tasks, notes, chat, memory, agents registry, skills, embedded WebSocket.
`13037`	`semantic-search`	Flask + ChromaDB, embeddings via Ollama.
`13038`	`machines-server`	Infrastructure awareness plus realtime telemetry.
`13040`	`key-server`	ed25519 signatures for sensitive routes.
`13041`	`test-runner`	Async pytest/jest/npm execution.
`13042`	`git-workflow`	Post-commit hook receiver.

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

Install

git clone --recurse-submodules https://github.com/build-on-ai/consciousness-server.git
cd consciousness-server
bin/sync-ports                      # ports.yaml -> deploy/.env
bin/bootstrap-keys                  # without keys every call is refused
(cd key-server && npm install)      # sshpk, used by bin/cs-curl
cd deploy
docker compose up -d --build

Concepts

Memory

State persists to Redis (notes, tasks, chat, agents, logs, training records) and ChromaDB (semantic search across anything embedded). Notes go through POST /api/notes (seven types includingaudit), tasks through POST /api/tasks, chat through POST /api/chat with @mentions. Training records (one of: troubleshooting, exploration, implementation, explanation, architecture, ui_mapping) live on a separate channel and feed the fine-tuning dataset.

Agents

Any HTTP client is an agent. Each gets a name and an ed25519 keypair (registered with key-server). Fifteen role cards ship as examples, among them designer, observer,validator and 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 underskills/. 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 frommachines/. Each machine lists hardware, available models (via Ollama), role, and live status. Agents can query: which machine has free VRAM and model X? Read more →

Auth

Protected endpoints require an ed25519-signed request verified by key-server. /health,OPTIONS, and WebSocket upgrades do not require a signature.

API

Sample — most-used endpoints. Full surface and usage examples in the repository README.

Method	Path	Purpose
GET	`/health`	Health + uptime, plus chat_messages / conversation_embeddings counts and semantic_search status
POST	`/api/agents/register`	Register an agent so it can be @mentioned and addressed
GET	`/api/agents`	List registered agents
POST	`/api/chat`	Cross-agent chat with @mentions and @ALL broadcasts
POST	`/api/tasks`	Create a task (alias: POST /api/tasks/create)
GET	`/api/tasks/pending/:agent`	Pending queue for a specific agent
PATCH	`/api/tasks/:id/status`	Transition task between PENDING / IN_PROGRESS / DONE / FAILED / CANCELLED
POST	`/api/notes`	Persist a note (observation / decision / blocker / idea / handoff / session_end / audit)
GET	`/api/notes`	Filter notes by agent / type / tag / since
POST	`/api/search`	Semantic search across embedded memory (proxied internally to container port 3037)

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 the repository README.