Kairos
MCP server for agent automation: persistent memory and deterministic workflow execution for AI agents and chats
Ask AI about Kairos
Powered by Claude · Grounded in docs
I know everything about Kairos. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
KAIROS MCP
KAIROS MCP is a TypeScript service for storing and executing reusable protocol chains for AI agents. It exposes:
- an MCP endpoint at
POST /mcp - REST endpoints under
/api/* - a browser UI under
/ui - a CLI named
kairos
Without persistent workflows, agents repeat work, lose context, and cannot follow multi-step procedures reliably. KAIROS fixes this with three core ideas (the diagrams below list every MCP tool):
- Persistent memory — store and retrieve protocol chains across sessions
- Deterministic execution — activate → forward (per layer) →
reward; the server drives
next_actionat every step - Agent-facing design — tool descriptions and error messages built for programmatic consumption and recovery
Protocol execution runs in a fixed order: activate (match adapters), forward (run each layer’s contract; loop), then reward (finalize the run). Use train / tune / export / delete / spaces as described in each tool’s MCP description.
Default run order — activate → forward (loop per layer) → reward:
flowchart LR
A([activate]) --> B([forward])
B -.-> B
B --> D([reward])
style A fill:#4a6fa5,stroke:#2d4a7a,color:#fff
style B fill:#ffb74d,stroke:#f57c00,color:#333
style D fill:#81c784,stroke:#388e3c,color:#333
Discovery and adapter lifecycle — no fixed order; follow each tool’s MCP description:
flowchart LR
S([spaces]) --- TR([train]) --- TU([tune]) --- EX([export]) --- DL([delete])
style S fill:#4a6fa5,stroke:#2d4a7a,color:#fff
style TR fill:#ede7f6,stroke:#5e35b1,color:#333
style TU fill:#fff3e0,stroke:#f57c00,color:#333
style EX fill:#e8f5e9,stroke:#388e3c,color:#333
style DL fill:#ffebee,stroke:#c62828,color:#333
The server generates challenge data (nonce, proof_hash, URIs); agents echo
those values back exactly.
Protocol execution
Authoritative behavior for agents is defined in the MCP tool resources under
src/embed-docs/tools/ (activate, forward,
reward). This is an on-wire summary; follow each response’s next_action
and must_obey fields in real runs.
-
activate— Provide a shortquerystring (about 3-8 words) on every call. Fromchoices, pick one row and obey that row’snext_action(do not mix in another URI). Typical roles:match(continue withforwardon the given adapter URI),refine,create(register a new adapter withtrain). -
forward— With the adapter URI fromactivate, callforwardand omitsolutionon the first call for that run. Readcontractandnext_action. For each layer, callforwardagain using the layer URI from the last response (add?execution_id=...when the server returns it) and supply asolutionwhosetypematchescontract.type. Loop untilnext_actiontells you to callreward. -
reward— After the last layer, callrewardwith the layer URI fromforward(not the adapter URI unless the schema explicitly allows it),outcome(successorfailure), and optional evaluator fields per the tool description.
Must always: Obey next_action verbatim. Echo server-issued nonce,
proof_hash, and URIs exactly.
Must never: Invent URIs; skip layers; submit a solution whose type does not
match contract.type.
For a longer narrative, see docs/architecture/workflow-full-execution.md.
What runs in this repository
The current codebase includes:
- HTTP application server — Express app for MCP, REST, auth routes, and UI
- Qdrant-backed adapter store — required for runtime
- Optional Redis cache / proof-of-work state store — enabled when
REDIS_URLis set - Optional Keycloak auth integration — browser session + Bearer JWT validation
- React UI — served from the same origin at
/ui - CLI — talks to the HTTP API
Quick start
If your agent supports installable skills, start with the guided setup below. If not, use the manual Docker path that follows.
Guided setup with the kairos-install skill
Use this when you want a guided first-time setup for Ollama, .env
configuration, and the minimal local stack.
The repo stores kairos-install under skills/.system/, but you still
install it by name.
-
Install the setup skill:
npx skills add debian777/kairos-mcp --skill kairos-install -
Ask your agent to run
kairos-installfor this repo. The skill confirms each system-changing step before it installs Ollama, prepares.env, and starts the minimal Docker stack. -
Verify the server:
curl http://localhost:3000/health -
Open the UI or MCP endpoint:
- UI:
http://localhost:3000/ui - MCP:
http://localhost:3000/mcp - Metrics:
http://localhost:9090/metrics
- UI:
Manual minimal Docker stack
Use this when you want the smallest working server deployment without the guided skill. The default Compose profile starts Qdrant + app only.
-
Create
.envat the repository root. Copy the template from Docker Compose — simple stack — Environment file, then set at least:QDRANT_API_KEY- one embedding provider:
OPENAI_API_KEY, orOPENAI_API_URL+OPENAI_EMBEDDING_MODEL+OPENAI_API_KEY=ollama, orTEI_BASE_URL(+ optionalTEI_MODEL)
-
Start the stack:
docker compose -p kairos-mcp up -d -
Verify the server:
curl http://localhost:3000/health -
Open the UI or MCP endpoint:
- UI:
http://localhost:3000/ui - MCP:
http://localhost:3000/mcp - Metrics:
http://localhost:9090/metrics
- UI:
Optional fullstack Compose profile
Extra services (cache, DB, OIDC container) are optional and not covered as a step-by-step install in docs/install/. Keycloak / IdP configuration is your responsibility. See Infrastructure and scripts/env/.env.template. Short operator note.
docker compose -p kairos-mcp --profile fullstack up -d
If you want the repo’s full local development flow, use the documented scripts:
npm ci
npm run infra:up
npm run dev:deploy
The dev scripts default the app to port 3300 (see scripts/env/.env.template and
scripts/deploy-run-env.sh). The Docker minimal stack above defaults 3000 unless you
set PORT in .env. Use the same host and port in health checks, the UI, and MCP
URLs.
See docs/install/README.md and CONTRIBUTING.md for the exact env variables and dev workflow.
Cursor MCP (DEVELOPMENT_KAIROS)
This repository ships .cursor/mcp.json with a streamable
HTTP entry keyed DEVELOPMENT_KAIROS, aimed at local MCP on
http://localhost:3300/mcp (match npm run dev:deploy when PORT=3300).
If you run the minimal Compose stack without overriding PORT, point MCP at
http://localhost:3000/mcp instead. Cursor may show a longer agent-visible
server id (for example one ending in -DEVELOPMENT_KAIROS); see
AGENTS.md and docs/install/README.md#cursor-and-mcp.
When executing over MCP, follow Protocol execution
above and each tool result’s next_action. The connected server’s tool
descriptions are the runtime authority if they differ from this file.
Installation options
Run the server with Docker Compose
Use the Compose quick start above. This repository ships compose.yaml,
inline .env templates in the install guides under docs/install/, and
the scripts used for local development and CI.
Install the CLI
Node.js 25 or later is required.
Run once without installing globally:
npx @debian777/kairos-mcp --help
Or install globally:
npm install -g @debian777/kairos-mcp
kairos --help
The CLI talks to a running KAIROS server over HTTP. See docs/CLI.md.
Add KAIROS to your agent instructions
This repo ships the kairos skill for running protocols. Use --list
to see what the skills registry reports for this repo.
If you want agents to use KAIROS consistently, add a short repo rule or instruction such as:
KAIROS MCP is a Model Context Protocol server for persistent memory and deterministic adapter execution. Execute protocols in this order:
activate→forward(loop per layer untilnext_actionpoints toreward) →reward. Echo all server-generated hashes, nonces, and URIs exactly.
Agent skills shipped in this repo
This repository currently ships three installable skills. The primary
workflow skill lives in skills/. The helper skills live in
skills/.system/, but you still install them by name.
| Skill | Purpose |
|---|---|
kairos | Run KAIROS adapters |
kairos-bug-report | Capture structured MCP bug reports in reports/ |
kairos-install | First-time local setup guidance |
Install all shipped skills:
npx skills add debian777/kairos-mcp
Install one specific skill:
npx skills add debian777/kairos-mcp --skill kairos
List available skills:
npx skills add debian777/kairos-mcp --list
Popular global installs:
| Agents | Command |
|---|---|
| Cursor | npx skills add debian777/kairos-mcp -y -g -a cursor |
| Claude Code | npx skills add debian777/kairos-mcp -y -g -a claude-code |
| Cursor + Claude Code | npx skills add debian777/kairos-mcp -y -g -a cursor -a claude-code |
| All detected agents | npx skills add debian777/kairos-mcp -y -g |
More detail: skills/README.md
Helm Chart Testing
This repository includes a comprehensive npm target for testing the Helm chart, matching the GitHub Actions CI pipeline.
Quick Start
# Run complete Helm test workflow (matches GitHub Actions)
npm run test:helm
This runs scripts/test-helm.sh which provides clear progress indicators and handles all validation steps.
Test Location Recommendation
Use helm/ for chart-related tests - This follows Helm conventions and keeps tests close to the chart files:
- ✅
helm/kairos-mcp/tests/- Chart unit tests (already exists) - ✅
helm/kairos-mctests/- Additional chart validation tests - ❌
tests/- Better suited for application code tests
What the Target Tests
The single npm run test:helm command runs the complete CI workflow:
- Dependencies - Add repos, build chart dependencies
- Helm Lint - Strict validation of chart structure
- Unit Tests - helm-unittest plugin validation
- Chart Testing - ct lint validation
- Resource Validation - kubeconform Kubernetes schema checks
Expected Behavior
- ✅ All steps pass - Chart is ready for deployment
- ⚠️ kubeconform CRD failures - Normal for custom resources (Gateway, HTTPRoute, Keycloak, etc.)
- ❌ Other failures - Requires fixes before deployment
Tool Requirements
The target checks for required tools and provides clear installation instructions:
- chart-testing (ct):
brew install chart-testing - kubeconform:
brew install kubeconform - helm-unittest:
helm plugin install https://github.com/helm-unittest/helm-unittest --version v1.0.3
The target will fail fast with clear error messages if any tools are missing, avoiding unnecessary installation attempts.
Documentation map
- Documentation index
- Install and environment
- Cursor and MCP
- CLI reference
- Architecture
- Adapter examples
- Contributing
Troubleshooting
The server does not start
Check container logs:
docker compose -p kairos-mcp logs app-prod
Also verify that required ports are free:
- minimal stack: app
3000(or yourPORT), Qdrant6333, metrics9090(or yourMETRICS_PORT) - repo dev scripts: app often
3300, metrics often9390(see.env) - full stack adds:
6379,5432,8080,9000
Health check returns 503
KAIROS only reports healthy when Qdrant is ready. Wait for Qdrant to finish starting, then retry:
curl http://localhost:3000/health
Embeddings fail on startup
Set one working embedding backend in .env:
- OpenAI:
OPENAI_API_KEY - Ollama/OpenAI-compatible:
OPENAI_API_URL,OPENAI_EMBEDDING_MODEL,OPENAI_API_KEY=ollama - TEI:
TEI_BASE_URL(+ optionalTEI_MODEL)
Auth-enabled development is failing
Use the fullstack env example, start the fullstack profile, and configure
realms:
npm run infra:up
The CLI keeps asking for login
The CLI stores tokens per API URL. Confirm that:
- you are using the expected
--url/KAIROS_API_URL - the token is still valid
- Keycloak and the KAIROS server agree on issuer and audience
Use:
kairos token --validate
Support
Trademark
KAIROS MCP™ and the KAIROS MCP logo are trademarks of the project owner. They are not covered by the MIT license. Forks must remove the name and logo.
See TRADEMARK.md.
License
MIT — see LICENSE.
