diff --git a/README.md b/README.md index 5685899..10434fe 100644 --- a/README.md +++ b/README.md @@ -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). + ::::::- -- **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 ` 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//`, 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///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 () 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).