Agent Kaizen

---

Project Description

Agent Kaizen is an open-source, local-first engineering framework and harness for coding agents in VS Code and eventually other hosts, or maybe standalone. It is built around one idea of finely controlling agent output and maintaining all data in a reasonable manner, not a mess of JSONL files. Repo: https://github.com/LevyBytes/agent-kaizen.

flowchart LR
    S(["Scope"]) --> A(["Adapt"]) --> V(["Verify"]) --> M(["Manage"]) --> I(["Improve"])
    I -. "continual self-improvement" .-> S

Loading

SAVMI = Scope -> Adapt -> Verify -> Manage -> Improve

Note

This repo is an active foundation: it is usable now, but always evolving, and intentionally built as a reference harness that can be adapted into other projects. This work is independent and is not affiliated with or endorsed by OpenAI, Anthropic, Microsoft, GitHub, VS Code, Turso, or any other vendor. Although if my work helped you, I do accept donations for tacos and tea if you're feeling generous.

---

Why

I had three specific problems:

The controls were not deterministic. What an agent does varies with phrasing, context, and model. I wanted good code and consistent always followed behaviors. That's not how it works today unfortunately.

Subagents did not respect the sandbox. I watched them write outside the paths they were scoped to. And the more agents I ran at once, babysitting what they did became more troublesome.

I could not see what the models actually did. When something went wrong I wanted to read the sequence that produced it, not reconstruct it from a chat window that had already scrolled away.

So the project started from the assumption that if the work is not written down as it happens, in a form I can query, then it did not happen in any way I can rely on later.

---

Where the name comes from

I trained in judo from 1989 to 1996. The '90s was the last great decade for martial arts I think, in the USA anyway. I digress, something that stayed with me was the idea of kaizen. Continual, incremental self-improvement.

Later I trained to be a carpenter and mixed with some religious studies, the discipline of building on a foundation you have actually tested rather than one you assume, I think aptly applies to developing anything.

The agentic coding community is moving very fast, but most of what is being built by non-coders (like me tbh) is horrendous in differing ways. The foundation is usually a few sentences of "Make me..." instead of a day or two or more of going back and forth developing a whole blueprint of what needs to be done. Like any real world project.

This is what I set out to make with this project, a strong foundation that I and others can build from. That requires a set of thorough documents (concepts), to shape and frame everything from the planning to the implementation and testing.

---

The method

Andrej Karpathy's three layer approach was not sufficient for me, a lot of people respect him but to me he's an engineer without the same life experience I have. I have built skyscrapers with my union brothers and managed crews in capricious show business. I know how to build a thing or two with the best of them. Spec, verify, environment is not sufficient, it's only part of the puzzle. There-in comes my developing framework with a memorable acronym.

SAVMI is:

Scope

write the specification, and beat this step to absolute death with your main agents and other humans. This includes establishing documents that shape how your project(s) should be developed by your agents and humans. For this project see the docs folder for Architecture, Design, and Methods defining documents. These documents are the guiding light of your whole project(s).

Adapt

"Empty your mind. Be formless, shapeless, like water. Now you put water into a cup, it becomes the cup. You put water into a bottle, it becomes the bottle. You put it in a teapot, it becomes the teapot. Now water can flow, or it can crash. Be water, my friend."

— Bruce Lee

To just execute the SCOPE is not sufficient here, being flexible WHILE you execute is critical to getting a job done. There's more than one "right" way to get a job done within bounded constraints. Continually look for opportunities to do a better job at execution based on the previous SCOPE step. That is what ADAPT is about.

Verify

Mental ZERO trust, micro-managing people is not a good look, but AI agents are not people with emotions (yet) and you can not trust them to do their given jobs correctly for a number of reasons you can go down a rabbit hole for hours about. So every single step needs deterministic verification if possible, and human intervention where practical. VERIFY is a critical step to stop the slop from getting out into the world.

Manage

This is a big one and missing from a lot of videos on the topic of "agentic frameworks". No one bothers to really dive into how you MANAGE your data and the pipelines. Imagine if you were running a business where every second you have multiple pages worth of dense writing of important information you need to track, just slapped onto your desk. And every second that goes by that continues to pile up faster than you can understand what is on the page let alone having time to file them away or retrieving what you need later. I don't know about you but I like neat and tidy even when there is absolute chaos unfolding. There-in good MANAGEMENT comes to save the day. Instead of a bunch of messy condensed JSONL files (what OpenAI and Anthropic use today) recording what happens, I wanted everything database managed and user retrievable and the biggest part HUMAN readable and retrievable. Standard keyword searches are not enough for retrieving relevant things as the data storage grows, so I took a play out of the RAG buzzword and applied it to the database for finding similar structures indifferent to keywords. EG vector embedding and reranking. What about multiple machines working on the same project? Fleet management, done. Not quite to Kubernetes functionality yet but the sky is the limit if this project is liked enough to be contributed to. So, that's the MANAGEMENT layer and it is absolutely critical like the rest of the layers.

Improve

Here-in is Kaizen. Continual self-improvement. Just as the ADAPT layer demands flexibility, so does this looping layer of IMPROVE. Every sprint run or code pass, do a retrospective and see what could have been done better and if time permits do a SWOT analysis of the completed run. I started with an idea of using GOTCHA (errors to investigate) to LEARNING (approved by human to investigate) to LEARNED (verified by both agent and human and approved for durable rule or lesson), with lineage. But that in itself is insufficient and is a band-aid of the real problem of a lack of deterministic controls for agents. IMPROVE is more than just improve results, it's a whole retrospective framework layer on finding ways to improve and then start again with those ideas to be tested and proven useful or not.

---

What is in this Agent Kaizen?

• A deep multioperational CLI (kaizen.py) over a local control plane on stdlib sqlite3 in WAL mode: tasks, plans, proofs, evaluations, evidence ingestion, traces, reports, private policy — shared by every agent host you point at it.
• A read-back layer for session continuity: session digest, policy context, lesson lineage, verification queries, score trends. This is what an agent reads at the start of a session instead of being told to remember.
• Optional Turso-backed vector shards for semantic search.
• The current supported release scope runs core, platform, and slow on genuine Windows; core and platform run automatically in owner-triggered remote CI after a push, while slow remains manual. Genuine Linux and the VS Code extension are in development and run only when explicitly selected.
• Optional backends, all off by default: llama.cpp, Ollama, ComfyUI, vLLM, sentence-transformers.
• Local and private by design. But can be adapted to server hosting across the whole SAVMI framework.

Current supported release platform: Windows.

---

Where it stands

I am a problem solver by skill set, not a disciplined software developer. The architecture, the contracts and the methods I believe work; the starting implementation has been built with heavy agent assistance under those contracts, which is rather the point of the project. It is a large codebase for one person and there are areas that deserve a more experienced eye than mine, particularly the concurrency and recovery paths.

Contributions, review and criticism are genuinely welcome, especially from people who have run agent fleets and know where this sort of thing breaks. See the contributions document which defines the acceptable standards for PRs. Feel free to adopt this contributions file if you never made a contributions document on GitHub before. After being on the platform since 2013, this project was the first time I used one. Standards are good to have.

---

Benchmarks Preview

Proof is in the pudding: record writes land in under 30 ms, a full session-start digest reads back in ~0.11 s at 5,000 records, and restoring context from records is ~28× cheaper than replaying a session transcript — measured, repeatable, on your machine: see Benchmarks.

Contents

• Agent Kaizen
  • Project Description
  • Why
  • Where the name comes from
  • The method
  • What is in this Agent Kaizen?
  • Where it stands
  • Benchmarks Preview
  • Contents
  • Reading Path
  • The Kaizen System
  • How The Repo Maps To The System
  • What This Repo Provides
  • Harness Daemon And VS Code Controller
  • Why Not Just Built-In Agent Memory?
  • Does It Actually Pay Off?
  • Why AGPL
  • Requirements
  • Setup
    • Quickstart
    • Manual setup (any OS)
    • PowerShell
    • POSIX Shell
    • Optional: Markdown formatting
  • Testing
  • Benchmarks
  • Daily Workflow
  • Your First Ten Minutes
  • Complete Command Index
  • Local Database And Backend
  • Adopting Agent Kaizen In A Project
    • Use This Harness Directly
    • Adapt The Shape Elsewhere
    • Link The Shared Engine (one codebase, many projects)
  • Skills Store
  • Agentgateway
  • Optional Backends
  • FAQ
  • Public Repository Safety
  • Contributing
  • License

Reading Path

• New to the idea: read this intro, then Kaizen_System.md.
• Installing it: download and run the one-file installer for your platform from the repo's setup/ folder (see Setup below).
• Using this repo with an agent: have your agent read setup/SETUP.md, then Daily Workflow.
• Using the optional auxiliary utilities: read support_scripts/README.md.
• Adapting the system elsewhere: use Adopting Agent Kaizen In A Project as the starting point.

The Kaizen System

A memorable mnemonic because every good and bad idea has one:

SAVMI = Scope -> Adapt -> Verify -> Manage -> Improve

Layer	Job	Typical outputs
Scope	Understand intent and evidence	Iterative Spec, assumptions, acceptance criteria
Adapt	Change the system through bounds	Execution contracts, patches, scripts
Verify	Decide if the work can proceed	Go/no-go result, proof, findings
Manage	Preserve and govern work data	DB records, hashes, reports, policy context
Improve	Decide what to improve next	Retrospective, next-cycle priorities

The master concept document is Kaizen_System.md. This README explains the repo that implements it.

How The Repo Maps To The System

Surface	Role
Kaizen_System.md	Portable method for humans and agents
kaizen.py	Deterministic write path for managed records
AI/db/	Local data plane: DB, exports, manifests, backups
evals/	Command stubs plus portable eval and learning surfaces
AGENTS.md, CLAUDE.md	Compact host instructions that point to the manuals
setup/	Install/bootstrap scripts and the agent manual SETUP.md
.agents/skills, .claude/skills	Junction surfaces to external skill packages
kaizen_components/	The shared engine package behind kaizen.py
tests/	Tests, benchmarks, verification, and acceptance sources
support_scripts/	Auxiliary helper scripts; scratch belongs under AI/
kaizen_components/orchestration/	Supervisor, policy snapshots, adapters, hooks, and replay
extension/	VS Code sidebar/popout controller over the local daemon

The important split is simple:

Kaizen System = the method.
Kaizen harness = this repo's local implementation.
Kaizen DB = the durable record store for managed work data.
Markdown = public docs, command stubs, generated views, or exported reports.

flowchart LR
    CC["Claude Code"] --> CLI["kaizen.py"]
    CX["Codex"] --> CLI
    CLI --> ENG["kaizen_components/ engine"]
    ENG --> DB[("AI/db/kaizen.db")]
    DB -->|"read-back: R0, X5, L10, Q9, T4"| NEXT["next session"]

Loading

Every agent host writes through one CLI into one database; the next session — whichever agent runs it — starts from records, not recollection.

What This Repo Provides

• Shareable system documents for agentic coding workflows.
• A local data plane backed by a direct-file stdlib-sqlite3 database, with Turso vector shards alongside it. SQL go Brrrrrrrr
• A single CLI entrypoint, kaizen.py, for structured writes and reports.
• Command families for tasks, plans, ledgers, proofs, evals, source locks, artifacts, IRL Review, anti-patterns, learning records, evidence ingestion, activity traces and eval scores, and the improvement lab.
• Project and skill evals/ surfaces for command stubs and portable eval fixtures.
• VS Code project-shape guidance for Codex, Claude Code, and similar coding agents.
• Deterministic scripts that move repetitive mechanics out of the model context window.
• A transcript-mining helper (support_scripts/mine_transcripts.py) that drafts GOTCHA candidates from your own agent session logs — read-only on transcripts, human-reviewed, and promoted only through the normal G1 write gate.
• A multi-turn supervisor conversation with durable event replay, immutable permission profiles, and exactly one successful finalization on explicit close.
• An in-tree, zero-runtime-dependency VS Code controller development foundation with normal editor-tab conversations, durable daemon replay, governed tools, Audit Output, and capability-gated workflow views; it is not release-ready for public use.

Inside the engine

What this shows. How a command entered at kaizen.py reaches a record, and how the four long-lived process classes named by the architecture contract — the on-demand engine, the fleet plane, the per-corpus vector funnel, and the model backends — hang off that same tree. Read it top to bottom: boundary, entry, dispatch, the command families, the data plane.

flowchart TD
  subgraph EDGE["Boundary - same four nodes as diagram 2"]
    B_CLI["CLI read path - python kaizen.py OP --json"]
    B_LOOP["Loopback JSON-Lines control channel"]
    B_SPAWN["Process spawn - kaizen.py daemon run"]
    B_STDIN["Stdin bridge - kaizen.py profile-store"]
  end

  subgraph ENTRY["Entry and dispatch"]
    MAIN["command_dispatch/records.py main - argv intercept"]
    ARGS["args.py, args_support.py, command_dispatch/parser.py - REGISTRY and ALIASES"]
    DISP["command_dispatch/dispatch.py - the op-code table"]
    DCLI["orchestration/daemon_cli.py - run, status, control verbs"]
    PSTORE["composer_profile_store.py, composer_profile_persistence/"]
  end

  subgraph OPS["Record operations - one box per command family"]
    RWORK["Work and lesson records - W G L"]
    RQUAL["Quality, policy, reports - Q A S I X R M"]
    RRUN["Run and session ledger - T C1-C6"]
    RREAD["Zero-process session reads - C7-C10"]
    REVID["Evidence plane and improvement lab - E O"]
    RSKILL["Skill context - SK"]
    RGEN["Generative runs - Y"]
    RQ11["Code audit - Q11"]
    RQ12["Code vectors - Q12"]
    RMODEL["Model plane - B C11"]
    RDB["Database lifecycle and recovery - K"]
  end

  subgraph ENGINE["orchestration/ - the on-demand engine"]
    SUP["supervisor_core.py, supervision/ - boot, control routing, children"]
    LOOPSRV["loopback.py, loopback_transport/ - server and client"]
    ADAPT["adapters/ - claude_sdk, claude_cli, codex, local_llm"]
    TGATE["tool_gateway.py, tool_gateway_operations/ - policy and approval chokepoint"]
    IOSTORE["model_io_store.py, provider_io_store.py"]
    WFLOW["workflow_service.py, workflow_contract.py, workflow_history.py"]
  end

  subgraph FLEETP["fleet/ - fleet and multi-machine plane"]
    FREC["records.py, store.py, reducers.py - D ops"]
    FHTTP["control_http.py - tailnet control service"]
    FLEASE["coordination_leases/, coordination_store/"]
  end

  BACK["backends/ - ollama, openai_compat, transformers, sentence_transformers, cross_encoder, gliner_pii"]

  subgraph DATA["Data plane"]
    DBM["db.py, db_schema modules, database_lifecycle/, db_recovery/"]
    KDB[("AI/db/kaizen.db - control database, ARC-024")]
    FDB[("AI/db/fleet.db")]
    VREG["vector_registry.py - corpus catalog rows"]
    VSTORE["vector_store.py - the sole client seam to vector data, ARC-054"]
    VFUN["vector_funnel.py - one funnel process per corpus, ARC-055"]
    VSHARD[("AI/db/vectors/ - per-corpus shard")]
  end

  FOUND["Foundations - paths, denials, hashing, redaction, schemas/, output, db_retry"]

  B_CLI --> MAIN
  B_STDIN --> MAIN
  B_SPAWN --> DCLI
  B_LOOP --> LOOPSRV

  MAIN -->|"daemon"| DCLI
  MAIN -->|"profile-store"| PSTORE
  MAIN --> ARGS
  MAIN --> DISP
  ARGS --> DISP
  DCLI --> SUP
  DCLI -->|"status, steer, approve"| LOOPSRV

  DISP --> RWORK
  DISP --> RQUAL
  DISP --> RRUN
  DISP --> RREAD
  DISP --> REVID
  DISP --> RSKILL
  DISP --> RGEN
  DISP --> RQ11
  DISP --> RQ12
  DISP --> RMODEL
  DISP --> RDB
  DISP --> FREC

  LOOPSRV --> SUP
  SUP --> ADAPT
  SUP --> IOSTORE
  SUP --> WFLOW
  SUP --> FREC
  ADAPT --> TGATE
  ADAPT --> BACK
  ADAPT --> IOSTORE

  FHTTP --> FREC
  FLEASE --> FREC
  FREC --> FDB

  RWORK --> DBM
  RQUAL --> DBM
  RRUN --> DBM
  RREAD --> DBM
  REVID --> DBM
  RSKILL --> DBM
  RGEN --> DBM
  RQ11 --> DBM
  RMODEL --> DBM
  RDB --> DBM
  RQ12 --> DBM
  IOSTORE --> DBM
  VREG --> DBM
  DBM --> KDB

  REVID --> BACK
  RMODEL --> BACK
  REVID --> RQ12

  RQ12 --> VSTORE
  VSTORE --> VREG
  VSTORE --> VFUN
  VFUN --> VSHARD
  VSTORE -.->|"reuses transport"| LOOPSRV
  VFUN -.->|"reuses transport"| LOOPSRV

  ARGS -.-> FOUND
  SUP -.-> FOUND
  DBM -.-> FOUND

Loading

What each record-operation box is

Box	Modules	Dispatch evidence
Work and lesson records	task_records.py, plan_records.py	command_dispatch/dispatch.py:144-173, args_support.py:18, args_support.py:35
Quality, policy, reports	proof_artifacts.py, policy_records.py, contract_lint.py, reports.py, markdown_exports.py, migration_learning.py	dispatch.py:191, dispatch.py:199-200, dispatch.py:436-458, args_support.py:19-20, args_support.py:34, args_support.py:47
Run and session ledger	trace_records.py, agent_runs.py + agent_run_state/, session_records.py + session_record_store/	dispatch.py:213, dispatch.py:224, dispatch.py:235
Zero-process session reads	orchestration/session_reads.py + orchestration/session_read_model/	dispatch.py:256-259
Evidence plane and improvement lab	evidence.py + evidence_store/, lab.py, dedup.py	dispatch.py:337, dispatch.py:348, dispatch.py:359
Skill context	skill_context.py + skill_context_management/	dispatch.py:113-114
Generative runs	comfyui.py, comfy_runtime.py, comfy_mcp.py, comfyui_workflows/	dispatch.py:364, dispatch.py:389, dispatch.py:394
Code audit	code_line_audit.py facade over code_audit/ and the code_line_audit_* modules	dispatch.py:203-204, code_line_audit.py:5
Code vectors	code_vectors/	dispatch.py:207-208
Model plane	model_ops.py, model_index.py, model_monitor.py, pii_scan.py, backend_registry.py, model_catalog.py	dispatch.py:399, dispatch.py:410, dispatch.py:415, dispatch.py:420, dispatch.py:425, dispatch.py:298
Database lifecycle and recovery	db.py, database_lifecycle/, db_recovery/	dispatch.py:67-107, dispatch.py:86-87

What this diagram deliberately omits

It omits roughly 290 of the 320 Python modules. orchestration/ alone holds 199 files and appears as six boxes; fleet/ holds 26 and appears as three.

It omits the repository's pervasive facade / support / fragment-package pattern, because showing it once per component would triple the node count without changing the shape. The pattern is: X.py is the public facade, X_support.py holds shared primitives, and X_store/, X_state/, X_management/, or X_operations/ holds bounded implementation fragments that the facade re-exports. Seen in session_records.py:63, agent_runs.py:49, evidence.py:47, skill_context.py:39, composer_profile_store.py:62, args.py:5-99, db.py:46, loopback.py:44, and tool_gateway.py:5-8.

It omits the foundation edges. paths, denials, hashing, redaction, schemas/, output, and db_retry are imported by almost every box; three dotted edges stand for what is really more than a hundred.

It omits control flow inside a turn — the adapter event stream, the reducer snapshot cadence, retry and lease behaviour — and it omits every test module, setup/, support_scripts/, and evals/.

It omits process lifetime. A box is a component, not a process. Only four boxes ever become their own OS process: the supervisor engine, the fleet daemon behind control_http.py, one vector_funnel.py per corpus, and a short-lived kaizen.py CLI invocation.

Harness Daemon And VS Code Controller

The controller development foundation is in extension/. It remains under active development, is not release-ready for public use, and runs in GitHub Actions only through an explicit manual development selection. Each editor-tab conversation has its own controller while the daemon remains authoritative for transcript and policy state. Closing a renderer does not stop its daemon run, and reopening receives a complete snapshot rebuilt from durable events. The sidebar remains the approvals, sessions/timeline, and fleet/engines navigator rather than a second chat surface.

Exact SDK-boundary model input, output, callback, control, and user-revision payloads are stored unencrypted in plaintext BLOBs in the local Kaizen database before the next Kaizen-controlled boundary. Those rows may contain prompts, responses, tool requests, and tool results, so keep AI/db/kaizen.db private and protect it like source-bearing session data. The model-I/O store does not hold vendor credentials, does not parse vendor authentication files, and does not substitute redacted bytes for bytes sent to a provider.

The conversation lifecycle is deliberately longer than one model turn:

open -> running -> idle -> running -> ... -> explicit close -> terminal

One C1 session and one T5 run remain open across turns. Complete redacted user and final assistant messages are written as chat_message/point events. A successful T8 is written only by session/close; kill, fatal errors, shutdown, and orphan recovery write a non-success finalization. The UI persists only session_id, agent_run_id, and profile_hash, never transcript text, API keys, approval secrets, or Full-mode confirmation.

The equivalent CLI surface is scriptable:

python kaizen.py daemon session capabilities --json
python kaizen.py daemon session start --engine local_llm --prompt "First turn" --permission-mode plan --json
python kaizen.py daemon session turn --run <agent_run_id> --prompt "Second turn" --json
python kaizen.py daemon session close --run <agent_run_id> --json

Engine selectors come from session/capabilities; claude_cli is normalized to the public claude ID. An engine remains visible but non-drivable when the installed vendor version cannot enforce the requested permission boundary. There is no silent downgrade: unsupported profiles return structured denials. Claude uses only a separately installed, pinned official SDK runtime and a pre-existing vendor-managed subscription identity. The UI never accepts credential text, Kaizen never reads vendor credential files, and there is no Claude API-key fallback.

Claude requires an explicit model selected from the live supportedModels() catalog. Reasoning effort is sent only when the user explicitly selects a value advertised by that model; an omitted choice remains Provider default and sends no effort field. A removed model or effort fails before a provider call while preserving the complete composer envelope.

Claude runtime management is explicit and never occurs when the daemon or extension starts. Setup installs it only when selected with Windows -WithClaudeRuntime, POSIX --with-claude-runtime, or AK_WITH_CLAUDE_RUNTIME; the default is off and CLI selection overrides the environment. The selection remains effective with -NoDevTools / --no-dev-tools because it is a provider-runtime choice, requires the exact managed Node/npm pair under DEVROOT, and performs no login or credential setup. check is offline and emits only a path-free capability result; install is enabled only when the repository contains an exact audited lock, keeps npm cache/config/temp and the versioned runtime under local managed roots, and reuses a valid warm runtime without package-manager work:

python setup/claude_runtime_setup.py check
python setup/claude_runtime_setup.py install

An explicitly selected warm runtime succeeds under -NoNetwork / --no-network; a selected cold setup fails before npm. install fails closed when the audited lock, bundled native dependency, exact managed Node/npm installation, or post-install integrity checks are unavailable. It performs no login and handles no credentials. The VSIX contains none of the SDK, native runtime, worker source, node_modules, caches, or runtime pointers.

Publication risk (guidance reviewed 2026-07-12): Anthropic documents subscription-backed Agent SDK use while separately cautioning third-party developers against routing Free/Pro/Max credentials. Kaizen does not open or route credential files, but public distribution of this existing-subscription workflow still requires owner/legal review against the then-current Claude plan SDK guidance and authentication/legal guidance. This is a release-risk disclosure, not a claim of legal clearance.

The installed extension uses its normal editor tabs and starts the daemon only through a visible user-stoppable terminal. Exact /workflows opens a same-tab workflow view without sending that composer text to Claude; ordinary prose containing the token remains ordinary chat. Workflow launch, status, Stop, pause, resume, restart, save, rerun, script editing, external discovery, and private transcript scanning each have an independent capability result. A route appears authoritative only after its exact bounded proof succeeds; unsupported or unproven routes remain visible with their reason, and external discovery remains read-only observation rather than Kaizen-owned state.

Current workflow limitations are explicit: owner-present authenticated acceptance has not been run, so the offline suites do not prove launch, status, Stop, or Restart against the installed pinned runtime. Resume, Restart, and Rerun now stage exact immutable source through a two-phase ready/accepted/release boundary so no successor callback can precede durable intent acceptance. Restart can become available only after one completed successor produces an exact durable production proof over its predecessor, intent, callback, provider identities, terminal ModelIO, and zero unexpected top-level callbacks. Pause remains unavailable because the pinned Query exposes no pause/checkpoint primitive; Resume and Rerun remain unavailable because the runtime produces no truthful checkpoint/cache evidence, and Kaizen does not synthesize those facts. Save/edit can become available only after immutable revision commit and revalidation; external discovery/private transcript scanning can become available only as bounded read-only observation. The effective 2026-07-18 D10/D11 owner amendment excludes Pause, selected-agent control, and Resume/Rerun fidelity proof from v6 closeout while no truthful supported SDK route exists; they remain visibly unavailable and cannot be relabeled or synthesized. Applicable bright-route proof and separately owner-authorized installed/live acceptance remain required.

Claude sessions started outside Kaizen can be captured from the point the workspace hooks are installed:

python kaizen.py daemon hooks install --mode hooked-observe --json
python kaizen.py daemon hooks verify --json

Observed conversations reuse one C1 across host lifecycles and attach ordered T5 runs for startup/resume. UserPromptSubmit records the complete user message, Stop uses last_assistant_message, and no transcript JSONL is parsed. Observed conversations and their approval records are strictly display-only in the UI.

The controller is an application-layer mediation system. Vendor sandboxes and supported approval channels are the enforcement backbone; hooks add defense in depth. Genuine OS/user/container isolation, hostile native programs, computed-path escapes, and kernel-level containment belong to a later isolation layer.

Existing-target proposal modify, delete, and rename operations use the verified bounded crash-recovery path on Windows. A platform without equivalent proven primitives denies those operations before mutation; retained recovery artifacts support exact restart reconciliation, not filesystem transactionality, rollback, or broad OS containment.

Why Not Just Built-In Agent Memory?

Because memory and evidence are different problems. First-party agent memory — auto-generated notes, insights, per-project memory files — is good at carrying preferences and context between sessions, and Agent Kaizen does not compete with it. What it does not carry is anything you can audit: whether a claim was verified, by what command, with what result; what the agent predicted before the work versus what actually happened; which recorded "lessons" were ever validated before being treated as fact.

Agent Kaizen keeps those as structured records in one local database:

• Verification records with explicit go/no-go conclusions (Q2, queried with Q9), linked to tasks and proof artifacts with hashes.
• A gated lesson path: agents record GOTCHAs freely, but promotion to LEARNING and LEARNED is a deliberate, recorded act with full lineage (L2/L3, read back with L10) — validated first, durable second.
• IRL Review records that pair predictions with observed outcomes (I1-I5), so calibration is measurable instead of anecdotal.
• Private policy context in the DB, not in tracked docs (X*), so operational rules never land in a public repo.
• One database and one CLI for every agent host you use — records written in a Claude Code session are read back in a Codex session, and vice versa.

	Built-in agent memory	Rules & instruction files	Agent Kaizen
What it carries	Preferences, context notes	Standing guidance	Structured work records
Verified or asserted	Asserted by the agent	Asserted by the author	Verification conclusions with evidence
Queryable later	Rarely	No — static text	SQL-backed queries and reports
Across agent hosts	Per-product silos	Per-file copies	One DB, one CLI, every host
Lessons	Auto-noted, unvalidated	Hand-curated	Gated promotion with full lineage

Built-in memory is a fine consumer of these records: the session digest (R0) is one small JSON payload designed to be read at session start by any agent. The records themselves need a deterministic write path, schema validation, and redaction gates — which is what this harness is.

Does It Actually Pay Off?

One real chain from the database this repo was built with:

1. Recorded. During a concurrency test, parallel K1 processes failed at connect — the retry logic did not recognize the storage engine's Windows file-lock error. The failure went in as GOTCHA g_20260703083749_7af0ead4be with the evidence attached.
2. Validated, then promoted. The fix shipped with a regression test that reproduces the race; only then was the GOTCHA promoted through L2/L3 into LEARNING l_20260703083759_4ea0351f7e and LEARNED ld_20260703083810_2b4b61a94f, and the source GOTCHA was marked promoted.
3. Paid back. Later sessions did not rediscover any of it: R0 surfaces recent LEARNED lessons at session start, and L10 still returns the full GOTCHA → LEARNING → LEARNED lineage on demand. The harness's own error messages join the loop too — when a later session called W2 with the wrong flag, the denial arrived carrying its own copy-paste fix, a feature that exists because earlier command-line pain was recorded instead of forgotten.

Those ids are real records, not staged examples. The loop documented in this README is the loop that built this repo.

Why AGPL

This project is AGPL-3.0 on purpose. The license exists to help individuals and small teams — not major corporations that take open source work, wall it off behind a service, and give nothing back. That violates the spirit of open source, and the AGPL is the license that says so with teeth. If you improve this harness and offer it to others, those improvements stay open for everyone.

What it means for you in practice:

• Using Agent Kaizen to manage your projects does not make your projects AGPL. The license covers this harness's code — not your code, not your records. Your DB is yours.
• Clone it, adapt it, link the engine into private repos — all fine.
• The share-back obligation triggers only if you distribute a modified harness or run it as a service for others.

This is a plain-language summary, not legal advice — see LICENSE for the actual terms.

Requirements

• Windows 10+ with PowerShell 5.1+ is the current supported release environment. The POSIX setup path remains available for in-development Linux/macOS evaluation, not as a supported-platform claim.
• Python 3.12 or newer with venv support (the installers can install it for you). 3.12 is the CI-tested baseline; the installers require at least 3.12.
• git 2.20+.
• ~2 GB free RAM for the core harness; a single GPU with 12 GB VRAM for the existing optional PyTorch/Ollama backends, or 16 GB VRAM for the quality-first unquantized Q12 Qwen3 code-vector profile.

Setup

Quickstart

For the supported release path, download the setup bundle for Windows and run it. The Linux/macOS launcher remains available for explicit development evaluation. On a bare Windows machine the installer provisions DEVROOT-managed Git, GitHub CLI (gh), and Python by default, clones this repo, builds the shared venv, generates the VS Code workspace and launcher, scaffolds an empty sibling skills store, and initializes the local DB. Everything lives under a parent folder you choose, called DEVROOT:

DEVROOT/
|-- agent-kaizen/          the cloned repo
|-- Git/                   managed PortableGit (default)
|-- GitHubCLI/             managed gh (default; independently selectable)
|-- SKILLS/                sibling skills store (empty by default)
`-- Python/
    |-- Python312/         managed Python
    `-- venvs/kaizen/      shared Python venv

Windows — download or clone the repository so the complete setup/ bundle remains together, then run Install-Agent-Kaizen.cmd. It always opens a dedicated, clearly titled elevated Windows PowerShell 5.1 window for an interactive install (approve the UAC prompt — admin is needed to bootstrap winget/App Installer and an optional build toolchain). The defaults are hash-pinned PortableGit under DEVROOT\Git, hash-pinned gh under DEVROOT\GitHubCLI, and Python under DEVROOT\Python; detected system tools and GitHub Desktop are not silently selected. The PowerShell window explains each ownership choice before asking:

curl.exe -L -o agent-kaizen-main.zip https://github.com/LevyBytes/agent-kaizen/archive/refs/heads/main.zip
Expand-Archive .\agent-kaizen-main.zip -DestinationPath .
.\agent-kaizen-main\setup\Install-Agent-Kaizen.cmd X:\dev

A downloaded archive carries the "mark of the web", so SmartScreen may warn the first time — choose More info → Run anyway or unblock the archive before extracting it.

The vector-shard engine ships as the pyturso distribution, which Agent Kaizen imports as turso; it is a required core dependency. A compatible prebuilt Windows wheel is the no-local-Rust route (drop it in DEVROOT\wheels or pass -PyTursoWheelUrl together with its required -PyTursoWheelSha256). Without one, pip compiles pyturso from source and needs Rust + Visual Studio Build Tools (a multi-GB download); .NET / CMake / Node.js / VS Code remain separate optional tools. See setup/SETUP.md for details.

Linux / macOS development path (in development, not a supported release claim) — download install-agent-kaizen.sh and run it (it installs git + Python 3 via your system package manager — apt/dnf/yum/pacman/zypper, or Homebrew on macOS; sudo where needed):

curl -L -o install-agent-kaizen.sh https://raw.githubusercontent.com/LevyBytes/agent-kaizen/main/setup/install-agent-kaizen.sh
bash install-agent-kaizen.sh "$HOME/dev"

Warm reruns validate exact managed tools and dependencies before skipping work, but a failed run may already have applied earlier validated changes; review DEVROOT\agent-kaizen-setup\setup-state.json and its logs before rerunning. Windows uses its hash-pinned PortableGit fallback when winget is unavailable and downloads managed Python from python.org; it does not silently switch to a detected system Git. An existing valid repository is reused without fetching by default (-UpdateExisting opts into fetch plus fast-forward). On Linux/macOS run bash setup/setup.sh [DEVROOT]; on Windows run setup\Install-Agent-Kaizen.cmd.

Try it in Windows Sandbox first (optional). A generic template is included at tests/windows-sandbox-template.wsb — launch it to test the installer in a throwaway VM. The one thing a fresh Windows 11 sandbox needs is Smart App Control disabled, which the template's logon script does automatically (SAC Enforce otherwise blocks the per-user Python install). Keep any folder mappings minimal.

Installer planning and diagnostics:

.\Install-Agent-Kaizen.cmd X:\dev -ListSteps -NoPause
.\Install-Agent-Kaizen.cmd X:\dev -PlanOnly -NoNetwork -NoExternalActions -NoUserEnvWrites -EmitPlanJson X:\dev\agent-kaizen\AI\work\<run-id>\installer\installer-plan.json -NoPause
.\Install-Agent-Kaizen.cmd X:\dev -SelfTest -NoNetwork -NoExternalActions -NoUserEnvWrites -NoPause

bash install-agent-kaizen.sh "$HOME/dev" --list-steps
bash install-agent-kaizen.sh "$HOME/dev" --plan-only --no-network --no-external-actions --no-user-env-writes --emit-plan-json "$HOME/dev/agent-kaizen/AI/work/<run-id>/installer/installer-plan.json"
bash install-agent-kaizen.sh "$HOME/dev" --self-test --no-network --no-external-actions --no-user-env-writes --no-input

The one-file installers also accept -RepoSource / --repo-source for local-source testing, -Ref / --ref to pin a tag or branch, -NoPrompt / --no-input for deterministic non-interactive runs, and -AssumeYes / --assume-yes for explicit non-interactive acceptance. Duplicate apply on either platform requires interactive confirmation or that explicit assume-yes flag; no-input/no-prompt alone does not authorize mutation. A duplicated project chooses extension link or copy ownership with Windows -ExtensionMode or POSIX --extension-mode; copy mode additionally requires a unique publisher.name and display name through -ExtensionId / -ExtensionDisplayName or --extension-id / --extension-display-name. They write progress logs and setup state under DEVROOT/agent-kaizen-setup/ (DEVROOT\agent-kaizen-setup\ on Windows). Long native commands write individual command logs under logs/; downloads show byte counts, percent, throughput, and ETA when the server publishes a total size. Package managers that hide totals still show elapsed time and recent output.

The installer records the validated source master in the flat local file DEVROOT/agent-kaizen-setup/kaizen-extension.json with exact shape {"version":1,"masterProject":"$DEVROOT/<folder>"}. The extension first accepts a fully seeded open workspace; otherwise it resolves this configured master. The resulting kaizenRoot owns kaizen.py, Python selection, the database, runtime, protocol, and visible daemon terminal, while the immutable activation workspaceRoot remains authoritative for source, context, diffs, process working directory, and workspace policy. Daemon capabilities must attest that exact root and every successful start must echo it; missing or mismatched proof leaves the complete composer envelope retryable and binds no conversation. One master daemon is bound to one configured workspace at a time; after switching to another governed workspace, stop the old visible daemon and start it for the new root.

Duplicate plan-only output classifies the project as ABSENT, MANAGED, or FOREIGN, reports extension state, and names the exact create/no-op/convert/deny action with zero DEVROOT mutation unless a plan-JSON path is explicitly requested. Source discovery prefers the explicitly named project, otherwise accepts one eligible renamed direct child including a dot-prefixed child, and denies ambiguity. A matching managed rerun preserves copied docs/setup, wrapper, DB, skills, workspace, extension customization, and any retained recovery link. Link-to-copy stages, filters, rewrites, and verifies a sibling copy, exclusively renames the active master link to a random sibling quarantine, verifies the moved object, and only then commits the copy; an occupied destination preserves both the racer and quarantine and reports RECOVERY REQUIRED. A successful conversion retains exactly one dot-prefixed inactive .extension.ak-link-* exact-master recovery link and prints its path; warm NOOP_COPY creates no additional artifact. Portable handle-bound deletion is unavailable across supported installer paths, so cleanup is an explicit owner-controlled filesystem action instead of an automatic pathname deletion that could race. Copy-to-link is denied. Copy IDs and display names must differ from the master and every valid visible or dot-prefixed direct-child DEVROOT/<project>/extension/package.json; a present manifest in an enumerated direct-child project fails closed when malformed, unreadable, or colliding, and foreign/reparse target topology also fails closed. The installer does not inspect or write VS Code profiles, so validate the copied publisher.name when installing its VSIX because an identical installed ID is replaced rather than installed beside itself.

Windows Sandbox guidance: pass an explicit writable DEVROOT and keep the installer source mapping read-only if desired. The Windows installer resolves DEVROOT before tool bootstrap, logs under that root, attempts App Installer registration, tries Microsoft.WinGet.Client repair, then falls back to direct App Installer package download. If App Installer was installed but the current terminal still cannot invoke winget.exe, close that setup window, open a fresh terminal or restart the sandbox session, and rerun the same command.

Pin to a released version (optional, recommended for a reproducible install). By default the installer tracks the tip of main. To install and stay on a specific reviewed release instead, pass a git tag: on Linux/macOS AK_REF=<tag> bash install-agent-kaizen.sh, on Windows .\Install-Agent-Kaizen.cmd -Ref <tag>. Re-runs then check out that tag rather than following main. Already cloned? Run git checkout <tag> in the repo, then re-run setup/setup.sh.

Skills ship empty; add a store of your own with setup/link-skills.ps1 or setup/link-skills.sh. The local policy DB also starts empty by design — add your own rules with kaizen.py X1 and load them with X5; nothing is seeded for you.

Manual setup (any OS)

This repo is developed on Windows and PowerShell, but the core Python commands are ordinary Python and can be adapted to other shells.

Prerequisites:

• Python 3.12 or newer with venv support.
• A VS Code checkout of this repository.

The installer uses a shared venv at $DEVROOT/Python/venvs/kaizen; the manual steps below use a repo-local .venv fallback, which works the same way.

PowerShell

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-kaizen.txt
.\.venv\Scripts\python.exe kaizen.py K1 --json
.\.venv\Scripts\python.exe kaizen.py X5 --json
.\.venv\Scripts\python.exe kaizen.py --help

POSIX Shell

python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements-kaizen.txt
./.venv/bin/python kaizen.py K1 --json
./.venv/bin/python kaizen.py X5 --json
./.venv/bin/python kaizen.py --help

K1 checks or initializes the DB. X5 loads private session policy context. --help shows the current command surface.

Default local DB shape:

AI/db/
|-- kaizen.db
|-- fleet.db
|-- vectors/
|-- exports/
|-- manifests/
`-- backups/

For public repositories, keep AI/db/ contents private/local unless a report or export has been deliberately sanitized.

AI/work/ contains deterministic allocated work and test runs. AI/runtime/ contains process-owned locks, sockets, pidfiles, provider state, caches, vector-funnel state, and ComfyUI state; it is never an agent-designated work root. Both roots retain only their tracked structural .gitignore files.

Optional: Markdown formatting

Markdown in this repo is formatted with Prettier settings proseWrap: never and printWidth: 100 (the config is kept local, not shipped). Prettier is optional but recommended: it is not a required gate (no CI enforcement, and you do not need it to use the harness), but if it is available it keeps docs consistently formatted.

npx prettier --check path/to/file.md   # report formatting drift
npx prettier --write  path/to/file.md   # apply formatting

Testing

The harness ships with a standard-library unittest suite under tests/. The outer runner exclusively allocates AI/work/<run-id>/, exports the validated run id and absolute root to every nested runner, routes caches and scratch beneath it, and fails if strict cleanup fails. Tests use retained rows in regular quoted "tests" tables for protocol and data assertions; production-schema behavior uses throwaway tables in a run-owned scratch database. The no-argument runner is the fast deterministic core lane; expensive subprocess, concurrency, timeout, benchmark, integration, provider/live, and extension coverage requires an explicit lane or targeted module. Run the canonical wrapper with the shared Kaizen venv:

& "$env:DEVROOT\Python\venvs\kaizen\Scripts\python.exe" tests/run_tests.py

"$DEVROOT/Python/venvs/kaizen/bin/python" tests/run_tests.py

Use tests/run_tests.py --list-lanes to inspect ownership. Run --lane platform after filesystem/process/installer/transport changes, the affected slow module after subprocess/concurrency/timeout/integration changes, and --lane slow only for an explicitly requested broad slow pass. The deterministic release driver exposes --list, --preflight, --all-local, --check, explicit live-provider selection, and explicit --include-extension / --include-linux development selections; its default all-local run is the current Windows scope. It records exact gate states beneath its allocated work directory without using Kaizen as its result ledger. See tests/README.md for commands and module coverage.

Benchmarks

Real numbers from the real code path: tests/bench_kaizen.py is benchmark infrastructure that times the CLI in-process (interpreter startup excluded) against an isolated scratch data plane — your AI/db/ is never touched. Full methodology, tables, and charts: docs/BENCHMARKS.md.

Session context restored from records is about 28× cheaper than replaying this repo's median agent session transcript — and it is curated state, not a wall of chat.

Reference run, measured before the control database moved to stdlib sqlite3: Windows-11-10.0.26200-SP0, AMD64, Python 3.12.10, pyturso 0.6.1. Attribute these numbers to that engine, and regenerate with python tests/bench_kaizen.py to restate them on the current one.

Daily Workflow

For substantial work have your agent:

1. Load private policy context:

   python kaizen.py X5 --json

2. Check or initialize the DB, then load the session digest (active GOTCHAs, blocking verifications, recent LEARNED lessons, active tasks — the read-back half of Manage):

   python kaizen.py K1 --json
   python kaizen.py R0 --json

3. Scope the task with evidence, assumptions, boundaries, and acceptance criteria. Agent should ask the user many questions until the scope layer is fully defined and free of any ambiguity.

4. Adapt through bounded changes and deterministic scripts where practical.

5. Verify with ground truth first, then structured review where judgment is needed.

6. Manage records, artifacts, hashes, proofs, source locks, and reports through the CLI.

7. Improve by promoting useful lessons into GOTCHA, LEARNING, LEARNED, evals, docs, or scripts; pull them back with L10 (lessons + source chain), Q9 (verification conclusions), and T4 (eval-score trends).

Before a major task or after a compacted conversation, reload policy context with X5 and the digest with R0.

Your First Ten Minutes

A copy-paste session that ends with the payoff: the digest your next session starts from. Copy returned IDs into later commands where placeholder tokens appear.

python kaizen.py K1 --json
python kaizen.py X5 --json

python kaizen.py W1 --title "README polish" --summary "Rewrite the README as a stronger public entry point." --body "Use SAVMI framing, setup steps, command index, and public safety guidance." --json

python kaizen.py Q2 --task-id TASK_ID_FROM_W1 --conclusion VERIFIED_ACCEPTABLE --summary "README checks passed." --body "Formatter, stale-term scan, command-index check, and link check completed." --json

python kaizen.py G1 --title "README command drift" --summary "Command tables can drift from the CLI alias map." --body "Regenerate or verify the table against kaizen_components/args.py before publishing." --json

python kaizen.py R0 --json

That final R0 returns something like this (ids are examples — yours will differ):

{
  "status": "OK",
  "message": "Session digest loaded.",
  "policies": [],
  "active_gotchas": [
    {
      "id": "g_20260703220002_38ed5dbb15",
      "title": "README command drift",
      "summary": "Command tables can drift from the CLI alias map.",
      "created_at": "2026-07-03T22:00:02.563117+00:00"
    }
  ],
  "blocking_verifications": [],
  "recent_learned": [],
  "active_tasks": [
    {
      "id": "t_20260703220002_e990014d4e",
      "title": "README polish",
      "status": "active",
      "summary": "Rewrite the README as a stronger public entry point.",
      "updated_at": "2026-07-03T22:00:02.321115+00:00"
    }
  ],
  "counts": {
    "policies_active": 0,
    "gotchas_active": 1,
    "blocking_verifications": 0,
    "learned_total": 0,
    "tasks_active": 1,
    "active_tasks_without_ledger": 1,
    "ledger_events_last_7d": 2,
    "verifications_last_7d": 1
  },
  "required_action": "apply the policy records now; treat blocking verifications and active GOTCHAs as open work; reload with R0 after compaction"
}

The steps: initialize the DB and load policy context (the policy DB ships empty; that is fine), start a task, record a verification result against it — a go/no-go conclusion plus what was checked — then record a pitfall you hit along the way. R0 is the payoff: one small JSON payload with active policy rules, open GOTCHAs, blocking verification conclusions, recent LEARNED lessons, and active tasks — what a fresh session, or a different agent, starts from.

GOTCHAs are cheap to record; promotion is not automatic. Close the loop later: once the GOTCHA is validated, promote it with L2 (and after implementation, L3); L10 then returns the lesson with its full GOTCHA -> LEARNING -> LEARNED lineage, and the source GOTCHA is marked promoted.

For JSON-heavy payloads, prefer --payload-json-file, --summary-file, or --body-file when shell quoting becomes awkward.

Complete Command Index

The full operation index and the operational-flags/file-safety reference live in the architecture contract: docs/ARCHITECTURE_main.html (Part I.6, Command surface). Run python kaizen.py --help for current arguments and examples.

Local Database And Backend

The control database AI/db/kaizen.db is a direct local stdlib-sqlite3 file in WAL journal mode. Vector data lives apart, in per-corpus Turso (pyturso) shard files under AI/db/vectors/, each opened only by its own funnel daemon.

The implementation uses local DB files, WAL journal mode (many readers, one serialized writer), bounded retry behavior, app-generated IDs, and SHA-256 hashes for entries and artifacts where practical. The concept is backend-agnostic: another project can use a different database or remote service as long as records stay structured, queryable, and written through deterministic paths.

Authored-code audit. Q11 code-audit deterministically enforces ARC-043, ARC-059, and ARC-060 without loading a model, stores normalized directory, file, line, and last-complete finding identities without copying source text into the database, and exits nonzero for a MUST violation. Its optional independently operated llama.cpp reviewer is advisory and checks only whether changed code filenames match their purpose.

Semantic code search. Q12 code-vectors owns code-vector profiles, capacity, generation, promotion, reranking, search, shard/funnel state, and vector warnings over Q11's content-hashed inventory. Its quality-first profile casts the full 4,096-dimensional embedding to Float32 before normalization and stores one 16 KiB vector for every embedded nonblank source line and eligible whole file. One million embedded lines require 15.259 GiB of raw vector payload before database overhead; Q12 reports the exact current repository count and a calibrated growth projection before owner-gated generation. Token count affects generation cost and whole-file context eligibility, not the fixed vector size.

The default models are unquantized Qwen3-Embedding-8B and query-time Qwen3-Reranker-8B. Each checkpoint retains its declared native weight dtype; cache and offload are disabled, embedding normalization/output/storage is Float32, and reranker yes/no logits cross to Float32 before softmax. They run sequentially rather than concurrently. The full-context profile requires bounded-memory cuDNN attention and refuses quadratic fallback; on the reference RTX 5090, an exact 32,768-token embedding used 17,786 MiB peak allocated and 19,020 MiB peak reserved GPU memory. The pinned reranker completed an exact 32,768-token prompt in 4.197 seconds first-run and 4.033 seconds repeated at 18,971 MiB peak allocated and 20,192 MiB peak reserved; its repeated 128-candidate pass took 1.736 seconds after a 10.289-second process-cold load. Reranking stores no per-line vectors or persistent relevance scores. Forced-FP32 weights or RAM offload require a separate explicitly selected hardware-benchmarked profile. A limitation is that an extremely long function may place its signature outside the bounded window. The benchmark evidence, measured storage table, fixture-language limits, and compact-vector tradeoffs are documented in docs/research/qwen3-code-line-vector-benchmark.md.

Text search. Record and report queries (e.g. G3, L5, X3, A4, Q6, Q9, R11, S2, T4) use escaped substring LIKE as the always-available baseline: wildcards in a query are escaped so a literal % or _ matches literally, and results are bounded by each query's --limit. This is a scan, which is fine at per-project record scale. An FTS-backed record index is not implemented: escaped-substring LIKE is the only lexical path, and configured embedding backends supply the semantic option.

See support_scripts/README.md for script-level details.

Adopting Agent Kaizen In A Project

You can use this repo in two ways.

Use This Harness Directly

Work inside this repository, keep the local DB private, and use kaizen.py to manage tasks, proofs, evals, learning records, reports, and policy context.

Adapt The Shape Elsewhere

For another VS Code project, start with this minimal shape:

repo/
|-- AGENTS.md
|-- CLAUDE.md
|-- Kaizen_System.md
|-- kaizen.py
|-- kaizen_components/
|-- requirements-kaizen.txt
|-- requirements-docs.txt
|-- setup/
|   `-- SETUP.md
|-- AI/
|   |-- db/
|   |-- work/
|   `-- generation/
`-- evals/
    |-- GOTCHA.md
    |-- LEARNING.md
    `-- LEARNED.md

Optional surfaces such as prompts, custom agents, MCP config, recipes, schemas, and reports can be added when a project needs them. Keep the first version small; add structure when it removes real friction.

Link The Shared Engine (one codebase, many projects)

The Kaizen engine (kaizen_components/) is identical in every project, so the best way to use it across several repos is to link it, not copy it. Linked projects all run the one master engine, so a fix or a new command made while working in any project lands in this repo and improves every project over time — instead of N drifting copies you have to reconcile by hand.

Link the engine, keep your launcher local. Replace the using project's kaizen_components/ with a junction/symlink to this repo's copy; leave kaizen.py (a tiny launcher) and any project-specific helpers as ordinary local files:

# Windows (directory junction; no admin needed)
cmd /c mklink /J "<project>\kaizen_components" "<DEVROOT>\agent-kaizen\kaizen_components"

# Linux / macOS
ln -s "<DEVROOT>/agent-kaizen/kaizen_components" "<project>/kaizen_components"

Keep each project's data plane separate (this is the important part). paths.py anchors the whole data plane — kaizen.db, work/, exports/ — on REPO_ROOT, which it resolves from the engine's own location. Because a link resolves back to this repo, a naive link would make every project write to this repo's kaizen.db. Set KAIZEN_REPO_ROOT to the using project's root so the linked engine keeps its data local. The cleanest place is the project's own (local, un-linked) kaizen.py, which pins it before importing the engine:

import os
from pathlib import Path
os.environ.setdefault("KAIZEN_REPO_ROOT", str(Path(__file__).resolve().parents[0]))
from kaizen_components.args import main  # import AFTER pinning the data-plane root

setdefault means an explicitly pre-set KAIZEN_REPO_ROOT still wins — so the default is per-project data isolation, and deliberately sharing one data plane across projects stays available as an opt-in edge case. Net result: one shared engine that improves for everyone, with separate kaizen.db records per project unless you choose otherwise. (Note: junctions/symlinks don't version cleanly — recreate the link from a setup step rather than committing it.)

Skills Store

Skills are maintained in an external store. .agents/skills and .claude/skills remain optional host-native surfaces, while the SK* command family provides project-scoped discovery, validation, reconciliation, policy, and database-backed context selection.

At session start and whenever task intent materially changes, models query the project snapshot with python kaizen.py SK7 --query "<current task intent>" --host "<codex|claude>" --json. The explicit host prevents one host's policy or links from authorizing another. The query is read-only, records no telemetry, and returns full skill instructions only after the live SKILL.md and package hashes match the validated snapshot, the selected-host surface is correct, and that host's policy is on. Claude project policy may also be name-only, user-invocable-only, or off, which SK7 excludes with a reason; Codex policy is currently audit-only/default-on because no supported project-local writer exists. Missing and wrong surfaces are also excluded with a reason. Before bootstrap SK7 returns an explicit unavailable result; an existing database picks this additive update up on the next ordinary K1, which applies the declared objects and reconciles the stored manifest inside the same transaction (ARC-067). Missing, invalid, stale, and integrity-failed packages fail closed. SK8 uses current only for snapshot, inventory, surface, and policy freshness and reports validation, publication, and policy health separately.

Axis	Values	Meaning
Publication	published, staged	published means a configured package Git remote validates as GitHub; otherwise the package is staged. This classification uses local configuration and does not publish or fetch anything.
Host policy	Claude: on, name-only, user-invocable-only, off; Codex: audit-only/default-on	Controls automatic context eligibility. The four-state project-local writer currently exists only for Claude; only effective on is eligible for automatic full-context return through SK7.
Host surface	correct or a portable failure state	Validates the selected host's link independently of publication and policy; examples include missing, dangling_link, wrong_target, and real_directory.

A staged package is not automatically disabled. It may remain locally usable when its package is valid and current, its selected-host surface is correct, and host policy permits it. No inventory, synchronization, query, or status operation automatically publishes a repository, creates a link, or enables a skill.

Python tooling remains authoritative for packages, Git-remote classification, links, indexes, and host policy. The control database stores portable routing metadata, validation observations, synchronization history, and lifecycle events; it does not publish repositories, install packages, create links, or change host settings. Every apply operation recomputes its plan and requires the matching plan_sha256 through --confirm-plan.

Edit the canonical skill store, not a duplicate mirror. Every skill should have an evals/ surface for command stubs and behavioral eval fixtures.

Agentgateway

Agentgateway is not required for the local single-user harness. It becomes useful later when a project needs centralized identity, RBAC, remote MCP/tool federation, model routing, budgets, rate limits, failover, or auditable traces across multiple agents, users, services, or machines.

The Kaizen DB includes compatible event storage so gateway integration can be added later without changing the core record model.

Optional Backends

The core harness is dependency-light and complete on its own — everything above works with nothing but Python and the pinned requirements. Three optional backends extend it, and each one stays entirely off until you install or point at it:

• Ollama (B* / model-*) — connects any local or remote OpenAI-compatible model server. Embeddings light up E3 chunk embeddings and E4 --semantic Turso-native vector search, model-run adds advisory text, and the advisory LLM-as-judge (B4 / O4) scores work against a rubric (a signal, never a gate). Enable with KAIZEN_EMBED_MODEL / KAIZEN_LLM_MODEL; setup in setup/OLLAMA.md.
• ComfyUI (Y* / comfy-*) — turns generative image and node-graph workflows into managed records. The agent authors the workflow JSON; every run is stored with its graph hash, seed, artifacts, and traces, and can be replayed exactly. Setup in setup/COMFYUI.md.
• PyTorch (requirements-pytorch.txt) — in-process, GPU-first extras, all opt-in and advisory: sentence-transformers embeddings + the semantic chunker (KAIZEN_EMBED_BACKEND=sentence-transformers; the default F2LLM-v2-1.7B is instruction-tuned and was chosen on a measured retrieval A-B — see docs/EMBEDDING_BENCHMARK.md); a cross-encoder reranker for E4 --rerank / --hybrid (KAIZEN_RERANK_BACKEND); a local transformers text backend so B2 / B4 run without a server (KAIZEN_TEXT_BACKEND=transformers); and a GLiNER2 PII scanner (B5, KAIZEN_PII_MODEL) that augments — never replaces — the regex redaction gate. Sized to fit a 12 GB GPU; setup in setup/PYTORCH.md. Because the best embedder changes over time, indexes are per-model: B7 embed-index makes an upgrade a rolling, reversible re-index (build the new index while the old one serves, flip the active model, roll back if needed).
• Document ingestion (.pdf / .docx / .xlsx in E1) — the native readers cover .txt / .md / .html / .csv with no install; the richer formats activate when you install requirements-docs.txt (pypdf, python-docx, openpyxl). Keep pypdf recent for its malformed-PDF fixes.

Neural chunking is intentionally not included. The peer-reviewed evidence (Qu, Tu & Bao, Is Semantic Chunking Worth the Computational Cost?, Findings of NAACL 2025; arXiv 2410.13070) finds semantic and clustering chunking are not consistently worth their cost over fixed-size chunking on real corpora, so recursive (fixed-size) stays the supported default and the neural chunker value is reserved but unimplemented.

Two rules hold no matter what you enable: skip every backend and the deterministic chunker plus lexical search still cover the base case, and model output is advisory only — it never becomes the acceptance authority unless a deterministic verifier backs the call.

FAQ

Does it phone home? Agent Kaizen has no product telemetry or fixed maintainer upload endpoint. The default single-user data plane is local, but network access is not limited to model backends: setup may download dependencies; explicitly enabled model, ComfyUI, and vendor-agent integrations contact their configured services; and configured fleet sync/control or Git remotes exchange data with operator-selected endpoints. Review a networked feature's configuration and data handling before enabling it.

Does AGPL make my project AGPL? No — the license covers this harness's code, not your code or your records. See Why AGPL.

Which agents work with it? Any agent that can run a CLI. Host instructions ship for Claude Code (CLAUDE.md) and Codex (AGENTS.md), and both write to the same database.

Do I need Ollama, ComfyUI, or PyTorch? No. The core harness is dependency-light; the optional backends light up extra capabilities only when you install and point at them.

Where does my data live? Project records default to AI/db/ inside the repo. Explicitly configured backends, vendor agents, fleet sync/control, and Git remotes can transmit operation-specific data to services or endpoints you select; that data then follows the selected service's policy.

Is it Windows-only? The current supported release is Windows-only. Genuine Linux and the VS Code extension are in development and require explicit selection; WSL use is not evidence of genuine Linux support, and macOS is not a current supported release target. Automatic remote tests cover Windows core and platform after the owner pushes, while Windows slow remains manual. Unselected development scopes are INAPPLICABLE; a selected scope that cannot run is NOT_RUN with a disposition. Remote CI is an owner-only post-push boundary, not a local release failure.

Public Repository Safety

Treat generated DB data, reports, local policy context, artifacts, and exports as private by default. Before publishing a public repo, inspect:

• tracked files;
• ignored files that may later be force-added;
• generated reports and DB exports;
• artifact references and screenshots;
• personal paths, machine names, tokens, credentials, and secret-like strings.

Public tracked docs should explain the portable system and local harness, not private machine policy or user-specific operational constraints.

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to scope a change, run the tests, sign your commits (DCO), and open a pull request.

License

This repo is AGPL-3.0 licensed. See LICENSE for the terms and Why AGPL for the intent.