# Philosophy — KeiSeiKit as a Living Neural Structure > The README claims KeiSeiKit is "a living neural structure." This document > is the long form of that claim: which biological properties we chose, > why, how each one maps to code shipped in this repo, and what the > tradeoffs are. --- ## The one-line thesis A software toolkit accumulates features. A living neural structure accumulates identity, memory, lineage, and the ability to recover from its own mistakes. KeiSeiKit is built around the second list. ## The five properties A neural system is distinguishable from a collection of functions by five properties. Each one is load-bearing — remove it and the structure stops being alive in the relevant sense. 1. **Identity** — each unit has a stable, reproducible name, not a random UUID or a human-friendly slug that drifts. 2. **Lineage** — each unit knows who produced it and from what. 3. **Memory** — the system remembers what it did yesterday, across restarts, across machines, across sessions. 4. **Consolidation** — memory is not raw logs; it is periodically replayed and compressed into patterns. 5. **Corrective learning** — mistakes the system notices in itself surface as explicit artefacts (rules, hooks, tests) the next session inherits. The rest of this document maps each property to the shipped code. --- ## 1. Identity — DNA Every agent invocation resolves to a deterministic variable-length string (≥33 chars; role + caps slugs are variable): ``` ::::::- ``` - `role` — role slug (e.g. `edit-local`, `research-web`). - `caps-bitmap` — the resolved capability list, encoded as ordered 2-char atom codes (`NG` = no-git-ops, `FW` = files-whitelist, `TG` = tests-green). - `scope-hash` — 8 hex chars (32-bit) of SHA-256 over canonicalised scope. - `body-hash` — 8 hex chars of SHA-256 over the task body text. - `nonce` — 8 hex chars of `rand::random::()`, full 32-bit entropy. The shape is enforced by `kei-agent-runtime::dna::parse`. Two invocations with the same role, capability set, scope, and task body produce the same `::::::` prefix, and differ only by nonce. That makes DNA both deterministic (for reasoning) and unique (for collision resistance — birthday threshold ≈ 65k agents per role+caps group). **Why not UUIDs.** A UUID hides what the agent was supposed to do. A DNA string is greppable: you can look at a ledger row and see the capability bitmap without joining five tables. **Why not slugs.** Slugs collide and drift. DNA is stable under renames because the role slug is part of the hash input, not a sidecar. Source: [`_primitives/_rust/kei-agent-runtime/src/dna.rs`](../_primitives/_rust/kei-agent-runtime/src/dna.rs). ## 2. Lineage — creator_id and fork_parent_id Every row in the agent ledger carries two additional columns: - `creator_id` — DNA or human id of whoever spawned this row. - `fork_parent_id` — DNA of the agent this row was forked from, if any. This is SQL-level lineage. Any artefact produced during a session can be traced back to the agent that produced it, to the agent that spawned *that* agent, to the human session the chain started from. **Why this matters.** Software without lineage produces "where did this file come from" questions at merge time. Lineage makes them disappear: the merge-ceremony skill prints the DAG and the human picks which forks merge, which squash, which defer. Schema: [`_primitives/_rust/kei-ledger/src/schema.rs`](../_primitives/_rust/kei-ledger/src/schema.rs) migration v4. ## 3. Memory — three layers The memory layer is deliberately three-tiered, mirroring the hippocampal + cortical split: 1. **Raw episodes** — session JSONL traces, append-only, one file per session. This is the hippocampus: fast, stateful, volatile (survives until the next full pull), not interpreted. 2. **Project memory** — `memory/{project}.md` one file per project, self-contained, constraints + stack + status + learnings with evidence grades. 3. **Index** — `MEMORY.md`, one line per project, ≤200 lines total. No inline data. Reading this file gives the shape of the world. Any session's "what did we decide last time" is a read of the corresponding project file, not a scroll through chat history. The index guarantees that read is fast. **Why this layering.** A single giant memory file stops being read because it cannot be scanned. A million tiny files stop being read because there is no entry point. Three layers — index → project file → raw traces — give you O(1) navigation to the right detail. Source: `~/.claude/rules/memory-protocol.md` (the full memory-protocol rule, reusable across projects). ## 4. Consolidation — REM and NREM Raw traces become patterns only if something replays them. KeiSeiKit's sleep layer runs in three phases on a nightly schedule: ### Phase A — Incubation ("sleep on it") During the day, you drop tasks into `/sleep-on-it`. Each task gets a priority (quick 15 min / standard 60 min / deep 240 min / marathon 480 min) and optionally a checkpoint cadence. At 03:00 local a remote Claude Code agent on Anthropic's cloud picks up the queue (up to 480 minutes total across ≤ 5 tasks, packed greedily in FIFO order) and works until the budget or checkpoint fires. Biological analog: the post-sleep insight gain documented by Wagner et al. 2004, *Nature* 427:352–355 [VERIFIED: doi:10.1038/nature02223]. The original paper showed that problems unsolved when you went to bed are sometimes solved on waking not because the brain ran harder but because it ran offline; the study did not isolate a specific sleep stage, and our metaphor is a loose mapping of that observation onto the kit's offline consolidation. ### Phase B — REM consolidation After Phase A, the same agent reads the last 24 h of JSONL traces, diffs them against the previous report, and writes `reports/sleep-YYYY-MM-DD.md`. Cross-session patterns (≥ 3 occurrences across ≥ 2 distinct sessions) are prepended to `backlog.md`. Biological analog: REM dream-state. Pattern extraction, not raw replay. ### Phase C — NREM deep sleep Every seven days (by default; configurable to zero to disable) the pipeline also runs `kei-conflict-scan` → `kei-refactor-engine` → optional `kei-graph-check`. The output is a **plan-only** markdown file or a **plan + fork** branch (`deep-sleep/YYYY-MM-DD`) with `git apply`-ready changes. Ambiguous conflicts are excluded from any auto-patch and listed explicitly for human decision. Biological analog: NREM slow-wave sleep. System-level consolidation. Integrating, not just reviewing. ### The no-feedback-loop invariant Nothing the cloud agent writes is ever auto-injected into a Claude Code session. The morning report is for human review. Any rule or hook that emerges from it is installed by hand via `/escalate-recurrence`. This is a deliberate architectural choice: auto-learning loops without human signoff are how models drift. Source: [`docs/SLEEP-LAYER.md`](./SLEEP-LAYER.md) and `~/.claude/rules/sleep-layer.md`. ## 5. Corrective learning — self-audit Three passive hooks run during any session: - `session-end-dump` — on Stop, archives the session trace and ingests it into `kei-memory`. - `milestone-commit-hook` — on `feat:` / `refactor:` / merge commits, appends a one-line summary to `audit-backlog.md`. - `error-spike-detector` — when three or more errors occur in the last twenty tool calls, tags the pattern. These feed the `/self-audit` skill, which classifies recurring problems and surfaces them via click-only `AskUserQuestion`. The user can route a finding to: - `/escalate-recurrence` — codify as rule + wiki + optional hook. - `/debug-deep` — 5-phase root-cause analysis. - hook-only — mechanical block / enforce / warn / remind. - backlog — log, surface next session. - postpone — keep open, resurface later. **Silent-first mode.** The first ten sessions log only — no prompts. This prevents false-positive fatigue while the memory store is still empty. Session 11 onward, the self-audit starts surfacing items. Source: `~/.claude/rules/session-self-audit.md` (RULE 0.14) and `skills/self-audit/`. --- ## Growth — the sixth property, emergent A substrate that satisfies properties 1–5 can support a sixth that is harder to design for directly: **growth**. New primitives, new blocks, new agents, new projects enter through user-driven commands and accumulate in a way the next session can find. - **New primitive.** `/compose-solution` decomposes a free-text problem, greps existing atoms for prior art, and drafts a block if nothing matches. The draft is persisted on user click, discoverable thereafter. - **New agent.** `/spawn-agent` emits a manifest + DNA + ledger row. The assembler hook rebuilds the markdown Claude Code picks up. - **New project.** `/new-project` is a 4-phase skill: intake, fork skeleton, parallel execution (orchestrator owns git per RULE 0.13), merge ceremony. Growth is not a feature we implemented. It is what the other five properties produce when you compose them. --- ## What this is not A neural network. The name "neural structure" is an analogy about properties (identity, lineage, memory, consolidation, corrective learning), not a claim about weights or gradients. Nothing in KeiSeiKit trains on your data. The cloud agent in the sleep layer is a standard Claude Code session with scheduled triggers — it reads your traces to write a report, not to fine-tune itself. A federation. As of v0.24, KeiSeiKit ships as a single-user substrate installed next to Claude Code. Cross-user signing, marketplace publishing of blocks, and federation are on the roadmap but not yet shipped. If a doc claims otherwise, that doc is stale. A framework. A framework tells you how to structure your application. A substrate gives your agents identity, lineage, memory, and sleep — nothing about it dictates the application. You can delete every skill in this repo and the substrate still works; you can also add fifty more and it still works. --- ## The constraints that shaped this Three constraints, made explicit because they push back against common defaults: - **Constructor Pattern.** One file, one class, one concern. Files greater than 200 lines are decomposed. Functions greater than 30 lines are split. No mixins, no DI containers, no abstract factories. This keeps the graph readable by both humans and Claude. - **Rust-first default.** New primitive code is Rust unless there is a cited exception (ML training > 10M params / existing-language project / platform UI / browser-DOM / one-off < 50 lines / external binding only / explicit user override). The reason is not performance — it is that the Rust type system catches the class of mistakes LLMs most often introduce (`None` vs `[]`, missing `.await`, unhandled `Result`) at compile time. - **Local-first.** Nothing is pushed anywhere by default. The sleep layer's memory-repo is user-owned, on whatever remote the user chose (or no remote — everything works locally). If these constraints feel restrictive, they are — deliberately. They are the shape of the substrate, not decorations. --- ## Further reading - [ARCHITECTURE.md](./ARCHITECTURE.md) — build pipeline + bridges + meta-composer - [SLEEP-LAYER.md](./SLEEP-LAYER.md) — Phase A / B / C in depth - [TAXONOMY.md](./TAXONOMY.md) — the seven-facet vocabulary - [SUBSTRATE-SCHEMA.md](./SUBSTRATE-SCHEMA.md) — atom contract - [WHY.md](./WHY.md) — the full origin story