KeiSeiKit-1.0/README.md

KeiSeiKit

Tester notice (2026-04-23): git history was rewritten to sanitise commit subjects before public launch. If you have an existing clone, run git fetch --all && git reset --hard origin/main to resync. Working tree content is unchanged; only historical commit subjects differ.

A living neural structure you install next to your AI assistant. A mini-universe where any user, from any domain, can discover a new primitive or grow a new class of agent.

KeiSeiKit is not a toolkit. It is a substrate for cognitive growth — an opinionated neural structure of Kei that a developer installs, shapes, and extends. It sleeps when you sleep, remembers what you decided yesterday, heals mistakes it notices in itself, and runs from a directory you can put on a USB stick and carry between machines.

Install in one line

/plugin marketplace add KeiSei84/KeiSeiKit
/plugin install keisei@keisei-marketplace

Twelve agents appear in Claude Code, forty-three skills become callable as /self-audit, /sleep-on-it, /compose-solution, /new-project, /spawn-agent — and the nightly consolidation cycle is wired. Other install paths: docs/INSTALL.md.

The five biological principles

KeiSeiKit is organised around five properties a living neural system has, and most software doesn't. Each principle maps to concrete code shipped in this repo.

• DNA and taxonomy. Every agent invocation gets a 80-character deterministic identifier composed from role, capability bitmap, scope hash, task-body hash, and per-spawn nonce. Every primitive and agent is tagged along seven orthogonal facets — kingdom, mechanism, domain, layer, stage, stability, language — so the graph is queryable along any axis. See _primitives/_rust/kei-agent-runtime/src/dna.rs and docs/TAXONOMY.md.

• Creator lineage. Every row in the agent ledger carries creator_id and fork_parent_id. Who spawned what, from which parent, under which DNA — traceable. No orphan artefacts, no "where did this come from". See _primitives/_rust/kei-ledger/src/schema.rs migration v4.

• Sleep. Three phases, every night. Phase A is incubation: during the day you drop tasks into /sleep-on-it; at 03:00 a remote Claude agent works on them. Phase B is REM: the same agent reads the day's JSONL traces, extracts cross-session patterns, and writes a report. Phase C is NREM (every seven days by default): a conflict-scan plus refactor-engine propose a clean-up branch. Nothing auto-injects into the next session — you git pull, read, decide. See docs/SLEEP-LAYER.md.

• Self-healing. Three passive hooks (session-end-dump, milestone-commit-hook, error-spike-detector) feed a session retrospective. When the same mistake reappears twice, /escalate-recurrence offers to codify it as rule plus wiki entry plus hook — at the severity you pick. Silent-first: the first ten sessions log without prompting, so the baseline is real.

• Growth by composition. /new-project scaffolds a project across four phases with branch + ledger + artefact bundle per fork. /spawn-agent emits a new agent manifest. /compose-solution decomposes a free-text problem, greps existing atoms for prior art, and proposes the smallest artefact — agent, skill, hook, rule, block, or pipeline — that closes the gap. Every session leaves the substrate slightly larger than it found it.

The deeper theory — why these five and not others, and the analogy with hippocampal / cortical dynamics — is in docs/PHILOSOPHY.md.

Four layers

4. Portability    USB stick / iCloud / S3 — keisei mount, any machine
3. Sleep          Phase A (incubation) → Phase B (REM) → Phase C (NREM)
2. Cognition      DNA + ledger + taxonomy + memory + self-audit
1. Substrate      atoms, agents, skills, hooks, blocks, bridges

Layer 1 is the body — the reusable parts. Layer 2 is identity and memory. Layer 3 is overnight learning. Layer 4 is the ability to pick up and move.

What ships (verified counts)

• 47 Rust primitives — pure Rust workspace crates, release-stripped, each ≤2 MB, no Python runtime. Covers the ledger, memory, router, migrate, agent runtime, forge, spawn/replay, fork lifecycle, DNA adjacency/cluster index, pruning + discovery + brain-view, sleep infrastructure, and the keisei CLI.
• 12 agents (kei-* namespaced) — code-implementer, infra-implementer, ml-implementer, critic, validator, security-auditor, architect, researcher, ml-researcher, cost-guardian, modal-runner, fal-ai-runner. All carry a substrate_role facet.
• 43 skills — one-command pipelines including /new-project, /spawn-agent, /self-audit, /sleep-on-it, /sleep-setup, /compose-solution, /schema-design, /api-design, /auth-setup, /observability-setup, /ci-scaffold, /pr-review, /debug-deep.
• 12 hooks — pre-commit safety net, always on: assembler, validator, no-hand-edit-agents, tomd-preread, agent-fork-logger, orchestrator-dirty-check, site-wysiwyd-check, session-end-dump, milestone-commit-hook, error-spike-detector, and two capability gates.
• 82 behavioural blocks — tested patterns composable into your own agents via blocks = [...] in a manifest.
• 11 capabilities / 5 roles — the capability-graph that agents resolve at spawn time.
• 11 cross-tool bridges — one source of truth emits .cursorrules, Cursor MDC, AGENTS.md, Copilot, Windsurf, Junie, Continue, Gemini, Aider, Replit. Switch AI tools without rewriting your setup.
• 800+ tests across the Rust workspace, green on cargo test --workspace on every supported OS.

Every number is regenerated from source by scripts/regen-counts.sh — no manual drift.

Domain-agnostic by construction

KeiSeiKit has no hardcoded domain. The same substrate ships unchanged for biology, finance, law, medicine, music, research, game dev, ops. What's domain-aware lives in the blocks — reusable markdown cubes you compose into an agent manifest — and the assembler rebuilds the affected agents when a block changes. If you work in a domain the kit doesn't yet cover, the path to first-class support is a manifest plus a handful of blocks, not a fork.

How to start

Install: the two-line plugin command above. Other paths — full profile, dev profile, MCP-only, manual, Nix, Docker — are in docs/INSTALL.md.

Discover a new primitive:

/compose-solution "I want a hook that blocks rm -rf ~/ in any Bash call"

The skill greps existing atoms, proposes the smallest intervention, drafts a block if nothing matches, and hands off to /escalate-recurrence to persist it.

Grow a new agent:

/spawn-agent

Four phases: role, task, scope, emit. The wizard writes the manifest, composes its DNA, forks a ledger row, and the assembler generates the agent markdown Claude Code will pick up.

Start a new project:

/new-project

Four phases: intake, fork skeleton, parallel execution (orchestrator owns git per RULE 0.13), merge ceremony with per-branch AskUserQuestion.

Portability

Every primitive is a pure Rust binary ≤2 MB. Every hook is POSIX shell. Every skill is markdown. Every manifest is TOML. The keisei CLI mounts a brain-directory into Claude Code + Cursor + Continue + Zed simultaneously; the directory can live on a USB stick, iCloud, S3, or any filesystem. Move it to another machine and the same agents, the same memory, the same artefact bundles are there. docs/USB-BRAIN-GUIDE.md.

Under the hood

Constructor Pattern: one file, one concern. TOML manifests are the source of truth. A Rust assembler compiles them to the Markdown Claude Code expects. When a block changes, a PostToolUse hook rebuilds every affected agent. Rust is the backbone because the type system catches the class of mistakes LLMs most often introduce — None vs [], missing .await, unhandled Result — at compile time, so they cannot ship. Python is reserved for the places where Python is genuinely better.

Build pipeline, cross-tool bridge mechanics, meta-composer internals, sleep-layer details → docs/ARCHITECTURE.md.

Docs

PHILOSOPHY.md	The biological principles, in depth
INSTALL.md	All install paths, profiles, keisei CLI, hook controls
ARCHITECTURE.md	Build pipeline, bridges, meta-composer
REFERENCE.md	Every primitive, hook, skill with flags and exit codes
SLEEP-LAYER.md	Phase A / B / C nightly cycle + self-audit
TAXONOMY.md	The seven-facet vocabulary
SUBSTRATE-SCHEMA.md	Atom contract
SECURITY.md	Threat model + mitigations
USB-BRAIN-GUIDE.md	Portable brain — macOS / Linux / Windows
WHY.md	The full story of why this exists
CHANGELOG.md	What changed, version by version
PLUGIN.md	Anthropic plugin-format details

Authorship

Built by Denis Parfionovich (parfionovich@keilab.io) at KeiLab, while running 4–8 parallel Claude Code terminals every day. What you are looking at is the scaffolding that makes that possible — shared now so you don't have to build your own. Forks and pull requests welcome.

License

MIT. See LICENSE.