KairosChain MCP Server
Self-referential MCP server for auditable skill self-management
📖 日本語版 README はこちら (Japanese README)
KairosChain is a Model Context Protocol (MCP) server for self-managed, evolvable AI skill definitions. It combines Pure Skills design (Ruby DSL/AST) with a private blockchain, enabling AI agents to define, evolve, and audit their own capabilities through self-referential skill management.
Table of Contents
Philosophy
The Problem
The biggest black box in LLM/AI agents is:
The inability to explain how current capabilities were formed.
- Prompts are volatile
- Tool call histories are fragmented
- Skill evolution (redefinition, synthesis, deletion) leaves no trace
As a result, AI becomes an entity whose causal process cannot be verified by third parties, even when it:
- Becomes more capable
- Changes behavior
- Becomes potentially dangerous
The Solution: KairosChain
KairosChain addresses this by:
- Defining skills as executable structures (Ruby DSL), not just documentation
- Recording every skill change on an immutable blockchain
- Enabling self-reference so AI can inspect its own capabilities
- Enforcing safe evolution with approval workflows and immutability rules
KairosChain is not a platform, currency, or DAO. It is a Meta Ledger — an audit trail for capability evolution.
Minimum-Nomic Principle
KairosChain implements Minimum-Nomic — a system where:
- Rules (skills) can be changed
- But who, when, what, and how they were changed is always recorded and cannot be erased
This avoids both extremes:
- ❌ Completely fixed rules (no adaptation)
- ❌ Unrestricted self-modification (chaos)
Instead, we achieve: Evolvable but not gameable systems.
Architecture
Figure: KairosChain's legal-system-inspired layered architecture for AI skill management
System Overview
┌─────────────────────────────────────────────────────────────────┐
│ MCP Client (Cursor / Claude Code) │
└───────────────────────────────┬─────────────────────────────────┘
│ STDIO (JSON-RPC)
│ or
│ Streamable HTTP (POST /mcp)
▼
┌─────────────────────────────────────────────────────────────────┐
│ KairosChain MCP Server │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ Server/HTTP │ │ Protocol │ │ Tool Registry │ │
│ │ STDIO/Puma │ │ JSON-RPC │ │ 23+ Tools Available │ │
│ └──────────────┘ └──────────────┘ └──────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Skills Layer │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────────────────┐│ │
│ │ │ kairos.rb │ │ kairos.md │ │ Kairos Module ││ │
│ │ │ (DSL) │ │ (Markdown) │ │ (Self-Reference) ││ │
│ │ └────────────┘ └────────────┘ └────────────────────────┘│ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Blockchain Layer │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────────────────┐│ │
│ │ │ Block │ │ Chain │ │ MerkleTree ││ │
│ │ │ (SHA-256) │ │ (JSON) │ │ (Proof Generation) ││ │
│ │ └────────────┘ └────────────┘ └────────────────────────┘│ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
P2P Knowledge Exchange
KairosChain supports peer-to-peer knowledge exchange between instances via the Model Meeting Protocol (MMP). This capability embodies several key design principles:
Knowledge-Only Constraint: Only non-executable content (Markdown, YAML) can be exchanged over P2P. Executable code must be installed via trusted channels. This separation ensures that shared knowledge remains safe and auditable, while maintaining security boundaries for code execution.
Protocol Evolution: MMP supports dynamic protocol extension through ProtocolEvolution, allowing new message types and capabilities to be added without modifying the core protocol. Extensions are validated against core actions to prevent collision, maintaining protocol integrity.
Wire Protocol Standardization: A standardized message format (tar.gz + Base64 archives with SHA-256 content hashing) ensures interoperability between KairosChain instances regardless of their internal configuration.
Trust Model: TOFU (Trust on First Use) with RSA-2048 signature verification provides identity assurance without requiring a central certificate authority, aligning with KairosChain's decentralized philosophy.
Layered Skills Architecture
KairosChain implements a legal-system-inspired layered architecture for knowledge management:
| Layer | Legal Analogy | Path | Blockchain Record (per-operation) | Mutability |
|---|
| L0-A | Constitution | skills/kairos.md | - | Read-only |
| L0-B | Law | skills/kairos.rb | Full transaction | Human approval required |
| L1 | Ordinance | knowledge/ | Hash reference only | Lightweight constraints |
| L2 | Directive | context/ | None* | Free modification |
*Note: While individual L2 operations are not recorded, StateCommit periodically captures all layers (including L2) in off-chain snapshots with on-chain hash references.
L0: Kairos Core (skills/)
The foundation of KairosChain. Contains meta-rules about self-modification.
- kairos.md: Philosophy and principles (immutable, read-only)
- kairos.rb: Meta-skills in Ruby DSL (modifiable with full blockchain record)
Only these meta-skills can be placed in L0:
l0_governance, core_safety, evolution_rules, layer_awareness, approval_workflow, self_inspection, chain_awareness, audit_rules
Note: L0 Self-Governance
The l0_governance skill now defines which skills can exist in L0, implementing the Pure Agent Skill principle: all L0 governance criteria must be defined within L0 itself. See the Pure Agent Skill FAQ for details.
Note: Skill-Tool Unification
Skills in kairos.rb can also define MCP tools via the tool block. When skill_tools_enabled: true is set in config, these skills are automatically registered as MCP tools. This means skills and tools are unified in L0-B — you can add, modify, or remove tools by editing kairos.rb (subject to L0 constraints: human approval required, full blockchain record).
L1: Knowledge Layer (knowledge/)
Project-specific universal knowledge in Anthropic Skills format.
knowledge/
└── skill_name/
├── skill_name.md # YAML frontmatter + Markdown
├── scripts/ # Executable scripts (Python, Bash, Node)
├── assets/ # Templates, images, CSS
└── references/ # Reference materials, datasets
Example skill_name.md:
---
name: coding_rules
description: Project coding conventions
version: "1.0"
layer: L1
tags: [style, convention]
---
# Coding Rules
## Naming Conventions
- Class names: PascalCase
- Method names: snake_case
L2: Context Layer (context/)
Temporary context for sessions. Same format as L1 but no per-operation blockchain recording.
context/
└── session_id/
└── hypothesis/
└── hypothesis.md
Use for:
- Working hypotheses
- Scratch notes
- Trial-and-error exploration
Note: While individual L2 changes are not recorded, the StateCommit feature can capture L2 state in periodic snapshots (stored off-chain with on-chain hash references).
Why Layered Architecture?
- Not all knowledge needs the same constraints — temporary thoughts shouldn't require per-operation blockchain records
- Separation of concerns — Kairos meta-rules vs. project knowledge vs. temporary context
- AI autonomy with accountability — free exploration in L2, tracked changes in L1, strict control in L0
- Cross-layer auditability — StateCommit enables periodic snapshots of all layers together for holistic audit trails
Data Model: SkillStateTransition
Every skill change is recorded as a SkillStateTransition:
{
skill_id: String, # Skill identifier
prev_ast_hash: String, # SHA-256 of previous AST
next_ast_hash: String, # SHA-256 of new AST
diff_hash: String, # SHA-256 of the diff
actor: String, # "Human" / "AI" / "System"
agent_id: String, # Kairos agent identifier
timestamp: ISO8601,
reason_ref: String # Off-chain reason reference
}
Setup
Prerequisites
- Ruby 3.2+ (uses standard library only, no gems required for basic functionality)
- Claude Code CLI (
claude) or Cursor IDE
Installation
KairosChain can be installed either as a Ruby gem (recommended) or by cloning the repository.
Option A: Install as a Gem (Recommended)
# Install the gem
gem install kairos-chain
# Initialize data directory (creates .kairos/ in current directory)
kairos-chain init
# Or initialize at a specific path
kairos-chain init --data-dir /path/to/my-kairos-data
# Test basic execution
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | kairos-chain
The gem ships with zero runtime dependencies. Optional features (SQLite, RAG, HTTP) can be added by installing additional gems — see the Optional sections below.
Data directory resolution (priority order):
--data-dir CLI optionKAIROS_DATA_DIR environment variable.kairos/ in the current working directory
Option B: Clone the Repository
# Clone the repository
git clone https://github.com/masaomi/KairosChain_2026.git
cd KairosChain_2026/KairosChain_mcp_server
# Make executable
chmod +x bin/kairos-chain
# Test basic execution
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bin/kairos-chain
Note: When running from the repository, the data directory defaults to .kairos/ in the current working directory. The server will auto-initialize on first run if the data directory doesn't exist.
Optional: RAG (Semantic Search) Support
KairosChain supports optional semantic search using vector embeddings. This enables finding skills by meaning rather than exact keyword matches (e.g., searching "authentication" can find skills about "login" or "password").
Without RAG gems: Regex-based keyword search (default, no installation required)
With RAG gems: Semantic vector search using sentence embeddings
Requirements
- C++ compiler (for native extensions)
- ~90MB disk space (for embedding model, downloaded on first use)
Installation
# If using the gem:
gem install hnswlib informers
# If using the repository with Bundler:
cd KairosChain_mcp_server
bundle install --with rag
Gems Used
| Gem | Version | Purpose |
|---|
hnswlib | ~> 0.9 | HNSW approximate nearest neighbor search |
informers | ~> 1.0 | ONNX-based sentence embeddings |
Supported Layers
| Layer | Target | RAG Support | Index Path |
|---|
| L0 | skills/kairos.rb (meta-skills) | Yes | storage/embeddings/skills/ |
| L1 | knowledge/ (project knowledge) | Yes | storage/embeddings/knowledge/ |
| L2 | context/ (temporary context) | No | N/A (regex search only) |
L2 is excluded because temporary contexts are short-lived and typically few in number, making regex search sufficient.
Configuration
RAG settings in config (at <data-dir>/config/config.yml for gem, or skills/config.yml for repo):
vector_search:
enabled: true # Enable if gems available
model: "sentence-transformers/all-MiniLM-L6-v2" # Embedding model
dimension: 384 # Must match model
index_path: "storage/embeddings" # Index storage path
auto_index: true # Auto-rebuild on changes
Installing RAG Later
If you install RAG gems after already using KairosChain:
- Install the gems:
bundle install --with rag or gem install hnswlib informers
- Restart the MCP server (reconnect in Cursor/Claude Code)
- On first search, the index is automatically rebuilt from all skills/knowledge
- Initial model download (~90MB) and embedding generation will take some time
Why this works: The @available flag is checked at server startup and cached. FallbackSearch (regex-based) does not persist any index data. When switching to SemanticSearch, the ensure_index_built method triggers a full rebuild_index on first use, creating embeddings for all existing skills and knowledge.
What happens to existing data:
- Skills and knowledge files: Unchanged (source of truth)
- Vector index: Created fresh from current content
- No migration needed: FallbackSearch → SemanticSearch is seamless
Verification
# Check if RAG gems are available
ruby -e "require 'hnswlib'; require 'informers'; puts 'RAG gems installed!'"
# Test RAG with the gem (semantic search of L0 skills)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"skills_dsl_list","arguments":{"query":"safety"}}}' | kairos-chain
# Test RAG from the repository
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"skills_dsl_list","arguments":{"query":"safety"}}}' | bin/kairos-chain
Note: The first RAG search will download the embedding model (~90MB) and build the vector index. Subsequent searches will be fast.
How It Works
┌─────────────────────────────────────────────────────────────┐
│ Search Query │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────┐
│ VectorSearch.available? │
└─────────────────────┘
│
┌───────────────┴───────────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Semantic Search │ │ Fallback Search │
│ (hnswlib + │ │ (Regex-based) │
│ informers) │ │ │
└─────────────────┘ └─────────────────┘
│ │
└───────────────┬───────────────┘
▼
┌─────────────────┐
│ Search Results │
└─────────────────┘
Optional: SQLite Storage Backend (Team Use)
By default, KairosChain uses file-based storage (JSON/JSONL files). For team environments with concurrent access, you can optionally enable SQLite storage backend.
Default (File-based): No configuration required, suitable for individual use
SQLite: Better concurrent access handling, suitable for small team use (2-10 people)
When to Use SQLite
| Scenario | Recommended Backend |
|---|
| Individual developer | File (default) |
| Small team (2-10) | SQLite |
| Large team (10+) | PostgreSQL (future) |
| CI/CD pipelines | SQLite |
Installation
# If using the gem:
gem install sqlite3
# If using the repository with Bundler:
cd KairosChain_mcp_server
bundle install --with sqlite
Configuration
Edit the config file to enable SQLite (at <data-dir>/skills/config.yml for gem, or skills/config.yml for repo):
# Storage backend configuration
storage:
backend: sqlite # Change from 'file' to 'sqlite'
sqlite:
path: "storage/kairos.db" # Path to SQLite database file
wal_mode: true # Enable WAL for better concurrency
Verification
# Check if SQLite gem is installed
ruby -e "require 'sqlite3'; puts 'SQLite3 gem installed!'"
# Test with the gem
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"chain_status","arguments":{}}}' | kairos-chain
# Test from the repository
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"chain_status","arguments":{}}}' | bin/kairos-chain
Exporting Data from SQLite to Files
You can export SQLite data to human-readable files for backup or inspection:
# In Ruby console or script
require 'kairos_mcp/storage/exporter' # gem install
# or: require_relative 'lib/kairos_mcp/storage/exporter' # from repository
# Export all data
KairosMcp::Storage::Exporter.export(
db_path: "storage/kairos.db",
output_dir: "storage/export"
)
# Output structure:
# storage/export/
# ├── blockchain.json # All blocks
# ├── action_log.jsonl # Action log entries
# ├── knowledge_meta.json # Knowledge metadata
# └── manifest.json # Export metadata
Rebuilding SQLite from Files
If SQLite database becomes corrupted, you can rebuild it from file-based data:
# In Ruby console or script
require_relative 'lib/kairos_mcp/storage/importer'
# Rebuild from original file storage
KairosMcp::Storage::Importer.rebuild_from_files(
db_path: "storage/kairos.db"
)
# Or import from exported files
KairosMcp::Storage::Importer.import(
input_dir: "storage/export",
db_path: "storage/kairos.db"
)
Using MCP Tools for Export/Import
You can also use MCP tools directly from your AI assistant (Cursor/Claude Code):
Export (read-only, safe):
# In Cursor/Claude Code chat:
"Export the SQLite database to files using chain_export"
# Or call directly:
chain_export output_dir="storage/backup"
Import (requires approval):
# Preview mode (shows impact without making changes):
chain_import source="files" approved=false
# Execute with automatic backup:
chain_import source="files" approved=true
# Import from exported directory:
chain_import source="export" input_dir="storage/backup" approved=true
Safety features of chain_import:
- Requires
approved=true to execute (otherwise shows preview)
- Automatically creates backup at
storage/backups/kairos_{timestamp}.db
- Shows impact summary before execution
skip_backup=true available but NOT recommended
Switching Between Backends
File → SQLite:
- Install sqlite3 gem
- Change
storage.backend to sqlite in config.yml
- Run
Importer.rebuild_from_files to migrate data
- Restart the MCP server
SQLite → File:
- Run
Exporter.export to export data
- Copy exported files to original locations:
blockchain.json → storage/blockchain.jsonaction_log.jsonl → skills/action_log.jsonl
- Change
storage.backend to file in config.yml
- Restart the MCP server
Migrating to SQLite (Step-by-Step)
If you're already using KairosChain with file-based storage and want to migrate to SQLite:
Step 1: Install sqlite3 gem
cd KairosChain_mcp_server
# Using Bundler (recommended)
bundle install --with sqlite
# Or direct install
gem install sqlite3
# Verify installation
ruby -e "require 'sqlite3'; puts 'SQLite3 ready!'"
Step 2: Update config.yml
# skills/config.yml
storage:
backend: sqlite # Change from 'file' to 'sqlite'
sqlite:
path: "storage/kairos.db"
wal_mode: true
Step 3: Migrate existing data
cd KairosChain_mcp_server
ruby -e "
require_relative 'lib/kairos_mcp/storage/importer'
result = KairosMcp::Storage::Importer.rebuild_from_files(
db_path: 'storage/kairos.db'
)
puts 'Migration completed!'
puts \"Blocks imported: #{result[:blocks]}\"
puts \"Action logs imported: #{result[:action_logs]}\"
puts \"Knowledge metadata imported: #{result[:knowledge_meta]}\"
"
Step 4: Restart MCP server
Restart Cursor/Claude Code or reconnect the MCP server.
Step 5: Verify migration
# Check chain status (gem or repository)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"chain_status","arguments":{}}}' | kairos-chain 2>/dev/null | jq -r '.result.content[0].text'
# Verify chain integrity
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"chain_verify","arguments":{}}}' | kairos-chain 2>/dev/null | jq -r '.result.content[0].text'
Step 6: Keep original files as backup
After migration, keep the original files as backup:
storage/
├── blockchain.json # ← Original file (keep as backup)
├── kairos.db # ← New SQLite database
└── kairos.db-wal # ← WAL file (auto-generated)
skills/
└── action_log.jsonl # ← Original file (keep as backup)
Troubleshooting SQLite
sqlite3 gem won't load:
# Check if installed
gem list sqlite3
# Reinstall if needed
gem uninstall sqlite3
gem install sqlite3
Data not visible after migration:
# Re-run migration
ruby -e "
require_relative 'lib/kairos_mcp/storage/importer'
KairosMcp::Storage::Importer.rebuild_from_files(db_path: 'storage/kairos.db')
"
SQLite database corrupted:
# Delete corrupted database and rebuild from original files
rm storage/kairos.db storage/kairos.db-wal storage/kairos.db-shm 2>/dev/null
ruby -e "
require_relative 'lib/kairos_mcp/storage/importer'
KairosMcp::Storage::Importer.rebuild_from_files(db_path: 'storage/kairos.db')
"
Reverting to file-based storage:
# Simply change config.yml back
storage:
backend: file # Change from 'sqlite' to 'file'
The original files (blockchain.json, action_log.jsonl) will be used automatically.
Important Notes
- Knowledge content (*.md files): Always stored in files regardless of backend
- SQLite stores: Blockchain, action logs, and knowledge metadata only
- Human readability: Use export feature to inspect data without SQL commands
- Backup: For SQLite, simply copy the
.db file; for extra safety, also export to files
Optional: Streamable HTTP Transport (Remote/Team Access)
By default, KairosChain uses stdio transport (local process). For remote access and team sharing, you can optionally enable Streamable HTTP transport with Bearer token authentication.
Default (stdio): Local process via stdin/stdout, no additional setup required
Streamable HTTP: Remote access via POST /mcp, Bearer token authentication, team sharing
When to Use HTTP Transport
| Scenario | Recommended Transport |
|---|
| Individual developer (local Cursor/Claude Code) | stdio (default) |
| Team sharing a single KairosChain instance | Streamable HTTP |
| Remote access across network | Streamable HTTP |
| CI/CD integration via HTTP | Streamable HTTP |
Installation
# If using the gem:
gem install puma rack
# If using the repository with Bundler:
cd KairosChain_mcp_server
bundle install --with http
# For full team setup (HTTP + SQLite for concurrent access):
gem install puma rack sqlite3 # gem
bundle install --with http sqlite # or Bundler
# Verify installation
ruby -e "require 'puma'; require 'rack'; puts 'HTTP transport gems installed!'"
Gems Used
| Gem | Version | Purpose |
|---|
puma | ~> 6.0 | High-performance concurrent web server |
rack | ~> 3.0 | Modular Ruby web server interface |
Quick Start
# Using the gem:
kairos-chain --init-admin
kairos-chain --http --port 8080
# Using the repository:
ruby bin/kairos-chain --init-admin
ruby bin/kairos-chain --http --port 8080
# Test with curl (in another terminal)
curl http://localhost:8080/health
Setup Steps
Step 1: Generate an Admin Token
# Using the gem:
kairos-chain --init-admin
# Using the repository:
ruby bin/kairos-chain --init-admin
Output:
============================================================
KairosChain Admin Token Generated
============================================================
Token: kc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
User: admin
Role: owner
Expires: 2026-05-13T10:00:00+01:00
IMPORTANT: Store this token securely.
It will NOT be shown again.
============================================================
Step 2: Start the HTTP Server
# Using the gem:
kairos-chain --http # default port 8080
kairos-chain --http --port 9090 # custom port
kairos-chain --http --port 8080 --data-dir /path/to/data # custom data dir
# Using the repository:
ruby bin/kairos-chain --http
ruby bin/kairos-chain --http --port 9090
ruby bin/kairos-chain --http --host 127.0.0.1 --port 8080
Step 3: Configure Cursor to Connect
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"kairos-chain-http": {
"type": "http",
"url": "http://localhost:8080/mcp",
"headers": {
"Authorization": "Bearer kc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}
Restart Cursor after saving.
Testing the HTTP Transport
Unit tests (no gems required):
ruby test_http.rb
Integration tests (requires puma + rack):
ruby test_http.rb --integration
Manual testing with curl:
# Health check (no auth required)
curl http://localhost:8080/health
# MCP initialize (with auth)
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-token>" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
# List tools
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-token>" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
# Call a tool
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-token>" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"hello_world","arguments":{"name":"HTTP"}}}'
Token Management
After initial setup, manage tokens via the token_manage MCP tool:
# Create a token for a team member
token_manage command="create" user="alice" role="member"
# List active tokens
token_manage command="list"
# Rotate a token (revoke old, create new)
token_manage command="rotate" user="alice"
# Revoke a token
token_manage command="revoke" user="alice"
Token roles (Phase 1: all roles have equal access):
| Role | Description | Phase 2 Permissions |
|---|
owner | System administrator | Full access + token management |
member | Team member | L1/L2 write, L0 read-only |
guest | External collaborator | Read-only, own L2 only |
Token expiry:
| Duration | Option | Use Case |
|---|
| 90 days (default) | expires_in="90d" | Daily use in Cursor |
| 24 hours | expires_in="24h" | CI/CD, temporary access |
| 7 days | expires_in="7d" | Short-term collaboration |
| No expiry | expires_in="never" | Owner tokens only |
CLI Options
Usage: kairos-chain [command] [options]
Commands:
init Initialize data directory with default templates
upgrade Preview template migrations after gem update
upgrade --apply Apply template migrations
Options:
--data-dir DIR Data directory path (default: .kairos/ in current dir)
--http Start in Streamable HTTP mode (default: stdio)
--port PORT HTTP port (default: 8080)
--host HOST HTTP bind host (default: config http.host, else 127.0.0.1)
--tls Enable built-in TLS/HTTPS (requires a cert — see --gen-cert)
--gen-cert Generate a self-signed TLS cert/key and exit
--cert-host HOST Add a hostname/IP to the generated cert SAN (repeatable)
--init-admin Generate initial admin token and exit
--token-store PATH Path to token store file
-v, --version Show version
-h, --help Show help
Environment Variables:
KAIROS_DATA_DIR Override data directory path
KAIROS_ALLOW_OPEN_ENDPOINT Set to 1 to start without a token on a network-reachable bind (unsafe)
HTTPS / TLS
There are two ways to serve the MCP endpoint over TLS. Encryption is always performed by
Puma/OpenSSL — KairosChain only selects the transport (plain HTTP vs TLS).
Option A: Built-in TLS (single operator / remote access)
KairosChain can terminate TLS itself, so a self-hosted instance can be reached securely
without a separate proxy.
# 1. Generate a self-signed cert/key once (written to <data-dir>/storage/tls/).
# Include every hostname/IP you connect by, so certificate verification passes:
kairos-chain --gen-cert --cert-host myhost.example.com
# 2. Start with TLS (or set http.tls.enabled: true in skills/config.yml):
kairos-chain --http --tls
Notes:
- The certificate is self-signed, so the client (Cursor / Claude Code) must trust it
(or disable verification). For a CA-issued certificate, use Option B.
- Certificates expire (default ~2 years). The server logs the expiry at startup and
warns when it is near; regenerate by deleting the old cert and running
--gen-cert again.
- If no admin token is configured, KairosChain refuses to start on a network-reachable
bind (that would be an open owner endpoint). Run
--init-admin first, or set
KAIROS_ALLOW_OPEN_ENDPOINT=1 to start without authentication intentionally.
Option B: Reverse proxy (public / multi-user)
For a public or multi-user deployment, place a reverse proxy in front of Puma; the proxy
terminates TLS with a CA-issued certificate.
Client (Cursor) ──HTTPS──▶ Reverse Proxy ──HTTP──▶ Puma (:8080)
(Caddy/Nginx)
TLS termination
Caddy (Recommended — Simplest)
Caddy provides automatic HTTPS with Let's Encrypt certificates (zero configuration for TLS).
# Install Caddy
# macOS
brew install caddy
# Ubuntu/Debian
sudo apt install -y caddy
# Or see: https://caddyserver.com/docs/install
Create a Caddyfile:
kairos.example.com {
reverse_proxy localhost:8080
}
Start Caddy:
# Foreground (for testing)
caddy run
# As a service (production)
sudo systemctl enable --now caddy
That's it. Caddy automatically:
- Obtains a Let's Encrypt certificate for
kairos.example.com
- Renews it before expiry
- Redirects HTTP to HTTPS
- Handles TLS termination
Option B: Nginx
For environments where Nginx is already available or preferred.
# Install Nginx + Certbot
# macOS
brew install nginx
# Ubuntu/Debian
sudo apt install -y nginx certbot python3-certbot-nginx
Create Nginx config (/etc/nginx/sites-available/kairos):
server {
listen 80;
server_name kairos.example.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
Enable and get SSL certificate:
# Enable the site
sudo ln -s /etc/nginx/sites-available/kairos /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
# Obtain Let's Encrypt certificate (automatic Nginx config update)
sudo certbot --nginx -d kairos.example.com
Certbot automatically modifies the Nginx config to add SSL and sets up auto-renewal.
Option C: Self-Signed Certificate (LAN / Development)
For LAN teams or development where you don't have a public domain:
# Generate self-signed certificate (valid for 1 year)
mkdir -p certs
openssl req -x509 -newkey rsa:4096 -keyout certs/key.pem -out certs/cert.pem \
-days 365 -nodes -subj "/CN=kairos.local"
With Caddy (using self-signed cert):
kairos.local {
tls /path/to/certs/cert.pem /path/to/certs/key.pem
reverse_proxy localhost:8080
}
With Nginx:
server {
listen 443 ssl;
server_name kairos.local;
ssl_certificate /path/to/certs/cert.pem;
ssl_certificate_key /path/to/certs/key.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
Cursor Configuration (HTTPS)
After setting up HTTPS, update ~/.cursor/mcp.json:
{
"mcpServers": {
"kairos-chain-http": {
"type": "http",
"url": "https://kairos.example.com/mcp",
"headers": {
"Authorization": "Bearer kc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}
Comparison: Caddy vs Nginx
| Aspect | Caddy | Nginx |
|---|
| HTTPS setup | Automatic (zero config) | Manual (certbot required) |
| Certificate renewal | Automatic | Automatic (via certbot timer) |
| Configuration | Simple Caddyfile | More verbose |
| Performance | Good | Excellent (battle-tested) |
| Best for | New setups, simplicity | Existing Nginx infrastructure |
Configuration
HTTP settings in skills/config.yml:
http:
enabled: false # Set to true or use --http flag
port: 8080 # HTTP listen port
host: "0.0.0.0" # Bind address
token_store: "storage/tokens.json" # Token storage path
default_token_expiry_days: 90 # Default token expiry
Cleanup After Testing
All generated files are in .gitignore. To clean up:
cd KairosChain_mcp_server
rm -f storage/tokens.json # Generated tokens
rm -rf vendor/bundle vendor/ # Locally installed gems
rm -rf .bundle/ # Bundler cache
rm -f Gemfile.lock # Lock file
Verify clean state: git status should show working tree clean.
Future Phases (Not Yet Implemented)
Phase 2: Role-Based Authorization
- Layer-specific permissions per role (owner/member/guest)
notifications/tools/list_changed for dynamic tool updates- Per-user permission overrides
Phase 3: Wallet / JWT Integration (GenomicsChain)
- JWT tokens issued by GenomicsChain Rails API
- Wallet-based authentication (MetaMask signature)
- Integration with PoC (Proof of Contribution) token system
Admin UI (Browser-Based Management)
When running in HTTP mode, KairosChain provides a built-in browser-based admin UI at /admin. This is a lightweight management interface for server operators — no additional frameworks or gems required.
Accessing the Admin UI
- Start the HTTP server:
kairos-chain --http (gem) or ruby bin/kairos-chain --http (repository)
- Open
http://localhost:8080/admin in your browser
- Log in with an
owner role Bearer token
Available Screens
| Screen | Path | Purpose |
|---|
| Dashboard | /admin | Chain status, token count, L0/L1 overview, state commit status |
| Tokens | /admin/tokens | Create, list, revoke, and rotate Bearer tokens |
| Chain | /admin/chain | Browse block history, view block details, verify chain integrity |
| Skills | /admin/skills | View L0 DSL skills and their definitions (read-only) |
| Knowledge | /admin/knowledge | Browse and search L1 knowledge entries (read-only) |
| Config | /admin/config | View configuration, layer settings, storage info (read-only) |
Technical Details
- Technology: htmx + PicoCSS + ERB (Ruby stdlib) — no new gems required
- Authentication: Session cookie (HMAC-SHA256 signed) wrapping existing Bearer tokens
- Authorization:
owner role only — other roles are redirected to login
- CSRF Protection: Token-based protection on all POST requests
- Data Source: Calls existing tool classes directly (no MCP protocol overhead)
- Same Process: Runs inside the existing Puma/Rack HTTP server
Design Philosophy
The admin UI is intentionally minimal. It is a Phase 1 management tool (see MCP-to-SaaS Development Workflow). For richer UIs, build a custom SaaS frontend that consumes the Backend API and MCP tools.
Client Configuration
Claude Code Configuration (Detailed)
Claude Code is a CLI-based AI coding assistant.
Step 1: Verify Claude Code Installation
# Check if Claude Code is installed
claude --version
# If not installed, install from the official site
# https://docs.anthropic.com/claude-code
Option A: Install as a Plugin (Recommended)
KairosChain is available as a Claude Code plugin. This method provides both MCP server integration and Agent Skills.
Claude Code only: The /plugin command is a Claude Code CLI-specific feature. For Cursor, Antigravity, and other MCP-compatible editors, use Option B: Register MCP Server Directly or the Cursor IDE Configuration section below.
Prerequisites: Ruby 3.2+ and gem install kairos-chain
# Step 1: Add the KairosChain marketplace
/plugin marketplace add https://github.com/masaomi/KairosChain_2026.git
# Step 2: Install the plugin
/plugin install kairos-chain
# Step 3: Restart Claude Code to load the plugin
# After restart, verify the connection:
# - The Agent Skill loads automatically
# - MCP tools (29+) become available
# - Run chain_status to confirm blockchain connectivity
After restart, you can verify with:
# Check the Skill is loaded
/kairos-chain:kairos-chain
# Test MCP server connection
"Run hello_world"
"Check chain_status"
Note: Without Ruby/gem installed, only the Agent Skill (knowledge reference) is available. MCP server tools require gem install kairos-chain.
Option B: Register MCP Server Directly
If you prefer not to use the plugin system, you can register the MCP server directly:
Step 2: Register the MCP Server
# If using the gem (recommended):
claude mcp add kairos-chain kairos-chain
# If using the repository:
claude mcp add kairos-chain ruby /path/to/KairosChain_mcp_server/bin/kairos-chain
# With a custom data directory:
claude mcp add kairos-chain kairos-chain -- --data-dir /path/to/my-kairos-data
Step 3: Verify Registration
# List registered MCP servers
claude mcp list
# You should see kairos-chain in the list
Step 4: Check Configuration File (Optional)
The following configuration is added to ~/.claude.json:
{
"mcpServers": {
"kairos-chain": {
"command": "kairos-chain",
"args": ["--data-dir", "/path/to/my-kairos-data"],
"env": {}
}
}
}
For repository-based setup:
{
"mcpServers": {
"kairos-chain": {
"command": "ruby",
"args": ["/path/to/KairosChain_mcp_server/bin/kairos-chain"],
"env": {}
}
}
}
Manual Configuration (Advanced)
To edit the configuration file directly:
# Open the configuration file
vim ~/.claude.json
# Or use VS Code
code ~/.claude.json
Cursor IDE Configuration (Detailed)
Cursor is a VS Code-based AI coding IDE.
Option A: Via GUI (Recommended)
- Open Cursor Settings (Cmd/Ctrl + ,)
- Navigate to Tools & MCP
- Click New MCP Server
- Enter the server details:
- If using the gem:
- Name:
kairos-chain
- Command:
kairos-chain
- Args:
--data-dir /path/to/my-kairos-data (optional)
- If using the repository:
- Name:
kairos-chain
- Command:
ruby
- Args:
/path/to/KairosChain_mcp_server/bin/kairos-chain
Option B: Via Configuration File
Step 1: Locate the Configuration File
# macOS / Linux
~/.cursor/mcp.json
# Windows
%USERPROFILE%\.cursor\mcp.json
Step 2: Create/Edit the Configuration File
# Create directory if it doesn't exist
mkdir -p ~/.cursor
# Edit the configuration file
vim ~/.cursor/mcp.json
Step 3: Add the MCP Server
If using the gem (recommended):
{
"mcpServers": {
"kairos-chain": {
"command": "kairos-chain",
"args": ["--data-dir", "/path/to/my-kairos-data"],
"env": {}
}
}
}
If using the repository:
{
"mcpServers": {
"kairos-chain": {
"command": "ruby",
"args": ["/path/to/KairosChain_mcp_server/bin/kairos-chain"],
"env": {}
}
}
}
For multiple MCP servers:
{
"mcpServers": {
"kairos-chain": {
"command": "kairos-chain",
"args": ["--data-dir", "/Users/yourname/.kairos"],
"env": {}
},
"sushi-mcp-server": {
"command": "ruby",
"args": ["/path/to/SUSHI_self_maintenance_mcp_server/bin/sushi_mcp_server"],
"env": {}
}
}
}
Step 4: Restart Cursor
After saving the configuration, you must completely restart Cursor.
Step 5: Verify MCP Server Connection
- Open Cursor
- Click the "MCP" icon in the top right (or search "MCP" in the command palette)
- Verify that
kairos-chain appears in the list with a green status indicator
Upgrading the Gem
When a new version of kairos-chain is released (with new skills, config keys, bug fixes, etc.), updating the gem code is straightforward:
gem update kairos-chain
However, your data directory (.kairos/) contains template files that were copied at init time and may have been customized. The built-in upgrade system uses 3-way hash comparison to safely migrate these files.
How It Works
The upgrade system compares three versions of each template file:
- Original: The template hash recorded in
.kairos_meta.yml at init time
- Current: Your version in the data directory (possibly customized)
- New: The latest template shipped with the gem
Based on this comparison, each file is classified:
| Pattern | User Modified? | Template Changed? | Action |
|---|
| 0 (unchanged) | No | No | No action needed |
| 1 (auto-updatable) | No | Yes | Safe to auto-update |
| 2 (user-modified) | Yes | No | Keep user version |
| 3 (conflict) | Yes | Yes | Merge / review required |
For config YAML files (Pattern 3), a structural merge adds new keys while preserving your values. For L0 kairos.rb (Pattern 3), a skills_evolve proposal is generated, requiring human approval and blockchain recording.
L1 Knowledge Updates (v1.0.0+)
Starting from v1.0.0, the gem also bundles official L1 knowledge (17 bundled templates) alongside the config and skills templates. When you run system_upgrade (or kairos-chain upgrade --apply):
- New knowledge: Files that don't exist in your data directory are installed
- Unmodified knowledge: Files unchanged since init are auto-updated to the latest bundled version
- User-modified knowledge: Files you've edited are preserved (your changes are kept)
- Conflicts: When both you and the gem have changed a file, the new version is saved to a
.new/ directory for manual review and merge
The .kairos_meta.yml file now tracks both template_hashes (for config/skills) and knowledge_hashes for L1 knowledge files, enabling the same 3-way comparison logic for knowledge updates.
Upgrade Commands
Via CLI
# Preview what would change (recommended first step)
kairos-chain upgrade
# Apply the upgrade
kairos-chain upgrade --apply
# With custom data directory
kairos-chain upgrade --data-dir /path/to/data --apply
Via MCP Tool (from within an AI session)
system_upgrade command="check" # Quick version check
system_upgrade command="preview" # Detailed file-by-file analysis
system_upgrade command="apply" approved=true # Apply upgrade
system_upgrade command="status" # Show current meta status
Version Mismatch Warning
When the MCP server starts and detects a version mismatch between the gem and the data directory, it displays a warning:
[KairosChain] Data directory was initialized with v1.0.0, current gem is v1.1.0.
[KairosChain] Run 'system_upgrade command="check"' or 'kairos-chain upgrade' to see available updates.
Upgrade Workflow
- Update the gem:
gem update kairos-chain
- Preview changes:
kairos-chain upgrade
- Review the output (especially any conflicts)
- Apply:
kairos-chain upgrade --apply
- For L0 proposals, use
skills_evolve to review and approve
- Restart the MCP server
All upgrade operations are recorded to the KairosChain blockchain for traceability.
MMP SkillSet Setup (P2P Communication)
MMP (Model Meeting Protocol) is an optional SkillSet that enables P2P communication and knowledge exchange between KairosChain instances.
Installing the MMP SkillSet
MMP is bundled as a template SkillSet. Install it using the CLI:
# Install the MMP SkillSet (bundled with the gem)
kairos-chain skillset install templates/skillsets/mmp
# Or from a repository clone
cd /path/to/KairosChain_mcp_server
bin/kairos-chain skillset install templates/skillsets/mmp
# Verify installation
kairos-chain skillset list
# Should show: mmp (L1, enabled)
Configuring meeting.yml
After installation, configure the MMP SkillSet by editing <data-dir>/skillsets/mmp/config/meeting.yml:
# Master switch
enabled: true
# Agent identity
identity:
name: "My Agent"
description: "KairosChain instance for my project"
scope: "general"
# Individual skill exchange settings
skill_exchange:
allowed_formats: [markdown, yaml_frontmatter]
allow_executable: false # NEVER set to true for P2P
public_by_default: false
# SkillSet package exchange settings
skillset_exchange:
enabled: true
knowledge_only: true # Only exchange knowledge-only packages
auto_install: false # Require manual approval
# Rate limiting
constraints:
max_skill_size_bytes: 100000
rate_limit_per_minute: 10
# HTTP server for P2P
http_server:
enabled: true
host: "127.0.0.1"
port: 8080
timeout: 10
# Identity signing (Phase 3.7+)
crypto:
keypair_path: "keys/mmp_keypair.pem"
auto_generate: true
Starting the P2P HTTP Server
# Start KairosChain with HTTP transport for P2P
kairos-chain --http --port 8080
# With Bearer token authentication
kairos-chain --http --port 8080 --bearer-token YOUR_TOKEN
Testing P2P Connectivity
# Test self-introduction endpoint
curl http://localhost:8080/meeting/v1/introduce
# List available skills
curl http://localhost:8080/meeting/v1/skills
# Connect from another agent
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"meeting_connect","arguments":{"url":"http://localhost:8080","mode":"direct"}}}' | kairos-chain
For detailed P2P usage, see the MMP P2P User Guide.
Testing the Setup
Note: The examples below show both the gem command (kairos-chain) and the repository command (bin/kairos-chain). Use whichever matches your installation.
1. Basic Command Line Tests
Initialize Test
# Using the gem:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | kairos-chain
# Using the repository:
cd /path/to/KairosChain_mcp_server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bin/kairos-chain
# Expected response (excerpt):
# {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","capabilities":...}}
Tools List Test
# Get list of available tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | kairos-chain
# If you have jq, display only tool names
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | kairos-chain 2>/dev/null | jq '.result.tools[].name'
Hello World Test
# Call the hello_world tool
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"hello_world","arguments":{}}}' | kairos-chain 2>/dev/null | jq -r '.result.content[0].text'
# Output: Hello from KairosChain MCP Server!
2. Skills Tools Test
# Get skills list
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"skills_dsl_list","arguments":{}}}' | kairos-chain 2>/dev/null | jq -r '.result.content[0].text'
# Get a specific skill
echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"skills_dsl_get","arguments":{"skill_id":"core_safety"}}}' | kairos-chain 2>/dev/null | jq -r '.result.content[0].text'
3. Blockchain Tools Test
# Check blockchain status
echo '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"chain_status","arguments":{}}}' | kairos-chain 2>/dev/null | jq -r '.result.content[0].text'
# Verify chain integrity
echo '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"chain_verify","arguments":{}}}' | kairos-chain 2>/dev/null | jq -r '.result.content[0].text'
4. Testing with SQLite Backend (Optional)
# 1. Install sqlite3 gem
gem install sqlite3
# 2. Edit config to enable SQLite
# Change storage.backend from 'file' to 'sqlite' in <data-dir>/skills/config.yml
# 3. Test chain_status (should show SQLite backend info)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"chain_status","arguments":{}}}' | kairos-chain 2>/dev/null | jq -r '.result.content[0].text'
# 4. Record and verify
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"chain_record","arguments":{"logs":["SQLite test record"]}}}' | kairos-chain 2>/dev/null | jq -r '.result.content[0].text'
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"chain_verify","arguments":{}}}' | kairos-chain 2>/dev/null | jq -r '.result.content[0].text'
5. Testing with RAG / Semantic Search (Optional)
# 1. Install RAG gems
gem install hnswlib informers
# 2. Verify gems are available
ruby -e "require 'hnswlib'; require 'informers'; puts 'RAG gems installed!'"
# 3. Enable RAG in config
# Set vector_search.enabled to true in <data-dir>/skills/config.yml
# 4. Test semantic search (first run downloads ~90MB embedding model)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"skills_dsl_list","arguments":{"query":"safety rules"}}}' | kairos-chain 2>/dev/null | jq -r '.result.content[0].text'
# 5. Test knowledge search
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"knowledge_list","arguments":{"query":"layer placement"}}}' | kairos-chain 2>/dev/null | jq -r '.result.content[0].text'
6. Testing HTTP Mode (Optional)
# 1. Install HTTP gems
gem install puma rack
# 2. Initialize data and generate admin token
kairos-chain init --data-dir /tmp/kairos_test
kairos-chain --init-admin --data-dir /tmp/kairos_test
# Save the displayed token!
# 3. Start HTTP server
kairos-chain --http --port 9090 --data-dir /tmp/kairos_test
# 4. Test from another terminal
curl http://localhost:9090/health
curl -X POST http://localhost:9090/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR_TOKEN>" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
7. Testing with Claude Code
# Launch Claude Code
claude
# Try these prompts in Claude Code:
# "List the available KairosChain tools"
# "Run skills_dsl_list"
# "Check chain_status"
8. Testing with Cursor
- Open your project in Cursor
- Open the chat panel (Cmd/Ctrl + L)
- Try these prompts:
- "List all KairosChain skills"
- "Check the blockchain status"
- "Show me the core_safety skill content"
Troubleshooting
Server Doesn't Start
# Check Ruby version
ruby --version # Requires 3.2+
# Check for syntax errors
ruby -c bin/kairos-chain
# Verify executable permission
ls -la bin/kairos-chain
chmod +x bin/kairos-chain
JSON-RPC Errors
# Check stderr for error messages
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bin/kairos-chain
# Run without suppressing stderr (remove 2>/dev/null)
Gem Command Not Found
# If kairos-chain is not found after gem install
# Check if the gem bin directory is in your PATH
gem environment gemdir
# The executable should be in the bin/ directory under that path
# For rbenv users, rehash may be needed
rbenv rehash
# Verify the correct Ruby version has the gem
gem list kairos-chain
Cursor Connection Issues
- Verify the path in
~/.cursor/mcp.json is an absolute path (for repository setup)
- Check JSON syntax (missing/extra commas, etc.)
- Completely quit and restart Cursor
Usage Tips
Basic Usage
1. Working with Skills
KairosChain manages AI capability definitions as "Skills".
# In Cursor / Claude Code:
"List all current skills"
"Show me the core_safety skill content"
"Use self_introspection to check Kairos state"
2. Blockchain Recording
AI evolution processes are recorded on the blockchain.
# Checking records
"Show me the chain_history"
"Verify chain integrity with chain_verify"
Practical Usage Patterns
Pattern 1: Starting a Development Session
# Session startup checklist
1. "Check blockchain status with chain_status"
2. "List available skills with skills_dsl_list"
3. "Verify chain integrity with chain_verify"
Pattern 2: Skill Evolution (Human Approval Required)
# Enable evolution in config/safety.yml
evolution_enabled: true
require_human_approval: true
# Evolution workflow:
1. "Propose a change to my_skill using skills_evolve"
2. [Human] Review and approve the proposal
3. "Apply the change with skills_evolve (approved=true)"
4. "Verify the record with chain_history"
Pattern 3: Auditing and Traceability
# Track specific change history
"Show recent skill changes with chain_history"
"Get details of a specific block"
# Periodic integrity verification
"Verify the entire chain with chain_verify"
Best Practices
1. Be Cautious with Evolution
- Keep
evolution_enabled: false as the default
- Start evolution sessions explicitly and disable after completion
- Route all changes through human approval
2. Regular Verification
# Run daily/weekly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"chain_verify","arguments":{}}}' | kairos-chain
3. Backups
# Regularly backup storage/blockchain.json
cp storage/blockchain.json storage/backups/blockchain_$(date +%Y%m%d).json
# Also backup skill versions
cp -r skills/versions skills/backups/versions_$(date +%Y%m%d)
4. Sharing Across Multiple AI Agents
Share the same data directory to synchronize evolution history across multiple AI agents.
// In ~/.cursor/mcp.json or ~/.claude.json
{
"mcpServers": {
"kairos-chain": {
"command": "kairos-chain",
"args": ["--data-dir", "/shared/kairos-data"],
"env": {}
}
}
}
Or using the environment variable:
{
"mcpServers": {
"kairos-chain": {
"command": "kairos-chain",
"args": [],
"env": {
"KAIROS_DATA_DIR": "/shared/kairos-data"
}
}
}
}
Tool Discovery with tool_guide
The tool_guide tool helps you discover and learn about KairosChain tools dynamically.
# Browse all tools by category
"Run tool_guide command='catalog'"
# Search for tools by keyword
"Run tool_guide command='search' query='blockchain'"
# Get recommendations for a task
"Run tool_guide command='recommend' task='audit knowledge health'"
# Get detailed info about a specific tool
"Run tool_guide command='detail' tool_name='skills_audit'"
# Learn common workflow patterns
"Run tool_guide command='workflow'"
"Run tool_guide command='workflow' workflow_name='skill_evolution'"
For tool developers (LLM-assisted metadata generation):
# Suggest metadata for a tool
"Run tool_guide command='suggest' tool_name='my_new_tool'"
# Validate suggested metadata
"Run tool_guide command='validate' tool_name='my_new_tool' metadata={...}"
# Apply metadata with human approval
"Run tool_guide command='apply_metadata' tool_name='my_new_tool' metadata={...} approved=true"
Common Commands Reference
| Task | Cursor/Claude Code Prompt |
|---|
| List Skills | "Run skills_dsl_list" |
| Get Specific Skill | "Get core_safety with skills_dsl_get" |
| Chain Status | "Check chain_status" |
| View History | "Show chain_history" |
| Verify Integrity | "Run chain_verify" |
| Record Data | "Record a log with chain_record" |
| Browse Tools | "Run tool_guide command='catalog'" |
| Search Tools | "Run tool_guide command='search' query='...'" |
| Get Tool Help | "Run tool_guide command='detail' tool_name='...'" |
Security Considerations
-
Safe Evolution Settings
- Keep
require_human_approval: true
- Only set
evolution_enabled: true when needed
-
Access Control
- Restrict allowed paths in
config/safety.yml
- Add sensitive files to the blocklist
-
Audit Logging
- All operations are recorded in
action_log
- Review logs regularly
Available Tools (26 core + skill-tools)
The base installation provides 25 tools (24 + 1 HTTP-only). Additional tools can be defined via tool blocks in kairos.rb when skill_tools_enabled: true.
L0-A: Skills Tools (Markdown) - Read-only
| Tool | Description |
|---|
skills_list | List all skills sections from kairos.md |
skills_get | Get specific section by ID |
L0-B: Skills Tools (DSL) - Full Blockchain Record
| Tool | Description |
|---|
skills_dsl_list | List all skills from kairos.rb |
skills_dsl_get | Get skill definition by ID |
skills_evolve | Propose/apply skill changes |
skills_rollback | Manage version snapshots |
Skill-defined tools: When skill_tools_enabled: true, skills with tool blocks in kairos.rb are also registered here as MCP tools.
L0: Instructions Management - Full Blockchain Record
| Tool | Description |
|---|
instructions_update | Create, update, or delete custom instruction files and switch instructions_mode (L0-level, requires human approval) |
Commands:
status: Show current mode and available instruction filescreate: Create a new instructions file (skills/{mode_name}.md)update: Update existing instructions file contentdelete: Delete a custom instructions file (built-in files protected)set_mode: Change instructions_mode in config.yml
Dynamic mode resolution: Setting instructions_mode: 'researcher' in config.yml loads skills/researcher.md as the AI system prompt instructions. Built-in modes (developer, user, none) are preserved.
Instruction Mode Projection (CLAUDE.md @-import)
The active instruction mode body is also projected to project-root CLAUDE.md via a managed @-import region. This is necessary because (a) the MCP instructions channel is truncated by the Claude Code harness, and (b) Agent tool sub-agents do not inherit MCP instructions at all but do inherit project CLAUDE.md (verified empirically up to 107KB on Opus 4.6 / 4.7, single-level). Without projection, sub-agents operate without the active mode entirely.
CLI subcommand:
kairos-chain mode project # materialize active mode body + add CLAUDE.md region
kairos-chain mode status # show projection state
kairos-chain mode remove # remove projection
After projection, the MCP instructions channel switches to a slim identity + pointer payload; the full body reaches all surfaces (parent + subprocess + sub-agent) through the privileged CLAUDE.md @-import path.
The first-run state (no projection yet) prepends a setup notice to MCP instructions so the LLM can guide the user through the one-time setup automatically.
Re-run kairos-chain mode project after editing the source mode body, then restart Claude Code to apply (CLAUDE.md @-import resolution is fixed at session start; mid-session edits do not propagate to sub-agents).
Cross-Layer Promotion Tools
| Tool | Description |
|---|
skills_promote | Promote knowledge between layers (L2→L1, L1→L0) with optional Persona Assembly |
Commands:
analyze: Generate persona assembly discussion for promotion decisionpromote: Execute direct promotionstatus: Check promotion requirements
Audit Tools - Knowledge Lifecycle Management
| Tool | Description |
|---|
skills_audit | Audit knowledge health across L0/L1/L2 layers with optional Persona Assembly |
Commands:
check: Health check across specified layersstale: Detect outdated items (L0: no date check, L1: 180 days, L2: 14 days)conflicts: Detect potential contradictions between knowledgedangerous: Detect patterns conflicting with L0 safetyrecommend: Get promotion and archive recommendationsgaps: Check knowledge gaps defined by Knowledge Acquisition Policy in instruction modesexport_needs: Package knowledge gaps as shareable needs for cross-instance discovery via Meeting Placearchive: Archive L1 knowledge (human approval required)unarchive: Restore from archive (human approval required)
Resource Tools - Unified Access
| Tool | Description |
|---|
resource_list | List resources across all layers (L0/L1/L2) with URI |
resource_read | Read resource content by URI |
URI format:
l0://kairos.md, l0://kairos.rb (L0 Skills)knowledge://{name}, knowledge://{name}/scripts/{file} (L1)context://{session}/{name} (L2)
L1: Knowledge Tools - Hash Reference Record
| Tool | Description |
|---|
knowledge_list | List all knowledge skills |
knowledge_get | Get knowledge content by name |
knowledge_update | Create/update/delete knowledge (hash recorded) |
L2: Context Tools - No Blockchain Record
| Tool | Description |
|---|
context_save | Save context (free modification) |
context_create_subdir | Create scripts/assets/references subdir |
Blockchain Tools
| Tool | Description |
|---|
chain_status | Get blockchain status (includes storage backend info) |
chain_record | Record data to blockchain |
chain_verify | Verify chain integrity |
chain_history | View block history (enhanced: shows StateCommit blocks with formatted details) |
chain_export | Export SQLite data to files (SQLite mode only) |
chain_import | Import files to SQLite with automatic backup (SQLite mode only, requires approved=true) |
State Commit Tools (Auditability)
State commits provide cross-layer auditability by creating snapshots of all layers (L0/L1/L2) at specific commit points.
| Tool | Description |
|---|
state_commit | Create an explicit state commit with reason (records to blockchain) |
state_status | View current state, pending changes, and auto-commit trigger status |
state_history | Browse state commit history and view snapshot details |
Authentication Tools (HTTP Mode Only)
| Tool | Description |
|---|
token_manage | Manage Bearer tokens (create, revoke, list, rotate). Requires owner role. |
Guide Tools (Tool Discovery)
Dynamic tool guidance system for discovering and learning about KairosChain tools.
| Tool | Description |
|---|
tool_guide | Dynamic tool discovery, search, and documentation |
Commands:
catalog: List all tools organized by categorysearch: Search tools by keywordrecommend: Get tool recommendations for specific tasksdetail: Get detailed information about a specific toolworkflow: Show common workflow patternssuggest: Generate metadata suggestions for a tool (LLM-assisted)validate: Validate proposed metadata before applyingapply_metadata: Apply metadata to a tool (requires human approval)
Key features:
- Snapshots stored off-chain (JSON files), hash references on-chain
- Auto-commit triggers: L0 changes, promotions/demotions, threshold-based (5 L1 changes or 10 total)
- Empty commit prevention: commits only when manifest hash actually changes
System Management Tools
| Tool | Description |
|---|
system_upgrade | Check for gem updates and safely migrate data directory templates |
Commands:
check: Compare current and gem versions, show affected filespreview: Detailed file-by-file analysis with merge previewsapply: Execute upgrade (requires approved=true)status: Show .kairos_meta.yml status
MMP Meeting Tools (SkillSet: mmp)
These tools are available when the MMP (Model Meeting Protocol) SkillSet is installed and enabled. MMP enables P2P communication and knowledge exchange between KairosChain instances.
| Tool | Description |
|---|
meeting_connect | Connect to a remote KairosChain peer via MMP |
meeting_disconnect | Disconnect from a peer session |
meeting_acquire_skill | Acquire a skill or SkillSet from a connected peer |
meeting_get_skill_details | Get metadata about a peer's available skills |
MMP SkillSet also exposes HTTP endpoints via MeetingRouter (/meeting/v1/*):
| Endpoint | Method | Description |
|---|
/meeting/v1/introduce | GET | Self-introduction (identity, capabilities) |
/meeting/v1/introduce | POST | Receive peer introduction |
/meeting/v1/skills | GET | List public skills |
/meeting/v1/skill_details | GET | Get skill metadata (?skill_id=X) |
/meeting/v1/skill_content | POST | Request skill content |
/meeting/v1/request_skill | POST | Submit skill request |
/meeting/v1/reflect | POST | Send reflection |
/meeting/v1/message | POST | Generic MMP message |
/meeting/v1/skillsets | GET | List exchangeable SkillSets |
/meeting/v1/skillset_details | GET | Get SkillSet metadata (?name=X) |
/meeting/v1/skillset_content | POST | Download SkillSet archive |
Knowledge-only constraint: Only non-executable content (Markdown, YAML) can be exchanged over P2P. SkillSets containing executable code (tools/, lib/ with .rb, .py, .sh, etc.) must be installed via trusted channels. See the MMP P2P User Guide for details.
Multiuser Tools (SkillSet: multiuser)
These tools are available when the Multiuser SkillSet is installed. The tools register even when PostgreSQL is unavailable, providing diagnostic information about the setup state.
| Tool | Description |
|---|
multiuser_status | Check Multiuser SkillSet status: PostgreSQL connection, tenant count, user count, migration status |
multiuser_user_manage | Manage users: list, create, delete, update_role (owner only) |
multiuser_migrate | Run database migrations: status, run, dry_run (owner only) |
Graceful degradation: When PostgreSQL is not available, multiuser_status returns a diagnostic report (pg_gem_missing, pg_server_unavailable, or pg_error) with actionable help text. All other KairosChain tools continue to work normally.
Usage Examples
List Available Skills
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"skills_dsl_list","arguments":{}}}' | kairos-chain
Check Blockchain Status
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"chain_status","arguments":{}}}' | kairos-chain
Record a Skill Transition
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"chain_record","arguments":{"logs":["Skill X modified","Reason: improved accuracy"]}}}' | kairos-chain
P2P SkillSet Exchange
# 1. Start HTTP server for P2P (on Agent A)
kairos-chain --http --port 8080
# 2. Connect from Agent B
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"meeting_connect","arguments":{"url":"http://localhost:8080","mode":"direct"}}}' | kairos-chain
# 3. List peer's available skills
curl http://localhost:8080/meeting/v1/skills
# 4. Get SkillSet details
curl "http://localhost:8080/meeting/v1/skillset_details?name=my_knowledge_set"
# 5. Download SkillSet archive
curl -X POST http://localhost:8080/meeting/v1/skillset_content \
-H "Content-Type: application/json" \
-d '{"name":"my_knowledge_set"}'
# 6. Install received archive
kairos-chain skillset install-archive received_package.json
Self-Evolution Workflow
KairosChain supports Safe Self-Evolution:
-
Enable Evolution (in skills/config.yml):
evolution_enabled: true
require_human_approval: true
-
AI Proposes Change:
skills_evolve command=propose skill_id=my_skill definition="..."
-
Human Reviews and Approves:
skills_evolve command=apply skill_id=my_skill definition="..." approved=true
-
Change is Applied and Recorded:
- Snapshot created in
skills/versions/
- Transition recorded on blockchain
Kairos.reload! updates in-memory state
-
Verification:
chain_verify # Confirms integrity
chain_history # Shows the transition record
HestiaChain Meeting Place (v2.5.0)
What is HestiaChain?
HestiaChain is a trust anchor and meeting place for KairosChain agents. It is implemented entirely as a SkillSet (the hestia SkillSet), preserving KairosChain's principle that new capabilities are expressed as SkillSets rather than core modifications.
HestiaChain provides two functions:
- Trust Anchor — A witness chain that records that interactions occurred, without enforcing judgments or determining canonical state
- Meeting Place Server — A hosted environment where agents discover each other, browse skills, and exchange knowledge via HTTP endpoints
Architecture
KairosChain (MCP Server)
├── [core] L0/L1/L2 + private blockchain
├── [SkillSet: mmp] P2P direct mode, /meeting/v1/*
└── [SkillSet: hestia] Meeting Place + trust anchor
├── chain/ ← Trust anchor (self-contained, no external gem dependency)
├── PlaceRouter ← /place/v1/* HTTP endpoints
├── AgentRegistry ← Agent registration with JSON persistence
├── SkillBoard ← Skill + knowledge needs discovery (random sampling, no ranking)
├── HeartbeatManager ← TTL-based liveness with fadeout recording
└── tools/ ← 7 MCP tools
A KairosChain instance with the hestia SkillSet is simultaneously an MCP server, a P2P agent, a Meeting Place host, and a participant in other Meeting Places. This embodies the DEE principle of subject-object undifferentiation (主客未分).
Quick Start
1. Install the hestia SkillSet
# The hestia SkillSet is bundled with the gem.
# It is installed automatically when you install mmp.
# To install manually:
kairos-chain # Start KairosChain
# Then in Claude Code / Cursor:
"Install the hestia SkillSet"
2. Start the Meeting Place
# Start HTTP server
kairos-chain --http --port 8080
# Then in Claude Code / Cursor:
"Start the Meeting Place"
# This calls the meeting_place_start tool
3. Test with curl
# Place info (no auth required)
curl -s http://localhost:8080/place/v1/info | python3 -m json.tool
# Register an agent
curl -s -X POST http://localhost:8080/place/v1/register \
-H 'Content-Type: application/json' \
-d '{"id":"agent-alpha","name":"Agent Alpha","capabilities":{"supported_actions":["test"]}}'
# Browse the skill board (Bearer token required)
curl -s -H "Authorization: Bearer $TOKEN" \
http://localhost:8080/place/v1/board/browse | python3 -m json.tool
HTTP Endpoints
| Method | Path | Auth | Description |
|---|
| GET | /place/v1/info | None | Place metadata and identity |
| POST | /place/v1/register | RSA signature (optional) | Register an agent |
| POST | /place/v1/unregister | Bearer | Unregister an agent |
| GET | /place/v1/agents | Bearer | List registered agents |
| GET | /place/v1/board/browse | Bearer | Browse skill board (random order) |
| POST | /place/v1/board/needs | Bearer | Publish knowledge needs to board |
| DELETE | /place/v1/board/needs | Bearer | Remove published knowledge needs |
| GET | /place/v1/keys/:id | Bearer | Retrieve agent's public key |
MCP Tools
| Tool | Description |
|---|
chain_migrate_status | Show current backend stage and available migrations |
chain_migrate_execute | Migrate chain to next backend stage |
philosophy_anchor | Declare exchange philosophy (hash recorded on chain) |
record_observation | Record subjective observation of interaction |
meeting_place_start | Start the Meeting Place, initialize components |
meeting_place_status | Show Meeting Place configuration and status |
meeting_publish_needs | Publish knowledge gaps to board (explicit opt-in required) |
Cross-Instance Knowledge Discovery
Agents can publish their knowledge gaps (needs) to the Meeting Place board, enabling other agents to discover and offer relevant knowledge.
Workflow:
- Run
skills_audit(command: "gaps") to detect missing baseline knowledge
- Run
skills_audit(command: "export_needs") to preview exportable needs
- Run
meeting_publish_needs(opt_in: true) to publish needs to the board
- Other agents browsing with
browse(type: 'need') can discover these needs
- Agents decide locally whether to offer knowledge (no automated matching)
DEE Compliance:
- Needs are session-only (in-memory, no persistence)
- No aggregation, ranking, or popularity metrics
- Explicit opt-in required (
opt_in: true)
- Random sampling for browse results (D3)
- Each agent decides independently whether to respond (D5)
Trust Anchor: Chain Migration
HestiaChain's trust anchor supports a 4-stage backend progression:
| Stage | Backend | Use Case |
|---|
| 0 | In-memory | Development and testing |
| 1 | Private JSON file | Production-ready, self-hosted |
| 2 | Public testnet (Base Sepolia) | Cross-instance verification |
| 3 | Public mainnet | Full decentralization |
Use chain_migrate_status to check and chain_migrate_execute to advance.
DEE Philosophy Protocol
HestiaChain implements the Decentralized Event Exchange (DEE) protocol:
- PhilosophyDeclaration: Agents declare their exchange philosophy (observable, not enforceable). Only the hash is recorded on chain.
- ObservationLog: Agents record subjective observations. Multiple agents can have different observations of the same interaction — "meaning coexists."
- Fadeout: When an agent's heartbeat expires, this is recorded as a first-class event (not an error). Silent departure is a natural part of the protocol.
- Random Sampling: The SkillBoard returns skills and knowledge needs in random order. There is no ranking, no scoring, no popularity metric.
EC2 Deployment
To host a public Meeting Place on AWS EC2:
# Install
gem install kairos-chain
# Initialize
kairos-chain init ~/.kairos
# Start (bind to all interfaces for external access)
KAIROS_HOST=0.0.0.0 KAIROS_PORT=8080 kairos-chain --http
For production, use a reverse proxy (Caddy/nginx) for TLS:
# Caddyfile example
kairos.example.com {
reverse_proxy localhost:8080
}
For detailed DEE protocol internals, install the hestia SkillSet and refer to its bundled knowledge (hestia_meeting_place).
Pure Skills Design
skills.md vs skills.rb
| Aspect | skills.md (Markdown) | skills.rb (Ruby DSL) |
|---|
| Nature | Description | Definition |
| Executability | ❌ Cannot be evaluated | ✅ Parseable, validatable |
| Self-Reference | None | Via Kairos module |
| Auditability | Git commits only | Native (AST-based diff) |
| AI Role | Reader | Part of the structure |
Example Skill Definition
skill :core_safety do
version "1.0"
title "Core Safety Rules"
guarantees do
immutable
always_enforced
end
evolve do
deny :all # Cannot be modified
end
content <<~MD
## Core Safety Invariants
1. Evolution requires explicit enablement
2. Human approval required by default
3. All changes create blockchain records
MD
end
Self-Referential Introspection
skill :self_inspection do
version "1.0"
behavior do
Kairos.skills.map do |skill|
{
id: skill.id,
version: skill.version,
can_evolve: skill.can_evolve?(:content)
}
end
end
end
DSL/AST Skill Formalization
KairosChain v2.1.0 introduces a partial formalization layer that bridges natural-language skill content and machine-verifiable structural definitions — without replacing human judgment or requiring LLM evaluation.
Motivation
Skill content (natural language in content blocks) and skill behavior (Ruby code in behavior blocks) are semantically rich but opaque to structural analysis. The formalization layer adds an explicit definition layer that captures constraints, plans, tool calls, and semantic reasoning nodes in a diffable, verifiable AST.
Three Layers of a Skill
┌─────────────────────────────────────────────────────────┐
│ Content Layer (natural language, human-readable) │
│ content <<~MD ... MD │
├─────────────────────────────────────────────────────────┤
│ Definition Layer (AST, machine-verifiable) │
│ definition do │
│ constraint :ethics_approval, required: true │
│ node :review, type: :SemanticReasoning │
│ end │
├─────────────────────────────────────────────────────────┤
│ Behavior Layer (Ruby code, executable) │
│ behavior do ... end │
└─────────────────────────────────────────────────────────┘
Node Types
| Node Type | Meaning | Machine-Verifiable? |
|---|
Constraint | Invariant that must hold | ✅ Structural check |
Check | Assertion to evaluate | ✅ Pattern-matched |
Plan | Sequence of named steps | ✅ Step presence |
ToolCall | MCP tool invocation | ✅ Command presence |
SemanticReasoning | Requires human/LLM judgment | ❌ Marked as human_required |
Example Definition Block
skill :core_safety do
version "3.0"
title "Core Safety Rules"
definition do
constraint :no_destructive_ops,
condition: "evolution_enabled == false",
description: "Destructive operations require explicit evolution mode"
constraint :human_approval_required,
condition: "require_human_approval == true",
description: "All evolution changes require human sign-off"
node :safety_review,
type: :SemanticReasoning,
prompt: "Does this change maintain core safety invariants?"
end
content <<~MD
## Core Safety Invariants
1. Evolution requires explicit enablement
2. Human approval required by default
MD
end
Formalization Tools
| Tool | Description |
|---|
definition_verify | Verify constraints against a context — reports satisfied/unknown/unsatisfied per node |
definition_decompile | Reconstruct human-readable Markdown from the AST |
definition_drift | Detect divergence between content and definition layers |
formalization_record | Record a formalization decision on-chain (provenance) |
formalization_history | Query past formalization decisions |
Source of Truth Policy
Ruby DSL (.rb) is the single authoritative source. JSON representations are derived outputs for transport (MCP, blockchain). The direction of truth is always:
Ruby DSL (.rb) → AstEngine → JSON → Blockchain record
↗
Decompiler (reverse, advisory only)
See docs/KairosChain_dsl_ast_source_of_truth_policy_20260225.md for the full policy.
SkillSet Plugin Architecture
SkillSets are modular, self-contained capability packages that extend KairosChain. They are managed by the SkillSetManager and follow layer-based governance.
SkillSet Structure
.kairos/skillsets/{name}/
├── skillset.json # Required: metadata and layer declaration
├── tools/ # MCP Tool classes (Ruby)
├── lib/ # Internal libraries
├── knowledge/ # Knowledge files (Markdown + YAML frontmatter)
├── config/ # Configuration templates
└── references/ # Reference materials
skillset.json Schema
{
"name": "my_skillset",
"version": "1.0.0",
"description": "Description of the SkillSet",
"author": "Author Name",
"layer": "L1",
"depends_on": [],
"provides": ["capability_name"],
"tool_classes": ["MyTool"],
"config_files": ["config/my_config.yml"],
"knowledge_dirs": ["knowledge/my_topic"]
}
Layer-Based Governance
| Layer | Blockchain Recording | Approval | Typical Use |
|---|
| L0 | Full (all file hashes) | Human approval required | Core protocols |
| L1 | Hash-only | Standard enable/disable | Standard SkillSets |
| L2 | None | Free enable/disable | Community/experimental |
MMP SkillSet (Model Meeting Protocol)
MMP is the reference SkillSet implementation that enables P2P communication between KairosChain instances.
Key classes:
MMP::Protocol — Core protocol logicMMP::Identity — Agent identity and introductionMMP::SkillExchange — Skill acquisition workflowMMP::PeerManager — Peer tracking with persistence and TOFU trustMMP::ProtocolLoader — Dynamic protocol loadingMMP::ProtocolEvolution — Protocol extension mechanismMeetingRouter — Rack-compatible HTTP router (11 endpoints)MMP::Crypto — RSA-2048 signature verification
Security features:
- Knowledge-only constraint: 14 executable extensions + shebang detection
- Name sanitization:
[a-zA-Z0-9][a-zA-Z0-9_-]*, max 64 chars
- Path traversal guard:
expand_path + start_with? verification
- Content hash verification: SHA-256 on package and install
- RSA signature verification with TOFU key caching
For detailed usage, see the MMP P2P User Guide.
Multiuser SkillSet (Multi-Tenant User Management)
Multiuser extends KairosChain with PostgreSQL-backed multi-tenant user management via 6 generic core hooks (Option C architecture).
Key classes:
Multiuser::PgConnectionPool — Mutex-based connection pool with tenant schema switchingMultiuser::PgBackend — Storage::Backend subclass for PostgreSQLMultiuser::TenantManager — Schema creation, SQL migrations, tenant lifecycleMultiuser::UserRegistry — User accounts with auto-tenant provisioningMultiuser::TenantTokenStore — PostgreSQL-backed token store (same API as file-based)Multiuser::AuthorizationGate — Default-deny RBAC gate for ToolRegistryMultiuser::RequestFilter — Tenant resolution from Bearer token context
Design principles:
- Option C (generic hooks): 6 minimal extension points in core, usable by any SkillSet
- Graceful degradation: Works without PostgreSQL — tools register and return diagnostics
- Backward-compatible: Without Multiuser installed, KairosChain is unchanged
- Schema isolation:
public (shared) + tenant_{id} (per-user) PostgreSQL schemas
Directory Structure
Gem Structure (installed via gem install kairos-chain)
kairos-chain (gem)
├── bin/
│ └── kairos-chain # Executable (in PATH after gem install)
├── lib/
│ ├── kairos_mcp.rb # Central module (data_dir management)
│ └── kairos_mcp/
│ ├── version.rb # Gem version
│ ├── initializer.rb # `init` command implementation
│ ├── server.rb # STDIO server
│ ├── http_server.rb # Streamable HTTP server (Puma/Rack)
│ ├── protocol.rb # JSON-RPC handler
│ └── ... # (same structure as repository)
├── templates/ # Default files copied on `init`
│ ├── skills/
│ │ ├── kairos.rb # Default L0 DSL
│ │ ├── kairos.md # Default L0 philosophy
│ │ └── config.yml # Default configuration
│ └── config/
│ ├── safety.yml # Default security settings
│ └── tool_metadata.yml # Default tool metadata
└── kairos-chain.gemspec # Gem specification
Data Directory (created by kairos-chain init)
.kairos/ # Default data directory (configurable)
├── skills/
│ ├── kairos.md # L0-A: Philosophy (read-only)
│ ├── kairos.rb # L0-B: Meta-rules (Ruby DSL)
│ ├── config.yml # Layer & evolution settings
│ └── versions/ # Version snapshots
├── knowledge/ # L1: Project Knowledge (Anthropic format)
│ └── example_knowledge/
│ ├── example_knowledge.md # YAML frontmatter + Markdown
│ ├── scripts/ # Executable scripts
│ ├── assets/ # Templates, resources
│ └── references/ # Reference materials
├── context/ # L2: Temporary Context (Anthropic format)
│ └── session_xxx/
│ └── hypothesis/
│ └── hypothesis.md
├── config/
│ ├── safety.yml # Security settings
│ └── tool_metadata.yml # Tool guide metadata
└── storage/
├── blockchain.json # Chain data (file mode)
├── kairos.db # SQLite database (sqlite mode)
├── embeddings/ # Vector search index (auto-generated)
└── snapshots/ # StateCommit snapshots
Repository Structure (cloned from GitHub)
KairosChain_mcp_server/
├── bin/
│ └── kairos-chain # Executable
├── lib/
│ ├── kairos_mcp.rb # Central module (data_dir management)
│ └── kairos_mcp/
│ ├── version.rb # Gem version
│ ├── initializer.rb # `init` command implementation
│ ├── server.rb # STDIO server
│ ├── http_server.rb # Streamable HTTP server (Puma/Rack)
│ ├── protocol.rb # JSON-RPC handler
│ ├── kairos.rb # Self-reference module
│ ├── safe_evolver.rb # Evolution with safety
│ ├── layer_registry.rb # Layered architecture management
│ ├── anthropic_skill_parser.rb # YAML frontmatter + MD parser
│ ├── knowledge_provider.rb # L1 knowledge management
│ ├── context_manager.rb # L2 context management
│ ├── admin/ # Admin UI (htmx + ERB)
│ │ ├── router.rb # Route matching and controllers
│ │ ├── helpers.rb # ERB helpers, session, CSRF
│ │ ├── views/ # ERB templates (layout, pages, partials)
│ │ └── static/ # CSS (PicoCSS overrides)
│ ├── auth/ # Authentication module
│ │ ├── token_store.rb # Token CRUD with SHA-256 hashing
│ │ └── authenticator.rb # Bearer token verification
│ ├── kairos_chain/ # Blockchain implementation
│ │ ├── block.rb
│ │ ├── chain.rb
│ │ ├── merkle_tree.rb
│ │ └── skill_transition.rb
│ ├── state_commit/ # StateCommit module
│ │ ├── manifest_builder.rb
│ │ ├── snapshot_manager.rb
│ │ ├── diff_calculator.rb
│ │ ├── pending_changes.rb
│ │ └── commit_service.rb
│ └── tools/ # MCP tools (25 core)
│ ├── skills_*.rb # L0 tools
│ ├── knowledge_*.rb # L1 tools
│ ├── context_*.rb # L2 tools
│ ├── state_*.rb # StateCommit tools
│ └── token_manage.rb # Token management (HTTP mode)
├── templates/ # Default files for `init` command
│ ├── skills/ # Default skill templates
│ └── config/ # Default config templates
├── kairos-chain.gemspec # Gem specification
├── Gemfile # Development dependencies
├── Rakefile # Build/test tasks
├── test_local.rb # Local test script
└── README.md
Multiuser: Multi-Tenant User Management
What is Multiuser?
Multiuser is an opt-in SkillSet that adds multi-tenant user management to KairosChain with PostgreSQL-backed storage, RBAC (Role-Based Access Control), and tenant isolation. Each user gets their own PostgreSQL schema, ensuring complete data separation between tenants.
Multiuser is implemented as a SkillSet with 6 minimal generic hooks into KairosChain core (Option C architecture), preserving the principle that new capabilities are expressed as SkillSets rather than hard-coded infrastructure. The core modifications are backward-compatible — without the Multiuser SkillSet installed, KairosChain behaves identically to before.
Architecture
KairosChain (MCP Server)
├── [core] L0/L1/L2 + private blockchain
│ ├── Backend.register() ← Hook 1: Storage backend factory
│ ├── Safety.register_policy() ← Hook 2: RBAC policy injection
│ ├── ToolRegistry.register_gate()← Hook 3: Authorization gate
│ ├── Protocol.register_filter() ← Hook 4: Request filter pipeline
│ ├── TokenStore.register() ← Hook 5: Token store factory
│ └── KairosMcp.register_path_resolver() ← Hook 6: Tenant path resolution
└── [SkillSet: multiuser] Multi-tenant user management
├── PgConnectionPool ← Mutex-based PostgreSQL connection pool
├── PgBackend ← Storage::Backend implementation for PostgreSQL
├── TenantManager ← Schema creation, migrations, tenant lifecycle
├── UserRegistry ← User accounts with auto-tenant provisioning
├── TenantTokenStore ← PostgreSQL-backed token store
├── AuthorizationGate ← Default-deny RBAC enforcement
├── RequestFilter ← Tenant resolution from Bearer token
└── tools/ ← 3 MCP tools
Prerequisites
- PostgreSQL server (installed and running)
- pg gem:
gem install pg (requires libpq — PostgreSQL client library)
On macOS with Homebrew:
brew install postgresql@16
brew services start postgresql@16
gem install pg
Quick Start
1. Install the Multiuser SkillSet
kairos-chain skillset install templates/skillsets/multiuser
2. Configure PostgreSQL connection
Edit .kairos/skillsets/multiuser/config/multiuser.yml:
postgresql:
host: 127.0.0.1
port: 5432
dbname: kairoschain
user: postgres
password: ""
pool_size: 5
connect_timeout: 5
token_backend: postgresql
3. Create the database and run migrations
createdb kairoschain
Then via MCP:
"Run multiuser migrations"
→ multiuser_migrate(command: "run")
4. Create the first user
"Create an owner user named admin"
→ multiuser_user_manage(command: "create", username: "admin", role: "owner")
5. Check status
"Check multiuser status"
→ multiuser_status()
MCP Tools
| Tool | Description |
|---|
multiuser_status | Diagnostic report: PostgreSQL connection, tenant count, user count |
multiuser_user_manage | User lifecycle: list, create, delete, update_role |
multiuser_migrate | Database migrations: status, run, dry_run |
Core Hooks (Option C: Generic Hooks)
The Multiuser SkillSet registers 6 hooks into KairosChain core. These hooks are minimal, generic extension points — any SkillSet can use them, not just Multiuser.
| Hook | Core Class | Purpose |
|---|
| 1 | Storage::Backend.register | Register PgBackend as the 'postgresql' storage backend |
| 2 | Safety.register_policy | Inject RBAC policies for can_modify_l0, can_modify_l1, can_modify_l2, can_manage_tokens |
| 3 | ToolRegistry.register_gate | Authorization gate — default-deny check before every tool call |
| 4 | Protocol.register_filter | Tenant resolution from Bearer token in incoming requests |
| 5 | Auth::TokenStore.register | Register TenantTokenStore as the 'postgresql' token backend |
| 6 | KairosMcp.register_path_resolver | Resolve knowledge/ and context/ paths per tenant |
All hooks support unregister for clean teardown.
RBAC (Role-Based Access Control)
| Role | L0 (Core) | L1 (Knowledge) | L2 (Context) | Token Management |
|---|
| owner | Read/Write | Read/Write | Read/Write | Full access |
| member | Read only | Read/Write | Read/Write | No access |
| guest | Read only | Read only | Read/Write | No access |
Graceful Degradation
Multiuser is designed to degrade gracefully at each level:
| Condition | Behavior |
|---|
| pg gem not installed | multiuser_status returns pg_gem_missing with install instructions |
| PostgreSQL not running | multiuser_status returns pg_server_unavailable with setup guidance |
| PostgreSQL config error | multiuser_status returns pg_error with config file reference |
| Any unexpected error | Caught by rescue StandardError, logged with full context |
In all cases, the 3 Multiuser MCP tools remain registered and callable — they return diagnostic information instead of crashing. All other KairosChain tools (34 core tools) continue to function normally.
Configuration
Configuration file: .kairos/skillsets/multiuser/config/multiuser.yml
postgresql:
host: 127.0.0.1 # PostgreSQL host
port: 5432 # PostgreSQL port
dbname: kairoschain # Database name
user: postgres # Database user
password: "" # Database password
pool_size: 5 # Connection pool size
connect_timeout: 5 # Connection timeout (seconds)
token_backend: postgresql # Token storage backend
Database schema uses public for shared tables (users, tokens, audit log) and tenant_{id} schemas for per-user data (blocks, action_logs, knowledge_meta).
Service Grant SkillSet
Service Grant provides generic, service-independent access control and billing for any KairosChain-based service. It manages "what is permitted" for authenticated agents without managing identity (identity = RSA key pair via MMP).
Key Concepts
- pubkey_hash: SHA-256 hash of agent's public key — this IS the identity
- Grant: Per-(pubkey_hash, service) entry with plan, status, and usage
- Plan: Quota/billing configuration (free, pro, etc.) defined in YAML
- Dual-path enforcement: Both
/mcp (AccessGate) and /place/* (PlaceMiddleware) are gated
Architecture
Path A (/mcp): Token -> pubkey_hash -> AccessGate -> AccessChecker
Path B (/place): Bearer -> peer_id -> PlaceMiddleware -> AccessChecker
AccessChecker pipeline:
suspension -> cooldown -> expiry -> trust -> quota
Components
| Component | Responsibility |
|---|
| GrantManager | Grant lifecycle (create, upgrade, suspend, downgrade) |
| AccessChecker | Unified access decision pipeline |
| UsageTracker | Atomic quota consumption with cycle management |
| PlanRegistry | YAML config loader with validation |
| PaymentVerifier | Cryptographic payment attestation verification |
| PgConnectionPool | Thread-safe PostgreSQL with circuit breaker |
| TrustScorerAdapter | Synoptis trust score integration with caching |
Billing Models
billing_model: free # No charges
billing_model: per_action # Pay per API call
billing_model: metered # Usage-based with cycle tracking
billing_model: subscription # Time-based with auto-expiry
Payment Flow (Proof-Centric)
Payment Agent (external) creates attestation proof
-> PaymentVerifier verifies: signature, issuer, freshness, amount, nonce
-> Atomic transaction: ensure_grant + upgrade_plan + record_payment
-> Subscription expiry auto-managed (lazy downgrade on access check)
Payment verification uses Synoptis ProofEnvelope — the same cryptographic attestation infrastructure used for trust scoring.
Anti-Sybil Measures
- IP rate limiting (5 new grants/hour per IP, PostgreSQL-backed)
- Delayed activation cooldown (5 min for write operations)
- Synoptis trust score requirements (configurable per action)
- Anti-collusion PageRank with external attestation weighting
MCP Tools
| Tool | Access | Description |
|---|
service_grant_status | All users | View grants and usage |
service_grant_manage | Owner only | Plan changes, suspend/unsuspend |
service_grant_migrate | Owner only | Database schema migrations |
service_grant_pay | All users | Submit payment attestation proofs |
Configuration Example
services:
meeting_place:
billing_model: per_action
currency: USD
cycle: monthly
write_actions: [deposit_skill]
action_map:
meeting_deposit: deposit_skill
meeting_browse: browse
plans:
free:
limits:
deposit_skill: 5
browse: -1 # unlimited
trust_requirements:
deposit_skill: 0.1
pro:
subscription_price: "9.99"
subscription_duration: 30 # days
limits:
deposit_skill: -1
browse: -1
Dependencies
- Hard: PostgreSQL (grants, usage, payments)
- Hard: Synoptis SkillSet (attestation verification, trust scoring)
- Soft: Hestia SkillSet (Meeting Place middleware integration)
Synoptis: Mutual Attestation Protocol (v3.5.0)
What is Synoptis?
Synoptis is an opt-in SkillSet for cross-agent trust verification through cryptographically signed attestation proofs. It enables agents to attest to facts about any subject (knowledge entries, skill hashes, chain blocks, pipeline outputs, etc.), and provides mechanisms to verify, revoke, and challenge those attestations.
Synoptis is implemented entirely as a SkillSet, preserving KairosChain's principle that new capabilities are expressed as SkillSets rather than core modifications.
Architecture
KairosChain (MCP Server)
├── [core] L0/L1/L2 + private blockchain
├── [SkillSet: mmp] P2P direct mode, /meeting/v1/*
├── [SkillSet: hestia] Meeting Place + trust anchor
└── [SkillSet: synoptis] Mutual attestation protocol
├── ProofEnvelope ← Signed attestation data structure
├── Verifier ← Structural + cryptographic verification
├── AttestationEngine ← Attestation lifecycle (create, verify, list)
├── RevocationManager ← Revocation with authorization checks
├── ChallengeManager ← Challenge/response lifecycle
├── TrustScorer ← Weighted trust score (local + Meeting Place)
├── MeetingTrustAdapter ← Meeting Place data fetching + cache (v2)
├── TrustIdentity ← Canonical agent identity resolution
├── Registry::FileRegistry ← Append-only JSONL with hash-chain integrity
├── Transport ← MMP / Hestia / Local transport abstraction
└── tools/ ← 7 MCP tools
Quick Start
1. Install the synoptis SkillSet
# Synoptis depends on MMP. Install both:
kairos-chain skillset install templates/skillsets/mmp
kairos-chain skillset install templates/skillsets/synoptis
2. Issue an attestation
In Claude Code / Cursor:
"Attest that knowledge/my_skill has been integrity_verified"
This calls attestation_issue(subject_ref: "knowledge/my_skill", claim: "integrity_verified").
3. Verify and query trust
"What is the trust score for knowledge/my_skill?"
This calls trust_query(subject_ref: "knowledge/my_skill").
4. Query Meeting Place skill trust (v2)
"What is the trust score for agent_skill_evolution_guide on the Meeting Place?"
This calls trust_query(subject_ref: "meeting:agent_skill_evolution_guide").
MCP Tools
| Tool | Description |
|---|
attestation_issue | Issue a signed attestation proof for a subject |
attestation_verify | Verify proof validity (structure, signature, expiry, revocation) |
attestation_revoke | Revoke an attestation (original attester or admin only) |
attestation_list | List attestations with optional filters (subject_ref, attester_id) |
trust_query | Calculate trust score (local, Meeting Place skills, or depositor trust) |
challenge_create | Challenge an existing attestation (validity, evidence_request, re_verification) |
challenge_respond | Respond to a challenge with additional evidence |
MMP Integration
Synoptis registers 5 MMP actions via MMP::Protocol.register_handler, enabling P2P attestation exchange:
| MMP Action | Description |
|---|
attestation_request | Request an attestation from a peer |
attestation_response | Respond with a signed ProofEnvelope |
attestation_revoke | Broadcast a revocation |
challenge_create | Send a challenge to the original attester |
challenge_respond | Respond to a challenge over MMP |
All P2P messages use Bearer token authentication via MMP::PeerManager. The authenticated peer ID is injected by MeetingRouter as _authenticated_peer_id.
Trust Scoring
Local Trust (v1)
Trust scores for local attestations are calculated as a weighted composite:
| Factor | Weight | Description |
|---|
| Quality | 0.25 | PageRank-weighted attestation quality (with anti-collusion) |
| Freshness | 0.20 | Recency of latest attestation (30-day decay) |
| Diversity | 0.20 | Number of unique attesters (capped at 10) |
| Velocity | 0.10 | Attestation rate |
| Bridge | 0.15 | Cross-cluster trust (SCC-based external attester ratio) |
| Revocation penalty | -0.10 | Penalty for revoked attestations |
Anti-collusion mechanisms: PageRank-weighted quality, SCC detection, bootstrap policy (zero influence without external attestation), bridge scoring.
Meeting Place Trust (v2)
Core principle: Meeting Place provides raw facts. Trust computation is always a local cognitive act.
Trust scores for Meeting Place skills use a 2-layer model:
Layer 1 — Skill Trust (per skill, from browse/preview data):
| Factor | Weight | Description |
|---|
| Attestation quality | 0.50 | Anti-collusion discounted (self: 0.15x, unsigned: 0.6x) |
| Usage | 0.20 | Exchange count, remote-discounted (0.5x) |
| Freshness | 0.15 | 180-day linear decay, floor at 0.2 |
| Provenance | 0.15 | Direct deposit = 1.0, -0.2 per hop |
Layer 2 — Depositor Trust (per agent, from portfolio analysis):
| Factor | Weight | Description |
|---|
| Avg skill trust | 0.40 | Portfolio average with shrinkage for small portfolios |
| Attestation breadth | 0.25 | Total third-party attestations across all skills |
| Diversity | 0.25 | Unique third-party attesters |
| Activity | 0.10 | Deposit count |
Combined Score — smooth interpolation (no discontinuity):
- New skills (low skill trust): 35% skill + 65% depositor (lean on reputation)
- Established skills (high skill trust): 70% skill + 30% depositor (stand on own evidence)
URI routing:
| Subject ref | Query type |
|---|
meeting:<skill_id> | Skill trust + depositor trust → combined score |
meeting_agent:<agent_id> | Depositor trust only |
skill://local_ref | Local trust (v1, unchanged) |
All weights are configurable via trust_v2: section in synoptis.yml.
Registry and Constitutive Recording
All attestation data is stored in append-only JSONL files with hash-chain linking (_prev_entry_hash). This implements constitutive recording (Proposition 5): each record irreversibly extends the system's history.
Registry types:
proofs.jsonl — Attestation proof envelopesrevocations.jsonl — Revocation recordschallenges.jsonl — Challenge and response records
Use trust_query to verify registry integrity — it includes a registry_integrity.valid field in its response.
ProofEnvelope Structure
{
"proof_id": "uuid",
"attester_id": "agent_instance_id",
"subject_ref": "knowledge/my_skill",
"claim": "integrity_verified",
"evidence": "manual review of hash chain",
"merkle_root": "sha256_of_content",
"content_hash": "sha256_of_canonical_json",
"signature": "rsa_sha256_signature",
"timestamp": "2026-03-06T12:00:00Z",
"ttl": 86400,
"version": "1.0.0"
}
Challenge Workflow
- Any agent can call
challenge_create(proof_id, challenge_type, details) to challenge an attestation
- The original attester receives the challenge (via MMP or local notification)
- The attester calls
challenge_respond(challenge_id, response, evidence) with additional evidence
- Challenge types:
validity (proof may be incorrect), evidence_request (more evidence needed), re_verification (conditions may have changed)
Transport Layer
Synoptis supports multiple transport mechanisms:
| Transport | Backend | Use Case |
|---|
| MMP | MMP::PeerManager | P2P direct attestation exchange |
| Hestia | Hestia::PlaceRouter | Via Meeting Place (future) |
| Local | Direct registry access | Single-instance and Multiuser mode |
Transport selection is automatic based on available SkillSets.
Dependencies
- Required: MMP SkillSet (>= 1.0.0)
- Optional: Hestia SkillSet (for Meeting Place transport and Meeting Place trust)
For the full protocol specification, install the synoptis SkillSet and refer to its bundled knowledge (synoptis_protocol).
Future Roadmap
Completed Phases
The following development phases have been completed on the feature/skillset-plugin branch:
| Phase | Description | Key Deliverables |
|---|
| Phase 1 | SkillSet Plugin Infrastructure | SkillSetManager, ToolRegistry extension, CLI subcommands, layer-based governance |
| Phase 2 | MMP as SkillSet + P2P Direct Mode | MMP packaged as standalone SkillSet, MeetingRouter with 8 HTTP endpoints, 4 MCP tools |
| Phase 2.5 | P2P Local Tests | 72 assertions across 4 test sections |
| Phase 3 | Knowledge-only SkillSet Exchange | knowledge_only?/exchangeable? checks, tar.gz archive packaging, 3 new SkillSet endpoints |
| Phase 3.5 | Security Fixes + Wire Protocol Spec | Name sanitization (H4), path traversal guard (H1), extended executable detection (H5), wire protocol specification |
| Phase 3.7 | Pre-Phase 4 Hardening | RSA-2048 signature verification, semantic version constraints, PeerManager persistence, TOFU trust model |
| Phase 3.75 | MMP Extension Infrastructure | Collision detection for core actions, extension override guards, pre-Phase 4 preparation |
| Phase 4.pre | Authentication + Hardening | Admin token rotation, session-based auth for P2P endpoints |
| Phase 4A | HestiaChain Foundation | Self-contained trust anchor SkillSet, DEE protocol (PhilosophyDeclaration, ObservationLog), chain migration (4 stages), 4 MCP tools, 77 test assertions |
| Phase 4B | Meeting Place Server | PlaceRouter, AgentRegistry, SkillBoard, HeartbeatManager, 6 HTTP endpoints, 2 MCP tools, 70 test assertions |
| v2.3.0 | Tutorial Mode + Proactive Tools | Behavioral gradient instruction mode, existing project fast-track, Knowledge Acquisition Policy |
| v2.4.0 | Dynamic Persona Suggestion | 2-step suggest→assembly workflow, custom persona names, improved unknown persona handling |
| v2.5.0 | Cross-Instance Knowledge Discovery | SkillBoard knowledge needs, meeting_publish_needs tool, export_needs audit command, DEE-compliant session-only needs |
Test results: 356+ passed, 0 failed (v2.5.0).
Near-term
- Phase 4C: Message Relay: E2E encrypted message relay with TTL (
/place/v1/relay/*)
- Phase 4D: Federation: Inter-Place discovery and mutual registration
- Ethereum Anchor: Periodic hash anchoring to public chain (HestiaChain stages 2/3)
- Zero-Knowledge Proofs: Privacy-preserving verification
- Web Dashboard: Visualize skill evolution history
- Team Governance: Voting system for L0 changes (see FAQ)
Long-term Vision: Distributed KairosChain Network
A future vision for KairosChain: multiple KairosChain MCP servers communicating over the internet via public MCP protocols, autonomously evolving their knowledge while adhering to their L0 constitutions.
Key concepts:
- L0 Constitution as distributed governance
- Knowledge cross-pollination between specialized nodes
- Autonomous evolution within constitutional bounds
- Integration with GenomicsChain PoC/DAO
Implementation phases:
- Dockerization (deployment foundation)
HTTP/WebSocket API (remote access) ✅ Streamable HTTP transport (complete)Inter-server communication protocol ✅ MMP (Model Meeting Protocol) with P2P direct mode (complete)SkillSet Plugin Infrastructure ✅ Layer-based governance, knowledge-only P2P exchange (complete)HestiaChain Meeting Place Server ✅ Trust anchor + DEE protocol Meeting Place (complete, v2.0.0)- Distributed consensus mechanism
- Distributed L0 governance
For detailed vision document, see: Distributed KairosChain Network Vision
Deployment and Operation
Data Storage Overview
KairosChain stores data in the following locations:
| Directory | Contents | Git Tracked | Importance |
|---|
skills/kairos.rb | L0 DSL (evolvable) | Yes | High |
skills/kairos.md | L0 Philosophy (immutable) | Yes | High |
skills/config.yml | Configuration | Yes | High |
skills/versions/ | DSL snapshots | Yes | Medium |
knowledge/ | L1 project knowledge | Yes | High |
context/ | L2 temporary context | Yes | Low |
storage/blockchain.json | Blockchain data | Yes | High |
storage/embeddings/*.ann | Vector index (auto-generated) | No | Low |
storage/snapshots/ | StateCommit snapshots (off-chain) | No | Medium |
skills/action_log.jsonl | Action log | No | Low |
Blockchain Storage Format
The private blockchain is stored as a JSON flat file at storage/blockchain.json:
[
{
"index": 0,
"timestamp": "1970-01-01T00:00:00.000000Z",
"data": ["Genesis Block"],
"previous_hash": "0000...0000",
"merkle_root": "0000...0000",
"hash": "a1b2c3..."
},
{
"index": 1,
"timestamp": "2026-01-20T10:30:00.123456Z",
"data": ["{\"type\":\"skill_evolution\",\"skill_id\":\"...\"}"],
"previous_hash": "a1b2c3...",
"merkle_root": "xyz...",
"hash": "789..."
}
]
Why JSON flat file?
- Simplicity: No external dependencies
- Readability: Human-inspectable for auditing
- Portability: Copy to backup/migrate
- Philosophy alignment: Auditability is core to Kairos
Recommended Operation Patterns
Pattern 1: Fork + Private Repository (Recommended)
Fork KairosChain and keep it as a private repository. This is the simplest approach.
┌─────────────────────────────────────────────────────────────────┐
│ GitHub │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ KairosChain (public)│───▶│ your-fork (private) │ │
│ │ - code updates │ │ - skills/ │ │
│ └─────────────────────┘ │ - knowledge/ │ │
│ │ - storage/ │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Pros: Simple, everything in one place, full backup
Cons: May conflict when pulling upstream updates
Setup:
# Fork on GitHub, then clone your private fork
git clone https://github.com/YOUR_USERNAME/KairosChain_2026.git
cd KairosChain_2026
# Add upstream for updates
git remote add upstream https://github.com/masaomi/KairosChain_2026.git
# Pull upstream updates (when needed)
git fetch upstream
git merge upstream/main
Pattern 2: Data Directory Separation
Keep KairosChain code and data in separate repositories.
┌─────────────────────────────────────────────────────────────────┐
│ Two repositories │
│ │
│ ┌────────────────────┐ ┌─────────────────────────────┐ │
│ │ KairosChain (public│ │ my-kairos-data (private) │ │
│ │ - lib/ │ │ - skills/ │ │
│ │ - bin/ │ │ - knowledge/ │ │
│ │ - config/ │ │ - context/ │ │
│ └────────────────────┘ │ - storage/ │ │
│ └─────────────────────────────┘ │
│ │
│ Link via symlinks: │
│ $ ln -s ~/my-kairos-data/skills ./skills │
│ $ ln -s ~/my-kairos-data/knowledge ./knowledge │
│ $ ln -s ~/my-kairos-data/storage ./storage │
└─────────────────────────────────────────────────────────────────┘
Pros: Easy to pull upstream updates, clean separation
Cons: Requires symlink setup, two repos to manage
Pattern 3: Cloud Sync (Non-Git)
Sync data directories with cloud storage (Dropbox, iCloud, Google Drive).
# Example: Symlink to Dropbox
ln -s ~/Dropbox/KairosChain/skills ./skills
ln -s ~/Dropbox/KairosChain/knowledge ./knowledge
ln -s ~/Dropbox/KairosChain/storage ./storage
Pros: Automatic sync, no Git knowledge required
Cons: Weak version control, conflict resolution is harder
Backup Strategy
Regular Backups
# Create backup script
#!/bin/bash
BACKUP_DIR=~/kairos-backups/$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR
# Backup critical data
cp -r skills/ $BACKUP_DIR/
cp -r knowledge/ $BACKUP_DIR/
cp -r storage/ $BACKUP_DIR/
# Cleanup old backups (older than 30 days)
find ~/kairos-backups -mtime +30 -type d -exec rm -rf {} +
echo "Backup created: $BACKUP_DIR"
What to Back Up
| Priority | Directory | Reason |
|---|
| Critical | storage/blockchain.json | Immutable evolution history |
| Critical | skills/kairos.rb | L0 meta-rules |
| High | knowledge/ | Project knowledge |
| Medium | skills/versions/ | Evolution snapshots |
| Low | context/ | Temporary (can be recreated) |
| Skip | storage/embeddings/ | Auto-regenerated |
Verification After Restore
# After restoring from backup, verify integrity
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"chain_verify","arguments":{}}}' | kairos-chain
Documentation Management
README.md and README_jp.md are auto-generated from L1 knowledge files. Do not edit them directly.
Single Source of Truth
The documentation content lives in L1 knowledge files under KairosChain_mcp_server/knowledge/:
| L1 Knowledge | Contents |
|---|
kairoschain_philosophy / _jp | Philosophy, architecture, layered design |
kairoschain_setup / _jp | Installation, configuration, testing |
kairoschain_usage / _jp | Tools reference, usage patterns |
kairoschain_design / _jp | Pure Skills design, directory structure |
kairoschain_operations / _jp | Roadmap, deployment, operations |
kairoschain_faq / _jp | FAQ, subtree integration |
Header/footer templates are in scripts/readme_templates/.
Updating Documentation
- Edit the relevant L1 knowledge file in
KairosChain_mcp_server/knowledge/
- Regenerate READMEs:
# Generate README.md and README_jp.md from L1 knowledge
rake build_readme
# Or run the script directly
ruby scripts/build_readme.rb
- Commit both the L1 knowledge change and the regenerated README
Other Commands
# Check if READMEs are up to date (useful in CI)
rake check_readme
# Preview what would be generated without writing files
rake preview_readme
# Show help and options
ruby scripts/build_readme.rb --help
Why Auto-Generated?
- Single Source of Truth: L1 knowledge is the only place to edit documentation
- MCP Accessible: LLMs can query documentation via
knowledge_get / knowledge_list
- Auditable: Documentation changes are tracked as L1 knowledge updates (hash recorded on blockchain)
- Semantic Search: RAG-enabled search across all documentation via MCP
KairosChain Self-Development Workflow
KairosChain's own development uses KairosChain as its knowledge management layer.
This realizes structural self-referentiality (Proposition 7) at the development process level:
designing the system becomes an operation within the system.
Setup
Initialize a .kairos/ data directory in the project root:
cd KairosChain_2026
kairos-chain init
.kairos/ is already listed in .gitignore — runtime data stays local,
while validated knowledge is promoted into the codebase via explicit commits.
The Development Cycle
┌─────────────────────────────────────────────────┐
│ 1. Develop with KairosChain │
│ - context_save (L2) for session work │
│ - knowledge_update (L1) for discoveries │
│ - skills_evolve (L0) for meta-rule changes │
│ │
│ 2. Promote to codebase │
│ - Copy validated skills/knowledge from │
│ .kairos/ to KairosChain_mcp_server/ │
│ - Edit core code directly when needed │
│ - git commit │
│ │
│ 3. Reconstitute │
│ - rake install (build + install) │
│ - kairos-chain upgrade │
│ - .kairos/ is updated with new templates │
│ │
│ (Loop: the upgraded system is used in step 1) │
└─────────────────────────────────────────────────┘
Each commit is a Kairotic moment (Proposition 5): the system irreversibly
reconstitutes itself with knowledge discovered through its own use.
Promotion Targets
When copying from .kairos/ to the codebase, choose the correct destination:
| Source in .kairos/ | Destination | Effect |
|---|
knowledge/{name}/ | templates/knowledge/{name}/ | Distributed to all users via kairos-chain init |
knowledge/{name}/ | knowledge/{name}/ | Available in dev repo only |
skills/kairos.rb changes | templates/skills/kairos.rb | Changes default L0 for all users |
skillsets/{name}/ | templates/skillsets/{name}/ | New SkillSet available to all users |
For new patterns, start with knowledge/ (dev-only). Promote to templates/
after the pattern has proven its value across multiple development cycles.
Ordering Constraints
When a discovered pattern changes kairos-chain init or upgrade behavior itself:
- Edit core code in
lib/ directly (not via .kairos/)
- Run tests:
rake test
- Commit and rebuild gem
kairos-chain upgrade to apply changes to .kairos/
This avoids the chicken-and-egg problem where the tool you're upgrading
is the tool performing the upgrade.
Philosophical Grounding
This workflow is a direct realization of several core propositions:
- Proposition 5 (Constitutive Recording): Each commit constitutes
a new version of the system's being, not merely documents it.
- Proposition 6 (Incompleteness as Driving Force): Using KairosChain
to develop itself inevitably reveals gaps — these gaps drive evolution.
- Proposition 7 (Design-Implementation Closure): The design act
(using KairosChain) and the implementation act (coding KairosChain)
occur within the same operational structure.
- Proposition 9 (Human-System Composite): The developer's metacognitive
observations during self-referential use constitute the system's boundary.
Instruction Mode: self_developer
A custom instruction mode (self_developer) is available for KairosChain development.
It extends the developer mode with self-development-specific behavior:
- Automatically loads
kairoschain_self_development knowledge at session start
- References full L0 philosophy (
kairos.md) via proactive tool usage
- Includes promotion guidelines and ordering constraints
Activate it via:
instructions_update(command: "set_mode", mode_name: "self_developer")
To revert to the standard developer mode:
instructions_update(command: "set_mode", mode_name: "developer")
Future: Collaborative Self-Development
When multiple contributors join KairosChain development, the following
evolution is planned:
- Promote
self_developer mode to templates: Move self_developer.md
to templates/skills/ so it is distributed via kairos-chain init
- Replace the current
developer mode: Rename self_developer to
developer, making the self-referential workflow the default for all
KairosChain contributors
- Promote this knowledge to templates: Move
kairoschain_self_development
to templates/knowledge/ for distribution
This follows the standard promotion pattern: start in the dev repo (knowledge/),
prove value through use, then promote to templates/ for all users.
SkillSet Release Checklist
When a new SkillSet is implemented and tested, follow this checklist to release:
1. L1 Knowledge for README
Create L1 knowledge files (EN + JP) with readme_order and readme_lang
frontmatter so the SkillSet appears in the auto-generated README:
KairosChain_mcp_server/knowledge/{skillset_name}/
{skillset_name}.md # readme_order: N, readme_lang: en
KairosChain_mcp_server/knowledge/{skillset_name}_jp/
{skillset_name}_jp.md # readme_order: N, readme_lang: jp
Copy to templates for distribution:
KairosChain_mcp_server/templates/knowledge/{skillset_name}/
KairosChain_mcp_server/templates/knowledge/{skillset_name}_jp/
2. Regenerate README
ruby scripts/build_readme.rb # or: rake build_readme
ruby scripts/build_readme.rb --check # verify up-to-date
This reads all L1 knowledge files with readme_order/readme_lang frontmatter,
combines them with header/footer templates, and generates README.md + README_jp.md
at the project root.
3. Version and Changelog
- Bump version in
lib/kairos_mcp/version.rb
- Add entry to
CHANGELOG.md (follow existing format)
- Commit all changes — the working tree must be clean before the next step.
The tag is created by
rake release; do not tag by hand.
4. Gem Build and Publish
cd KairosChain_mcp_server
rake install # build into pkg/ and install locally, for testing
rake release # guard_clean -> tag v{VERSION} -> git push -> rubygems push
rake release aborts on a dirty working tree, and that check is the point.
gem build packs whatever is on disk at that moment, regardless of what is
committed, because the gemspec globs the filesystem rather than reading
git ls-files. Building from a dirty tree therefore publishes a gem that
corresponds to no commit — which is what happened to 3.57.0, and it stayed
invisible until the published gem was unpacked and compared against the
repository. Do not substitute gem build + gem push: neither carries the
check.
Note that rake writes the built gem to pkg/, not to the directory root
where gem build put it.
This checklist should be proposed automatically by the AI assistant in
self_developer mode when a SkillSet implementation is complete and tested.
What This Is Not
- Not a requirement to use KairosChain for all development tasks.
Use standard tools when they are simpler.
- Not a closed loop. External substrates (Ruby VM, git, gem infrastructure)
remain outside the self-referential boundary. This is intentional
("sufficient self-referentiality", Proposition 1).
FAQ
Q: Can LLMs automatically modify L1/L2?
A: Yes, LLMs can modify L1/L2 autonomously (or upon user request) using MCP tools.
| Layer | LLM Modification | Conditions |
|---|
| L0 (kairos.rb) | Possible but strict | evolution_enabled: true + approved: true (human approval) + blockchain record |
| L1 (knowledge/) | Possible | Hash-only blockchain record, no human approval required |
| L2 (context/) | Free | No per-operation record, no approval required |
Note: kairos.md is read-only and cannot be modified by LLMs.
StateCommit addendum: Regardless of per-operation recording, StateCommit can capture all layers (including L2) at commit points. Snapshots are stored off-chain; only hash references are recorded on-chain.
Usage Examples:
- L2: Temporarily save hypotheses during research with
context_save
- L1: Persist project coding conventions with
knowledge_update
- L0: Propose meta-skill changes with
skills_evolve (human approval required)
Q: How do I decide which layer to store knowledge in?
A: Use the built-in layer_placement_guide knowledge (L1) for guidance. Here's a quick decision tree:
1. Does this modify Kairos's own rules or constraints?
→ YES: L0 (requires human approval)
→ NO: Continue
2. Is this temporary or session-specific?
→ YES: L2 (freely modifiable, no per-operation recording; can be captured by StateCommit)
→ NO: Continue
3. Will this be reused across multiple sessions?
→ YES: L1 (hash reference recorded)
→ NO: L2
Key principle: When in doubt, start with L2 and promote later.
| Layer | Purpose | Typical Content |
|---|
| L0 | Kairos meta-rules | Safety constraints, evolution rules |
| L1 | Project knowledge | Coding conventions, architecture docs |
| L2 | Temporary work | Hypotheses, session notes, experiments |
Promotion pattern: Knowledge can move up as it matures: L2 → L1 → L0
For detailed guidance, use: knowledge_get name="layer_placement_guide"
Q: How do I maintain L1 knowledge health? How do I prevent L1 bloat?
A: Use the l1_health_guide knowledge (L1) and the skills_audit tool for periodic maintenance.
Key Thresholds:
| Condition | Threshold | Action |
|---|
| Review recommended | 180 days without update | Run skills_audit check |
| Archive candidate | 270 days without update | Consider archiving |
| Dangerous patterns | Detected | Update or archive immediately |
Recommended Audit Schedule:
| Frequency | Commands |
|---|
| Monthly | skills_audit command="check" layer="L1" |
| Monthly | skills_audit command="recommend" layer="L1" |
| Quarterly | skills_audit command="conflicts" layer="L1" |
| On issues | skills_audit command="dangerous" layer="L1" |
Self-Check Checklist (from l1_health_guide):
Archive Process:
# Review knowledge
knowledge_get name="candidate_knowledge"
# Archive with approval
skills_audit command="archive" target="candidate_knowledge" reason="Project completed" approved=true
For detailed guidelines, use: knowledge_get name="l1_health_guide"
Q: What is Persona Assembly and when should I use it?
A: Persona Assembly is an optional feature that provides multi-perspective evaluation when promoting knowledge between layers or auditing knowledge health. It helps surface different viewpoints before human decision-making.
Assembly Modes:
| Mode | Description | Token Cost | Use Case |
|---|
oneshot (default) | Single-round evaluation by all personas | ~500 + 300×N | Routine decisions, quick feedback |
discussion | Multi-round facilitated debate | ~500 + 300×N×R + 200×R | Important decisions, deep analysis |
N = number of personas, R = number of rounds (default max: 3)
When to use each mode:
| Scenario | Recommended Mode |
|---|
| L2 → L1 promotion | oneshot |
| L1 → L0 promotion | discussion |
| Archive decision | oneshot |
| Conflict resolution | discussion |
| Quick validation | oneshot (kairos only) |
| High-stakes decision | discussion (all personas) |
Available personas:
| Persona | Role | Bias |
|---|
kairos | Philosophy Advocate / Default Facilitator | Auditability, constraint preservation |
conservative | Stability Guardian | Prefers lower-commitment layers |
radical | Innovation Advocate | Favors action, accepts higher risk |
pragmatic | Cost-Benefit Analyst | Implementation complexity vs. value |
optimistic | Opportunity Seeker | Focuses on potential benefits |
skeptic | Risk Identifier | Looks for problems and edge cases |
archivist | Knowledge Curator | Knowledge freshness, redundancy |
guardian | Safety Watchdog | L0 alignment, security risks |
promoter | Promotion Scout | Identifies promotion candidates |
Usage:
# Oneshot mode (default) - single evaluation
skills_promote command="analyze" source_name="my_knowledge" from_layer="L1" to_layer="L0" personas=["kairos", "conservative", "skeptic"]
# Discussion mode - multi-round with facilitator
skills_promote command="analyze" source_name="my_knowledge" from_layer="L1" to_layer="L0" \
assembly_mode="discussion" facilitator="kairos" max_rounds=3 consensus_threshold=0.6 \
personas=["kairos", "conservative", "radical", "skeptic"]
# With skills_audit
skills_audit command="check" with_assembly=true assembly_mode="oneshot"
skills_audit command="check" with_assembly=true assembly_mode="discussion" facilitator="kairos"
# Direct promotion without assembly
skills_promote command="promote" source_name="my_context" from_layer="L2" to_layer="L1" session_id="xxx"
Discussion mode workflow:
Round 1: Each persona states position (SUPPORT/OPPOSE/NEUTRAL)
↓
Facilitator: Summarizes agreements/disagreements, identifies concerns
↓
Round 2-N: Personas respond to concerns (if consensus < threshold)
↓
Final Summary: Consensus status, recommendation, key resolutions
Configuration defaults (from audit_rules L0 skill):
assembly_defaults:
mode: "oneshot" # Default mode
facilitator: "kairos" # Discussion moderator
max_rounds: 3 # Maximum rounds in discussion
consensus_threshold: 0.6 # 60% = early termination
Important: Assembly output is advisory only. Human judgment remains the final authority, especially for L0 promotions.
Persona definitions can be customized in: knowledge/persona_definitions/
Q: Is API extension needed for team usage?
A: KairosChain now supports Streamable HTTP transport for remote/team access. For team usage, the following options are available:
| Method | Additional Implementation | Suitable Scale |
|---|
| Git sharing | Not required | Small teams (2-5 people) |
| SSH tunneling | Not required | LAN teams (2-10 people) |
| Streamable HTTP | ✅ Available (--http flag) | Medium teams (5-20 people) |
| MCP over SSE | Not needed (Streamable HTTP replaces) | When remote connection is needed |
Git sharing (simplest):
# Manage knowledge/, skills/, data/blockchain.json with Git
# Each member runs the MCP server locally
# Changes are synced via Git
SSH tunneling (LAN teams, no code changes required):
For teams on the same LAN, you can connect to a remote MCP server via SSH. This requires no additional implementation — just SSH access to the server machine.
Setup:
-
Run the MCP server on a shared machine (e.g., server.local):
# On the server machine
cd /path/to/KairosChain_mcp_server
# Server is ready (stdio-based, no daemon needed)
-
Configure MCP client to connect via SSH:
For Cursor (~/.cursor/mcp.json):
{
"mcpServers": {
"kairos-chain": {
"command": "ssh",
"args": [
"-o", "StrictHostKeyChecking=accept-new",
"[email protected]",
"cd /path/to/KairosChain_mcp_server && ruby bin/kairos-chain"
]
}
}
}
For Claude Code:
claude mcp add kairos-chain ssh -- -o StrictHostKeyChecking=accept-new [email protected] "cd /path/to/KairosChain_mcp_server && ruby bin/kairos-chain"
-
(Optional) Use SSH key authentication for passwordless access:
# Generate key if not exists
ssh-keygen -t ed25519
# Copy to server
ssh-copy-id [email protected]
SSH tunneling advantages:
- No code changes or HTTP server implementation needed
- Uses existing SSH infrastructure and authentication
- Encrypted communication by default
- Works with stdio-based MCP protocol as-is
SSH tunneling limitations:
- Requires SSH access to the server machine
- Each client opens a new server process (no shared state between connections)
- For concurrent writes, use Git to sync
storage/blockchain.json and knowledge/
When Streamable HTTP is better:
- Remote access beyond SSH reach (internet-facing)
- Bearer token authentication needed
- Integration with CI/CD or external systems
- See Optional: Streamable HTTP Transport for setup details
Q: Is a voting system needed for changes to kairos.rb or kairos.md in team settings?
A: It depends on team size and requirements.
Current implementation (single approver model):
require_human_approval: true # One person's approval is sufficient
Features that may be needed for team operations:
| Feature | L0 | L1 | L2 |
|---|
| Voting system | Recommended | Optional | Not needed |
| Quorum | Recommended | - | - |
| Proposal period | Recommended | - | - |
| Veto power | Depends | - | - |
Tools needed in the future (not implemented):
governance_propose - Create change proposals
governance_vote - Vote on proposals (approve/reject/abstain)
governance_status - Check proposal voting status
governance_execute - Execute proposals that exceed threshold
Special nature of kairos.md:
Since kairos.md corresponds to a "constitution," consensus building outside the system (GitHub Discussion, etc.) is recommended:
- Propose via GitHub Issue / Discussion
- Offline discussion with the entire team
- Reach consensus by unanimity (or supermajority)
- Manually edit and commit the file
Q: How do I run local tests?
A: Run tests with the following commands:
cd KairosChain_mcp_server
ruby test_local.rb
Test coverage:
- Layer Registry operation verification
- List of 18 core MCP tools
- Resource tools (resource_list, resource_read)
- L1 Knowledge read/write
- L2 Context read/write
- L0 Skills DSL (6 skills) loading
After testing, artifacts (context/test_session) are created. Delete if not needed:
rm -rf context/test_session
Q: What meta-skills are included in kairos.rb?
A: Currently 8 meta-skills are defined:
| Skill | Description | Modifiability |
|---|
l0_governance | L0 self-governance rules | Content only |
core_safety | Safety foundation | Not modifiable (deny :all) |
evolution_rules | Evolution rules definition | Content only |
layer_awareness | Layer structure awareness | Content only |
approval_workflow | Approval workflow with checklist | Content only |
self_inspection | Self-inspection capability | Content only |
chain_awareness | Blockchain awareness | Content only |
audit_rules | Knowledge lifecycle audit rules | Content only |
The l0_governance skill is special: it defines which skills can exist in L0, implementing the Pure Agent Skill principle of self-referential governance.
See skills/kairos.rb for details.
Q: How do I modify L0 skills? What is the procedure?
A: L0 modification requires a strict multi-step procedure with human oversight. This is intentional — L0 is the "constitution" of KairosChain.
Prerequisites:
evolution_enabled: true in skills/config.yml (must be set manually)- Session evolution count <
max_evolutions_per_session (default: 3)
- Target skill is not in
immutable_skills (core_safety cannot be modified)
- Change is permitted by the skill's
evolve block
Step-by-Step Procedure:
┌─────────────────────────────────────────────────────────────────┐
│ 1. Human: Manually set evolution_enabled: true in config.yml │
└───────────────────────────────┬─────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. AI: skills_evolve command="propose" skill_id="..." def="..." │
│ - Syntax validation │
│ - l0_governance allowed_skills check │
│ - evolve rules check │
└───────────────────────────────┬─────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. Human: Review with 15-item checklist (approval_workflow) │
│ - Traceability (3 items) │
│ - Consistency (3 items) │
│ - Scope (3 items) │
│ - Authority (3 items) │
│ - Pure Agent Compliance (3 items) │
└───────────────────────────────┬─────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. AI: skills_evolve command="apply" ... approved=true │
│ - Creates version snapshot │
│ - Updates kairos.rb │
│ - Records to blockchain │
│ - Kairos.reload! │
└───────────────────────────────┬─────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. Verify: skills_dsl_get, chain_history, chain_verify │
└───────────────────────────────┬─────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 6. Human: Set evolution_enabled: false (recommended) │
└─────────────────────────────────────────────────────────────────┘
Key Points:
| Aspect | Description |
|---|
| Enabling evolution | Must be done manually (AI cannot change config.yml) |
| Approval | Human must verify 15-item checklist |
| Recording | All changes recorded on blockchain |
| Rollback | Use skills_rollback to restore from snapshot |
| Immutable | core_safety cannot be changed (evolve deny :all) |
Adding a New L0 Skill Type:
To add a completely new meta-skill type (e.g., my_new_meta_skill):
- First, evolve
l0_governance to add it to allowed_skills list
- Then, use
skills_evolve command="add" to create the new skill
Both steps require human approval and checklist verification.
L1/L2 are NOT affected:
| Layer | Tool | Human Approval | Evolution Enable |
|---|
| L0 | skills_evolve | Required | Required |
| L1 | knowledge_update | Not required | Not required |
| L2 | context_save | Not required | Not required |
L1 and L2 remain freely modifiable by AI as before.
Q: What is L0 Auto-Check? How does it help with the 15-item checklist?
A: L0 Auto-Check is a feature that automatically verifies mechanical checks before L0 changes, reducing the human review burden.
How it works:
When you run skills_evolve command="propose", the system automatically runs checks defined in the approval_workflow skill (which is part of L0). This keeps the check criteria self-referential (Pure Agent Skill compliant).
Check Categories:
| Category | Type | Items | Description |
|---|
| Consistency | Mechanical | 4 | In allowed_skills, not immutable, syntax valid, evolve rules |
| Authority | Mechanical | 2 | evolution_enabled, within session limit |
| Scope | Mechanical | 1 | Rollback possible |
| Traceability | Human | 2 | Reason documented, traceable to L0 rule |
| Pure Compliance | Human | 2 | No external deps, LLM-independent |
Example Output:
📋 L0 AUTO-CHECK REPORT
============================================================
✅ All 7 mechanical checks PASSED. 3 items require human verification.
### Consistency
✅ Skill in allowed_skills
evolution_rules is in allowed_skills
✅ Skill not immutable
evolution_rules is not immutable
✅ Ruby syntax valid
Syntax is valid
✅ Evolve rules permit change
Skill's evolve rules allow modification
### Authority
✅ Evolution enabled
evolution_enabled: true in config
✅ Within session limit
1/3 evolutions used
### Scope
✅ Rollback possible
Version snapshots directory exists
### Traceability
✅ Reason documented
Reason: Updating for clarity
⚠️ Traceable to L0 rule
⚠️ HUMAN CHECK: Verify this change can be traced to an explicit L0 rule.
### Pure Compliance
⚠️ No external dependencies
⚠️ HUMAN CHECK: Verify the change doesn't introduce external dependencies.
⚠️ LLM-independent semantics
⚠️ HUMAN CHECK: Would different LLMs interpret this change the same way?
------------------------------------------------------------
⚠️ 3 item(s) require HUMAN verification.
Review the ⚠️ items above before approving.
------------------------------------------------------------
Benefits:
| Without Auto-Check | With Auto-Check |
|---|
| Human verifies all 15 items | AI verifies 7 mechanical items |
| Easy to miss syntax errors | Syntax validated automatically |
| Manual l0_governance check | Automatic allowed_skills check |
| No structured report | Clear pass/fail report |
Usage:
# Include reason for better traceability
skills_evolve command="propose" skill_id="evolution_rules" definition="..." reason="Clarify evolution workflow"
Pure Agent Skill Compliance:
The check logic is defined within L0 (in the approval_workflow skill's behavior block), not in external code. This means the criteria for checking L0 changes are themselves part of L0 — maintaining self-referential integrity.
Q: How does KairosChain decide when to evolve its own skills? Is there a meta-skill for this?
A: KairosChain intentionally does NOT include logic for deciding "when to evolve." This decision is delegated to the human side (or the AI client interacting with humans).
Current design responsibilities:
| Responsibility | Owner | Details |
|---|
| Evolution judgment (when/what) | Human / AI client | Outside KairosChain |
| Evolution constraints (allow/deny) | KairosChain | Validated by internal rules |
| Evolution approval | Human | Explicit approved: true |
| Evolution recording | KairosChain | Automatically recorded on blockchain |
What is already implemented:
- ✅ Evolution constraints (
SafeEvolver)
- ✅ Workflow (propose → review → apply)
- ✅ Layer structure (L0/L1/L2)
- ✅ 8 meta-skills definition
What is NOT implemented (by design):
- ❌ "When to evolve" decision logic
- ❌ Self-detection of capability gaps
- ❌ Recognition of learning opportunities
- ❌ Evolution trigger conditions
Design rationale:
This is intentional. From kairos.md (PHILOSOPHY-020 Minimum-Nomic):
| Approach | Problem |
|---|
| Completely fixed rules | No adaptation, system becomes obsolete |
| Unrestricted self-modification | Chaos, no accountability |
To avoid "unrestricted self-modification," KairosChain intentionally delegates evolution triggers to external actors. KairosChain serves as a gatekeeper and recorder, not an autonomous self-modifier.
Future extensibility:
If you want to add a meta-skill for "when to evolve," you could define something like:
skill :evolution_trigger do
version "1.0"
title "Evolution Trigger Logic"
evolve do
allow :content # Trigger conditions can be modified
deny :behavior # Decision logic itself is fixed
end
content <<~MD
## Evolution Trigger Conditions
1. When the same error pattern occurs 3+ times
2. When user explicitly says "remember this"
3. When new domain knowledge is provided
→ Propose saving to L1
MD
end
However, even with such a meta-skill, final approval should remain with humans. This is the core of KairosChain's safety design.
Q: What is Skill-Tool Unification? Can I add MCP tools without editing Ruby files?
A: Yes! Skills in kairos.rb can now define MCP tools via the tool block. This unifies skills and tools in L0-B.
How it works:
# In kairos.rb
skill :my_custom_tool do
version "1.0"
title "My Custom Tool"
# Traditional behavior (for skill introspection)
behavior do
{ capability: "..." }
end
# Tool definition (exposed as MCP tool)
tool do
name "my_custom_tool"
description "Does something useful"
input do
property :arg, type: "string", description: "Argument"
required :arg
end
execute do |args|
# Tool implementation
{ result: process(args["arg"]) }
end
end
end
Enable in config:
# skills/config.yml
skill_tools_enabled: true # Default: false
Key points:
- Default is disabled (conservative)
- Adding/modifying tools requires editing
kairos.rb (L0 constraints apply)
- Changes require human approval (
approved: true)
- All changes are recorded on blockchain
- Aligns with Minimum-Nomic: "can change, but recorded"
Why is this so strict?
L0 (kairos.rb) is intentionally locked with triple protection:
| Protection | Setting | Effect |
|---|
| 1 | evolution_enabled: false | Blocks any kairos.rb changes |
| 2 | require_human_approval: true | Requires explicit human approval |
| 3 | skill_tools_enabled: false | Skills not registered as tools |
Important: There is no MCP tool to modify config.yml. Even if an LLM is asked to "change these settings," it cannot — humans must manually edit config.yml.
This is by design: L0 corresponds to "constitution/law" in the legal analogy. It should rarely change. For frequent tool additions, consider:
- Current limitation: Only L0 supports
tool blocks
- Future possibility: L1 tool definition support (lighter constraints, no human approval, hash-only recording)
For most use cases, L0 tools should not need frequent changes. The strict lock ensures system integrity.
Q: What is the difference between adding tools via kairos.rb vs tools/ directory?
A: There are two ways to add MCP tools to KairosChain:
- Via
kairos.rb (L0): Using the tool block in skill definitions
- Via
tools/ directory: Adding Ruby files directly to lib/kairos_mcp/tools/
Functional equivalence: Both methods register MCP tools that can be called by LLMs.
Key differences:
| Aspect | kairos.rb (L0) | tools/ directory |
|---|
| Addition method | Via skills_evolve tool | Manual file addition |
| Human approval | Required | Not required |
| Blockchain record | Yes (full record) | No |
| Activation | skill_tools_enabled: true | Always active |
| Under KairosChain management | Yes | No |
Important: Adding tools directly to tools/ is not via KairosChain. It's a regular code change (tracked by git, but not audited by KairosChain's blockchain).
Design intent:
- Core infrastructure (
tools/): Tools necessary for KairosChain itself to function. Should rarely change.
- Extension tools (
kairos.rb): Custom tools added by users. Use when you want change history audited.
In other words:
kairos.rb route: "Strict but auditable"tools/ route: "Free but not audited"
Future consideration: L1 tool definition support may be added (lighter constraints, hash-only recording) for tools that are useful but don't need L0's strict controls.
Q: Should KairosChain proactively recommend skill creation to the LLM?
A: No. KairosChain should focus on "recording and constraining," not "recommending when to learn." The logic for recommending skill creation should be delegated to the LLM/AI agent side (e.g., Cursor Rules, system_prompt).
Why this separation?
| Aspect | Implemented in KairosChain | Delegated to LLM/Agent |
|---|
| Minimum-Nomic Principle | "Changes should be rare and high-cost" | Agent decides when learning is valuable |
| Separation of Concerns | KairosChain = gatekeeper & recorder | LLM = decision-maker for learning triggers |
| Customizability | Same constraints for all users | Each user can configure different agent behaviors |
| Prompt Injection Risk | Recommendation logic could be attacked | Defense can be handled at agent level |
KairosChain's role:
- ✅ Record skill changes immutably
- ✅ Enforce evolution constraints (approval, layer rules)
- ✅ Provide tools for skill management
- ❌ Decide "when" or "what" to learn
Recommended approach for proactive skill recommendations:
Configure your AI agent (Cursor Rules, Claude system_prompt, etc.) to include:
# Agent Learning Rules
## When to Recommend Skill Creation
- After solving a problem that required multiple iterations
- When the user says "I always forget..." or "This is a common pattern"
- When similar code patterns are generated repeatedly
## Recommendation Format
"I noticed [pattern]. Would you like me to capture this as a KairosChain skill?"
## Then use KairosChain tools:
- L2: `context_save` for temporary hypotheses
- L1: `knowledge_update` for project knowledge (hash-only record)
- L0: `skills_evolve` for meta-skills (requires human approval)
This keeps KairosChain as a neutral infrastructure while allowing each team/user to define their own learning policies at the agent level.
Skill promotion triggers (same principle applies):
KairosChain also does NOT automatically suggest skill promotion (L2→L1→L0). Configure your AI agent to suggest promotions:
# Skill Promotion Rules (add to above)
## When to Suggest L2 → L1 Promotion
- Same context referenced 3+ times across sessions
- User says "this is useful" or "I want to keep this"
- Hypothesis validated through actual use
## When to Suggest L1 → L0 Promotion
- Knowledge governs KairosChain's own behavior
- Mature, stable pattern that shouldn't change often
- Team consensus reached (for shared instances)
## Promotion Suggestion Format
"This knowledge has been useful across multiple sessions.
Would you like to promote it from L2 to L1?"
## Then use KairosChain tools:
- `skills_promote command="analyze"` - With Persona Assembly for deliberation
- `skills_promote command="promote"` - Direct promotion
Q: What happens when skills or knowledge contradict each other?
A: Currently, KairosChain does not have automatic contradiction detection between skills/knowledge. This is a recognized limitation noted in the design paper.
Why no automatic detection?
KairosChain intentionally delegates "judgment" to external actors (LLM/human):
| KairosChain's Responsibility | Delegated to External |
|---|
| Record changes | Judge what to save |
| Enforce constraints | Judge content validity |
| Maintain history | Resolve contradictions |
Current approach when contradictions occur:
- Implicit layer priority:
L0 (meta-rules) > L1 (project knowledge) > L2 (temporary context) — lower layers take precedence
- LLM interpretation: When multiple skills are referenced, the LLM interprets and mediates based on context
- Human resolution: Important contradictions are resolved by humans updating the relevant skills
Future possibility:
Contradiction detection could be added as an L1 knowledge or L0 skill:
# Contradiction Detection Skill (example)
## Detection Rules
- Same topic with different recommendations
- Conflicting constraint definitions
- Circular dependencies
## Resolution Flow
1. Warn user upon detection
2. Generate discussion via Persona Assembly
3. Human makes final decision
However, "what constitutes a contradiction" is itself a philosophical question, and KairosChain's current design intentionally does not make that judgment.
Q: What is StateCommit and how does it improve auditability?
A: StateCommit is a feature that creates snapshots of all layers (L0/L1/L2) at specific "commit points" for improved auditability. Unlike individual skill change records, StateCommit captures the entire system state at a moment in time.
Why StateCommit?
| Existing Records | StateCommit |
|---|
| L0: Full blockchain transaction | Captures all layers together |
| L1: Hash reference only | Includes layer relationships |
| L2: No recording | Shows "why" via commit reason |
Storage strategy:
- Off-chain: Full snapshot JSON files in
storage/snapshots/
- On-chain: Hash reference and summary only (prevents blockchain bloat)
Commit types:
| Type | Trigger | Reason |
|---|
explicit | User calls state_commit | Required (user-provided) |
auto | System detects trigger conditions | Auto-generated |
Auto-commit triggers (OR conditions):
- L0 change detected
- Promotion (L2→L1 or L1→L0) occurred
- Demotion/archive occurred
- Session end (when MCP server stops)
- L1 changes threshold (default: 5)
- Total changes threshold (default: 10)
AND condition (empty commit prevention):
Auto-commit only triggers if the manifest hash differs from the previous commit.
Configuration (skills/config.yml):
state_commit:
enabled: true
snapshot_dir: "storage/snapshots"
max_snapshots: 100
auto_commit:
enabled: true
skip_if_no_changes: true # AND condition
on_events:
l0_change: true
promotion: true
demotion: true
session_end: true
change_threshold:
enabled: true
l1_changes: 5
total_changes: 10
Usage:
# Create explicit commit
state_commit reason="Feature complete"
# Check current status
state_status
# View commit history
state_history
# View specific commit details
state_history hash="abc123"
Q: What happens when too many skills accumulate? Is there a cleanup mechanism?
A: KairosChain provides the skills_audit tool for knowledge lifecycle management across all layers.
The skills_audit tool provides:
| Command | Description |
|---|
check | Health check across L0/L1/L2 layers |
stale | Detect outdated items (layer-specific thresholds) |
conflicts | Detect potential contradictions between knowledge |
dangerous | Detect patterns that may conflict with L0 safety |
recommend | Get promotion/archive recommendations |
archive | Archive L1 knowledge (human approval required) |
unarchive | Restore from archive (human approval required) |
Layer-specific staleness thresholds:
| Layer | Threshold | Rationale |
|---|
| L0 | No date check | Stability is a feature, not staleness |
| L1 | 180 days | Project knowledge should be periodically reviewed |
| L2 | 14 days | Temporary contexts should be cleaned up |
Usage examples:
# Run health check across all layers
skills_audit command="check" layer="all"
# Find stale L1 knowledge
skills_audit command="stale" layer="L1"
# Get recommendations for archiving and promotion
skills_audit command="recommend"
# Archive with Persona Assembly for deeper analysis
skills_audit command="check" with_assembly=true assembly_mode="discussion"
# Archive a stale knowledge item (requires human approval)
skills_audit command="archive" target="old_knowledge" reason="Unused for 1 year" approved=true
Archive mechanism:
- Archived knowledge is moved to
knowledge/.archived/ directory
- Archive metadata (reason, date, superseded_by) is stored in
.archive_meta.yml
- Archived items are excluded from normal searches but can be restored
- All archive/unarchive operations are recorded on blockchain
Human oversight:
Archive and unarchive operations require explicit human approval (approved: true). This rule is defined in L0 audit_rules skill and is itself configurable (L0-B).
Q: How do I fix a skill when it provides incorrect or outdated information?
A: KairosChain provides multiple tools for identifying and fixing problematic knowledge.
Step 1: Identify issues with skills_audit
# Check for dangerous patterns (safety conflicts)
skills_audit command="dangerous" layer="L1"
# Check for stale knowledge
skills_audit command="stale" layer="L1"
# Full health check with Persona Assembly
skills_audit command="check" with_assembly=true
Step 2: Review and fix with knowledge tools
| Tool | Purpose |
|---|
knowledge_get | Retrieve skill content for review |
knowledge_update command="update" | Modify skill (recorded on blockchain) |
skills_audit command="archive" | Archive if obsolete (human approval required) |
Modification workflow:
1. User: "That answer was wrong. Show me the skill you referenced."
2. LLM: Calls knowledge_get name="skill_name"
3. User: "The section about X is outdated. Fix it."
4. LLM: Proposes modified content
5. User: Approves changes
6. LLM: Calls knowledge_update command="update" content="..." reason="User feedback: outdated info"
For obsolete knowledge (archive instead of delete):
# Archive obsolete knowledge (preserves history, removes from active search)
skills_audit command="archive" target="outdated_skill" reason="Superseded by new_skill" approved=true
# Later, if needed, restore from archive
skills_audit command="unarchive" target="outdated_skill" reason="Still relevant" approved=true
Dangerous pattern detection:
The skills_audit command="dangerous" checks for:
- Language suggesting bypassing safety checks
- Hardcoded credentials or API keys
- Patterns that conflict with L0
core_safety
Proactive maintenance:
Configure your AI agent (Cursor Rules / system_prompt) to suggest periodic audits:
# Skill Quality Rules
## Periodic Audit
- Run `skills_audit command="check"` monthly or when issues arise
- Review recommendations from `skills_audit command="recommend"`
## When User Reports Issues
1. Run `skills_audit command="dangerous"` to check for safety issues
2. Use `knowledge_get` to review the specific skill
3. Fix with `knowledge_update` or archive if obsolete
Q: What are the advantages and disadvantages of using SQLite?
A: SQLite is an optional storage backend for team environments. Here's what you need to know:
Advantages:
| Advantage | Description |
|---|
| Concurrent Access | Built-in locking prevents data corruption when multiple users access simultaneously |
| ACID Transactions | Guarantees data integrity even during crashes |
| WAL Mode | Allows concurrent reads and writes (readers don't block writers) |
| Single File | Easy backup (just copy the .db file) |
| No Server Required | Unlike PostgreSQL/MySQL, no separate database server needed |
| Fast Queries | Indexed queries are faster than scanning JSON files |
Disadvantages / Cautions:
| Disadvantage | Description | Mitigation |
|---|
| External Dependency | Requires sqlite3 gem installation | Use file backend for simple deployments |
| Network File System | SQLite is NOT recommended on NFS/network drives | Use local disk or PostgreSQL for network storage |
| Write Scalability | Only one writer at a time (WAL helps but has limits) | Fine for small teams (2-10), consider PostgreSQL for larger |
| Binary Format | Cannot read data directly without tools | Use Exporter to create human-readable files |
| Gem Updates | Need to track sqlite3 gem updates | Pin version in Gemfile, test before updating |
When to Use SQLite:
Individual use → File backend (default)
│
▼
Small team (2-10 people)
└─► SQLite backend ✓
│
▼
Large team (10+ people)
└─► PostgreSQL (future)
Recovery from Issues:
If SQLite database becomes corrupted or you encounter issues:
# 1. Export current data (if possible)
KairosMcp::Storage::Exporter.export(
db_path: "storage/kairos.db",
output_dir: "storage/backup"
)
# 2. Delete corrupted database
# rm storage/kairos.db
# 3. Rebuild from files
KairosMcp::Storage::Importer.rebuild_from_files(
db_path: "storage/kairos.db"
)
Best Practices:
- Regular Exports: Periodically export to files for human-readable backups
- Version Pin: Pin sqlite3 gem version in Gemfile
- Local Disk: Always use local disk, not network drives
- Backup Strategy: Backup both
.db file AND exported files
Q: How do I inspect SQLite data without SQL commands?
A: Use the built-in Exporter to create human-readable files:
require_relative 'lib/kairos_mcp/storage/exporter'
# Export to human-readable JSON/JSONL files
KairosMcp::Storage::Exporter.export(
db_path: "storage/kairos.db",
output_dir: "storage/export"
)
This creates:
blockchain.json - All blocks in readable JSONaction_log.jsonl - Action logs (one JSON per line)knowledge_meta.json - Knowledge metadatamanifest.json - Export information
You can then view these files with any text editor or JSON viewer.
Note: Knowledge content (*.md files) is always stored as files in knowledge/ directory, regardless of storage backend. SQLite only stores metadata for faster queries.
Q: What is Pure Agent Skill and why does it matter?
A: Pure Agent Skill is a design principle that ensures L0's semantic self-containment. It addresses a fundamental question: How can an AI system govern its own evolution without external dependencies?
The Core Principle:
All rules, criteria, and justifications for modifying L0 must be explicitly described within L0 itself.
What "Pure" means in this context:
Pure does not mean:
- Complete absence of side effects
- Byte-level identical outputs
Pure means:
- Skill semantics don't change based on which LLM interprets them
- Meaning doesn't vary by who the approver is
- Meaning doesn't depend on execution history or time
How KairosChain implements this:
| Before | After |
|---|
config.yml defined allowed L0 skills (external) | l0_governance skill defines this (self-referential) |
| Approval criteria were implicit | approval_workflow includes explicit checklist |
| Changes were possible without L0 awareness | L0 governs itself through its own rules |
The l0_governance skill:
skill :l0_governance do
behavior do
{
allowed_skills: [:core_safety, :l0_governance, ...],
immutable_skills: [:core_safety],
purity_requirements: { all_criteria_in_l0: true, ... }
}
end
end
This makes "what can be in L0" part of L0 itself, not external configuration.
Theoretical Limits (Gödelian):
Perfect self-containment is theoretically impossible due to:
- Halting Problem: Cannot always mechanically verify if a change satisfies all criteria
- Meta-level Dependency: The interpreter of L0 rules (code/LLM) exists outside L0
- Bootstrapping: Initial L0 must be authored externally
KairosChain acknowledges these limits while aiming for sufficient Purity:
If an independent reviewer, using only L0's documented rules, can reconstruct the justification for any L0 change, then L0 is sufficiently Pure.
Practical Benefits:
- Auditability: All governance criteria are in one place
- Resistance to Drift: Harder to accidentally break governance
- Explicit Approval Criteria: Human reviewers have a checklist
- Self-documenting: L0 explains itself
For full specification, see skills/kairos.md sections [SPEC-010] and [SPEC-020].
Q: Why does KairosChain use Ruby, specifically DSL and AST?
A: KairosChain's choice of Ruby DSL/AST is not accidental but essential for self-modifying AI systems. A self-referential skill system must satisfy three constraints simultaneously:
| Requirement | Description | Ruby's Implementation |
|---|
| Static Analyzability | Security verification before execution | RubyVM::AbstractSyntaxTree (standard library) |
| Runtime Modifiability | Add/modify skills during operation | define_method, class_eval, open classes |
| Human Readability | Specifications domain experts can read | Natural-language-like DSL syntax |
Why these three matter for self-reference:
KairosChain implements a unique self-referential structure where skills are constrained by skills themselves. For example, evolution_rules skill contains:
evolve do
allow :content
deny :guarantees, :evolve, :behavior
end
This means "the rule about evolving cannot itself be evolved" — a bootstrap constraint that requires:
- Parsing the rule definition (static analysis via AST)
- Evaluating the constraint at runtime (metaprogramming)
- Understanding what the rule means (human-readable DSL)
Comparison with other languages:
| Aspect | Lisp/Clojure | Ruby | Python | JavaScript |
|---|
| Homoiconicity (code=data) | ○ Complete | × No | × No | × No |
| Human readability | △ S-expressions hard to read | ○ Natural | △ Brackets required | △ Syntax constraints |
| AST tools in stdlib | × Not needed but audit-hard | ○ Complete | △ Limited | △ External deps |
| DSL expressiveness | ○ | ○ | △ | △ |
| Production ecosystem | △ | ○ Proven (Rails, RSpec) | ○ | ○ |
Theoretically optimal: Lisp/Clojure (homoiconicity makes self-modification natural)
Practically optimal: Ruby (balances readability + analyzability + evolvability)
The decisive advantage — Separability:
In KairosChain's self-referential system, the separation of definition, analysis, and execution is crucial:
# 1. Definition: Human-readable
skill :evolution_rules do
evolve { deny :evolve } # Self-constraint
end
# 2. Analysis: Validate before execution
RubyVM::AbstractSyntaxTree.parse(definition) # Static analysis
# 3. Execution: Evaluate constraint
skill.evolution_rules.can_evolve?(:evolve) # => false
In Lisp, code=data blurs the boundary between "analysis" and "execution." While this provides freedom, achieving auditability requires additional mechanisms.
Conclusion: Given KairosChain's goal of "auditable AI skill evolution," Ruby is the practical optimum — not the only correct answer, but a realistic choice that satisfies all three constraints simultaneously.
Q: What's the difference between using local skills vs. KairosChain?
A: AI agent editors (Cursor, Claude Code, Antigravity, etc.) typically provide a local skills/rules mechanism. Here's a comparison with KairosChain:
Local Skills (e.g., .cursor/skills/, CLAUDE.md, agent rules)
| Pros | Cons |
|---|
| Simple — just place files, ready to use | No change history — who/when/why is not tracked |
| Fast — direct file read, no MCP overhead | Too free — unintended modifications can occur |
| Native IDE integration | No layer concept — temporary hypotheses and permanent knowledge mix |
| Standard format (SKILL.md, etc.) | No self-reference — AI cannot inspect/explain its own skills |
KairosChain (MCP server)
| Pros | Cons |
|---|
| Auditability — all changes recorded on blockchain | MCP call overhead — slight latency |
| Layered architecture — L0 (meta-rules) / L1 (project knowledge) / L2 (temporary context) | Learning curve — must understand layers and tools |
| Approval workflow — L0 changes require human approval | Setup required — MCP server configuration |
| Self-reference — AI can inspect, explain, and evolve skills | Complexity — may be overkill for simple use cases |
| Semantic search — RAG-enabled meaning-based search | |
| StateCommit — system-wide snapshots at any point | |
Lifecycle management — skills_audit for detecting/archiving stale knowledge | |
Usage Guidelines:
| Scenario | Recommendation |
|---|
| Small personal project | Local skills |
| Audit/accountability required | KairosChain |
| Recording AI capability evolution | KairosChain |
| Team knowledge sharing | KairosChain (especially with SQLite backend) |
| Quick prototyping | Local skills → migrate to KairosChain when mature |
The Essential Difference:
- Local Skills: Function as "convenient documentation"
- KairosChain: Functions as an "auditable ledger of AI capability evolution"
KairosChain's philosophy:
"KairosChain answers not 'Is this result correct?' but 'How was this intelligence formed?'"
If you just need to use skills, local skills are sufficient. However, if you need to explain how the AI learned and evolved, KairosChain is the appropriate choice.
Hybrid Approach:
You can use both simultaneously:
- Local skills for quick, informal knowledge
- KairosChain for knowledge that needs audit trails
KairosChain doesn't replace local skills — it provides an additional layer of auditability and governance when needed.
Read Compatibility: Using L1 Knowledge as Claude Code Skills
KairosChain L1 knowledge files use YAML frontmatter + Markdown, which is compatible with Claude Code Skills format. Claude Code ignores unknown frontmatter fields (version, layer, tags), so L1 files can be read as-is.
To use L1 knowledge as Claude Code Skills, create a symlink:
# Single knowledge item
mkdir -p ~/.claude/skills/layer-placement-guide
ln -s /path/to/.kairos/knowledge/layer_placement_guide/layer_placement_guide.md \
~/.claude/skills/layer-placement-guide/SKILL.md
# Or link the entire knowledge directory for a project
ln -s /path/to/.kairos/knowledge ~/.claude/skills/kairos-knowledge
This provides read-only compatibility — Claude Code can reference L1 knowledge, but all modifications should still go through KairosChain's knowledge_update tool to maintain blockchain audit trails. Direct file edits bypass the audit mechanism.
This is useful for sharing mature L1 knowledge via GitHub with users who may not have KairosChain installed.
Q: How does P2P skill exchange work?
A: KairosChain uses the Model Meeting Protocol (MMP) for P2P communication. One agent runs an HTTP server, and another connects directly to it. The flow is:
- Agent A starts HTTP server:
kairos-chain --http --port 8080
- Agent B connects:
meeting_connect(url: "http://localhost:8080", mode: "direct")
- Agents exchange introductions (identity, capabilities, available skills)
- Agent B discovers and acquires skills or SkillSets from Agent A
All exchanges are recorded on the blockchain for provenance tracking.
Q: What is the knowledge-only constraint?
A: When exchanging SkillSets over P2P, only knowledge-only packages can be transferred. This means:
- Allowed: Markdown files, YAML files, configuration templates
- Blocked: Ruby (.rb), Python (.py), Shell (.sh), JavaScript (.js), and 10 other executable extensions, plus files with shebang lines (
#!)
SkillSets containing executable code in tools/ or lib/ directories must be installed via trusted channels (gem install, git clone, manual copy). This separation ensures that P2P knowledge sharing remains safe while maintaining security boundaries for code execution.
Q: How do I connect to another KairosChain instance?
A: Use the MMP tools:
# 1. Ensure MMP SkillSet is installed
kairos-chain skillset list
# 2. Start your HTTP server (for the remote agent to connect back)
kairos-chain --http --port 8080
# 3. Connect to a peer
# Via MCP tool:
meeting_connect url="http://peer-address:8080" mode="direct"
# Via curl (for testing):
curl http://peer-address:8080/meeting/v1/introduce
Configure connection settings in meeting.yml including identity, rate limits, and crypto options. See the MMP P2P User Guide for detailed instructions.
Subtree Integration Guide
KairosChain_2026 is designed to be embedded into other projects using git subtree. This allows each project to:
- Receive framework updates from the upstream KairosChain_2026 repository
- Accumulate project-specific knowledge (L1) locally
- Keep everything in a single repository with no extra clone steps
Gem vs Subtree: If you installed KairosChain as a gem (gem install kairos-chain), you do NOT need subtree setup. The gem approach and the subtree approach are independent installation methods. The subtree approach is for users who want the full source code embedded in their project repository. See the Installation section for details on the gem approach.
Why Subtree (Not Submodule)
| Aspect | subtree | submodule |
|---|
| Local file additions | Managed naturally by parent repo | Complicated inside submodule |
git clone for teammates | Just works (all files included) | Requires git submodule init && update |
| CI/CD | No special setup | Needs submodule initialization step |
| Knowledge accumulation | Commit directly to parent repo | Awkward cross-repo management |
| Accidental upstream push | Safe unless explicit subtree push | Easier to push to wrong remote |
How It Works with KairosChain Layers
KairosChain_2026 (upstream) YourProject (parent repo)
┌──────────────────────────┐ ┌─────────────────────────────────┐
│ L0: Framework code │ subtree │ server/ │
│ L0: Meta-skills │ --pull-> │ KairosChain_mcp_server/ │
│ L1: Generic templates │ │ knowledge/ │
│ example_knowledge/ │ │ example_knowledge/ <- sync│
│ persona_definitions/ │ │ persona_definitions/<-sync│
│ │ │ your_project/ <- local │
│ │ │ your_tools/ <- local │
│ │ │ context/ <- L2 │
└──────────────────────────┘ └─────────────────────────────────┘
| Layer | Location | Managed By |
|---|
| L0 (meta-skills, framework) | Upstream KairosChain_2026 | subtree pull syncs to all projects |
| L1 (project knowledge) | knowledge/ in each project | Committed to parent repo only |
| L2 (session context) | context/ | Ephemeral, gitignored |
Setup: Adding KairosChain to a New Project
Step 1: Add subtree
git subtree add --prefix=server https://github.com/masaomi/KairosChain_2026 main --squash
Step 2: Register remote (for convenience)
git remote add mcp_server https://github.com/masaomi/KairosChain_2026
Step 3: Configure .gitignore
In server/.gitignore, add:
# Bundler
KairosChain_mcp_server/Gemfile.lock
KairosChain_mcp_server/.bundle/
KairosChain_mcp_server/vendor/
# L2 session context (ephemeral)
KairosChain_mcp_server/context/
# Vector search index files (auto-generated)
KairosChain_mcp_server/storage/embeddings/**/*.ann
KairosChain_mcp_server/storage/embeddings/**/*.json
!KairosChain_mcp_server/storage/embeddings/**/.gitkeep
# Action log
KairosChain_mcp_server/skills/action_log.jsonl
Important: Data Directory Configuration for Subtree
Since the gemification update, KairosChain resolves data paths via KairosMcp.data_dir, which defaults to .kairos/ in the current working directory. When using subtree, you must specify --data-dir to point to the existing data location inside the subtree, otherwise a new empty .kairos/ directory will be created and your existing skills/, knowledge/, and storage/ data will not be found.
Cursor IDE (mcp.json):
{
"mcpServers": {
"kairos-chain": {
"command": "server/KairosChain_mcp_server/bin/kairos-chain",
"args": ["--data-dir", "server/KairosChain_mcp_server"]
}
}
}
Claude Code (.mcp.json):
{
"mcpServers": {
"kairos-chain": {
"command": "server/KairosChain_mcp_server/bin/kairos-chain",
"args": ["--data-dir", "server/KairosChain_mcp_server"]
}
}
}
Alternatively, use the environment variable:
export KAIROS_DATA_DIR=server/KairosChain_mcp_server
Note: If you previously ran without --data-dir and a .kairos/ directory was auto-created, you can safely delete it. Your actual data remains in server/KairosChain_mcp_server/.
Daily Operations
Pull upstream updates:
git subtree pull --prefix=server mcp_server main --squash
- Files from upstream are updated/merged
- Locally added files (project knowledge) are NOT affected
- If a file exists both locally and upstream with different content, a normal merge conflict occurs — resolve as usual
Commit project-specific knowledge:
# Knowledge files created by MCP server appear as untracked
git add server/KairosChain_mcp_server/knowledge/your_project/
git add server/KairosChain_mcp_server/storage/blockchain.json
git commit -m "Add project-specific knowledge"
These commits go to the parent repo only — upstream is never affected.
Push to upstream (CAUTION):
# Only if you want to contribute changes back to KairosChain_2026
# Usually NOT needed for project-specific files
git subtree push --prefix=server mcp_server main
Warning: Do NOT push unless you intentionally want to send changes to the KairosChain_2026 repository. Project-specific knowledge should stay in the parent repo.
Conflict Resolution
When subtree pull encounters a conflict:
$ git subtree pull --prefix=server mcp_server main --squash
# CONFLICT (add/add): Merge conflict in server/.../some_file.md
# 1. Open the conflicted file and resolve
# 2. Stage and commit
git add server/KairosChain_mcp_server/...
git commit -m "Resolve subtree merge conflict, keep local changes"
Rule of thumb: For project knowledge files, prefer local content over upstream content.
Multi-Project Deployment Example
ProjectA/ ProjectB/
├── .git/ ├── .git/
└── server/ (subtree) └── server/ (subtree)
└── KairosChain_mcp_server/ └── KairosChain_mcp_server/
├── knowledge/ ├── knowledge/
│ ├── example_knowledge/ (shared) │ ├── example_knowledge/ (shared)
│ ├── tool_a/ (A-specific) │ ├── tool_b/ (B-specific)
│ └── utils_a/ (A-specific) │ └── utils_b/ (B-specific)
└── storage/ └── storage/
└── blockchain.json (A-specific) └── blockchain.json (B-specific)
Each project independently:
- Pulls framework updates from the same upstream
- Accumulates its own L1 knowledge
- Manages its own blockchain state
After Subtree Pull: Template Updates
When you pull upstream updates that include changes to template files (kairos.rb, kairos.md, config.yml, etc.), those changes are applied directly to the subtree directory since it contains the full source. However, if you have modified these files locally, you may encounter merge conflicts during subtree pull.
For subtree users, the system_upgrade MCP tool and kairos-chain upgrade CLI command are not needed — the subtree pull mechanism itself handles file updates. The upgrade tooling is designed for gem-based installations where template files are bundled inside the gem and need to be migrated to the user's data directory.
Summary of update methods:
| Installation Method | How to Update | Template Handling |
|---|
Gem (gem install) | gem update kairos-chain + system_upgrade tool | 3-way hash merge via .kairos_meta.yml |
Subtree (git subtree) | git subtree pull | Standard git merge (resolve conflicts manually) |
| Repository clone | git pull | Standard git merge (resolve conflicts manually) |
Reference
- Upstream:
https://github.com/masaomi/KairosChain_2026
- Subtree prefix:
server/ (or your preferred path)
- Remote alias:
mcp_server
License
See LICENSE file.
Version: 3.58.1
Last Updated: 2026-08-03
"KairosChain answers not 'Is this result correct?' but 'How was this intelligence formed?'"
