ce9ba61ee0
README down from 89 KB to 7.8 KB (11x reduction, target was 10-15 KB). Visitor-facing README now loads in one screen — hero + 3 killer features + what-it-solves + quick install + docs index. Extracted 6 new files under docs/: - INSTALL.md (15 KB) — prerequisites, profiles, interactive install, MCP binary, keisei CLI intro, runtime hook controls, what-you-get table - REFERENCE.md (35 KB) — every one of 25 Rust primitives + 13 shell primitives + 10 hooks + 39 skills with actual CLI surface (clap flags, exit codes, env vars, state paths), keisei CLI deep-dive, 12 pipelines - ARCHITECTURE.md (11 KB) — build pipeline, creating-a-new-agent, adding custom blocks/manifests, agents overview, cross-tool bridges, meta-composer, regen counts, workflow-file editing protocol - SLEEP-LAYER.md (11 KB) — three-phase nightly cycle diagram, session self-audit (RULE 0.14), Cloud REM sync, sleep-on-it incubation, deep-sleep NREM consolidation with 4-primitive pipeline + example - SECURITY.md (7.6 KB) — threat surface table + 8 mitigations in detail (memory-repo privacy, secrets-guard patterns, supply-chain SHA pinning, S3 SSRF, brain path/name validation, exFAT warning, battle matrix) - WHY.md (3.6 KB) — full 'From the author' manifesto restored from git history (pre-1f3aaca product pivot). Medium/dev.to-friendly for virality, separate from the product README New docs cross-link each other + README has docs index in tail. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
112 lines
7.7 KiB
Markdown
112 lines
7.7 KiB
Markdown
# KeiSeiKit — Constructor-Pattern Agent Kit for Claude Code
|
||
|
||
**A structural layer over Claude Code, Cursor, Continue, and Zed that catches the failure modes LLMs introduce at commit time — not after they ship.**
|
||
|
||
Drop-in toolkit: portable agent personas, tool-use hooks that refuse known-bad actions, click-through skill wizards, a Rust primitive library for the tasks Python ships wrongly, and a portable "brain" directory (USB / git / S3) that mounts into any MCP-capable client via one command.
|
||
|
||
## Why it exists
|
||
|
||
LLMs are statistically wired to produce plausible-but-wrong output. Context windows drop prior decisions, confident citations turn out to be fabricated, parallel terminals clobber each other's files, the same mistake lands on the third try because the retrospective from the first never reached the second session. None of that is solvable by better prompts — it is solvable by structure *around* the prompt.
|
||
|
||
KeiSeiKit is that structure: persistent agent memory across sessions, pre-commit hooks at every tool boundary, typed handoff artifacts between agents, a deterministic manifest-to-agent build, and a three-phase overnight consolidation via a cloud cron. Constructor Pattern throughout — one file per concern, every abstraction replaceable.
|
||
|
||
**Rust-first by design.** Type-system guarantees remove entire classes of hallucination at compile time: no `None`-vs-`[]` confusions, no missing `.await`, no unhandled `Result`. For LLM-authored code this is survival, not style. The full philosophical backstory lives in [docs/WHY.md](./docs/WHY.md).
|
||
|
||
## Three killer features
|
||
|
||
### 1. The nightly cycle
|
||
|
||
Day session → overnight consolidation → morning report. **Three phases on an Anthropic-cloud agent** mirror biological sleep:
|
||
|
||
- **Phase A — Incubation** ("sleep on it"): you defer a hard question via `/sleep-on-it`; the remote agent processes it during the night (15 min / 60 min / 4 h / full-night marathon).
|
||
- **Phase B — REM**: the agent reads your day's trace JSONL, extracts cross-session patterns, commits `reports/sleep-YYYY-MM-DD.md` back to your private memory-repo.
|
||
- **Phase C — NREM**: every 7 days (by default), scans `_rules/` + `hooks/` + `_blocks/` + `memory/` for conflicts (duplicate matchers, orphan wikilinks, CP violations) and emits a structured refactor plan.
|
||
|
||
Morning `git pull` — you read, you decide. Nothing is auto-injected into a future session. Full mechanics: [docs/SLEEP-LAYER.md](./docs/SLEEP-LAYER.md).
|
||
|
||
### 2. Constructor-Pattern agent kit
|
||
|
||
Agents are built deterministically from TOML manifests + reusable Markdown blocks. Edit a block, the `assemble-agents` hook rebuilds every affected agent. Ship the same `kei-critic` persona to every machine by installing the kit. 12 ready agents (`kei-code-implementer`, `kei-critic`, `kei-validator`, `kei-security-auditor`, `kei-architect`, `kei-researcher`, `kei-ml-implementer`, ...) — all namespaced under `kei-*` so they won't collide with your own. Full wiring: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md).
|
||
|
||
### 3. Exobrain — one brain, every client
|
||
|
||
Portable **brain directory** (memory + artifacts + manifests + per-platform MCP server binaries) that mounts into Claude Code, Cursor, Continue, and Zed via a single command. USB stick, iCloud, S3 / R2 / MinIO — same state follows you.
|
||
|
||
```bash
|
||
keisei mount /Volumes/MyBrain # attaches to every detected AI client
|
||
keisei detach # clean unmount from all clients
|
||
```
|
||
|
||
Setup path: [docs/INSTALL.md § keisei CLI](./docs/INSTALL.md#the-keisei-cli--multi-client-exobrain-mount-v019).
|
||
|
||
## What it solves (vs vanilla Claude Code)
|
||
|
||
| Problem you hit | What the kit adds |
|
||
|---|---|
|
||
| Every session starts cold — prior decisions forgotten | `kei-memory` session traces + cloud REM consolidation + `/self-audit` retrospective |
|
||
| Same mistake twice | `RULE 0.10 recurrence-escalate` skill + hook codifies it (rule file + wiki + block/enforce/warn/remind hook) |
|
||
| 4–8 parallel Claude terminals clobber each other | `kei-ledger` fork-tracking + `orchestrator-dirty-check` hook + `RULE 0.13` (orchestrator owns git) |
|
||
| Hallucinated API / fabricated citation shipped | `genesis-leak-guard` + `secrets-guard` + `citation-verify` hooks; Rust primitives replace Python where `None`-vs-`[]`-class bugs matter |
|
||
| Single-client lock-in (Claude Code OR Cursor OR Zed) | `keisei` CLI + 4 adapters — one brain, every client |
|
||
| No audit trail across branches | `kei-ledger` SQLite agent-fork history + `kei-store` memory-repo abstraction (GitHub / Forgejo / Gitea / FS / S3) |
|
||
| Drift between declared config and running state | `firewall-diff`, `ssh-check`, `kei-ci-lint`, `assemble-validate` hook |
|
||
|
||
Not a replacement for Claude Code — a persistent structural layer over it.
|
||
|
||
## Quick install
|
||
|
||
Two paths, pick what fits your Claude Code version:
|
||
|
||
```bash
|
||
# Plugin (recommended on Claude Code 2.1+, zero cargo build)
|
||
/plugin marketplace add KeiSei84/KeiSeiKit
|
||
/plugin install keisei@keisei-marketplace
|
||
|
||
# OR classic (required for Rust primitives)
|
||
git clone <your-fork-of-this-repo> KeiSeiKit
|
||
cd KeiSeiKit
|
||
./install.sh # minimal profile, ~5s, no primitives
|
||
./install.sh --profile=full # everything, ~5 min, ~200 MB
|
||
```
|
||
|
||
Plugin vs classic install, profiles (`minimal` / `core` / `frontend` / `ops` / `dev` / `full`), MCP-server pre-built binaries, and runtime hook controls → [docs/INSTALL.md](./docs/INSTALL.md).
|
||
|
||
## What's in the box
|
||
|
||
| Category | Count |
|
||
|---|---:|
|
||
| Behavioral blocks | 79 |
|
||
| Generic agents (manifests) | 12 |
|
||
| Hooks (PreToolUse / PostToolUse) | 10 |
|
||
| Portable skills | 39 |
|
||
| Rust primitives (opt-in, profile-gated) | 25 |
|
||
| Shell primitives (opt-in) | 13 |
|
||
| Cross-tool bridges | 11 |
|
||
|
||
Every primitive / hook / skill with its actual CLI surface → [docs/REFERENCE.md](./docs/REFERENCE.md).
|
||
|
||
## Docs
|
||
|
||
| File | What's in it |
|
||
|---|---|
|
||
| [docs/INSTALL.md](./docs/INSTALL.md) | Install paths, profiles, MCP binary, `keisei` CLI, runtime hook controls |
|
||
| [docs/REFERENCE.md](./docs/REFERENCE.md) | Every primitive / hook / skill / pipeline with flags + exit codes |
|
||
| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Build pipeline, cross-tool bridges, meta-composer, workflow editing |
|
||
| [docs/SLEEP-LAYER.md](./docs/SLEEP-LAYER.md) | Three-phase nightly cycle + session self-audit |
|
||
| [docs/SECURITY.md](./docs/SECURITY.md) | Threat model + mitigations |
|
||
| [docs/WHY.md](./docs/WHY.md) | Full "From the author" philosophical backstory |
|
||
| [docs/USB-BRAIN-GUIDE.md](./docs/USB-BRAIN-GUIDE.md) | Portable brain on removable media — macOS / Linux / Windows splits |
|
||
| [CHANGELOG.md](./CHANGELOG.md) | Release notes (Conventional Commits → Markdown via `kei-changelog`) |
|
||
| [PLUGIN.md](./PLUGIN.md) | Anthropic plugin-format install path (v0.16+) |
|
||
|
||
## About
|
||
|
||
Built by Denis Parfionovich (<parfionovich@keilab.io>) as a personal working environment — not a commercial product. The problems it solves are ones I hit every day across 4–8 parallel Claude Code terminals.
|
||
|
||
Most of what is here is well-established bricks (git-as-state, cron, TF-IDF, Constructor-Pattern composition). What may be new in the Claude Code context is the Constructor Pattern for agents (composable blocks, deterministic build, rebuild-on-block-edit hooks) and the three-phase sleep layer (using a git repo as the transport layer between sessions, with an Anthropic-cloud agent doing nightly incubation + REM + NREM consolidation).
|
||
|
||
Treat this as **my sample, not a claim of originality.** Forks and PRs welcome from everyone, not only from those who write code. Open an issue at [github.com/KeiSei84/KeiSeiKit/issues](https://github.com/KeiSei84/KeiSeiKit/issues) — a well-formulated problem is already half the solution. Full backstory in [docs/WHY.md](./docs/WHY.md).
|
||
|
||
## License
|
||
|
||
MIT. See [LICENSE](./LICENSE).
|