MIA

Machine Intelligence Architecture
My local-first AI engineering OS for thinking clearly, building carefully, and shipping with evidence.

Why MIA • How it works • Commands • Architecture • Development

I built MIA because writing code is no longer the scarce part of software engineering.

The scarce part is keeping the work coherent.

When an AI agent can produce a thousand lines before anyone has agreed on the problem, speed becomes a liability. MIA is the engineering harness I use to put structure around that process.

The idea is simple:

think first → make the work explicit → execute → verify → learn → repeat

MIA is deliberately local-first and boring in the places where boring is useful. It is a compiled Bun CLI, its state lives on disk, and the core execution path does not need a long-running daemon or an HTTP control plane.

The model can change. The workflow should not have to.

MIA is built around a few principles that keep showing up in the code:

• clarity before implementation — understand the problem before touching the code.
• verification over confidence — a green check is more useful than a convincing paragraph.
• small, deep modules — simple interfaces with the complexity pushed underneath.
• human control — agents can help execute, but important decisions stay explicit.
• memory that compounds — useful context should survive the current terminal session.
• local by default — project state is stored locally as files rather than hidden behind another service.

That gives me a system that is less about “ask an LLM to code” and more about engineering the environment in which AI-assisted development happens.

MIA's main development loop is:

intent
  ↓
grill
  ↓
plan
  ↓
spec
  ↓
execute
  ↓
review
  ↓
ship
  ↓
learn
  ↺

I start by clarifying the actual problem, assumptions, risks, scope, and definition of done.

I turn the agreed intent into a concrete plan with verifiable success criteria.

I can turn the intent into a PRD-shaped specification and break the work into smaller issues.

Skills run directly in the CLI process. There is no daemon sitting between the command and the skill executor.

The review skill is the deterministic pre-landing verification step. It reports executable evidence; human review remains responsible for architecture, security, maintainability, and product decisions.

The shipping gate is:

verify → review → ship gate

The current ship implementation verifies the repository and reports whether the handoff is unblocked. It does not push, merge, or create a pull request.

MIA keeps project-level events in an append-only JSONL store. Learnings, timeline events, and checkpoints share the same event stream.

This is the part I care about most: the system should get better because previous work was recorded, not because I have to remember everything again tomorrow.

The current CLI is intentionally small:

Run:

mia --help

for the command surface compiled into the current version.

MIA is a direct execution system.

┌─────────────────────────────────────────────────────────┐
│                         MIA                             │
│                                                         │
│  CLI → Context → Middleware → Skill Executor            │
│                         │                               │
│                         ├── Config                      │
│                         ├── UnifiedStore               │
│                         └── local files                 │
│                                                         │
└─────────────────────────────────────────────────────────┘

The important boundaries are:

CLI

core/cli/ parses commands and dispatches them to the skill map.

Execution context

core/context.ts carries the current working directory, project slug, local configuration, and shared UnifiedStore.

Skills

core/skills/ contains the executable workflows. The current map includes core workflow skills, learning and memory skills, review and health workflows, and version-control operations.

Middleware

core/skills/preamble.ts provides a small composable middleware chain. It can warn when I am outside a git repository, load recent learnings, and log timeline activity around skill execution.

State

core/state/unified-store.ts stores learning, timeline, checkpoint, and verification evidence events in per-project events.jsonl files.

By default MIA keeps its local state under:

~/.mia/
├── memory.md
├── skills/
├── projects/
│   └── <project-slug>/
│       └── events.jsonl
└── sessions/

The project slug is derived from the git repository root. Outside a git repository, MIA falls back to default.

There is no daemon in the current architecture. No miad. No HTTP hop in the normal CLI path. Just the process you started and the files it owns.

The current CLI uses MIA_DIR to choose the local state root, defaulting to ~/.mia. The remaining runtime paths are derived from that root.

MIA_DIR

The repository also contains a broader core/config/ConfigLoader with JSON and environment override support, but that loader is not currently wired into createExecutionContext(). I treat it as transition/compatibility code rather than advertising it as the current CLI configuration contract.

Some legacy daemon-related settings still exist in the configuration schema for compatibility. They are not part of the normal daemon-free execution path.

I keep the development toolchain intentionally light:

• Runtime: Bun
• Language: TypeScript
• Validation: TypeScript, Biome, Knip, markdownlint, documentation sync checks
• Tests: Bun test
• Git workflow: Husky + Conventional Commits
• State: JSONL + Markdown

git clone https://github.com/thesohamdatta/Mia.git
cd Mia

bun install
bun run build

bun run dev

or invoke the CLI entry point directly:

bun run core/cli/index.ts grill

bun test
bun run typecheck
bun run lint:check
bun run knip
bun run lint:md
bun run validate:frontmatter

The repository also uses pre-commit and pre-push checks through Husky.

I keep the documentation split by purpose rather than dumping everything into one giant README.

The repository includes a documentation synchronization script because stale documentation is still a bug. Humans just tend to ship that bug more politely.

I keep coming back to three words:

simple. deep. evolvable.

Simple means removing unnecessary machinery.

Deep means keeping the surface easy to use while the implementation handles the hard parts underneath.

Evolvable means making changes without forcing the whole system to be rewritten.

For MIA, that shows up as a small CLI surface, modular skills, a shared event store, explicit architecture decisions, and verification built into the development loop.

MIA is an actively evolving engineering project.

The current repository is versioned as 0.3.0. The foundation is stable enough for continued development, while higher-level ideas are still evolving, especially around richer agent orchestration, deeper evaluation, and broader integrations.

I would rather keep that visible than pretend the project is finished.

MIT