# KeiSeiKit

> 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

```bash
/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](./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](./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](./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](./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)

- **36 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, 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.
- **500+ 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](./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](./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/ARCHITECTURE.md).

## Docs

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