# KairosChain MCP Server **Self-referential MCP server for auditable skill self-management** > 📖 [日本語版 README はこちら (Japanese README)](README_jp.md) 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](#philosophy) - [The Problem](#the-problem) - [The Solution: KairosChain](#the-solution-kairoschain) - [Minimum-Nomic Principle](#minimum-nomic-principle) - [Architecture](#architecture) - [System Overview](#system-overview) - [P2P Knowledge Exchange](#p2p-knowledge-exchange) - [Layered Skills Architecture](#layered-skills-architecture) - [L0: Kairos Core (`skills/`)](#l0-kairos-core-skills) - [L1: Knowledge Layer (`knowledge/`)](#l1-knowledge-layer-knowledge) - [L2: Context Layer (`context/`)](#l2-context-layer-context) - [Why Layered Architecture?](#why-layered-architecture) - [Data Model: SkillStateTransition](#data-model-skillstatetransition) - [Setup](#setup) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Optional: RAG (Semantic Search) Support](#optional-rag-semantic-search-support) - [Optional: SQLite Storage Backend (Team Use)](#optional-sqlite-storage-backend-team-use) - [Optional: Streamable HTTP Transport (Remote/Team Access)](#optional-streamable-http-transport-remoteteam-access) - [Admin UI (Browser-Based Management)](#admin-ui-browser-based-management) - [Client Configuration](#client-configuration) - [Claude Code Configuration (Detailed)](#claude-code-configuration-detailed) - [Cursor IDE Configuration (Detailed)](#cursor-ide-configuration-detailed) - [Upgrading the Gem](#upgrading-the-gem) - [How It Works](#how-it-works) - [L1 Knowledge Updates (v1.0.0+)](#l1-knowledge-updates-v100) - [Upgrade Commands](#upgrade-commands) - [Version Mismatch Warning](#version-mismatch-warning) - [Upgrade Workflow](#upgrade-workflow) - [MMP SkillSet Setup (P2P Communication)](#mmp-skillset-setup-p2p-communication) - [Installing the MMP SkillSet](#installing-the-mmp-skillset) - [Configuring meeting.yml](#configuring-meetingyml) - [Starting the P2P HTTP Server](#starting-the-p2p-http-server) - [Testing P2P Connectivity](#testing-p2p-connectivity) - [Testing the Setup](#testing-the-setup) - [1. Basic Command Line Tests](#1-basic-command-line-tests) - [2. Skills Tools Test](#2-skills-tools-test) - [3. Blockchain Tools Test](#3-blockchain-tools-test) - [4. Testing with SQLite Backend (Optional)](#4-testing-with-sqlite-backend-optional) - [5. Testing with RAG / Semantic Search (Optional)](#5-testing-with-rag-semantic-search-optional) - [6. Testing HTTP Mode (Optional)](#6-testing-http-mode-optional) - [7. Testing with Claude Code](#7-testing-with-claude-code) - [8. Testing with Cursor](#8-testing-with-cursor) - [Troubleshooting](#troubleshooting) - [Usage Tips](#usage-tips) - [Basic Usage](#basic-usage) - [Practical Usage Patterns](#practical-usage-patterns) - [Best Practices](#best-practices) - [Tool Discovery with tool_guide](#tool-discovery-with-tool_guide) - [Common Commands Reference](#common-commands-reference) - [Security Considerations](#security-considerations) - [Available Tools (26 core + skill-tools)](#available-tools-26-core-skill-tools) - [L0-A: Skills Tools (Markdown) - Read-only](#l0-a-skills-tools-markdown-read-only) - [L0-B: Skills Tools (DSL) - Full Blockchain Record](#l0-b-skills-tools-dsl-full-blockchain-record) - [L0: Instructions Management - Full Blockchain Record](#l0-instructions-management-full-blockchain-record) - [Cross-Layer Promotion Tools](#cross-layer-promotion-tools) - [Audit Tools - Knowledge Lifecycle Management](#audit-tools-knowledge-lifecycle-management) - [Resource Tools - Unified Access](#resource-tools-unified-access) - [L1: Knowledge Tools - Hash Reference Record](#l1-knowledge-tools-hash-reference-record) - [L2: Context Tools - No Blockchain Record](#l2-context-tools-no-blockchain-record) - [Blockchain Tools](#blockchain-tools) - [State Commit Tools (Auditability)](#state-commit-tools-auditability) - [Authentication Tools (HTTP Mode Only)](#authentication-tools-http-mode-only) - [Guide Tools (Tool Discovery)](#guide-tools-tool-discovery) - [System Management Tools](#system-management-tools) - [MMP Meeting Tools (SkillSet: mmp)](#mmp-meeting-tools-skillset-mmp) - [Multiuser Tools (SkillSet: multiuser)](#multiuser-tools-skillset-multiuser) - [Usage Examples](#usage-examples) - [List Available Skills](#list-available-skills) - [Check Blockchain Status](#check-blockchain-status) - [Record a Skill Transition](#record-a-skill-transition) - [P2P SkillSet Exchange](#p2p-skillset-exchange) - [Self-Evolution Workflow](#self-evolution-workflow) - [HestiaChain Meeting Place (v2.5.0)](#hestiachain-meeting-place-v250) - [What is HestiaChain?](#what-is-hestiachain) - [Architecture](#architecture) - [Quick Start](#quick-start) - [HTTP Endpoints](#http-endpoints) - [MCP Tools](#mcp-tools) - [Cross-Instance Knowledge Discovery](#cross-instance-knowledge-discovery) - [Trust Anchor: Chain Migration](#trust-anchor-chain-migration) - [DEE Philosophy Protocol](#dee-philosophy-protocol) - [EC2 Deployment](#ec2-deployment) - [Pure Skills Design](#pure-skills-design) - [skills.md vs skills.rb](#skillsmd-vs-skillsrb) - [Example Skill Definition](#example-skill-definition) - [Self-Referential Introspection](#self-referential-introspection) - [DSL/AST Skill Formalization](#dslast-skill-formalization) - [Motivation](#motivation) - [Three Layers of a Skill](#three-layers-of-a-skill) - [Node Types](#node-types) - [Example Definition Block](#example-definition-block) - [Formalization Tools](#formalization-tools) - [Source of Truth Policy](#source-of-truth-policy) - [SkillSet Plugin Architecture](#skillset-plugin-architecture) - [SkillSet Structure](#skillset-structure) - [skillset.json Schema](#skillsetjson-schema) - [Layer-Based Governance](#layer-based-governance) - [MMP SkillSet (Model Meeting Protocol)](#mmp-skillset-model-meeting-protocol) - [Multiuser SkillSet (Multi-Tenant User Management)](#multiuser-skillset-multi-tenant-user-management) - [Directory Structure](#directory-structure) - [Gem Structure (installed via `gem install kairos-chain`)](#gem-structure-installed-via-gem-install-kairos-chain) - [Data Directory (created by `kairos-chain init`)](#data-directory-created-by-kairos-chain-init) - [Repository Structure (cloned from GitHub)](#repository-structure-cloned-from-github) - [Multiuser: Multi-Tenant User Management](#multiuser-multi-tenant-user-management) - [What is Multiuser?](#what-is-multiuser) - [Architecture](#architecture) - [Prerequisites](#prerequisites) - [Quick Start](#quick-start) - [MCP Tools](#mcp-tools) - [Core Hooks (Option C: Generic Hooks)](#core-hooks-option-c-generic-hooks) - [RBAC (Role-Based Access Control)](#rbac-role-based-access-control) - [Graceful Degradation](#graceful-degradation) - [Configuration](#configuration) - [Key Concepts](#key-concepts) - [Architecture](#architecture) - [Components](#components) - [Billing Models](#billing-models) - [Payment Flow (Proof-Centric)](#payment-flow-proof-centric) - [Anti-Sybil Measures](#anti-sybil-measures) - [MCP Tools](#mcp-tools) - [Configuration Example](#configuration-example) - [Dependencies](#dependencies) - [Synoptis: Mutual Attestation Protocol (v3.5.0)](#synoptis-mutual-attestation-protocol-v350) - [What is Synoptis?](#what-is-synoptis) - [Architecture](#architecture) - [Quick Start](#quick-start) - [MCP Tools](#mcp-tools) - [MMP Integration](#mmp-integration) - [Trust Scoring](#trust-scoring) - [Registry and Constitutive Recording](#registry-and-constitutive-recording) - [ProofEnvelope Structure](#proofenvelope-structure) - [Challenge Workflow](#challenge-workflow) - [Transport Layer](#transport-layer) - [Dependencies](#dependencies) - [Future Roadmap](#future-roadmap) - [Completed Phases](#completed-phases) - [Near-term](#near-term) - [Long-term Vision: Distributed KairosChain Network](#long-term-vision-distributed-kairoschain-network) - [Deployment and Operation](#deployment-and-operation) - [Data Storage Overview](#data-storage-overview) - [Blockchain Storage Format](#blockchain-storage-format) - [Recommended Operation Patterns](#recommended-operation-patterns) - [Backup Strategy](#backup-strategy) - [Documentation Management](#documentation-management) - [Setup](#setup) - [The Development Cycle](#the-development-cycle) - [Promotion Targets](#promotion-targets) - [Ordering Constraints](#ordering-constraints) - [Philosophical Grounding](#philosophical-grounding) - [Instruction Mode: `self_developer`](#instruction-mode-self_developer) - [Future: Collaborative Self-Development](#future-collaborative-self-development) - [SkillSet Release Checklist](#skillset-release-checklist) - [1. L1 Knowledge for README](#1-l1-knowledge-for-readme) - [2. Regenerate README](#2-regenerate-readme) - [3. Version and Changelog](#3-version-and-changelog) - [4. Gem Build and Publish](#4-gem-build-and-publish) - [What This Is Not](#what-this-is-not) - [FAQ](#faq) - [Q: Can LLMs automatically modify L1/L2?](#q-can-llms-automatically-modify-l1l2) - [Q: How do I decide which layer to store knowledge in?](#q-how-do-i-decide-which-layer-to-store-knowledge-in) - [Q: How do I maintain L1 knowledge health? How do I prevent L1 bloat?](#q-how-do-i-maintain-l1-knowledge-health-how-do-i-prevent-l1-bloat) - [Q: What is Persona Assembly and when should I use it?](#q-what-is-persona-assembly-and-when-should-i-use-it) - [Q: Is API extension needed for team usage?](#q-is-api-extension-needed-for-team-usage) - [Q: Is a voting system needed for changes to kairos.rb or kairos.md in team settings?](#q-is-a-voting-system-needed-for-changes-to-kairosrb-or-kairosmd-in-team-settings) - [Q: How do I run local tests?](#q-how-do-i-run-local-tests) - [Q: What meta-skills are included in kairos.rb?](#q-what-meta-skills-are-included-in-kairosrb) - [Q: How do I modify L0 skills? What is the procedure?](#q-how-do-i-modify-l0-skills-what-is-the-procedure) - [Q: What is L0 Auto-Check? How does it help with the 15-item checklist?](#q-what-is-l0-auto-check-how-does-it-help-with-the-15-item-checklist) - [Q: How does KairosChain decide when to evolve its own skills? Is there a meta-skill for this?](#q-how-does-kairoschain-decide-when-to-evolve-its-own-skills-is-there-a-meta-skill-for-this) - [Q: What is Skill-Tool Unification? Can I add MCP tools without editing Ruby files?](#q-what-is-skill-tool-unification-can-i-add-mcp-tools-without-editing-ruby-files) - [Q: What is the difference between adding tools via kairos.rb vs tools/ directory?](#q-what-is-the-difference-between-adding-tools-via-kairosrb-vs-tools-directory) - [Q: Should KairosChain proactively recommend skill creation to the LLM?](#q-should-kairoschain-proactively-recommend-skill-creation-to-the-llm) - [Q: What happens when skills or knowledge contradict each other?](#q-what-happens-when-skills-or-knowledge-contradict-each-other) - [Q: What is StateCommit and how does it improve auditability?](#q-what-is-statecommit-and-how-does-it-improve-auditability) - [Q: What happens when too many skills accumulate? Is there a cleanup mechanism?](#q-what-happens-when-too-many-skills-accumulate-is-there-a-cleanup-mechanism) - [Q: How do I fix a skill when it provides incorrect or outdated information?](#q-how-do-i-fix-a-skill-when-it-provides-incorrect-or-outdated-information) - [Q: What are the advantages and disadvantages of using SQLite?](#q-what-are-the-advantages-and-disadvantages-of-using-sqlite) - [Q: How do I inspect SQLite data without SQL commands?](#q-how-do-i-inspect-sqlite-data-without-sql-commands) - [Q: What is Pure Agent Skill and why does it matter?](#q-what-is-pure-agent-skill-and-why-does-it-matter) - [Q: Why does KairosChain use Ruby, specifically DSL and AST?](#q-why-does-kairoschain-use-ruby-specifically-dsl-and-ast) - [Q: What's the difference between using local skills vs. KairosChain?](#q-whats-the-difference-between-using-local-skills-vs-kairoschain) - [Q: How does P2P skill exchange work?](#q-how-does-p2p-skill-exchange-work) - [Q: What is the knowledge-only constraint?](#q-what-is-the-knowledge-only-constraint) - [Q: How do I connect to another KairosChain instance?](#q-how-do-i-connect-to-another-kairoschain-instance) - [Subtree Integration Guide](#subtree-integration-guide) - [Why Subtree (Not Submodule)](#why-subtree-not-submodule) - [How It Works with KairosChain Layers](#how-it-works-with-kairoschain-layers) - [Setup: Adding KairosChain to a New Project](#setup-adding-kairoschain-to-a-new-project) - [Important: Data Directory Configuration for Subtree](#important-data-directory-configuration-for-subtree) - [Daily Operations](#daily-operations) - [Conflict Resolution](#conflict-resolution) - [Multi-Project Deployment Example](#multi-project-deployment-example) - [After Subtree Pull: Template Updates](#after-subtree-pull-template-updates) - [Reference](#reference) ## 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: 1. **Defining skills as executable structures** (Ruby DSL), not just documentation 2. **Recording every skill change** on an immutable blockchain 3. **Enabling self-reference** so AI can inspect its own capabilities 4. **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](#state-commit-tools-auditability) 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](#q-what-is-pure-agent-skill-and-why-does-it-matter) 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`: ```markdown --- 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](#state-commit-tools-auditability) feature can capture L2 state in periodic snapshots (stored off-chain with on-chain hash references). ### Why Layered Architecture? 1. **Not all knowledge needs the same constraints** — temporary thoughts shouldn't require per-operation blockchain records 2. **Separation of concerns** — Kairos meta-rules vs. project knowledge vs. temporary context 3. **AI autonomy with accountability** — free exploration in L2, tracked changes in L1, strict control in L0 4. **Cross-layer auditability** — [StateCommit](#state-commit-tools-auditability) enables periodic snapshots of all layers together for holistic audit trails ## Data Model: SkillStateTransition Every skill change is recorded as a `SkillStateTransition`: ```ruby { 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) ```bash # 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): 1. `--data-dir` CLI option 2. `KAIROS_DATA_DIR` environment variable 3. `.kairos/` in the current working directory #### Option B: Clone the Repository ```bash # 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 ```bash # 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 `/config/config.yml` for gem, or `skills/config.yml` for repo): ```yaml 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: 1. Install the gems: `bundle install --with rag` or `gem install hnswlib informers` 2. **Restart the MCP server** (reconnect in Cursor/Claude Code) 3. On first search, the index is automatically rebuilt from all skills/knowledge 4. 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 ```bash # 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 ```bash # 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 `/skills/config.yml` for gem, or `skills/config.yml` for repo): ```yaml # 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 ```bash # 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: ```ruby # 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: ```ruby # 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:** 1. Install sqlite3 gem 2. Change `storage.backend` to `sqlite` in config.yml 3. Run `Importer.rebuild_from_files` to migrate data 4. Restart the MCP server **SQLite → File:** 1. Run `Exporter.export` to export data 2. Copy exported files to original locations: - `blockchain.json` → `storage/blockchain.json` - `action_log.jsonl` → `skills/action_log.jsonl` 3. Change `storage.backend` to `file` in config.yml 4. 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** ```bash 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** ```yaml # skills/config.yml storage: backend: sqlite # Change from 'file' to 'sqlite' sqlite: path: "storage/kairos.db" wal_mode: true ``` **Step 3: Migrate existing data** ```bash 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** ```bash # 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:** ```bash # Check if installed gem list sqlite3 # Reinstall if needed gem uninstall sqlite3 gem install sqlite3 ``` **Data not visible after migration:** ```bash # 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:** ```bash # 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:** ```yaml # 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 ```bash # 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 ```bash # 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** ```bash # 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** ```bash # 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`: ```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):** ```bash ruby test_http.rb ``` **Integration tests (requires puma + rack):** ```bash ruby test_http.rb --integration ``` **Manual testing with curl:** ```bash # 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 " \ -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 " \ -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 " \ -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: ```bash # 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. ```bash # 1. Generate a self-signed cert/key once (written to /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). ```bash # 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: ```bash # 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. ```bash # 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`): ```nginx 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: ```bash # 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: ```bash # 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: ```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`: ```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`: ```yaml 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: ```bash 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 1. Start the HTTP server: `kairos-chain --http` (gem) or `ruby bin/kairos-chain --http` (repository) 2. Open `http://localhost:8080/admin` in your browser 3. 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](KairosChain_mcp_server/knowledge/mcp_to_saas_development_workflow/mcp_to_saas_development_workflow.md)). 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 ```bash # 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](#option-b-register-mcp-server-directly) or the [Cursor IDE Configuration](#cursor-ide-configuration-detailed) section below. **Prerequisites:** Ruby 3.2+ and `gem install kairos-chain` ```bash # 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 ```bash # 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 ```bash # 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`: ```json { "mcpServers": { "kairos-chain": { "command": "kairos-chain", "args": ["--data-dir", "/path/to/my-kairos-data"], "env": {} } } } ``` For repository-based setup: ```json { "mcpServers": { "kairos-chain": { "command": "ruby", "args": ["/path/to/KairosChain_mcp_server/bin/kairos-chain"], "env": {} } } } ``` #### Manual Configuration (Advanced) To edit the configuration file directly: ```bash # 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) 1. Open **Cursor Settings** (Cmd/Ctrl + ,) 2. Navigate to **Tools & MCP** 3. Click **New MCP Server** 4. 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 ```bash # macOS / Linux ~/.cursor/mcp.json # Windows %USERPROFILE%\.cursor\mcp.json ``` #### Step 2: Create/Edit the Configuration File ```bash # 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):** ```json { "mcpServers": { "kairos-chain": { "command": "kairos-chain", "args": ["--data-dir", "/path/to/my-kairos-data"], "env": {} } } } ``` **If using the repository:** ```json { "mcpServers": { "kairos-chain": { "command": "ruby", "args": ["/path/to/KairosChain_mcp_server/bin/kairos-chain"], "env": {} } } } ``` **For multiple MCP servers:** ```json { "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 1. Open Cursor 2. Click the "MCP" icon in the top right (or search "MCP" in the command palette) 3. 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: ```bash 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 ```bash # 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 1. Update the gem: `gem update kairos-chain` 2. Preview changes: `kairos-chain upgrade` 3. Review the output (especially any conflicts) 4. Apply: `kairos-chain upgrade --apply` 5. For L0 proposals, use `skills_evolve` to review and approve 6. 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: ```bash # 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 `/skillsets/mmp/config/meeting.yml`: ```yaml # 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 ```bash # 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 ```bash # 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](docs/KairosChain_MMP_P2P_UserGuide_20260220_en.md). --- ## 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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) ```bash # 1. Install sqlite3 gem gem install sqlite3 # 2. Edit config to enable SQLite # Change storage.backend from 'file' to 'sqlite' in /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) ```bash # 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 /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) ```bash # 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 " \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' ``` ### 7. Testing with Claude Code ```bash # 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 1. Open your project in Cursor 2. Open the chat panel (Cmd/Ctrl + L) 3. Try these prompts: - "List all KairosChain skills" - "Check the blockchain status" - "Show me the core_safety skill content" ### Troubleshooting #### Server Doesn't Start ```bash # 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 ```bash # 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 ```bash # 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 1. Verify the path in `~/.cursor/mcp.json` is an absolute path (for repository setup) 2. Check JSON syntax (missing/extra commas, etc.) 3. 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) ```yaml # 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 ```bash # Run daily/weekly echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"chain_verify","arguments":{}}}' | kairos-chain ``` #### 3. Backups ```bash # 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. ```json // 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: ```json { "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 1. **Safe Evolution Settings** - Keep `require_human_approval: true` - Only set `evolution_enabled: true` when needed 2. **Access Control** - Restrict allowed paths in `config/safety.yml` - Add sensitive files to the blocklist 3. **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 files - `create`: Create a new instructions file (`skills/{mode_name}.md`) - `update`: Update existing instructions file content - `delete`: 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: ```bash 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 decision - `promote`: Execute direct promotion - `status`: 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 layers - `stale`: Detect outdated items (L0: no date check, L1: 180 days, L2: 14 days) - `conflicts`: Detect potential contradictions between knowledge - `dangerous`: Detect patterns conflicting with L0 safety - `recommend`: Get promotion and archive recommendations - `gaps`: Check knowledge gaps defined by Knowledge Acquisition Policy in instruction modes - `export_needs`: Package knowledge gaps as shareable needs for cross-instance discovery via Meeting Place - `archive`: 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 category - `search`: Search tools by keyword - `recommend`: Get tool recommendations for specific tasks - `detail`: Get detailed information about a specific tool - `workflow`: Show common workflow patterns - `suggest`: Generate metadata suggestions for a tool (LLM-assisted) - `validate`: Validate proposed metadata before applying - `apply_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 files - `preview`: Detailed file-by-file analysis with merge previews - `apply`: 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](docs/KairosChain_MMP_P2P_UserGuide_20260220_en.md) 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 ```bash echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"skills_dsl_list","arguments":{}}}' | kairos-chain ``` ### Check Blockchain Status ```bash echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"chain_status","arguments":{}}}' | kairos-chain ``` ### Record a Skill Transition ```bash 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 ```bash # 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**: 1. **Enable Evolution** (in `skills/config.yml`): ```yaml evolution_enabled: true require_human_approval: true ``` 2. **AI Proposes Change**: ```bash skills_evolve command=propose skill_id=my_skill definition="..." ``` 3. **Human Reviews and Approves**: ```bash skills_evolve command=apply skill_id=my_skill definition="..." approved=true ``` 4. **Change is Applied and Recorded**: - Snapshot created in `skills/versions/` - Transition recorded on blockchain - `Kairos.reload!` updates in-memory state 5. **Verification**: ```bash 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: 1. **Trust Anchor** — A witness chain that records *that* interactions occurred, without enforcing judgments or determining canonical state 2. **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 ```bash # 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 ```bash # 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 ```bash # 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:** 1. Run `skills_audit(command: "gaps")` to detect missing baseline knowledge 2. Run `skills_audit(command: "export_needs")` to preview exportable needs 3. Run `meeting_publish_needs(opt_in: true)` to publish needs to the board 4. Other agents browsing with `browse(type: 'need')` can discover these needs 5. 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: ```bash # 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 ```ruby 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 ```ruby 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 ```ruby 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 ```json { "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 logic - `MMP::Identity` — Agent identity and introduction - `MMP::SkillExchange` — Skill acquisition workflow - `MMP::PeerManager` — Peer tracking with persistence and TOFU trust - `MMP::ProtocolLoader` — Dynamic protocol loading - `MMP::ProtocolEvolution` — Protocol extension mechanism - `MeetingRouter` — 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](docs/KairosChain_MMP_P2P_UserGuide_20260220_en.md). ### 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 switching - `Multiuser::PgBackend` — `Storage::Backend` subclass for PostgreSQL - `Multiuser::TenantManager` — Schema creation, SQL migrations, tenant lifecycle - `Multiuser::UserRegistry` — User accounts with auto-tenant provisioning - `Multiuser::TenantTokenStore` — PostgreSQL-backed token store (same API as file-based) - `Multiuser::AuthorizationGate` — Default-deny RBAC gate for `ToolRegistry` - `Multiuser::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: ```bash brew install postgresql@16 brew services start postgresql@16 gem install pg ``` ### Quick Start #### 1. Install the Multiuser SkillSet ```bash kairos-chain skillset install templates/skillsets/multiuser ``` #### 2. Configure PostgreSQL connection Edit `.kairos/skillsets/multiuser/config/multiuser.yml`: ```yaml 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 ```bash 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` ```yaml 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 ```yaml 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 ```yaml 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 ```bash # 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 trust + depositor trust → combined score | | `meeting_agent:` | 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 envelopes - `revocations.jsonl` — Revocation records - `challenges.jsonl` — Challenge and response records Use `trust_query` to verify registry integrity — it includes a `registry_integrity.valid` field in its response. ### ProofEnvelope Structure ```json { "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 1. Any agent can call `challenge_create(proof_id, challenge_type, details)` to challenge an attestation 2. The original attester receives the challenge (via MMP or local notification) 3. The attester calls `challenge_respond(challenge_id, response, evidence)` with additional evidence 4. 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 1. **Phase 4C: Message Relay**: E2E encrypted message relay with TTL (`/place/v1/relay/*`) 2. **Phase 4D: Federation**: Inter-Place discovery and mutual registration 3. **Ethereum Anchor**: Periodic hash anchoring to public chain (HestiaChain stages 2/3) 4. **Zero-Knowledge Proofs**: Privacy-preserving verification 5. **Web Dashboard**: Visualize skill evolution history 6. **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**: 1. Dockerization (deployment foundation) 2. ~~HTTP/WebSocket API (remote access)~~ ✅ Streamable HTTP transport (complete) 3. ~~Inter-server communication protocol~~ ✅ MMP (Model Meeting Protocol) with P2P direct mode (complete) 4. ~~SkillSet Plugin Infrastructure~~ ✅ Layer-based governance, knowledge-only P2P exchange (complete) 5. ~~HestiaChain Meeting Place Server~~ ✅ Trust anchor + DEE protocol Meeting Place (complete, v2.0.0) 6. Distributed consensus mechanism 7. Distributed L0 governance For detailed vision document, see: [Distributed KairosChain Network Vision](docs/distributed_kairoschain_vision_20260128_en.md) --- ## 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`: ```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:** ```bash # 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). ```bash # 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 ```bash # 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 ```bash # 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 1. Edit the relevant L1 knowledge file in `KairosChain_mcp_server/knowledge/` 2. Regenerate READMEs: ```bash # Generate README.md and README_jp.md from L1 knowledge rake build_readme # Or run the script directly ruby scripts/build_readme.rb ``` 3. Commit both the L1 knowledge change and the regenerated README #### Other Commands ```bash # 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: ```bash 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: 1. Edit core code in `lib/` directly (not via `.kairos/`) 2. Run tests: `rake test` 3. Commit and rebuild gem 4. `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: 1. **Promote `self_developer` mode to templates**: Move `self_developer.md` to `templates/skills/` so it is distributed via `kairos-chain init` 2. **Replace the current `developer` mode**: Rename `self_developer` to `developer`, making the self-referential workflow the default for all KairosChain contributors 3. **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 ```bash 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 1. Bump version in `lib/kairos_mcp/version.rb` 2. Add entry to `CHANGELOG.md` (follow existing format) 3. 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 ```bash 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](#q-what-is-statecommit-and-how-does-it-improve-auditability) 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):** - [ ] **Relevance**: Is this knowledge still applicable? - [ ] **Uniqueness**: Does similar knowledge already exist? - [ ] **Quality**: Is the information accurate and up-to-date? - [ ] **Safety**: Does it align with L0 safety constraints? **Archive Process:** ```bash # 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:** ```bash # 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):** ```yaml 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:** 1. Run the MCP server on a shared machine (e.g., `server.local`): ```bash # On the server machine cd /path/to/KairosChain_mcp_server # Server is ready (stdio-based, no daemon needed) ``` 2. Configure MCP client to connect via SSH: **For Cursor (`~/.cursor/mcp.json`):** ```json { "mcpServers": { "kairos-chain": { "command": "ssh", "args": [ "-o", "StrictHostKeyChecking=accept-new", "user@server.local", "cd /path/to/KairosChain_mcp_server && ruby bin/kairos-chain" ] } } } ``` **For Claude Code:** ```bash claude mcp add kairos-chain ssh -- -o StrictHostKeyChecking=accept-new user@server.local "cd /path/to/KairosChain_mcp_server && ruby bin/kairos-chain" ``` 3. (Optional) Use SSH key authentication for passwordless access: ```bash # Generate key if not exists ssh-keygen -t ed25519 # Copy to server ssh-copy-id user@server.local ``` **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](#optional-streamable-http-transport-remoteteam-access) 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):** ```yaml 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: 1. Propose via GitHub Issue / Discussion 2. Offline discussion with the entire team 3. Reach consensus by unanimity (or supermajority) 4. Manually edit and commit the file --- ### Q: How do I run local tests? **A:** Run tests with the following commands: ```bash 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: ```bash 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`): 1. First, evolve `l0_governance` to add it to `allowed_skills` list 2. 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:** ```bash # 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: ```ruby 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:** ```ruby # 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:** ```yaml # 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: 1. **Via `kairos.rb` (L0)**: Using the `tool` block in skill definitions 2. **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: ```markdown # 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: ```markdown # 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:** 1. **Implicit layer priority**: `L0 (meta-rules) > L1 (project knowledge) > L2 (temporary context)` — lower layers take precedence 2. **LLM interpretation**: When multiple skills are referenced, the LLM interprets and mediates based on context 3. **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: ```markdown # 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`):** ```yaml 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:** ```bash # 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:** ```bash # 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`** ```bash # 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):** ```bash # 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: ```markdown # 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: ```ruby # 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:** 1. **Regular Exports**: Periodically export to files for human-readable backups 2. **Version Pin**: Pin sqlite3 gem version in Gemfile 3. **Local Disk**: Always use local disk, not network drives 4. **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: ```ruby 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 JSON - `action_log.jsonl` - Action logs (one JSON per line) - `knowledge_meta.json` - Knowledge metadata - `manifest.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:** ```ruby 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: 1. **Halting Problem**: Cannot always mechanically verify if a change satisfies all criteria 2. **Meta-level Dependency**: The interpreter of L0 rules (code/LLM) exists outside L0 3. **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: ```ruby evolve do allow :content deny :guarantees, :evolve, :behavior end ``` This means "the rule about evolving cannot itself be evolved" — a bootstrap constraint that requires: 1. **Parsing** the rule definition (static analysis via AST) 2. **Evaluating** the constraint at runtime (metaprogramming) 3. **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: ```ruby # 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: ```bash # 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: 1. Agent A starts HTTP server: `kairos-chain --http --port 8080` 2. Agent B connects: `meeting_connect(url: "http://localhost:8080", mode: "direct")` 3. Agents exchange introductions (identity, capabilities, available skills) 4. 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: ```bash # 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](docs/KairosChain_MMP_P2P_UserGuide_20260220_en.md) 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](#installation-gem-or-repository) 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** ```bash git subtree add --prefix=server https://github.com/masaomi/KairosChain_2026 main --squash ``` **Step 2: Register remote (for convenience)** ```bash git remote add mcp_server https://github.com/masaomi/KairosChain_2026 ``` **Step 3: Configure .gitignore** In `server/.gitignore`, add: ```gitignore # 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`):** ```json { "mcpServers": { "kairos-chain": { "command": "server/KairosChain_mcp_server/bin/kairos-chain", "args": ["--data-dir", "server/KairosChain_mcp_server"] } } } ``` **Claude Code (`.mcp.json`):** ```json { "mcpServers": { "kairos-chain": { "command": "server/KairosChain_mcp_server/bin/kairos-chain", "args": ["--data-dir", "server/KairosChain_mcp_server"] } } } ``` Alternatively, use the environment variable: ```bash 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:** ```bash 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:** ```bash # 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):** ```bash # 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: ```bash $ 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](./LICENSE) file. --- **Version**: 3.58.1 **Last Updated**: 2026-08-03 > *"KairosChain answers not 'Is this result correct?' but 'How was this intelligence formed?'"*