keisei/KeiSeiKit-1.0
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: rewrite README for LLM-readers

Browse source 
Target audience: someone asking an LLM "what is this project". The LLM
needs claims it can verify and user-profiles it can match against. The
previous README leaned on metaphors ("living neural structure") that
don't anchor to code; replacement is claim → file:line → verify command.

Key changes:
- Remove tester-notice header (force-push done, resync complete)
- Lede: "local-first substrate … Rust core … TypeScript plugin glue"
  (concrete, extractable)
- Each mechanism (DNA, fork, memory, prompts, sleep, self-audit) now
  has a file-path citation and a verify-command
- DNA section expanded: full format example, per-segment semantics,
  use-case "has this task type run before" via kei-dna-index precedent
- Sleep section expanded: Phase A/B/C with queue paths, trace paths,
  report paths, plan-only vs plan+fork mode
- New "Deployment modes" table: laptop / USB / iCloud / VPS / Docker /
  MCP-only (answers cloud-deployment question up-front)
- New "Why Rust + TypeScript (no Python)" section with transformer-math
  argument (Rust: 0 debug loops; Python: unbounded token burn from
  runtime-error iteration). RULE 0.2 enforced by hook + install.sh
  verifies zero Python runtime
- "Probably fits" section replaces stark "Not a fit if you…" — keeps
  honest constraints but framed as lifestyle-invite with 7 profiles
- Comparison table: +OpenCode/OpenClaude compat row, +cross-tool
  bridges row
- "Verify everything works (60 sec)" smoke test with expected output
- Explicit cross-tool bridges + OpenCode/OpenClaude compat in lede

Ties to RULE 0.2 (Rust First), RULE 0.13 (orchestrator git ops),
RULE 0.15 (sleep layer). Every linked doc exists under docs/.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Parfii-bot 2026-04-24 00:02:45 +08:00
parent 5f7a5b2639
commit 0c814736ff
1 changed files with 215 additions and 76 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

291
README.md
View file

@ -1,99 +1,239 @@
# 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 local-first substrate that installs next to any LLM-based assistant
and keeps its memory, accountability, and nightly learning persistent.
Rust core (48 crates, ≤ 2 MB each), TypeScript plugin glue. MIT.
> 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.
Primary target: Claude Code. Also compatible with Cursor, Continue,
Zed, Aider, Windsurf via 11 cross-tool bridges, and with any
OpenCode / OpenClaude / open-source Claude-Code clone that speaks
the MCP server protocol + standard hook events.
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
## One-line install (Claude Code)
```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).
Twelve agents, 43 skills, 12 hooks, nightly consolidation wired in
60 seconds. Install paths for MCP-only, Cursor, Continue, Zed, Aider,
Docker, Nix — [`docs/INSTALL.md`](./docs/INSTALL.md).
## The five biological principles
## What it does (and where to verify)
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 — persistent identity per agent run.** Every invocation gets an
80-char deterministic string of the form:
- **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).
<role>::<caps-bitmap>::<sha8-scope>::<sha8-body>-<hex8-nonce>
- **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.
Example:
- **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).
edit-local::NG-FW-FD-CP-CG-TG-ND-RF::5435F821::AC73A6A3-e9bf468d
- **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.
- `role` — which capability bundle the agent got (edit-local / read-
only / auditor / merger / …).
- `caps-bitmap` — which policy fragments composed its prompt (no-git-
ops, files-whitelist, constructor-pattern, cargo-check-green, …).
- `scope` — 32-bit hash of the files-whitelist + denylist. Same files
→ same scope regardless of who asks.
- `body` — 32-bit hash of the task description. Two people asking
the same thing → same body.
- `nonce` — random per spawn. Distinguishes reruns of identical tasks.
- **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.
Same scope+body → same problem space. You can ask **"has this type of
task run before, how did it go"** in one query, without embeddings,
without a vector DB, without round-tripping through an LLM. The index
is a plain 32-bit hash lookup against the SQLite ledger. `kei-dna-index
precedent --body <sha8>` returns every past run with its status
merged / failed / running — instantly. Code: `_primitives/_rust/kei-
shared/src/dna.rs` (format SSoT), `_primitives/_rust/kei-dna-index/**`
(queries), `_primitives/_rust/kei-ledger/src/schema.rs` (storage).
The deeper theory — why these five and not others, and the analogy with hippocampal / cortical dynamics — is in [docs/PHILOSOPHY.md](./docs/PHILOSOPHY.md).
**Git branch per work-unit.** `kei-fork create` makes an atomic
triplet: a branch, a worktree under `_forks/<agent-id>/`, and a ledger
row. Agent writes in isolation, touches `.DONE`, `kei-fork collect`
atomically merges + archives + updates ledger. On any step failure,
everything rolls back. No more "the agent overwrote main". Code:
`_primitives/_rust/kei-fork/**`.
## Four layers
**Persistent memory on disk.** Three SQLite files:
`~/.claude/agents/ledger.sqlite` (who-did-what), `~/.claude/memory/
sessions.sqlite` (JSONL traces + embedding cache), `~/.claude/memory/
kei-memory.sqlite` (cross-session patterns). All backupable with
`cp`, portable with `keisei mount`, inspectable with `kei-brain-view
summary`. Nothing in RAM-only; nothing in a cloud you don't control.
Code: `_primitives/_rust/kei-{ledger,memory}/**`.
```
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
**Prompts composed from fragments.** Agent prompts aren't hand-written
— they're assembled from `_capabilities/<cat>/<slug>/text.md` files at
spawn time. Edit a fragment, every agent inherits the change. Single
source of truth for prompt engineering. Code: `_primitives/_rust/kei-
agent-runtime/src/compose.rs`.
**Sleep — three phases of overnight consolidation.** Your assistant
keeps working while you're asleep, but on your rules, on your machine.
- **Phase A — incubation.** Anytime during the day:
/sleep-on-it "write a 4-page literature review on …"
adds a task to `~/.claude/memory/sleep-queue/`. At 03:00 local, a
scheduled agent picks up the queue (up to 5 tasks, ≤ 480 min total
budget), works on each, checkpoints partial results every N minutes
so a cut-short run still leaves a readable artefact.
- **Phase B — REM.** Same agent reads the day's JSONL traces under
`~/.claude/memory/traces/`, finds cross-session patterns ("you hit
the same error three times this week", "these two tasks touched the
same files"), and writes a morning report to `~/.claude/memory/
sleep-reports/YYYY-MM-DD.md`. You `git pull` and read. Nothing
auto-injects into your next session — decisions stay with you.
- **Phase C — NREM, every 7 days.** A conflict-scan checks the whole
substrate for drift: rules that contradict, hooks that overlap,
duplicate capability fragments. A refactor-engine then proposes a
clean-up branch — in *plan-only* mode (markdown proposal) or
*plan + fork* mode (actual git branch with patch applied). You pick
during `/sleep-setup`.
Code + rule: [`docs/SLEEP-LAYER.md`](./docs/SLEEP-LAYER.md), `hooks/
sleep-*.sh`, `_primitives/_rust/kei-conflict-scan/`, `_primitives/
_rust/kei-refactor-engine/`.
**Self-audit, silent-first.** Three hooks — `session-end-dump`,
`milestone-commit-hook`, `error-spike-detector` — feed a retrospective.
Sessions 1–10 log without prompting. From session 11 on, if the same
mistake reappears twice, `/escalate-recurrence` offers to codify it
as rule + wiki entry + hook. Code: `hooks/*.sh`, `skills/self-audit/`,
`skills/escalate-recurrence/`.
## Deployment modes
| Where | How | When you want it |
|---|---|---|
| **Local laptop** | `/plugin install keisei` | Daily dev / research / writing |
| **USB stick** | `keisei mount /Volumes/usb/brain` | Move between machines |
| **iCloud / Dropbox** | Same `keisei mount` on a cloud-synced folder | Auto-backup + multi-device |
| **Cloud VPS** | `ssh user@host && ./install.sh && keisei serve` | Always-on agent, tablet client, shared team brain |
| **Docker** | `docker run -v ./brain:/home/kei/.claude keiseikit` | Ephemeral CI runs, reproducible test envs |
| **MCP-only** | `./install.sh --profile=mcp` | Plug the memory layer into a different assistant, skip the plugin |
Rust binaries are ≤ 2 MB each, statically linked where possible, no
Python runtime. Any x86_64 / arm64 host with git + SQLite works.
Bring your own API key (Anthropic / OpenAI / OpenRouter / local
Ollama) via `~/.claude/secrets/.env` — the kit never ships keys.
## Why Rust + TypeScript (no Python)
**Rust** for the engine — 47 crates covering ledger, memory, DNA,
fork, scheduler, watcher, assembler, CLI. The class of mistakes LLMs
make most often — `None` vs empty array, missing `.await`, unhandled
`Result`, mutex misuse — are compile-time errors in Rust. The LLM
literally cannot ship them. The type system is the fence.
**TypeScript** only for the thin adapter that talks to Claude Code's
Node-based plugin API. Three packages under `_ts_packages/`, each
≤ 300 LOC: marketplace manifest, installer helpers, plugin surface.
The substrate itself never assumes Node is running.
**Why not Python — it's transformer math, not taste.** Writing Rust
costs more tokens up-front (explicit types, explicit errors, explicit
ownership) but debugging costs ≈ 0 — the compiler is the fence.
Writing Python costs ~5 minutes (no types, no lifetimes, no compile
step), then debugging loops for hours: each failed run produces new
tokens the assistant must read, reason about, correct — often
triggering the next failure, another iteration, another token burn.
This isn't empirical. Python's tokenization (indentation-as-syntax,
runtime dynamic dispatch, late-binding names) leaves each token with
low semantic commitment, so the transformer must track more
conditional paths forward. Rust pins each token to a compile-time
shape: fewer open paths, fewer silent surprises, fewer debug loops.
Net cost of a shipped Rust primitive: predictable. Net cost of a
Python primitive: unbounded. RULE 0.2 enforces this with a hook that
blocks `python` / `python3` / `uv run python` without an explicit
opt-in prefix. `install.sh` runs on a fresh host with zero Python
installed — if Python slips into this repo, it's a bug.
## Probably fits — it's a way of working with AI as much as a tool
You'll like this if you prefer:
- **Seeing what your AI did**, rather than a dashboard that hides the
mistakes. The ledger shows every agent run, every fork, every
rollback. Honesty by construction.
- **Your own machine over someone else's cloud.** Brain lives on your
disk, backs up with `cp`, moves on a USB.
- **Two install commands once**, instead of a SaaS onboarding flow.
- **One of**: macOS, Linux, or Windows-via-WSL2. Native Windows is on
the backlog.
- **Owning your API keys** — bring your own Anthropic / OpenAI /
OpenRouter / local Ollama, never ours.
- **Working across multiple AI assistants** — Claude Code today,
Cursor on the plane, an OpenCode fork next month; the substrate
moves with you.
- **A workflow that learns while you sleep** rather than a tool you
restart every morning.
If you'd rather have a hosted multi-tenant SaaS with a polished web
UI and no CLI — this isn't that, and that's OK. Plenty of great tools
in that space. KeiSeiKit is for the other camp.
## What ships (run the command, get the number)
| Thing | Count | Verify |
|---|---|---|
| Rust crates (workspace) | 47 | `ls -d _primitives/_rust/*/ \| wc -l` |
| Tests green on `cargo test --workspace` | 801 | `cd _primitives/_rust && cargo test --workspace` |
| Agents | 12 | `ls _agents/kei-*.md 2>/dev/null \| wc -l` |
| Skills | 43 | `ls -d skills/*/ \| wc -l` |
| Hooks | 12 | `ls hooks/*.sh \| wc -l` |
| Behavioural blocks | 82 | `ls _blocks/*.md \| wc -l` |
| Capabilities | 11 | `find _capabilities -name text.md \| wc -l` |
| Roles | 7 | `ls _roles/*.toml \| wc -l` |
| Cross-tool bridges | 11 | `ls _bridges/*.tmpl _bridges/*.mdc 2>/dev/null \| wc -l` |
Counts regenerate from source via `scripts/regen-counts.sh`.
## Architecture in one paragraph
One hub crate (`kei-entity-store`) owns SQLite migrations, FTS
indexes, verb dispatch. Sibling store crates (chat, content, social,
crossdomain, task, scheduler) are thin shims over the hub — star
topology, zero sibling-to-sibling edges. DNA format is SSoT'd in
`kei-shared` (grep-verify: `grep -l "kei_shared::dna" _primitives/
_rust/*/src/*.rs`). Constructor Pattern is enforced pre-commit:
every file ≤ 200 LOC, every function ≤ 30 LOC. See
[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
## Verify everything works (60 seconds)
```bash
git clone https://github.com/KeiSei84/KeiSeiKit && cd KeiSeiKit
cd _primitives/_rust && cargo test --workspace
# Expect: test result: ok. 801 passed; 0 failed
cd .. && tests/substrate_integration.sh && tests/hook_wiring_integration.sh
# Expect: two PASS lines
```
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.
If both pass, the repo you're reading matches the repo I'm describing.
## What ships (verified counts)
## Compared to similar tools
- **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.
| | KeiSeiKit | LangChain | AutoGen | MCP alone |
|---|---|---|---|---|
| Local-first, no cloud required | ✓ | partial | ✓ | ✓ |
| Rust core, ≤ 2 MB binaries | ✓ | ✗ | ✗ | N/A |
| Per-run deterministic DNA | ✓ | ✗ | ✗ | ✗ |
| Git-fork work isolation | ✓ | ✗ | ✗ | ✗ |
| Three-phase nightly cycle | ✓ | ✗ | ✗ | ✗ |
| Capability-fragment prompts | ✓ | partial | partial | ✗ |
| Cross-tool bridges (Cursor, Zed, Aider, …) | 11 | ✗ | ✗ | ✗ |
| Works with OpenCode / OpenClaude clones | ✓ | ✗ | ✗ | ✓ |
| Enforced Constructor Pattern | ✓ | ✗ | ✗ | N/A |
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).
Sits alongside these tools, not a replacement. Uses MCP where MCP
fits; LangChain stays useful for its retriever zoo.
## Docs
@ -112,10 +252,9 @@ Build pipeline, cross-tool bridge mechanics, meta-composer internals, sleep-laye
| [CHANGELOG.md](./CHANGELOG.md) | What changed, version by version |
| [PLUGIN.md](./PLUGIN.md) | Anthropic plugin-format details |
## Authorship
## Author
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.
Built by Denis Parfionovich at KeiLab (`parfionovich@keilab.io`) while
running 4–8 parallel Claude Code terminals per day. Forks welcome.
## License
MIT. See [LICENSE](./LICENSE).
MIT License. See [LICENSE](./LICENSE).