Đọc phiên bản tiếng Việt tại đây.
What is it? Konductor is an AI orchestration workflow: a set of Markdown files that give AI coding agents memory and coordination, kept entirely inside your local repository.
Who is it for? Developers, indie hackers, and teams who use AI coding agents (Gemini, Claude, Cursor, Trae) across many sessions of real development work.
Why use it? AI agents forget everything between sessions. Konductor keeps your project's rules, architecture, and current state in files the agent reads and updates, so you stop re-onboarding it from scratch every time.
We didn't set out to build a framework. We wanted to stop repeating ourselves.
We used to manage teams of 20+ engineers, and now we run lean, AI-assisted development across a fleet of production systems. In both settings, the biggest drain on our time was rebuilding context every time we switched models, started a new session, or handed work to a different agent. Writing the code took less time than that.
So we fixed it. The result is konductor-workflow, a Markdown-first workflow standard for AI coding agents. It now runs underneath more than a dozen of our live projects.
The problem: AI has no memory
Every AI coding session starts the same way. You open a chat, the AI generates something reasonable, you correct it, and it picks up your patterns. Then the context fills up, the session ends, or you switch models, and the next session starts from zero.
Do that across a team, on a complex ERP, over weeks of iterating on a payment gateway integration, and the cost adds up. We were spending more time re-orienting agents than shipping.
The usual advice is to write better prompts or longer system instructions. That moves the problem around without solving it.
What Konductor is
Konductor is a set of durable Markdown files that live inside your codebase, laid out so any AI agent can orient itself in seconds.
The core files are:
KONDUCTOR.md: a compact contract at the repo root covering the repo's role, stack, mission, and rules. You tag it on every prompt.docs/CHECK_IN.md: short-term working memory with the current task, work in progress, and what's next..konductor/memory/KONDUCTOR_MEMORY.md: long-term constraints and the anti-patterns the AI has learned to avoid..konductor/memory/KONDUCTOR_VISION_ROADMAP.md: why the project exists..konductor/memory/KONDUCTOR_ADR_HISTORY.md: important architectural decisions, logged as embedded ADRs.
The workflow is a 9-step metacognitive loop: load context, clarify and plan, check in before executing, execute, reflect, persist memory, and loop. The AI writes what it learned back into these files, so the next session starts with more than the last one had.
Everything is plain Markdown in your Git repository. There's no cloud service, subscription, or vendor to depend on.
Token usage and context
Konductor has the AI read and write its documentation with the filler stripped out. That keeps prompts small and keeps the agent's attention on the technical requirements.
A typical AI explanation of three basic architectural facts runs to about 45 tokens. Konductor enforces a "caveman" style instead (- UI: Next.js + React, - State: Zustand), which costs a fraction of that and leaves more of the context window for code.
Where we've used it
Over the past year, Konductor has been the coordination layer on:
- eCommerce ERPs with multi-tenant inventory, order processing pipelines, and fulfilment tracking
- Payment gateway integrations, where agents hand work between planning and execution sessions every day
- Delivery and taxi booking platforms, whose complex state machines an agent has to understand before it touches anything
- POS systems for F&B chains, where decisions made months ago still have to be respected by today's agents
- Internal tooling and client projects, both greenfield builds and legacy codebases
The pattern held on all of them. With the Konductor memory files, agents produced better code with fewer regressions and needed less correction. Without them, they drifted.
Why we open-sourced it
We've run this internally since 2020 and changed it as the AI tools around us changed. It started as a shared set of guidelines across IDEs and grew as we adopted Claude, Gemini, and other coding agents at scale.
Every team using coding agents has this problem, and keeping our fix proprietary wouldn't make it work any better, so we published it.
The Claude Code architecture leak in April 2026 reinforced something we had already built around: you should be able to inspect what your agent knows, which rules it follows, and what decisions it has made. With Konductor, all of that is readable Markdown checked into your repository, and none of it is synced to a cloud you don't control.
.konductor/
├── KONDUCTOR_VERSION.json
└── memory/
├── KONDUCTOR_ADR_HISTORY.md
├── KONDUCTOR_MEMORY.md
└── KONDUCTOR_VISION_ROADMAP.md
Who this is for
Konductor is for developers, indie builders, and small teams who already use AI coding agents seriously and are tired of rebuilding context every session.
It works best if you:
- Use AI agents in a real development workflow, beyond one-off completions
- Work across multiple sessions, models, or team members
- Have a codebase with established architectural patterns you want the AI to respect
- Want reproducible results, and don't want the AI inventing your own past decisions
Konductor only works if you keep the documentation up to date. That's ordinary engineering discipline (writing down what you decided and why), and the AI does much of the writing.
Get started
Paste this prompt into the AI agent in your IDE and let it do the setup:
Install this package npx konductor-workflow@latest
then begin review this codebase and update/compact all project docs
to match progress, must follow strict Konductor workflow
Or install it yourself:
npx konductor-workflow
After installing, initialise the framework inside your repo by following the setup in KONDUCTOR_WORKFLOW.md, then tag @KONDUCTOR.md at the start of every prompt.
The package, blueprints, and workflow documentation are at npmjs.com/package/konductor-workflow.
Update: custom skills and stricter guardrails (late April 2026)
Since the first release we've kept extending Konductor internally. It now supports custom project skills and custom workflows, so agents can run scoped project logic (such as statically syncing the knowledge base from new Markdown blog posts) instead of reaching for generic tools.
We've also tightened the guardrails. Our own KONDUCTOR.md contract now forbids agents from using native browser interaction tools, so every verification goes through deterministic, headless Playwright regression checks.
Thanks to everyone who has tried it in their own projects. As of this week, konductor-workflow passed 600 monthly downloads on npm.
Acknowledgments and references
These are the ideas and projects Konductor draws on:
-
Hyperagent and Darwin Gödel Machine (DGM)
The concepts behind the self-improvement architecture and the metacognitive loop that structures our reasoning workflow.
Reference: arXiv:2603.19461
-
Architecture Decision Records (ADR)
The method we use to record long-term architectural decisions and the reasons behind them, so that context survives from one development phase to the next.
Reference: adr.github.io
-
The "caveman" token reduction technique
Shaped how we structure workflow files to cut token use without losing the context the agent needs.
Reference: JuliusBrussee/caveman on GitHub
-
Behavior guardrail patterns for coding agents
Sharpened Konductor's behavior layer: think before coding, prefer the simplest approach, keep diffs surgical, and teach anti-patterns with examples.
Reference: forrestchang/andrej-karpathy-skills on GitHub
-
Verifiable memory architectures
The case for keeping an AI agent's memory secure, verifiable, and open to inspection, which recent industry events made hard to ignore.
Reference: Claude Code leak implications
-
Field notes
Our running record of trials, mistakes, and lessons from adapting to AI workflows on real projects.
Reference: alphabits.team/blogs
-
The Second Brains "Conductor" node (March 2024)
Konductor's predecessor. We built it in Node-RED as the orchestration node that routed flows and managed agents across our whole architecture.
Reference: AlphaBitsCode/second.brains on GitHub
Alpha Bits is a technology company based in Vietnam. We build AI-powered systems for businesses and share what we learn in the open. If you want to see Konductor in action at one of our upcoming workshops in Da Nang, register your interest here.