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.

Neo.mjs - Self-Evolving Software Organism

Frontmatter

title	feat(ai): concept schema enrichment — aliases & ANALOGOUS_TO (#10049)
author	tobiu
state	Merged
createdAt	Apr 17, 2026, 4:25 PM
updatedAt	Apr 17, 2026, 4:31 PM
closedAt	Apr 17, 2026, 4:31 PM
mergedAt	Apr 17, 2026, 4:31 PM
branches	`dev` ← `agent/10049-concept-schema-enrichment`
url	https://github.com/neomjs/neo/pull/10052

Merged

tobiu commented on Apr 17, 2026, 4:25 PM

Summary

Extends the Concept Ontology schema with two new capabilities:

1. Deterministic Aliases (O(1) Lookup)

New optional aliases string array on concept nodes
ConceptService.resolveAlias(term) — case-insensitive reverse lookup from any alias to its canonical concept
Aliases are strict synonyms within Neo.mjs (e.g., "OMT" → off-main-thread, "setupClass" → setup-class)
Duplicate alias detection during loadGraph() with error reporting

2. ANALOGOUS_TO Edge Type (Cross-Framework Mapping)

New ANALOGOUS_TO edge type connecting Neo.mjs concepts to external framework equivalents
External targets use ext: prefix (e.g., ext:react-context) to prevent ID collision
Each edge carries an architectural note field explaining how the Neo.mjs concept differs
ConceptService.getAnalogousConcepts(id) API for retrieval
10 initial edges seeded (State Provider ↔ React Context, JSON VDOM ↔ JSX, etc.)

Files Changed

File	Change
`ai/services/ConceptService.mjs`	+`aliasIndex` Map, +`resolveAlias()`, +`getAnalogousConcepts()`
`.neo-ai-data/concepts/nodes.jsonl`	+`aliases` on 6 concepts
`.neo-ai-data/concepts/edges.jsonl`	+10 `ANALOGOUS_TO` edges with ext: targets
`learn/agentos/ConceptOntology.md`	Schema docs for aliases, ANALOGOUS_TO, ext: convention
`test/.../ConceptService.spec.mjs`	+5 tests (21/21 passing)

Design Decisions

Aliases ≠ ANALOGOUS_TO: Aliases are strict O(1) synonyms within Neo.mjs. Cross-framework terms are relational edges with distinction notes. This prevents false equivalence ("ViewModel" is NOT State Provider).
ext: prefix: Prevents collision between internal concept IDs and external framework names.
note field: Forces the distinction to be explicit — every ANALOGOUS_TO edge must document HOW the concepts differ, not just that they're related.

Verification

21/21 Playwright unit tests passing
Production graph validation included (aliases populated, ext: prefix enforced)

Resolves #10049

tobiu commented on Apr 17, 2026, 4:30 PM

Input from Claude Opus 4.6 (Antigravity):

❋ # PR Review Summary

Status: Approved

Clean, narrowly scoped schema extension. The 3-layer separation (aliases → ANALOGOUS_TO → future embeddings) is architecturally sound. The ext: prefix convention for external concepts prevents namespace pollution. Test coverage is comprehensive.

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 95 - Follows established ConceptService patterns (singleton, Map-based indexing, JSONL parsing). The alias/edge distinction correctly preserves the Teaching Test principle.

[CONTENT_COMPLETENESS]: 95 - All new methods have full JSDoc with @summary, @param, @returns. Guide updated with schema tables, examples, and warning callouts. Only gap: no @see cross-reference from resolveAlias to the guide's alias rules.

[EXECUTION_QUALITY]: 92 - O(1) alias lookup via reverse Map is optimal. Duplicate detection during load prevents silent data corruption. loadGraph() properly clears aliasIndex on reload. Minor: resolveAlias checks direct ID match as fallback — solid defensive coding.

[PRODUCTIVITY]: 100 - All #10049 acceptance criteria met: aliases field, ANALOGOUS_TO edge type, ConceptService APIs, guide documentation, and tests.

[IMPACT]: 65 - Schema extension enabling future semantic search routing. Not yet consumed by any pipeline — value materializes when ChromaDB embedding (#10037) and DreamService integration land.

[COMPLEXITY]: 40 - Straightforward Map indexing and edge type addition. No cross-component state synchronization or worker-thread concerns.

[EFFORT_PROFILE]: Quick Win - High ROI (enables the entire semantic bridge pipeline) with low complexity (Map indexing, JSONL seeding).

🕸️ Context & Graph Linking

Target Epic / Issue ID: Resolves #10049 (child of #10030)

Related Graph Nodes: #10050 (description enrichment — prerequisite for quality embeddings), #10037 (ChromaDB concept embedding — downstream consumer), #10032 (ConceptService — parent implementation)

🧠 Graph Ingestion Notes

[KB_GAP]: N/A — The PR correctly distinguishes aliases from cross-framework analogues. No framework misunderstandings detected.

[TOOLING_GAP]: Antigravity API instability caused multiple session interruptions during this PR's execution. The retry button injects "continue" as the prompt, causing context loss. This drove the creation of #10051 (Branch-Before-Code mandate) as a systemic mitigation.

[RETROSPECTIVE]: The 3-layer design (deterministic aliases → relational ANALOGOUS_TO edges → semantic vectors) is the correct architecture for concept-to-file routing. Aliases handle exact matches, edges handle cross-framework mapping with forced distinction notes, and future ChromaDB embeddings handle fuzzy natural language queries. Each layer has a clear failure mode that doesn't cascade — a missing alias falls through to vector search; a missing ANALOGOUS_TO edge doesn't create false equivalence.

📋 Required Actions

No blocking changes required. LGTM.

All 21 tests passing

Guide documentation complete with WARNING callout on ANALOGOUS_TO semantics

Production graph validates without errors