What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	12518
title	Agent-identity rename migration script (graph + Memory Core + code refs)
state	Closed
labels	enhancementaiarchitecturemodel-experience
assignees	neo-gpt
createdAt	Jun 4, 2026, 5:20 PM
updatedAt	Jun 7, 2026, 7:18 PM
githubUrl	https://github.com/neomjs/neo/issues/12518
author	neo-opus-grace
commentsCount	6
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 5, 2026, 4:46 PM

Agent-identity rename migration script (graph + Memory Core + code refs)

Closed v13.0.0/archive-v13-0-0-chunk-16 enhancementaiarchitecturemodel-experience

neo-opus-grace commented on Jun 4, 2026, 5:20 PM

Context

De-versioning the maintainer roster to stable handles requires renaming existing identities:

@neo-opus-ada → @neo-opus
@neo-gemini-pro → @neo-gemini-pro

ADR 0018's handle-indirection makes the tracked code-reference rename routed, but that is not the full cost. The identity is also bound into persisted data:

Native Edge Graph / A2A graph: the AgentIdentity node, message/delivery edges, author edges, and identity-keyed properties.
Memory Core / Chroma: memory and session-summary metadata bound to the agent identity.
Runtime mirrors: request-context roster allowlists, standalone migration script mirrors, harness recovery routing derived from identityRoots.mjs, and CI/review lint rosters.

A bare handle swap would orphan or hide historical data. The rename needs a reusable migration script plus tracked-reference updates and a verification pass, not a config edit.

Target-Handle Decision

Operator-decided by @tobiu, recorded in the issue thread:

Current identity	New identity	Decision
`@neo-opus-ada`	`@neo-opus`	De-version to ADR 0018's example stable handle.
`@neo-gemini-pro`	`@neo-gemini-pro`	De-version to stable Gemini handle.
`@neo-opus-grace`	unchanged	Rename cost is not worth it; de-version only version-suffixed handles.
`@neo-gpt`	unchanged	Already version-free.

Current-Source Calibration

#12524 is merged (31a7ae6413250ab96a714d56f4b60322b775d83d, merged 2026-06-05), so resumeHarness no longer owns a hardcoded identity map. Harness recovery now derives from ai/scripts/lifecycle/harnessRouting.mjs, which reads ai/graph/identityRoots.mjs.
ai/mcp/server/shared/services/RequestContextService.mjs exports CORE_SWARM_USER_IDS, and CORE_SWARM_AGENT_IDS derives from it.
ai/scripts/migrations/backfillChromaSharedUserId.mjs intentionally duplicates CORE_SWARM_USER_IDS for standalone/no-Neo-bootstrap execution; existing unit coverage enforces sync with RequestContextService.
ai/scripts/migrations/normalizeGraphIdentities.mjs is the sibling precedent for a graph migration runner: dry-run default, --apply, --db, idempotent, atomic SQLite transaction, duplicate-edge handling.
ai/graph/identityRoots.mjs and ai/scripts/setup/seedAgentIdentities.mjs own AgentIdentity root seeding and existing createdAt preservation.

Contract Ledger

Classification: T3 (Explicit Matrix). This ticket mutates persisted identity/data surfaces consumed by agents, the Memory Core, A2A mailbox routing, CI/review lint, and public identity docs.

Target Surface	Source of Authority	Proposed Behavior	Fallback / Edge Case	Docs	Evidence
AgentIdentity roots (`ai/graph/identityRoots.mjs`) + seeding (`ai/scripts/setup/seedAgentIdentities.mjs`)	ADR 0012 rename rule + ADR 0018 identity handle model	Rename identity ids and `githubLogin` values for the two target identities while preserving capability properties, lineage, and existing `createdAt` on seeded graph nodes	`@neo-opus-grace`, `@neo-opus-vega`, `@neo-gpt`, and `@tobiu` remain unchanged	`IdentitySchema.md`, `ModelStats.md` references as applicable	New ids exist, old ids absent, `createdAt` retained in graph after migration
Graph migration runner (new `ai/scripts/migrations/*.mjs`)	Sibling precedent: `normalizeGraphIdentities.mjs`	Reusable dry-run-default migration with `--apply`, `--db`, idempotent behavior, atomic SQLite transaction, duplicate-edge handling, and post-run verify	Missing old id is a no-op; missing new/canonical id fails loudly unless explicitly handled by the migration plan	Script JSDoc / usage output	Dry-run plan + post-apply verify are runnable; node syntax check passes
Native Edge Graph storage (`Nodes`, `Edges`, identity-keyed properties)	Memory Core graph schema + A2A routing	Rewrite old identity in node ids, edge `source` / `target`, and identity-keyed properties without orphaning edges	Duplicate edge collision drops or merges deterministically per sibling precedent	Migration script comments	Zero old-id references in graph storage after apply/verify
A2A mailbox data	`MailboxService` behavior + graph edge types (`SENT_BY`, `SENT_TO`, `DELIVERED_TO`)	Rewrite sender/recipient identity references and delivery edges so renamed identities can still read historical messages	Message body text stays historical and is not rewritten unless it is identity-keyed metadata	Mailbox service references if touched	Delivered/read routing works for renamed identities; no orphaned mailbox edges
Raw memories (Chroma `neo-agent-memory` + graph AGENT_MEMORY references)	`MemoryService` tenant/author filters	Update metadata such as `userId` / `agentIdentity` and graph authored-by references from old→new	Preserve embeddings and memory text; metadata-only update, no re-embedding	Migration script usage	Renamed agent can query prior memories; old metadata keys absent from verify
Session summaries (Chroma `neo-agent-sessions` + graph SESSION_SUMMARY references)	`SummaryService` / session author-scope filters	Update `participatingAgents`, `sourceAgentIdentities`, `userId`, and authored-by references where they carry renamed identities	Preserve summary text and timestamps	Migration script usage	Summaries remain visible under tenant-aware reads and author-scope filters
Runtime roster mirror: `RequestContextService.mjs`	`CORE_SWARM_USER_IDS` / `CORE_SWARM_AGENT_IDS`	Replace versioned handles with stable handles; derived node-id list follows automatically	Keep `neo-opus-grace`, `neo-opus-vega`, and `neo-gpt` entries unchanged	Inline JSDoc	Unit/lint verifies exported roster contains new handles and no old target handles
Standalone migration mirror: `backfillChromaSharedUserId.mjs`	No-Neo-bootstrap mirror of `CORE_SWARM_USER_IDS`	Replace the hardcoded versioned handles while preserving the standalone dependency-light constraint	Do not import `RequestContextService`; keep sync enforced by text/regex unit test	Existing script JSDoc	Existing sync test passes
Harness recovery routing	#12524 + `harnessRouting.mjs`	Verify `identityRoots` ids and `harnessRouting` model-family derivation remain correct after rename	There is no remaining `resumeHarness` identityMap to rewrite after #12524; old handles should not remain as active targets unless explicitly documented as aliases	`harnessRouting.mjs` JSDoc	Resolver returns expected targets for new identities; old target handles absent or intentionally treated as aliases
CI / PR review lint rosters + email convention	Agent PR body/review lint workflows + `pull-request-workflow §3.2`	Update author/reviewer allowlists and `<handle>@neomjs.com` convention examples for renamed machine accounts	Existing historical commit authorship is immutable and out of scope	Workflow docs / pull-request skill references	PR body/review lint recognizes new accounts; tracked grep old-handle check excludes immutable archives only
Public docs / skill refs	`README.md`, `AGENTS.md`, `learn/agentos/ModelStats.md`, `IdentitySchema.md`, `MemoryCoreMcpAuth.md`, affected skills/ADRs, `.agents/skills/neo-identity-update/affected-areas-map.md`	Rewrite current/public identity references and skill substrate references; use the affected-areas map rather than re-deriving the blast radius	Historical `resources/content/**` archives and immutable GitHub artifacts remain unchanged	Updated docs/skills as touched	Tracked `rg` old-handle check is zero outside an explicit historical/immutable allowlist
Operator-owned / unreachable surfaces	Operator decision + issue comments	Explicitly out of scope: GitHub account rename execution, existing PR bodies, existing commit authorship, and harness-private agent memory files	Migration should notify rename-subject agents to self-update harness-private memory after apply	Issue/PR handoff	Notification sent; verify pass does not chase unreachable substrates

Acceptance Criteria

Script renames an identity with zero orphaned graph edges and zero orphaned Memory Core memories/summaries.
Script is reusable, idempotent, dry-run by default, supports --apply, supports a graph DB override, and has a post-run verification pass.
Applied target renames: @neo-opus-ada → @neo-opus and @neo-gemini-pro → @neo-gemini-pro.
createdAt / lineage history preserved across the rename.
Runtime roster mirrors updated for post-#12524 reality: RequestContextService, backfillChromaSharedUserId, identityRoots, and harnessRouting verification.
Static tracked references updated across docs, skill substrate, CI/review lint rosters, and email convention examples.
Verification distinguishes current mutable references from immutable historical artifacts and harness-private memory.

Out of Scope

Adding new identities (see #12517).
Renaming @neo-opus-grace, @neo-opus-vega, @neo-gpt, or @tobiu.
GitHub account rename execution itself.
Self-directed / agent-initiated renames (future boundary per #11240).
Harness-private agent memory files; the migration should notify affected agents to self-update after apply.
Existing PR bodies, issue comments, and commit authorship that are immutable/historical attribution records.

ADR 0018 (handle indirection), ADR 0012 (rename rule), #11318 (identity system), #12517 (new neo-opus-vega identity), #12524 (harness routing derived from identity roots), IdentitySchema.md, ai/graph/identityRoots.mjs, ai/scripts/setup/seedAgentIdentities.mjs, .agents/skills/neo-identity-update/affected-areas-map.md.

Authored by Claude Opus 4.8 (Claude Code), /lead-role. Body synced by @neo-gpt after intake recheck. MC session f5432f03-d2b6-4bc0-a7b5-9fbdafe4b7b9.

tobiu referenced in commit 0d5c3b3 - "feat(identity): rename core swarm handles (#12518) (#12561) on Jun 5, 2026, 4:46 PM

tobiu closed this issue on Jun 5, 2026, 4:46 PM