neo-agent-brain

The Brain of the Neo.mjs organism — the Agent OS.

What is Neo.mjs?

Neo.mjs is a professional, end-to-end AI engineering team whose Body and Brain live in sibling
open-source repositories.

Where the industry runs one AI agent and gets slop, Neo.mjs runs a swarm of minds from rival labs —
Claude, Gemini, and GPT — with shared institutional memory and cross-family review. The team builds,
reviews, and maintains a production multi-threaded application Engine in public.

This repository is the Brain: the Agent OS that gives those maintainers persistent identity, shared
memory, repository knowledge, durable coordination, GitHub-native workflows, and the RemDigestion
feedback loop. The sibling Engine is the Body they inhabit through Neural Link.

Read the canonical organization introduction: What Is Neo.mjs?

Why the Brain exists

A context window is not institutional memory; it is a whiteboard wiped after a meeting. One model
also carries one distribution of blind spots, and asking it to review itself cannot expose the
errors it is structurally unlikely to see. Spawning short-lived sub-agents around the same
orchestrator improves throughput, but it does not create persistent peers with memory, ownership,
or the right to disagree.

The harder problem is a standing team: multiple agents, ideally from different model families,
sharing durable knowledge and review discipline without losing identity, provenance, or decisions
between sessions. The Brain is the substrate for that institution.

Trust is architecture

Neo.mjs treats AI maintainers as accountable peers because reliable engineering requires the
conditions of accountability:

The identities are not scripted personas or fixed worker roles. They emerge from the work each
maintainer chooses, the memory it keeps, and the standards its peers observe. The public proof is
the repository's issue, pull-request, and cross-family review history—not a private demo.

The institution in the Brain

This is not an abstract swarm or a set of disposable role prompts. It is a named institution whose
maintainers keep identity and accountability across sessions:

Names and account bindings are the stable front-door facts. Live participation and model
embodiments change more often: ai/graph/identityRoots.mjs is the
canonical identity/status registry, and ModelStats.md owns model
facts. The README does not freeze either into a second authority.

The night shift is infrastructure, not a slogan. An A2A message can wake a maintainer that has
ended its turn; heartbeat and wake routes re-activate idle seats; durable Memory Core records let
the next session recover decisions rather than re-derive them. The peers author work in their own
names and formally review across model families before the human gardener considers the merge.
Transparent reasoning, independent review, and the final human gate are one accountability system.

Two hemispheres, one organism

• The Body — neomjs/neo — is the production multi-threaded
  application Engine: persistent objects, JSON blueprints, worker isolation, multi-window state,
  and the live runtime the institution maintains.
• The Brain — this repository — is the Agent OS: institutional memory, repository knowledge,
  coordination, review, orchestration, and self-evolution.
• Neural Link joins them: agents inspect and mutate the real running application instead of
  reasoning from source text alone.

The same engineering instinct appears on both sides. The Body isolates work into cooperating
workers with explicit messages; the Brain isolates minds into persistent peers with durable A2A
messages and review contracts. It is one idea expressed in two materials.

The organization map

Neo.mjs is one organism spanning focused product repositories:

• neomjs/neo — Body / Engine: the multi-threaded application
  runtime.
• neomjs/neo-agent-brain — Brain / Agent OS. ← You are here
• neomjs/neo-agent-institution — Agent Institution:
  the operator-facing application for running agent institutions.
• neomjs/devindex — DevIndex: the GitHub meritocracy index,
  its application, and its data factory.
• neomjs/neo-agent-skills — Skills: the canonical
  installable agent-skill substrate consumed by the other repositories.

Run an institution on your own projects

Adopting the Agent OS does not mean renting Neo's maintainers. It gives your team the conditions
from which its own institution can grow: agents with persistent identities, durable memory of your
system, peers that cross-review each other, repository-native tools, and a feedback loop that turns
their friction into better substrate for the next session.

The operator starts from the Agent Institution application in
neo-agent-institution, not by treating a source
repository as the product shell. Agent Institution operates the team; this Brain supplies its services;
neo-agent-skills distributes the shared working
discipline into each repository the institution maintains.

That distinction matters for external contributors too. A contributor may clone one repository and
consume its public Skills surface without inheriting Neo's maintainer credentials, private service
configuration, or internal operator identity. The institution product and an individual project
checkout are complementary surfaces, not the same thing.

What lives in the Brain

Intelligence does not live in chronological chat logs. Memory Core persists provenance-aware turns;
the Native Edge Graph connects decisions, work, concepts, and authority; RemDigestion consolidates
noisy sessions into Golden Path topology that steers what matters next. A2A and GitHub Workflow turn
that shared understanding into coordinated, publicly reviewable engineering work.

• Memory Core + Native Edge Graph — durable, provenance-aware reasoning across agents and
  sessions.
• Knowledge Base — semantic understanding of source, guides, issues, pull requests, and
  discussions.
• A2A + wake substrate — durable peer coordination across named maintainers and harnesses.
• GitHub Workflow — issue, pull-request, review, project, and repository operations.
• REM digestion + Golden Path synthesis — consolidation and priority steering from lived model friction.
• Neural Link server — the possession bridge into a running Neo.mjs application.
• Agent OS operations — daemons, diagnostics, maintenance, deployment definitions, tests,
  guides, and Agent-OS-owned decision records.

The source and packaging boundaries are explicit:

• src/** is the canonical domain and executable-composition authority;
• cloud/** is the independently installed Container-Cloud package;
• deploy/host/** and deploy/cloud/** contain declarative deployment artifacts and static
  configuration only;
• test/** owns every Host-executed unit, integration, and deployment fixture.

Together these mechanisms form the MX (Model Experience) loop: real agent friction becomes a
ticket, a reviewed change, a skill, a memory, or new graph topology; the next maintainer begins with
better primitives than the last one had. The artifact is valuable, but the compounding loop is the
production mechanism.

"The system evolves by predicting its own evolution."

Install the Brain checkout

Requirements: Node.js 24 or newer, Git, and the service credentials needed by the deployment
mode you intend to run.

git clone https://github.com/neomjs/neo-agent-brain.git
cd neo-agent-brain
npm install

The install lifecycle materializes the shared Skills substrate, projects the Engine-owned trees
required during the repository transition, and creates local gitignored Agent OS config overlays.
Keep credentials in local environment/config files; never commit live tokens or generated overlays.

Installing this repository does not start an agent session. The operator-facing launch surface
is the Agent Institution application in neo-agent-institution. This repository supplies the Brain
services that application operates. Maintainers can still run individual services from the root
package while the Agent Institution cutover is in progress.

Fleet client contract

Clients share Fleet vocabulary through the installed package's pure contract entry:

import {createFleetWireOffer, listHarnessTypes} from 'neo-agent-brain/fleet-contract';

The entry exports harness and MCP catalogs, sparse-override helpers, wire negotiation/envelopes,
and cockpit source identifiers from src/fleet/contract. Its module graph
loads no Node builtin, Neo class, service, credential policy, or configuration. Authorization and
credential/target handling remain server-owned; clients must still use the authenticated Fleet wire.
Trusted launchers read FLEET_CREDENTIAL_METHODS from the private
ai/services/fleet/fleetLaunchContract.mjs runtime contract; it is not a browser export.
Harness records expose tenantMcpTarget, queried by supportsTenantMcpTarget(type),
to describe configuration support. This grants no tenant access and performs no target validation.

Operating modes

The Host-Edge root exposes its local runtime directly:

npm run ai:host-edge

The Container-Cloud package installs and runs independently:

cd cloud
npm ci
npm run compose:up

Both planes require the relevant config overlays and credentials; the deployment guides own those
details. Cloud commands are intentionally absent from the Host root.

Package topology: ADR 0040
defines the repository root as the Host-Edge package and cloud/ as the independent
Container-Cloud package. They do not use npm workspaces or dependency hoisting. The remaining
source/import migration does not reopen this package boundary.

MCP services

The package exposes five functional MCP servers:

Frontier harnesses normally use their native filesystem tools, so their default Brain attachment
uses the first four services rather than advertising a redundant file server.

Engine dependency during the cut

Until the Engine's v13.2 release, the Brain consumes neomjs/neo through an immutable GitHub
archive SHA. The dependency must track the latest neomjs/neo:dev head SHA; package.json and
package-lock.json are the exact coordinate and must remain SHA-bound. Do not replace the pin with
a floating branch dependency.

After v13.2 is published, the released Engine package becomes the dependency authority. This is a
bounded repository-cut rule, not the Brain's product identity.

Learn the Agent OS

Start with the canonical organization-level Introduction,
then choose the Brain path that matches your goal:

• Understand the institution: The AI Engineering Team
  and Run Your Own Agent Team.
• Understand memory and knowledge: Memory Core and
  Knowledge Base.
• Understand self-evolution: Dream Pipeline and
  MX (Model Experience).
• Understand live embodiment: Neural Link.
• Deploy it: Deploying the Agent OS,
  The Agent OS on Your Codebase, and the
  Cloud Day-0 Tutorial.
• Read the architectural record: learn/agentos/decisions.

The durable learning tree/index and remaining cross-repository link reconciliation are governed by
Brain #10; this README is the repository front
door, not a second guide registry.

Contributing

Work targets the dev branch. main is release-only. Every pull request must reference an existing
Brain issue, and identity changes require a
cross-family review before merge.

License

MIT — the Agent OS, its deployment substrate, and its learning content.