Mozi Development

Working on MOZI

Load this before adding or changing anything in this codebase. Its job is to stop you rediscovering the architecture by grep every time — and, more importantly, to stop you drawing the wrong map, which is the failure this codebase keeps repeating.

The companion artifact is docs/atlas/MOZI-架构全景.html — a module-by-module map of this runtime: design, implementation, third-party vs custom, call paths, wiring verdicts backed by non-test callers, examples and known traps. Read the section for the layer you are touching before designing anything. Its code excerpts are extracted from the tree by anchor, not transcribed, so they cannot silently drift.

When you finish a change, run python3 docs/atlas/staleness.py. It reports which atlas modules your diff invalidated — usually a handful — so the map is updated by targeted rescans rather than by repeating the full sweep, which is what let the previous atlas rot 151 commits behind. If it reports files that belong to no module, you have either added a subsystem the map does not know about or found a coverage gap; either way it needs an entry.

Why a scan of the code lies to you

Three failure modes, all with real incidents behind them. Assume all three are present until you have checked.

1. Code exists, nothing calls it. Vector memory sat installed and dead for four months. memory_summaries had a UI reading a table nothing wrote. The whole telemetry pipeline had dashboards and replay tooling while its three writers had zero callers. A grep that finds a function proves nothing about whether it runs.
2. Documentation describes intent, not behaviour. Files claim capabilities the runtime never registered. docs/ and CLAUDE.md have both been wrong about live call paths. Trust the call graph over any prose, including this file.
3. A second implementation quietly wins. Two build-script allowlists existed; only one was read, so a dependency's install step never ran and the conflict also swallowed the warning. When behaviour contradicts configuration, look for the other implementation before concluding the config is broken.

Before you design: find what already exists

Ask these in order. Most "new" features in this codebase are a new entry in an existing registry, not new machinery.

• Is it a tool the model can call? Tools are declared centrally and gated by runtime predicates — adding one is a definition plus an executor branch plus a permission entry, not a new subsystem.
• Is it a capability the model should reach for by name? That is a SKILL.md, discovered from disk. No code change at all.
• Is it a persona that should run isolated with its own tools? That is an AGENT.md, and the delegation path already exists.
• Is it a new LLM vendor? The provider catalog is data. Check whether the existing openai-compat mode can express it (custom headers and query params are supported) before adding an API mode or a dependency.
• Is it a new chat surface? Channels are registry plugins; the gateway does not change.
• Is it long-running work? There is already a background job runner with a handler registry, and a managed-worker contract for external CLI agents.
• Does it need to survive a restart? There is a durable job state machine and an event log. Do not invent a second one.

If the answer to all of these is no, say so explicitly in your plan and explain why the existing seams do not fit. That sentence is where over-engineering gets caught.