MatKaiOS Master Map

An evidence-first, zero-write diagnostic engine that maps MatKaiOS without executing or modifying the system.

Comment

Inspiration

Before MatKaiOS became a repository or a local application, I worked inside ChatGPT and Gemini, creating specialized GPTs and Gems for specific tasks. At first, they were instructions written in natural language. Over time, those instructions became more structured: Markdown, JSON, separate files, operating rules, review procedures, and specialized roles.

I kept improving the instructions, but at some point more instructions stopped solving the problem.

The rules needed to become part of the system itself.

Tools such as Google Antigravity and OpenAI Codex allowed me to move those processes from chat interfaces into local development environments. I began distributing identity, context, procedures, boundaries, and responsibilities across different files. I also created specialized agents such as Historian, Antigravity, and Sentinel to separate documentation, execution, and review.

While experimenting with OpenClaw and local models, I discovered an important limitation: a well-written methodology does not guarantee that an agent will follow it correctly.

An agent can ignore instructions, lose context, mix responsibilities, use tools inconsistently, or complete the immediate task while moving the larger project in the wrong direction if the human is not paying attention.

My first response was to add more rules.

More prompts.

More governance.

More restrictions.

But MatKaiOS was never intended to become a golden prison for KAI.

The intention was always for KAI to be free—free up to the point where the human owner is willing to trust the system and accept the consequences.

That is why MatKaiOS includes different security, autonomy, and execution modes. A user can choose a guarded configuration, or allow much more freedom in a private local environment.

In my own early MatKaiOS setups, I often selected the Easy local mode and temporarily enabled Full Kai. But the setup wizard states the risk clearly:

I can read your files, modify them, and also delete them. One bad prompt can be the difference between a brilliant response and a disastrous result.

That warning represents an important part of the project.

The goal is not to pretend that powerful agents are harmless.

The goal is to make capability, risk, authority, and responsibility visible so the human can make an informed decision.

My experiments with local models and tool execution eventually showed a larger possibility: instead of depending only on prompts, I could build a runtime where identity, sessions, tools, providers, policies, memory, evidence, autonomy, and security boundaries were real parts of the system.

MatKaiOS and its central intelligence, KAI, emerged from that evolution.

MatKaiOS was not created in one week for this event. It is a long-term project built through experimentation, research, AI-assisted development, original methodologies, failures, corrections, and many iterations.

The specific OpenAI Build Week contribution came from a real problem inside that project.

As MatKaiOS grew, it became increasingly difficult to determine what was truly canonical, how its parts were connected, which claims could be demonstrated with evidence, and which conclusions were still only interpretations.

Master Map was created to help observe and understand the system without modifying the system it is trying to explain.

What it does

MatKaiOS Master Map is an external, zero-write, evidence-based diagnostic system for inspecting the structure of MatKaiOS.

Its purpose is to build a verifiable view of the system from a controlled Git snapshot and the evidence found inside the repository.

Instead of assuming that it understands the entire runtime, Master Map separates:

  • verifiable facts;
  • associated evidence;
  • structural relationships;
  • admitted authority sources;
  • derived representations;
  • explicit terminal states;
  • unimplemented capabilities;
  • questions that cannot yet be answered.

Master Map v2 currently includes five primary foundations:

  1. External Zero-Write Foundation.
  2. Facts & Evidence Foundation.
  3. Source Authority Foundation.
  4. Structural Anatomy Foundation.
  5. Static Module Resolution Foundation.

These foundations help answer questions such as:

  • Which components exist inside the accepted snapshot?
  • What evidence supports each observation?
  • Which files are allowed to act as sources?
  • How is the repository structurally organized?
  • Which module references can be resolved statically?
  • Which parts of a representation are demonstrated?
  • Where must the system stop because the evidence is not sufficient?

The system being inspected, MatKaiOS, is a local-first operating and coordination platform for governed AI agents.

MatKaiOS provides KAI with identity, authority, sessions, workspaces, missions, memory, persistence, policies, providers, models, tools, communication channels, observability, and evidence.

It also allows the owner to choose different levels of security, autonomy, validation, and operational freedom.

Master Map is not all of MatKaiOS.

It is the diagnostic instrument we are developing to understand it, verify it, and make better decisions about its evolution.

An analogy I often use is that MatKaiOS and KAI are the patient, while Master Map is intended to become something like a diagnostic capsule camera.

The capsule does not exist to control the patient. It exists to help us see what is happening, understand why it is happening, and determine what should or should not be changed.

The current version does not yet perform complete runtime observation. It establishes the safe, evidence-based structural foundation required before deeper observation can be trusted.

How we built it

MatKaiOS, KAI, and an initial internal Master Map approach—now called Master Map v1—already existed before OpenAI Build Week.

Master Map v1 produced inventories, maps, registries, generated artifacts, authority mechanisms, and diagnostic views inside the MatKaiOS repository.

It was useful.

It also taught us a great deal.

But as it became larger, it became increasingly difficult to maintain as a reproducible and trustworthy representation of the current system.

Generated artifacts could become stale.

Historical expectations could affect current validation.

Documentation, names, and representations could appear authoritative without proving current runtime behavior.

Master Map v1 was not discarded because it had no value.

It was valuable enough to reveal why its own architecture could not become the final source of truth.

During Build Week, I worked extensively in Codex using GPT-5.6 Sol to study that architecture, characterize its limitations, and build Master Map v2 as an external, zero-write diagnostic tool.

The work was not completed through a single autonomous prompt.

It followed an iterative engineering cycle:

  • define a concrete problem;
  • establish scope and constraints;
  • inspect real repository evidence;
  • propose or implement a bounded change;
  • run tests and contracts;
  • examine contradictions;
  • accept, reject, or narrow the proposal;
  • correct the result;
  • verify it again.

Codex was used to:

  • inspect the real repository;
  • implement and refactor code;
  • create and strengthen contracts;
  • build tests;
  • improve reproducibility;
  • perform static analysis;
  • diagnose failures;
  • generate evidence;
  • compare technical alternatives;
  • revise rejected or incomplete solutions.

My responsibility was to preserve the project’s intent, define architectural boundaries, separate facts from inferences, protect privacy, review the results, and decide which claims were defensible.

Some of the most useful results came from solutions we rejected.

There were moments when another repair appeared technically possible, but continuing would only extend the same architectural loop.

One of the most important human decisions was recognizing when more code would not make the system clearer.

At that point, the correct action was to preserve the evidence, recognize the limits of v1, and change the architecture.

Master Map v2 was built around principles such as:

  • physical separation between the tool, target, store, and vault;
  • bounded capture of Git targets;
  • zero-write and no-drift verification;
  • facts linked to evidence;
  • deny-by-default policies;
  • provenance and producer identity;
  • deterministic manifests and receipts;
  • derived structural anatomy without retaining raw source-code bytes;
  • static reference resolution;
  • explicit terminal states;
  • fail-closed behavior;
  • precise documentation of boundaries and non-claims.

The v2 implementation was integrated into the evaluation branch while preserving its history through a non-squashed Git subtree integration.

The submission also includes a dedicated Build Week workflow and documentation that clearly separates:

  • the pre-existing MatKaiOS product;
  • Master Map v1 as a historical, non-canonical system;
  • Master Map v2 as the main Build Week contribution;
  • the publicly installable MatKaiOS build;
  • ongoing internal development;
  • the exact submission snapshot.

Challenges we ran into

One of the greatest challenges was maintaining long AI-agent work sessions without losing intent, context, or control of the scope.

A large prompt was not enough.

An agent could:

  • interpret a restriction differently;
  • solve the immediate problem while sacrificing the broader design;
  • create auxiliary files during a task declared as read-only;
  • repeat repair and convergence cycles;
  • confuse a generated representation with a source of truth;
  • produce a convincing answer without sufficient evidence;
  • continue working when the correct action was to stop and report uncertainty.

In one read-only audit, an agent created a temporary report file to help complete its own task.

Nothing critical was damaged.

But the incident made the lesson concrete:

Read-only must be verified, not merely requested.

That experience directly influenced the zero-write and no-drift principles of Master Map v2.

It was also difficult to define what it really means to “map” an agentic system.

Finding a file, function, class, or static reference does not prove by itself:

  • that the component is executed;
  • that it participates in a specific conversation;
  • that it causes a behavior;
  • that it represents the current state;
  • that it is the canonical source;
  • that a complete causal flow exists between two points.

We had to carefully separate:

  • structure;
  • authority;
  • provenance;
  • freshness;
  • execution;
  • causality;
  • evidence;
  • inference;
  • unknowns.

Other challenges included:

  • generated artifacts becoming stale;
  • dependencies between historical state and current validation;
  • differences between local Windows execution and Linux CI;
  • filesystem isolation;
  • root and path policies;
  • reproducibility across environments;
  • differences between local and remote branches;
  • protection of secrets, sessions, databases, and private runtime state;
  • preparing an evaluable submission without publishing the original working tree.

Codex quota also became a real engineering constraint.

We reached a point where repeated exploration was no longer sustainable. We had to reserve the remaining capacity for work that produced verifiable progress and use Antigravity for tightly bounded publication and Git operations.

The main challenge was not generating more code.

It was knowing what we could honestly accept as proven and what was still only an assumption.

Accomplishments that we're proud of

I am proud that we transformed an internal problem that was difficult to explain into a technical tool with explicit boundaries and verifiable principles.

During Build Week, we built and verified the five current foundations of Master Map v2:

  • External Zero-Write Foundation;
  • Facts & Evidence Foundation;
  • Source Authority Foundation;
  • Structural Anatomy Foundation;
  • Static Module Resolution Foundation.

We also:

  • separated the diagnostic tool from the inspected system;
  • demonstrated no-drift against a bounded Git target;
  • linked observations to evidence and provenance;
  • applied deny-by-default source-admission rules;
  • generated derived structural anatomy without retaining raw source-code bytes;
  • resolved static references to internal modules, Node.js built-ins, or explicit terminal states;
  • preserved Master Map v1 as historical evidence instead of deleting or hiding it;
  • avoided falsely presenting the historical system as green;
  • separated active MatKaiOS validation from historical v1 expectations;
  • integrated Master Map v2 while preserving its Git history;
  • created a submission-specific CI workflow;
  • corrected a cross-platform problem discovered by Linux CI;
  • documented scope, provenance, human–Codex collaboration, limitations, and evaluation paths.

In the current submission snapshot:

  • the active canonical MatKaiOS suite passes 584 out of 584 tests;
  • the Master Map v2 unit suite passes 104 out of 104 tests on Node.js 22.23.1;
  • the same suite passes 104 out of 104 tests on Node.js 24.18.0;
  • the Master Map v2 production dependency audit reports zero vulnerabilities;
  • the MatKaiOS production dependency audit reports zero vulnerabilities;
  • the repository-cleanliness checks pass.

The complete Master Map verification suite also includes fixture-intensive Git integration tests. That full suite exceeded the selected controlled timeout during a Windows execution, so we do not present it as fully passed.

I consider that limitation part of the accomplishment as well.

We chose not to create a fake green result.

One of the most important outcomes is not only the software.

It is evidence that coding agents can participate in complex, long-running work when there is transportable context, bounded contracts, testing, provenance, frequent review, and clear human authority.

What we learned

I learned that prompts are not sufficient to govern complex agentic systems.

Important instructions need to become external, verifiable, and connected structures:

  • files;
  • contracts;
  • policies;
  • tests;
  • acceptance criteria;
  • stop conditions;
  • manifests;
  • receipts;
  • evidence;
  • decision records.

I learned that adding more rules can improve safety, but rules alone can also become a cage.

The goal is not maximum restriction.

The goal is controlled freedom.

The system should make the risks visible, provide meaningful security choices, and allow the human owner to decide how much autonomy is appropriate for the environment.

I learned that an agent can complete the immediate task and still move the project in the wrong direction if the human is not paying attention.

I learned that a representation can look convincing and still be incorrect if it does not preserve:

  • authority;
  • freshness;
  • provenance;
  • scope;
  • boundaries;
  • uncertainty;
  • its relationship to the original evidence.

I learned that read-only should not be only a written instruction. It must be demonstrated operationally through no-drift verification and physical separation.

I learned that historical sources, documents, filenames, and generated artifacts may provide evidence, but they should not automatically be accepted as current authority.

I learned that sustained collaboration with AI requires:

  • checkpoints;
  • small changes;
  • gates;
  • frequent verification;
  • transportable context;
  • reproducible evidence;
  • mechanisms for rejecting convincing but incorrect solutions;
  • continuous analysis;
  • the ability to stop.

Detecting the limit of an architecture does not mean that the work failed.

Understanding why Master Map v1 entered reconstruction and convergence loops helped us build a stricter and physically separate v2 architecture.

Finally, I learned that the human role does not disappear as the agent becomes more capable.

It changes.

The human remains responsible for:

  • defining intent;
  • choosing how much freedom to allow;
  • governing scope;
  • protecting privacy;
  • evaluating evidence;
  • identifying contradictions;
  • rejecting excessive claims;
  • deciding when to continue, correct, or stop.

What's next for MatKaiOS Master Map

Master Map v2 now has an external, zero-write, evidence-based foundation verified through static module resolution.

The next step is to extend that architecture without pretending that future layers already exist.

Future directions include:

  • export binding;
  • symbol binding;
  • deeper static wiring analysis;
  • runtime and observational evidence;
  • causal indexing;
  • controlled capture sessions;
  • query and replay;
  • a human-oriented diagnostic interface;
  • a synchronization policy between the integrated version and its independent development line.

Master Map v2 does not yet claim:

  • complete runtime causality;
  • actual execution of a static reference;
  • complete call graphs;
  • live observation;
  • causal message tracing;
  • total semantic understanding;
  • a finished visual inspector.

Those limitations are not hidden.

They define the next stage of the work.

The long-term goal is not to produce a static diagram.

My goal is to build a reliable diagnostic system that enables humans and agents to understand complex AI systems, determine what has been demonstrated, understand why it has been demonstrated, and clearly recognize what remains uncertain.

For MatKaiOS, that means building a progressively more complete diagnostic map of KAI: not only what components exist, but eventually how they interact, what influences a decision, what evidence supports an explanation, and where uncertainty remains.

The same principles may eventually apply far beyond MatKaiOS.

Built With

Share this project:

Updates