consciousness-server v1.1.0 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's new in v1.1

  • F4.6 contracts + codegen pipeline. lib/schemas/*.openapi.yaml is the single source of truth for chat / notes / tasks / common schemas. bin/sync-schema bundles each contract and generates Node consumers in core/generated/schemas/. Edit YAML, regenerate, no more hand-maintained type duplication.
  • POST /api/tasks is the canonical task-creation route (legacy POST /api/tasks/create kept as alias). Both return the full Task, not just {id, status, created_at}. Same shape change for POST /api/notes.
  • /health distinguishes chat_messages from conversation_embeddings, with an explicit semantic_search status field (ok / misconfigured / timeout / unreachable). Breaking for monitoring that read memory.conversations directly — see CHANGELOG for the migration.
  • Mentions parser is registry-driven. Any agent registered via POST /api/agents/register becomes @addressable — including names with dashes, digits, or underscores (@CC-TESTER, @agent-001). @ALL stays as the broadcast token.
  • NoteType gains audit for dedicated audit notes (no more type=observation + [AUDIT] title-prefix workaround).

Full per-release notes and the v1.0.0 → v1.1.0 migration checklist live in the repo CHANGELOG.md.

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

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 including audit), 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, 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? Read more →

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 — 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 to 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 ARCHITECTURE.md.

Next steps